Headless Legacy

Introduction

This headless mode is the Legacy one. So, if you are already familiar with headless from version 1.8.1 or older, nothing changed. This mode is able to run one or a finite set of simulations. Those simulations, mostly for legacy reason, have to be of type gui, and does not work with batch experiments.

Easy mode

If you just want to run one experiment of a file, with default parameters and stop it at a given step, there is a simplified way of doing so that doesn't require you to write intermediate files. To use it you will need to use the gama-headless script (see the running headless page) with the parameter -gaml followed in that order by the experiment name, the path to the experiment file and the path to an output folder where the snapshots of the displays and the console outputs will be saved. _Optionally _you can use the parameter -steps followed by a number to indicate the number of steps you want to execute, if this parameter is omitted the default value will be 1000 steps. It is required that the -steps parameter and its value are placed before the experiment name.

So for example, to run 243 steps of the experiment exp in the model file /home/user/my_model.gaml and to store its outputs in /home/user/my_results/, you could use this command line:

gama-headless.sh -gaml -steps 243 exp /home/user/my_model.gaml /home/user/my_results/

Advanced mode

If you need more control over the experiment to run, for example exploring different values for the parameters, then you will need to have an explicit simulation plan in an XML file, fortunately we have some commands ready to help.

You can generate a first XML file corresponding to an existing experiment with the following command:

./gama-headless.sh -xml experimentName /path/to/inputFile.gaml /path/to/outputFile.xml

• with:
  • -xml: the flag asking the headless to generate a XML file well-formatted for our experiment
  • experimentName: the name of the experiment you want to run in headless
  • /path/to/inputFile.gaml: the path (relative or absolute) to your GAML file containing the experiment you want to run
  • /path/to/outputFile.xml: the path (relative or absolute) to the generated XML file

You can see more in details the content of the generated XML file (applied on the model Predator Prey) in the Experiment Input File part to learn how to edit the XML so it fits your needs.

Once you finished preparing your XML file, you can run it with a command similar to the following one:

./gama-headless.sh /path/to/file.xml /path/to/generated/outputFolder

• with:
  • /path/to/file.xml: the path (relative or absolute) to the XML file containing the full exploration plan to run by the headless
  • /path/to/generated/outputFolder: the path (relative or absolute) which will be generated by GAMA and hold every output files (variables, snapshots, and console messages)

You can see result output folder in the Simulation Output part

Experiment Input File

The XML input file contains for example (you can find it next to the file gama-headless.sh at the path samples/predatorPrey.xml:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Experiment_plan>
	<Simulation experiment="prey_predatorExp" finalStep="1000" id="0" seed="1.0" sourcePath="./samples/predatorPrey/predatorPrey.gaml">
		<Parameters>
			<Parameter name="Nb Preys: " type="INT" value="200" var="nb_preys_init"/>
			<Parameter name="Prey max energy: " type="FLOAT" value="1.0" var="prey_max_energy"/>
			<Parameter name="Prey max transfert: " type="FLOAT" value="0.1" var="prey_max_transfert"/>
			<Parameter name="Prey energy consumption: " type="FLOAT" value="0.05" var="prey_energy_consum"/>
			<Parameter name="Nb predators: " type="INT" value="20" var="nb_predators_init"/>
			<Parameter name="Predator max energy: " type="FLOAT" value="1.0" var="predator_max_energy"/>
			<Parameter name="Predator energy transfert: " type="FLOAT" value="0.5" var="predator_energy_transfert"/>
			<Parameter name="Predator energy consumption: " type="FLOAT" value="0.02" var="predator_energy_consum"/>
		</Parameters>
		<Outputs>
			<Output framerate="1" id="0" name="Number of preys"/>
			<Output framerate="1" id="1" name="Number of predators"/>
			<Output framerate="1" id="2" name="main_display"/>
		</Outputs>
	</Simulation>
</Experiment_plan>

NB: Several simulations can be determined in one experiment plan. These simulations are run in parallel according to the number of allocated cores.

Simulation

<Simulation experiment="prey_predatorExp" finalStep="1000" id="0" seed="1.0" sourcePath="./samples/predatorPrey/predatorPrey.gaml">

• with:
  • experiment (required): determines which experiment should be run on the model. This experiment should exist, otherwise, the headless mode will exit.
  • finalStep (required): determines the number of simulation steps you want to run.
  • id (required): permits to prefix output files for experiment plans with huge simulations.
  • seed (optional): permits to set the seed value of the simulation.
  • sourcePath (required): contains the relative or absolute path to read the gaml model.
  • until (optional): defines a stop condition in GAML. It can be combined with the finalStep facet (in this case a simulation will finish when the stop condition is fulfilled or when the final step is reached).

Parameters

One line per parameter you want to specify a value to:

<Parameter name="Nb Preys: " type="INT" value="200" var="nb_preys_init"/>

• with:
  • name: name of the parameter in the gaml model
  • type (required): type of the parameter (INT, FLOAT, BOOLEAN, STRING)
  • value (required): the chosen value
  • var: name of the parameter variable in the gaml model

NB: You need to set at least one of the attributes name or var in your Parameter tag)

