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{alchemist,
  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

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.

Recommended IDE configuration

The project is easiest to import in IntelliJ Idea. The project can be imported directly as a Gradle project. If you intend to develop new parts in Scala, we suggest to install the Scala plugin for IntelliJ Idea.

Importing the project

1. Clone this repository in a folder of your preference using git clone --recurse-submodules <ALCHEMIST_REPO_URI>.
2. 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 system)

Developing the project

Contributions to this project are welcome. Just some rules:

• Use conventional commits. The build auto-generates aggressive git hooks that enforce the rules.
• We recommend forking the project, developing your stuff, then contributing back via pull request directly from GitHub.
• Keep in sync with the mainline (our master branch), preferably via rebasing.
• Commit often. Small pull requests targeting a small part of a larger work are very welcome if they can be merged individually.
• 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.
• Fixes should include a regression test.
• New features must include appropriate test cases.

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 assemble check --parallel

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

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.