Preliminary remarks 🔗

GAMA is a modelling and simulation development environment for building spatially explicit agent-based simulations. OpenMOLE supports GAMA model natively through the GAMATask.
The GAMATask uses the Singularity container system. You should install Singularity on your system otherwise you won't be able to use it.

The GAMATask supports files and directories, in and out. Get some help on how to handle it by reading this page.

The GAMATask 🔗

GAMA by example 🔗

You can provide your .gaml file to the GAMATask to run your model and explore it with OpenMOLE. The example below illustrates an exploration of the predator-prey model of the GAMA model library using a direct sampling:

// Declare the variables
val numberOfPreys = Val[Double]
val nbPreysInit = Val[Int]
val mySeed = Val[Long]

// Gama task
// The first argument is the project directory
// The second argument is the relative path of the gaml file in the project directory
// The second argument is the Gama experiment name
// The third argument is the number of steps
val gama =
  GAMATask(project = workDirectory / "predator", gaml = "predatorPrey.gaml", experiment = "prey_predatorExp", finalStep = 100, seed = mySeed) set (
    inputs += (nbPreysInit mapped "nb_preys_init"),
    outputs += (numberOfPreys mapped "Number of preys")
  )

// Explore and replicate the model
DirectSampling(
  evaluation =
    Replication(
      evaluation = gama,
      seed = mySeed,
      sample = 10,
      aggregation = Seq(numberOfPreys evaluate average)) hook(workDirectory / "result"),
  sampling = nbPreysInit in (0 to 200 by 50)
) hook display

Task arguments 🔗

The GAMA task uses the following arguments:

• project the location of your GAMA project directory, mandatory, for instance project = workDirectory / "gamaproject"
• gaml the relative path of your .gaml file in your work directory, mandatory, for instance gaml = "model/model.gaml"
• experiment the name of your experiment as implemented in the .gaml file, mandatory
• finalStep the last simulation step of you simulation, mandatory
• frameRate the frame rate to sample you simulation dynamics, in this case the outputs should be arrays, optional
• seed the OpenMOLE variable used to set the GAMA random number generator seed, optional the seed is randomly drawn if not set
• containerImage the label of a container image or a container file containing GAMA headless, optional, the default value is "gamaplatform/gama:1.9.0"
• memory the memory allocated to the gama headless, optional, for example memory = 3000 megabytes
• install some command to run on the host system to initialise the container, for instance Seq("apt update", "apt install mylib"), optional

Reproduce an error using GAMA headless 🔗

The integration of GAMA into OpenMOLE is achieved through a container. OpenMOLE downloads the container for the version you're interested in and use it to run your simulation. Sometimes, issues can arise in the communication between these two tools. To get a clearer understanding, it's important to determine which of the two is causing the problem. Here, using the predator-prey model as a basis, we suggest testing your model within the virtual machine that will be used by OpenMole. This allows you to perform diagnostics in case of a failure. OpenMOLE communicates with Gama through XML injection. Therefore, to run GAMA in headless mode, you need to:

• generate an XML file,
• launch the simulation from this XML file.

Using a existing GAMA installation 🔗

You can run:

./gama-headless.sh -xml <experiment_name> input.gaml output.xml
./gama-headless.sh output.xml .

Once the headless has run, you should find a file named simulation-outputsXX.xml. Check that it exists, is well formed and contains the simulation results. Otherwise you can report the bug to the GAMA developers on Github.

Using Docker 🔗

To reproduce a behaviour close from what OpenMOLE executes you can run the GAMA docker image. You should have docker installed on your computer.
Download the Gama Docker image. All available containers can be found on the docker hub. Here, we will use the alpha version.

export GAMA_VERSION="alpha" # Replace by the version you want to test
docker pull gamaplatform/gama:$GAMA_VERSION

To get an interactive shell into the GAMA docker:

docker run -it -v "/tmp/gama model/":/work --entrypoint  /bin/bash gamaplatform/gama:$GAMA_VERSION

-it stands for interactive terminal. -v "/tmp/gama model/":/work mounts is a volume between your host system and the container. /tmp/gama model/ is a folder on your computer. /work is the folder inside the container. This mount allows the container to access the model files.
Once inside the Docker container, you're in the /opt/gama-platform/headless directory, and the model is in the folder /work. You can then run GAMA commands to generate XML files.

./gama-headless.sh -xml prey_predatorExp /work/predatorPrey.gaml /work/predatorPrey.xml

This command generates an XML file at the location you specify (it's the last part of the command line). Once the XML is created, it's the one that will be used by OpenMOLE to inject the values from the exploration plan you defined. You can launch the experiment from the XML like this :

./gama-headless.sh /work/predatorPrey.xml .

Once the headless has run, you should find a file named simulation-outputsXX.xml. Check that it exists, is well formed and contains the simulation results. Otherwise you can report the bug to the GAMA developers on Github.