The Alchemist Simulator
This website hosts the documentation of the Alchemist Simulator, created towards the end of 2010 as a by-product of the European Project SAPERE, and grown ever since into a full-fledged simulation framework.
Where to start
We recommend that you check out our showcase to understand what you can simulate, and our tutorials to learn how to fiddle with the tool. Once you are on track, we prepared specific how-to guides for the most common operations. To better understand how the simulator works, refer to our explanation section; to master it, building your own extensions and advanced scenarios or customizing what is available, take a look to the reference.
Alchemist for Academia
If you happen to use Alchemist for academic purposes, please add a reference to the following paper:
Pianini, D., Montagna, S., & Viroli, M. (2013). Chemical-oriented simulation of computational systems with ALCHEMIST. Journal of Simulation, 7(3), 202–215. https://doi.org/10.1057/jos.2012.27Here is a BibTeX for LaTeX users:
@article{Pianini_2013, title={Chemical-oriented simulation of computational systems with ALCHEMIST}, volume={7}, ISSN={1747-7786}, url={http://dx.doi.org/10.1057/jos.2012.27}, DOI={10.1057/jos.2012.27}, number={3}, journal={Journal of Simulation}, publisher={Informa UK Limited}, author={Pianini, D and Montagna, S and Viroli, M}, year={2013}, month=aug, pages={202–215} }
Index of contents
- Tutorials
Tutorials are lessons that take the reader by the hand through a series of steps. They are meant to show a beginner that they can achieve something with Alchemist.
- Quickstart
A super-fast way to get an instance of the simulator up and running.
- Step-by-step tutorial
A (video) guide through the main features of the simulator, as presented at DAIS 2021
- Protelis Incarnation Tutorial
Ready-to-run examples of increasing complexity with the Protelis incarnation
- SAPERE Incarnation Tutorial
Ready-to-run examples of increasing complexity with the SAPERE incarnation
- Scafi Incarnation Tutorial
Ready-to-run examples of increasing complexity with the Scafi incarnation
- Quickstart
- How-to Guides
How-to guides take the reader through the steps required to solve a real-world problem. They are recipes, directions to achieve a specific end: while a tutorial is what a beginner needs to know, a how-to guide is an answer to a question that only a user with some experience could even formulate. In how-to guides, we assume some knowledge and understanding, we assume that the user already knows how to do basic things and use basic tools.
- Preparation
Preliminary operations for using Alchemist: installation, setup
- Alchemist stand-alone
The recommended way to run the simulator and fetch all the required modules.
- Alchemist via Gradle
The recommended way to run the simulator and fetch all the required modules.
- Alchemist stand-alone
- Simulation
Guides on how to create simulation environments, configure node behaviour, and control the simulation details
- Create reusable variables
Define reusable pieces of information and compute upon them, prepare for the execution of simulation batches.
- Ensure repeatability
Control randomness, ensuring reproducibility and replicability of experiments.
- Cognitive Agents
Agents with realistic human behavior.
- Create a network
Define how nodes should be connected with each other.
- Create Layers
Define data layers that live in the environment
- Create rich environments
How to create complex environments (obstacles, and so on)
- Find paths indoors
How to navigate the environment, especially indoors.
- Maps and GPS traces
How to simulate using maps and GPS traces.
- Simulate indoor
How to create indoor environments based on planimetries.
- Simulate physical interactions among pedestrians
Physical interaction between nodes
- Find paths indoors
- Deploy Nodes
How to place nodes within Alchemist environments
- (Irregular) Grids
Deployment of nodes in (possibly irregular) grids.
- Nodes inside shapes
Deployment of nodes randomly inside arbitrary shapes.
- GPS Traces
Deployment of nodes on map-based environments using GPS data.
- Graphs
Deployment of nodes into arbitrary graphs.
- (Irregular) Grids
- Export data
Select which data the simulator should output, in which format, and where.
- Monitor and Control Simulations through GraphQL
Monitor and Control a Simulation through a set of GraphQL APIs.
- Monitoring Simulations through Custom Output Monitors
Create custom monitors to track simulation progression and interact with standard hooks.
- Program Nodes
How to define the behavior of nodes
- Move nodes on maps
How to move node around in geospatial environments.
- Node contents
Definition of the initial content of nodes.
- Move nodes on maps
- Smart cameras and drones
Simulate robots with a field of view.
- Create reusable variables
- Execution
Execution of multiple simulations, locally or in a distributed environment
- Customize the Swing GUI
Customize the look of your simulation.
- Define the termination criteria
Decide when the simulator should stop and consider the simulation concluded.
- MultiVeStA
How to integrate MultiVesta in Alchemist
- Parameter Sweeping with simulation batches
Execute multiple instances of a simulation with different parameters
- Simulation Engine Configuration
Available simulation engine configurations.
- Customize the Swing GUI
- Workarounds
Pre-concocted solutions to well-known issues
- Graphical Glitches in Swing
Known issues with Swing and OpenGL acceleration, especially with legacy AMD/ATi drivers.
- Memory leaks under Linux
Known issue of some Java Virtual Machine implementations when requested to use more than 64GB of RAM
- Graphical Glitches in Swing
- Experiment-specific extensions
One-time changes or additions to the simulator behavior
- Development
How to contribute to the project, hence achieving eternal glory
- Developer's guide
How to contribute
- Enrich the GraphQL API
How to create a new Query, Subscription, or Mutation using the GraphQL API
- Import Alchemist in an IDE
The recommended way to get and import the Alchemist project in an IDE
- Build and run the QA
How to locally build and test the simulator
- Developer's guide
- Preparation
- Explanation
Explanation, or discussions, clarify and illuminate a particular topic. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
- The Alchemist Meta-Model
What does Alchemist simulate? A trip on the abstractions that populate the world of Alchemist.
- The Alchemist Simulation Engine
How does Alchemist simulate? What is at its core?
- Biochemistry Incarnation
Basics of the biochemistry incarnation.
- Cognitive Agents
Agents with realistic human behavior.
- Pathfinding
Strategies to navigate the environment.
- SAPERE Incarnation
Basics of SAPERE and how its concepts are mapped in Alchemist.
- The Alchemist Meta-Model
- Reference
Reference guides are technical, austere, and to the point descriptions of the machinery and how to operate it. Reference guides have one job only: to describe. They are code-determined, because ultimately that’s what they describe: key classes, functions, APIs, and so they list things like functions, fields, attributes and methods, and set out how to use them.
- YAML simulation specification
Specification of the YAML-based language simulations are configured with.
- KDoc API (per-module)
KDoc API docs. Captures both Java and Kotlin API abstractions.
- Project organization
Locations where things are found: build files, API implementations
- Biochemistry Incarnation
Reference documentation of the reactions language for the biochemistry incarnation.
- Command Line interface
Available CLI options.
- Default Graphical User Interface
Redirect page for the current default graphical interface
- SAPERE Incarnation
Reference API for the SAPERE Incarnation.
- Swing GUI
Key mappings for the Java Swing-based graphical interface
- KDoc API
KDoc API docs. Captures both Java and Kotlin API abstractions.
- Javadoc API
Javadoc API docs. Kotlin classes are not captured as well as in KDoc, so the KDoc could be a better pick for most tasks.
- YAML simulation specification