NetLogo

Guidance last updated: 20 October 2026

NetLogo is a multi-agent programmable modelling environment. It is used by many hundreds of thousands of students, teachers, and researchers worldwide. It also powers HubNet participatory simulations. It is authored by Uri Wilensky and developed at the CCL. You can also try it online through NetLogo Web.

Usage

Warning

NetLogo on Stanage is intended for headless (non-graphical) use, principally for running BehaviorSpace experiments (parameter sweeps) as batch jobs. A typical workflow is to build and test your model and its BehaviorSpace experiment on your own computer using the desktop application, then copy the model to Stanage and run the experiment at scale. Graphical usage is not supported on Stanage, so you will not be able to run netlogo-gui.sh or NetLogo. Use netlogo-headless.sh as described below.

After connecting to Stanage (see Establishing a SSH connection), start an interactive session:

salloc

You can load a specific version with the following commands:

module load NetLogo/7.0.4-64

After this any of the NetLogo commands can be run from the terminal prompt. The available commands are below:

$ # Run the headless (no GUI command) for batch jobs with appropriate arguments substituting for $ARGS.
$ netlogo-headless.sh $ARGS

Command line options for netlogo-headless.sh:

--model <path>: pathname of the model to open (required).
--experiment <name>: name of the BehaviorSpace experiment to run.
--setup-file <path>: read experiment setups from this XML file instead of from the model file. If you do not give --experiment you must give --setup-file.
--table <path>: write table output to this file (or - for standard output).
--spreadsheet <path>: write spreadsheet output to this file (or - for standard output).
--lists <path>: write lists output to this file (or - for standard output). Requires --table or --spreadsheet.
--stats <path>: write statistics output (mean and standard deviation across repetitions) to this file (or - for standard output). Requires --table or --spreadsheet.
--threads <number>: number of model runs to perform in parallel, or 1 to disable parallel runs. Defaults to 75% of the processors on the node, so always set this on Stanage.
--update-plots: enable plot and monitor updates. Only needed if your experiment exports plot data; leave it off for better performance.
--min-pxcor, --max-pxcor, --min-pycor, --max-pycor <number>: override the world size saved in the model. If you set any of these you must set all four.
--3D: run a NetLogo 3D model (also accepts --min-pzcor and --max-pzcor).

If you give neither --table nor --spreadsheet then no BehaviorSpace results are written, which is only useful if your model writes its own output files.

Note

Which output format? Table output is written to disk as each run completes, so you keep partial results if a job fails or hits its time limit. Spreadsheet, lists and stats output are held in memory and only written when the whole experiment finishes, so large experiments can run out of memory and a failed or timed-out job will produce no spreadsheet output at all. For long experiments, always request --table output, even if you also want the other formats.

Parallelism

NetLogo runs each model run on a single core by default. BehaviorSpace provides parallelism by performing several model runs at the same time, one per thread, so multiple cores only help if your experiment has multiple runs (several parameter combinations and/or repetitions). Request one Slurm task with several CPUs and pass the number of CPUs to --threads:

#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
...
netlogo-headless.sh ... --threads $SLURM_CPUS_PER_TASK

Memory

By default the launcher lets Java use up to 50% of the memory it detects. Each parallel run has its own copy of the model world, so memory use grows with --threads. Set an explicit maximum heap size below the job’s total Slurm memory request using JAVA_TOOL_OPTIONS. For example, four CPUs with --mem-per-cpu=2000 provide 8000 MB in total:

$ export JAVA_TOOL_OPTIONS="-Xmx7g"

(Only Java -D properties can be passed through netlogo-headless.sh itself, which is why the environment variable is used.) If your job fails with java.lang.OutOfMemoryError, increase both the Slurm memory request and -Xmx, or reduce --threads.

Interactive usage

To use NetLogo interactively you must use the netlogo-headless.sh start script. To do so, run the following commands :

$ module load NetLogo/7.0.4-64
$ netlogo-headless.sh \
    --model my_model.nlogox \
    --experiment "my experiment" \
    --threads 1 \
    --table -

Using --table - prints the results to the terminal, which is a quick way to check that the experiment produces the output you expect.

Batch usage

The following example batch submission script, batch_smp_4_core.sh, follows the BehaviorSpace command-line guidance:

This uses the installed Wolf Sheep Simple 5 model to run 110 simulations (11 initial wolf populations, each repeated 10 times), with up to four runs in parallel. The example requests 8000 MB of memory and limits the Java heap to 7 GB (7168 MB).

batch_smp_4_core.sh:

#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --mem-per-cpu=2000
#SBATCH --job-name=NetLogo_BehaviorSpace_smp_4
#SBATCH --output=%x-%j.out
#SBATCH --time=00:10:00
#SBATCH --mail-user=MyEmail@sheffield.ac.uk
#SBATCH --mail-type=ALL
module load NetLogo/7.0.4-64

# Keep the Java heap below the total Slurm memory request
export JAVA_TOOL_OPTIONS="-Xmx7g"

netlogo-headless.sh \
--model "$EBROOTNETLOGO/models/IABM Textbook/chapter 4/Wolf Sheep Simple 5.nlogox" \
--experiment "Wolf Sheep Simple model analysis" \
--table table_output.csv \
--spreadsheet spreadsheet_output.csv\
--stats stats_output.csv \
--threads $SLURM_CPUS_PER_TASK

The job is submitted to the queue by typing:

$ sbatch batch_smp_4_core.sh

When the job finishes, the current working directory will contain the Slurm log file (NetLogo_BehaviorSpace_smp_4-<jobid>.out) along with table_output.csv, spreadsheet_output.csv and stats_output.csv.

Large parameter sweeps with job arrays

For experiments with hundreds or thousands of runs, it is usually more efficient to split the experiment into many independent experiment files and run them as a Slurm job array, rather than requesting a single large job. Each array task then runs one part of the experiment, and the scheduler can start tasks as resources become free.

The NetLogo developers provide a script (split_bspace_exps.py) that splits an exported experiment into one XML file per parameter combination, named exp0.xml, exp1.xml, and so on, each containing an experiment with the same name as the file. See the NetLogo Cluster Computing (HPC) guide for the script and further details.

The following example batch submission script runs 24 such experiment files from an experiments directory, one per array task:

#!/bin/bash
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --mem-per-cpu=2000
#SBATCH --time=01:00:00
#SBATCH --job-name=NetLogo_array
#SBATCH --output=logs/%x-%A_%a.out
#SBATCH --array=0-23

module load NetLogo/7.0.4-64
export JAVA_TOOL_OPTIONS="-Xmx1500m"

mkdir -p results
EXP="exp${SLURM_ARRAY_TASK_ID}"

netlogo-headless.sh \
    --model my_model.nlogox \
    --setup-file "experiments/${EXP}.xml" \
    --experiment "${EXP}" \
    --threads $SLURM_CPUS_PER_TASK \
    --table "results/${EXP}.csv"

Create the logs directory before submitting (mkdir -p logs), and adjust --array to match the number of experiment files. If each experiment file still contains several repetitions, you can increase --cpus-per-task so that those repetitions run in parallel within each array task.

Installation notes

NetLogo was installed using Easybuild, build details can be found in $EBROOTNETLOGO/easybuild with a given module loaded.