This project is a quick start for the Alchemist simulator, it shows how to use the simulator via Gradle to run a simple simulation. More information can be found on the official Alchemist website.

Alchemist's prerequisites can be found here.

To run the example you can rely on the pre-configured Gradle build script. It will automatically download all the required libraries, set up the environment, and execute the simulator via command line for you. As first step, use git to locally clone this repository. In order to launch, open a terminal and move to the project root folder, then on UNIX:

./gradlew runAlchemist

On Windows:

gradlew.bat runAlchemist

Press P and you will see some pedestrians wandering around. For further information about the gui, see the graphical interface shortcuts.

Note that the first launch will be rather slow, since Gradle will download all the required files. They will get cached in the user's home folder (as per Gradle normal behavior).

Let's explain how things work by looking at the build.gradle script. First of all, we need to add Alchemist as a dependency, thus you will see something like this:

dependencies {
    implementation("it.unibo.alchemist:alchemist:SOME_ALCHEMIST_VERSION")
}

With SOME_ALCHEMIST_VERSION replaced by the version used, nothing special actually.

Now, let's look at the runAlchemist task, it is a simple gradle task responsible for launching the simulation. Let's dissect it:

tasks.register<JavaExec>("runAlchemist") {
    classpath = project.sourceSets.getByName("main").runtimeClasspath
    main = "it.unibo.alchemist.Alchemist"
    args = listOf("-y", "src/main/yaml/$simulation.yml")
}

Gradle has a special task to run a Java class from the build script: JavaExec. We can create our custom task of type JavaExec, name it runAlchemist and configure it to launch our simulation. In order to make it work, we need to explicit two things:

• the Alchemist main class, which is it.unibo.alchemist.Alchemist
• the classpath, or java won't be able to find all the classes needed

This is what we do with the first three lines of code, and it is sufficient to successfully start Alchemist. Now, to make it run our simulation we can rely on the command line interface, to run a simulation we can use the -y option followed by the path to the simulation file. Alchemist simulations are contained in *.yml files, more information about how to write such simulations can be found here. Let's suppose the $simulation variable contains the name of our simulation file, which is located in the src/main/yaml/ folder, what we want to do is to run Alchemist with the following arguments:

-y src/main/yaml/$simulation.yml

The last line of code specify these arguments.

Ok, that's it. You should be able to use Alchemist via Gradle in your own project now, or at least have a clue.

The CLI supports the following options