HeadlessLegacy - gama-platform/gama GitHub Wiki

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)
⚠️ **GitHub.com Fallback** ⚠️