HeadlessLegacy

Headless Legacy

Overview

Headless Legacy mode uses XML experiment plan files to run multiple simulations. This is an older mode but still useful for simple scripted runs and legacy workflows.

For batch experiments defined directly in your .gaml model, use Headless Batch. For interactive remote control, use Headless Server.

---

Quick Start

Generate an XML experiment plan from a model:

gama-headless.sh -xml experimentName /path/to/model.gaml plan.xml

Then run it:

gama-headless.sh plan.xml /path/to/results/

Simple One-Shot Run

For a single experiment without XML:

gama-headless.sh -gaml -steps 1000 experimentName /path/to/model.gaml /path/to/results/

---

XML Experiment Plan

Structure

<?xml version="1.0" encoding="UTF-8"?>
<Experiment_plan>
    <Simulation experiment="expName" finalStep="1000" id="0" seed="42">
        <source_path>/path/to/model.gaml</source_path>
        <Parameters>
            <Parameter name="Parameter Display Name" type="INT" value="10"/>
        </Parameters>
        <Outputs>
            <Output name="Monitor Name" framerate="1"/>
        </Outputs>
    </Simulation>
</Experiment_plan>

Multiple <Simulation> blocks can be added to run experiments in parallel (limited by the -hpc flag).

Element Reference

<Simulation>

Attribute	Required	Description
experiment	Yes	Name of the experiment in the GAML model
finalStep	Yes	Number of steps to run
id	Yes	ID to prefix output files
seed	No	Random seed value
source_path	Yes	Path to the .gaml model file
until	No	GAML stop condition (combinable with finalStep)

<Parameter>

Attribute	Required	Description
name	Yes (if var not set)	Display name as written in the GAML parameter statement
var	Yes (if name not set)	Variable name in the GAML model
type	Yes	Data type: INT, FLOAT, BOOLEAN, STRING
value	Yes	Value to assign

Note: Set either name or var, not both.

<Output>

Attribute	Required	Description
name	Yes	Name of a monitor, display, or global variable
framerate	Yes	Log frequency in steps
id	No	Prefix for output files (if multiple outputs share a name)

Note: Lower framerate values → more data but longer execution time.

---

Output Structure

Results are saved to the output directory:

results/
├── console-outputs-0.txt        # Console output
├── simulation-output0.xml       # Variable values over time
└── snapshot/                    # Display screenshots
    └── displayName-0-N.png      # Screen capture at step N

simulation-output0.xml

<?xml version="1.0" encoding="UTF-8"?>
<Simulation id="0">
    <Step id='0'>
        <Variable name='number_of_agents' value='50'/>
        <Variable name='main_display' value='main_display0-0.png'/>
        <Variable name='duration' value='4'/>
    </Step>
</Simulation>

Displays save screenshots as .png files; their path is stored in the XML.

---

Calling from Scripts

Python

import os
os.system(f"gama-headless.sh -xml exp /path/to/model.gaml plan.xml")
os.system(f"gama-headless.sh plan.xml /path/to/results/")

JavaScript/Node.js

const { exec } = require('child_process');
exec('gama-headless.sh -xml exp /path/to/model.gaml plan.xml', (err) => {
    exec('gama-headless.sh plan.xml /path/to/results/', (err) => {});
});

---

Common Errors

Error	Cause	Solution
No parameter named X in experiment Y	Typo in parameter name or variable name	Check spaces, capitalization, and exact wording
Model file does not exist	Incorrect model path	Use absolute paths, or verify relative paths from XML location
NumberFormatException	Type mismatch in XML	Ensure type matches value (INT vs FLOAT)
NoClassDefFoundError / resourcesResourcesPlugin	No write permission	Run from a writable directory (not Program Files on Windows)