Skip to content

RunningHeadless

RoiArthurB edited this page Sep 11, 2023 · 8 revisions

Running Headless

What is GAMA Headless

The headless mode gives the possibility run one or multiple instances of GAMA without any user interface so that models and experiments can be launched on a grid or a cluster. Without GUI, the memory footprint, as well as the speed of the simulations, are usually greatly improved.

In this mode, GAMA can only be used to run experiments. Editing or managing models is not possible. In order to launch experiments and still benefit from a user interface (which can be used to prepare headless experiments), launch GAMA normally (see here) and refer to this page for instructions.

Different headless modes

  1. The first and oldest way, called Legacy mode and detailed here, consists in explicitly writing your full experiment plan (i.e each simulation you want to run, with each parameter sets) in an XML file. This way of using the Headless was the first implementation of the headless inside GAMA.
  2. The second way, called Headless Batch and detailed on this page, allows launching a GAML batch experiment in headless mode (i.e. without having to open GAMA's interface). This way is the most natural way to use the headless as it works exactly like in GUI Batch mode.
  3. The last way, called Headless Server and described there, let you open an interactive GAMA headless server on which you can dynamically send experiments to run. This last mode is interesting for using GAMA as back-end of other project like web projects.

General knowledge about using GAMA Headless

There are two ways to run a GAMA experiment in headless mode: using a dedicated bash wrapper (recommended) or directly from the command line.

Bash Wrapper (recommended)

The wrapper file can be found in the headless directory located inside Gama's installed folder. It is named gama-headless.sh on macOS and Linux, or gama-headless.bat on Windows.

You can start using it like so :

./gama-headless.sh [m/c/hpc/v] [launchingMode]

with:

  • general headless options [-m/c/hpc/v]:
    • -m memory : memory allocated to gama (e.g. -m 8g to set it at 8GiB)
    • -c : console mode, the simulation description could be written with the stdin
    • -hpc nb_of_cores : limit to a specific number of cores the number of simulation running in parallel (eg. -hpc 3 to limit GAMA at using 3 cores/running 3 simulation at a time)
    • -v : verbose mode. trace are displayed in the console
  • launchingMode will depend on which headless mode you'll use and explained in following pages

You also can display general help on every options with this command:

./gama-headless.sh -help

Which, for release 1.9.2, will output:

******************************************************************
* GAMA version 1.9.2                                             *
* http://gama-platform.org                                       *
* (c) 2007-2023 UMI 209 UMMISCO IRD/SU & Partners                *
******************************************************************
Welcome to Gama-platform.org version GAMA 1.9.2

sh ./gama-headless.sh [Options]

List of available options:
	=== Headless Options ===
		-m [mem]                     -- allocate memory (ex 2048m)
		-c                           -- start the console to write xml parameter file
		-v                           -- verbose mode
		-hpc [core]                  -- set the number of core available for experimentation
		-socket [socketPort]         -- start socket pipeline to interact with another framework
		-p                           -- start pipeline to interact with another framework
	=== Infos ===
		-help                        -- get the help of the command line
		-version                     -- get the the version of gama
	=== Library Runner ===
		-validate                    -- invokes GAMA to validate models present in built-in library and plugins
		-test                        -- invokes GAMA to execute the tests present in built-in library and plugins and display their results
	=== GAMA Headless Runner ===
		-batch [experimentName] [modelFile.gaml]
		                             -- Run batch experiment in headless mode
		-xml [experimentName] [modelFile.gaml] [xmlOutputFile.xml]
		                             -- build an xml parameter file from a model
		[xmlHeadlessFile.xml] [outputDirectory]
		                             -- default usage of GAMA headless

Java Command (hard)

As GAMA is developed in Java, you can start the Headless mode by load appropriate bundle and starting it like this:

java -cp $GAMA_CLASSPATH -Xms512m -Xmx2048m -Djava.awt.headless=true org.eclipse.core.launcher.Main -application msi.gama.headless.id4 [options]

with:

  • $GAMA_CLASSPATH: contains the relative or absolute path of jars inside the GAMA plugin directory and jars created by users
  • options as explained above and in following pages

Note that we recommend you to open bash wrapper to have more detailed about how we imagine starting GAMA in headless mode.

  1. What's new (Changelog)
  1. Installation and Launching
    1. Installation
    2. Launching GAMA
    3. Updating GAMA
    4. Installing Plugins
  2. Workspace, Projects and Models
    1. Navigating in the Workspace
    2. Changing Workspace
    3. Importing Models
  3. Editing Models
    1. GAML Editor (Generalities)
    2. GAML Editor Tools
    3. Validation of Models
  4. Running Experiments
    1. Launching Experiments
    2. Experiments User interface
    3. Controls of experiments
    4. Parameters view
    5. Inspectors and monitors
    6. Displays
    7. Batch Specific UI
    8. Errors View
  5. Running Headless
    1. Headless Batch
    2. Headless Server
    3. Headless Legacy
  6. Preferences
  7. Troubleshooting
  1. Introduction
    1. Start with GAML
    2. Organization of a Model
    3. Basic programming concepts in GAML
  2. Manipulate basic Species
  3. Global Species
    1. Regular Species
    2. Defining Actions and Behaviors
    3. Interaction between Agents
    4. Attaching Skills
    5. Inheritance
  4. Defining Advanced Species
    1. Grid Species
    2. Graph Species
    3. Mirror Species
    4. Multi-Level Architecture
  5. Defining GUI Experiment
    1. Defining Parameters
    2. Defining Displays Generalities
    3. Defining 3D Displays
    4. Defining Charts
    5. Defining Monitors and Inspectors
    6. Defining Export files
    7. Defining User Interaction
  6. Exploring Models
    1. Run Several Simulations
    2. Batch Experiments
    3. Exploration Methods
  7. Optimizing Model Section
    1. Runtime Concepts
    2. Optimizing Models
  8. Multi-Paradigm Modeling
    1. Control Architecture
    2. Defining Differential Equations
  1. Manipulate OSM Data
  2. Diffusion
  3. Using Database
  4. Using FIPA ACL
  5. Using BDI with BEN
  6. Using Driving Skill
  7. Manipulate dates
  8. Manipulate lights
  9. Using comodel
  10. Save and restore Simulations
  11. Using network
  12. Headless mode
  13. Using Headless
  14. Writing Unit Tests
  15. Ensure model's reproducibility
  16. Going further with extensions
    1. Calling R
    2. Using Graphical Editor
    3. Using Git from GAMA
  1. Built-in Species
  2. Built-in Skills
  3. Built-in Architecture
  4. Statements
  5. Data Type
  6. File Type
  7. Expressions
    1. Literals
    2. Units and Constants
    3. Pseudo Variables
    4. Variables And Attributes
    5. Operators [A-A]
    6. Operators [B-C]
    7. Operators [D-H]
    8. Operators [I-M]
    9. Operators [N-R]
    10. Operators [S-Z]
  8. Exhaustive list of GAMA Keywords
  1. Installing the GIT version
  2. Developing Extensions
    1. Developing Plugins
    2. Developing Skills
    3. Developing Statements
    4. Developing Operators
    5. Developing Types
    6. Developing Species
    7. Developing Control Architectures
    8. Index of annotations
  3. Introduction to GAMA Java API
    1. Architecture of GAMA
    2. IScope
  4. Using GAMA flags
  5. Creating a release of GAMA
  6. Documentation generation

  1. Predator Prey
  2. Road Traffic
  3. 3D Tutorial
  4. Incremental Model
  5. Luneray's flu
  6. BDI Agents

  1. Team
  2. Projects using GAMA
  3. Scientific References
  4. Training Sessions

Resources

  1. Videos
  2. Conferences
  3. Code Examples
  4. Pedagogical materials
Clone this wiki locally