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
• Creating batches and run with different value of parameters
• Run in grid computing environments

Users

Alchemist users should rely on the documentation available on the official Alchemist website. Alchemist is available on Maven Central. You can import all the components by importing the it.unibo.alchemist:alchemist artifact.

Gradle

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 {
    implementation("it.unibo.alchemist:alchemist: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.

<dependency>
    <groupId>it.unibo.alchemist</groupId>
    <artifactId>alchemist</artifactId>
    <version>ALCHEMIST_VERSION</version>
</dependency>

Developers

Status Badges

Stable branch

Development branch

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. Clone this repository in a folder of your preference using git clone appropriately
1. Open IntellJ. If a project opens automatically, select "Close project". You should be on the welcome screen of IntelliJ idea, with an aspect similar to this image:
2. Select "Import Project"
3. 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
4. Select "Import Project from external model"
5. Make sure "Gradle" is selected as external model tool
6. click Next
7. Check "Use auto-import"
8. Check "Create directories for empty content roots automatically"
9. The correct group module option is "using explicit module groups", make sure it is selected
10. Check "Create separate module per source set"
11. Important: ensure that "Use default gradle wrapper (recommended) is selected
12. Click Finish
13. If prompted to override any .idea file, try to answer No. It's possible that IntelliJ refuses to proceed and comes back to the previous window, in which case click Finish again, then select Yes.
14. 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. In 'Settings -> Build, Execution, Deployment -> Build Tools > Gradle', select 'Use default gradle wrapper (recommended)'.
15. 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 Eclipse 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

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.