Outputs

One line per output value you want to retrieve. Outputs can be the name of monitors or displays defined in the 'output' section of experiments, or the names of attributes defined in the experiment or the model itself (in the 'global' section).

    ... with the name of a monitor defined in the 'output' section of the experiment...
    <Output framerate="1" id="1" name="Number of predators"/>
    ... with the name of a (built-in) variable defined in the experiment itself...
    <Output framerate="1" id="2" name="main_display"/>

• with:
  • framerate (required): the frequency of the monitoring (each step, every 2 steps, every 100 steps...).
  • id (optional): permits to prefix output files for simulation with huge outputs
  • name (required): name of the output in the 'output'/'permanent' section in the experiment or name of the experiment/model attribute to retrieve
  • output_path (optional): change the output directory where snapshot images are saved (for display output only!)

NB: the lower the framerate value is, the longer the experiment.

NB2: if the chosen output is a display, an image is produced and the output file contains the path to access this image

Output Directory

During headless experiments, a directory is created with the following structure:

Outputed-directory-path/
out
├── console-outputs-0.txt
├── simulation-outputs0.xml
└── snapshot
    ├── main_display0-0.png
    ├── main_display0-1.png
    ├── main_display0-2.png
    ├── main_display0-3.png
    ├── main_display0-4.png
    └── ...

• with:
  • console-outputs-<simulationId>.xml: containing every message written in GAMA's console
  • simulation-outputs<simulationId>.xml: containing variables' results in a XML format
  • snapshot: containing the snapshots (i.e. screenshots of gui displays) produced during the simulation

Simulation Output

A file named simulation-output.xml is created with the following contents when the experiment runs.

<?xml version="1.0" encoding="UTF-8"?>
<Simulation id="0" >
	<Step id='0' >
		<Variable name='main_display' value='main_display2-0.png'/>
		<Variable name='number_of_preys' value='613'/>
		<Variable name='number_of_predators' value='51'/>
                <Variable name='duration' value='6' />
	</Step>
	<Step id='1' >
		<Variable name='main_display' value='main_display2-0.png'/>
		<Variable name='number_of_preys' value='624'/>
		<Variable name='number_of_predators' value='51'/>
                <Variable name='duration' value='5' />
	</Step>
        <Step id='2'>

...

• With:
  • <Simulation id="0" >: tag containing results of the simulation. The id is set one set in the input file, in the heading part
  • <Step id='0' >: one block per step done containing the value of outputs variables. The id corresponds to the step number
    • <Variable /> with:
      • name: name of the output
      • value: the current value of the model variable at the given step.

NB: The value of an output is repeated according to the framerate defined in the input experiment file.

NB2: The value of an output display gives the relative path to the generated image saved in '.png' format.

Calling GAMA headless legacy on Windows

The example below assumes that your GAMA application is in folder D:\software\gama and your project (model) file is in folder D:\my_models\ The data structure of the example model as in following. The example models can be found in the GAMA headless folder (D:\software\gama\headless\samples\predatorPrey)

predatorPrey
├── includes
└── models
    ├── ...
    └── predatorPrey.gaml

In the predatorPrey model, we have a GUI experiment named prey_predator

Windows PowerShell

• You can open Windows PowerShell, change your directory to the headless folder and run gama-headless command:

cd D:\software\GAMA_1.9.2_Windows_with_JDK\headless\
.\gama-headless.bat -xml prey_predator D:\my_models\predatorPrey\models\predatorPrey.gaml D:\my_models\predatorPrey\models\predatorPrey.xml
.\gama-headless.bat D:\my_models\predatorPrey\models\predatorPrey.xml D:\my_models\predatorPrey\results

Command Prompt

• You can open Command Prompt, change your directory to the headless folder D:\software\gama\headless\ then run the commands:

gama-headless.bat -xml prey_predator D:\my_models\predatorPrey\models\predatorPrey.gaml D:\my_models\predatorPrey\models\predatorPrey.xml
gama-headless.bat D:\my_models\predatorPrey\models\predatorPrey.xml D:\my_models\predatorPrey\results

Python Script

• Your python script will have the following lines of code, mainly using the os package to run the native system commands

import os
os.chdir("D:\software\gama\headless")
os.system("gama-headless.bat -xml prey_predator D:\my_models\predatorPrey\models\predatorPrey.gaml D:\my_models\predatorPrey\models\predatorPrey.xml")
os.system("gama-headless.bat D:\my_models\predatorPrey\models\predatorPrey.xml D:\my_models\predatorPrey\results")