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:

Here is a BibTeX for LaTeX users:

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
• 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.
  • 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
    • 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.
    • 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.
    • Smart cameras and drones

      Simulate robots with a field of view.
  • 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.
  • 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
  • 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
• 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.
• 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.
  • API Docs

    KDoc API docs. Captures both Java and Kotlin API abstractions.
  • Per-module API Docs

    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