Alchemist

Note for academics

The Alchemist simulator license obliges those who use this software for an academic publication to provide proper attribution. This should be to the paper introducing Alchemist:

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.27

A BibTeX entry for LaTeX users is:

@article{Pianini2013,
  doi = {10.1057/jos.2012.27},
  url = {https://doi.org/10.1057/jos.2012.27},
  year = {2013},
  month = aug,
  publisher = {Informa {UK} Limited},
  volume = {7},
  number = {3},
  pages = {202--215},
  author = {D Pianini and S Montagna and M Viroli},
  title = {Chemical-oriented simulation of computational systems with {ALCHEMIST}},
  journal = {Journal of Simulation}
}

What is Alchemist

Alchemist is a simulator for pervasive, aggregate, and nature-inspired computing. At the moment, the simulator features:

Executing Protelis programs
Executing Scafi programs
Executing biological simulations with chemical-like reactions
Executing SAPERE -like programs, written in a tuple based language resembling Linda
Simulating bidimensional environments
Simulating real-world maps, with support for navigation along roads, and for importing gpx format gps traces
Simulating indoor environments by importing black and white images
Simulating networks of smart cameras (similarly to CamSim, but with much better scaling)
Simulating pedestrian with a cognitive model
Creating batches and run with different value of parameters
Run in grid computing environments

Alchemist users should rely on the documentation available on the official Alchemist website. If you are already there, well, this text is shared by the README.md file and the site front page, so you are on the right place, check the menu (should be on the left-hand side) to learn how to use the simulator.

If you need access to features of the simulator which are still in development, please refer to the "latest" version of the website.

Alchemist is available on Maven Central. You can import all the components by importing the it.unibo.alchemist:alchemist artifact.

Gradle

You need to add the alchemist core dependency, plus the modules you need for your simulation. Add this dependency to your build, substituting ALCHEMIST_VERSION with the version you want to use (change the scope appropriately if you need Alchemist only for runtime or testing).

dependencies {
    // Alchemist core dependency
    implementation("it.unibo.alchemist:alchemist:ALCHEMIST_VERSION")
    // Example incarnation
    implementation("it.unibo.alchemist:alchemist-incarnation-protelis:ALCHEMIST_VERSION")
    // Example additional module
    implementation("it.unibo.alchemist:alchemist-cognitive-agents:ALCHEMIST_VERSION")
}

Maven

Add this dependency to your build, substitute ALCHEMIST_VERSION with the version you want to use. If you do not need the whole Alchemist machinery but just a sub-part of it, you can restrict the set of imported artifacts by using as dependencies the modules you are actually in need of.

<dependencies>
    <dependency>
        <groupId>it.unibo.alchemist</groupId>
        <artifactId>alchemist</artifactId>
        <version>ALCHEMIST_VERSION</version>
    </dependency>
    <dependency>
        <groupId>it.unibo.alchemist</groupId>
        <artifactId>alchemist-incarnation-protelis</artifactId>
        <version>ALCHEMIST_VERSION</version>
    </dependency>
    <dependency>
        <groupId>it.unibo.alchemist</groupId>
        <artifactId>alchemist-cognitive-agents</artifactId>
        <version>ALCHEMIST_VERSION</version>
    </dependency>
</dependencies>

Developers

Status Badges

Stable branch

Info

master:

develop:

Quality

Progress

Javadocs

Javadocs are available for both the latest stable version and the latest development snapshot. If you need to access the documentation for any older stable version, javadoc.io is probably the right place to search in.

Developing Alchemist (namely evolving the simulator, not using it for simulating stuff)

Forking the project

To contribute to this project we recommend to fork it and work on your own copy so that you can:

push all your commits, saving your work on the cloud;
exploit the included continuous integration jobs to check the project status;
contribute back to the main project via pull requests directly from GitHub.

This project defines several CI jobs. Some rely on an automatic merge system (YAAGHA) which requires a repository secret with:

name = AUTOMERGE_TOKEN
value = a github token with public_repo scope (or repo, if your fork is private). If you already have a token with the required scope, then you can reuse it, otherwise you have to create a new token.

If you don't provide it, then the CI workflow is likely to fail even though the project status is correct.

Recommended IDE configuration

The project is easiest to import in IntelliJ Idea.

Install the following plugins (use Ctrl+Shift+A, then search for "Plugins"):

From the main list:
- Scala
- Kotlin
From "Browse Repositories":

Importing the project

Clone this repository in a folder of your preference using git clone --recurse-submodules <ALCHEMIST_REPO_URI>.
Right click on settings.gradle.kts, select "Open With" and use IntelliJ Idea. The procedure may be slightly different depending on your operating system and desktop environment. If you have a terminal, and if you can launch idea from there, just:
1. cd <LOCATION_WHERE_YOU_CLONED_THE REPOSITORY>
2. idea . (we are assuming that you can launch IntelliJ Idea with the idea command, replace it with the correct one for your syustem
In 'Settings -> Build, Execution, Deployment -> Build Tools > Gradle', for the option 'Use Gradle from' select 'gradle-wrapper.properties file'. Enabling auto-import is also recommended.
Important: Alchemist requires java 11+, so make sure the 'Gradle JVM' option points to such a version (if you don't have a JDK 11+ installed make sure to get one).
Once imported, the project may still be unable to compile, due to missing sources in incarnation-biochemistry. This problem can be solved by opening the IntelliJ terminal (e.g. with Ctrl+Shift+A, typing "terminal" and pressing Enter), and issue:

On Unix: ./gradlew alchemist-incarnation-biochemistry:generateGrammarSource
On Windows: gradlew.bat alchemist-incarnation-biochemistry:generateGrammarSource

Developing the project

Contributions to this project are welcome. Just some rules:

We use git flow, so if you write new features, please do so in a separate feature- branch.
We recommend forking the project, developing your stuff, then contributing back via pull request directly from GitHub
Commit often. Do not throw at me pull requests with a single giant commit adding or changing the whole world. Split it in multiple commits and request a merge to the mainline often.
Stay in sync with the develop branch: pull often from develop (if the build passes), so that you don't diverge too much from the main development line.
Do not introduce low quality code. All the new code must comply with the checker rules (that are quite strict) and must not introduce any other warning. Resolutions of existing warnings (if any is present) are very welcome instead.

Building the project

While developing, you can rely on IntelliJ to build the project, it will generally do a very good job. If you want to generate the artifacts, you can rely on Gradle. Just point a terminal on the project's root and issue

./gradlew build

This will trigger the creation of the artifacts the executions of the tests, the generation of the documentation and of the project reports.

NOTE THAT: Alchemist requires java 11+ to work, make sure to have a JDK version 11+ installed.

Build reports

Every Alchemist build triggers the creation of a set of reports, that provide hints regarding the current status of quality of the code base. Such reports are available for both the latest stable and the latest development versions.

mazzio97/Alchemist