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.

Importing the project

The project is easiest to import in IntelliJ Idea.

Recommended configuration

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

• From the main list:
  • Scala
  • Kotlin
• From "Browse Repositories":
  • ANTLR v4 grammar plugin
  • Checkstyle-IDEA
  • FindBugs-IDEA
  • PMDPlugin

Importing the project

0. Windows user should perform an additional first step: before cloning the repository, make sure that the autocrlf feature of git is disabled, by issuing git config --global core.autocrlf false. If the step is not performed, git will automatically insert CRLF line endings, violating the project's Checkstyle rules (which are rather strict, and prevent the build from succeeding).
1. Clone this repository in a folder of your preference using git clone appropriately
2. Open IntellJ. If a project opens automatically, select "Close project". You should be on the welcome screen of IntelliJ idea.
3. Select "Import Project"
4. Navigate your file system and find the folder where you cloned the repository. Do not select it. Open the folder, and you should find a lowercase alchemist folder. That is the correct project folder, not the outermost Alchemist folder (created by git in case you cloned without specifying a different folder name). Once the correct folder has been selected, click Ok
5. Select "Import Project from external model"
6. Make sure "Gradle" is selected as external model tool
7. Click Finish
8. If prompted to override any .idea file, try to answer No. It's possible that IntelliJ refuses to proceed, in which case click Finish again, then select Yes.
9. A dialog stating that "IntelliJ IDEA found a Gradle build script" may appear, in such case answer Import Gradle Project.
10. Wait for the IDE to import the project from Gradle. The process may take several minutes, due to the amount of dependencies. Should the synchronization fail, make sure that the IDE's Gradle is configured correctly:
11. 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.
12. 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).
13. 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.