-
Notifications
You must be signed in to change notification settings - Fork 99
HeadlessLegacy
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 rely on writing explicit simulation plan in XML file. Those simulations, mostly for legacy reason, have to be of type gui
(which is pretty counterintuitive, but this type let you set parameter value to each simulation independently).
You can generate a first XML file with the following command :
bash ./gama-headless.sh -xml /path/to/inputFile.gaml /path/to/outputFile.xml
- with:
-
-xml
: the flag asking the headless to generate us a XML file well formatted for our experiment -
experimentName
: the name of theexperiment
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/inputFile.gaml
: the path (relative or absolute) to the generated XML file
-
Let's see more in detailed one of the samples already included in GAMA and generated to run the model Predator Prey :
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>
Note that several simulations could be determined in one experiment plan. These simulations are run in parallel according to the number of allocated cores.
<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 step you want to run. -
id
(required): permits to prefix output files for experiment plan 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 thefinalStep
facet (in this case a simulation will finish when the stop condition is fulfilled or when the final step is reached).
-
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 parameter variable in the gaml model
-
NB: You need to set at least one the attribute
name
orvar
in yourParameter
tag)
One line per output value you want to retrieve. Outputs can be names 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 id="2" name="number_of_preys" framerate="1" />
... with the name of a (built-in) variable defined in the experiment itself...
<Output id="4" name="duration" framerate="1" />
-
with:
-
name
: name of the output in the 'output'/'permanent' section in the experiment or name of the experiment/model attribute to retrieve -
framerate
: the frequency of the monitoring (each step, every 2 steps, every 100 steps...).
-
-
Note that:
- the lower the framerate value the longer the experiment.
- if the chosen output is a display, an image is produced and the output file contains the path to access this image
During headless experiments, a directory is created with the following structure:
Outputed-directory-path/
|-simulation-output.xml
|- snapshot
|- main_display2-0.png
|- main_display2-10.png
|- ...
- with:
-
simulation-output.xml
: containing the results -
snapshot
: containing the snapshots produced during the simulation
-
Is it possible to change the output directory for the images by adding the attribute "output_path" in the xml :
If we write <Output id="1" name="my_display" file:"/F:/path/imageName" framerate="10" />
, then the display "my_display" will have the name "imageName-stepNb.png" and will be written in the folder "/F:/path/"
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="2" >
<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="2" >
: block containing results of the simulation 2 (this Id is identified in the Input Experiment File) -
<Step id='1' > ... </Step>
: one block per step done. The id corresponds to the step number
-
<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='6' />
</Step>
There is one Variable block per Output identified in the output experiment file.
<Variable name='main_display' value='main_display2-0.png'/>
- with:
-
name
: name of the output, the model variable -
value
: the current value of the model variable.
-
Note that the value of an output is repeated according to the framerate defined in the input experiment file.
This directory contains images generated during the experiment. There is one image per displayed output per step (according to the framerate). File names follow a naming convention, e.g:
[outputName][SimulationID]_[stepID].png -> main_display2-20.png
Note that images are saved in '.png' format.
- Installation and Launching
- Workspace, Projects and Models
- Editing Models
- Running Experiments
- Running Headless
- Preferences
- Troubleshooting
- Introduction
- Manipulate basic Species
- Global Species
- Defining Advanced Species
- Defining GUI Experiment
- Exploring Models
- Optimizing Model Section
- Multi-Paradigm Modeling
- Manipulate OSM Data
- Diffusion
- Using Database
- Using FIPA ACL
- Using BDI with BEN
- Using Driving Skill
- Manipulate dates
- Manipulate lights
- Using comodel
- Save and restore Simulations
- Using network
- Headless mode
- Using Headless
- Writing Unit Tests
- Ensure model's reproducibility
- Going further with extensions
- Built-in Species
- Built-in Skills
- Built-in Architecture
- Statements
- Data Type
- File Type
- Expressions
- Exhaustive list of GAMA Keywords
- Installing the GIT version
- Developing Extensions
- Introduction to GAMA Java API
- Using GAMA flags
- Creating a release of GAMA
- Documentation generation