Skip to content
ahrenberg edited this page Feb 10, 2012 · 4 revisions

Usage and Examples

Switches and options

This page contain some basic examples. To list all possible program options run:

split_nlogo_experiment --help

Basic usage

To split an experiment called 'experiment' in the file model.nlogo run:

split_nlogo_experiment model.nlogo experiment

This will produce a set of files called experiment<XYZ>.xml where <XYZ> is a zero-padded number. Each XML file represents a unique variable value combination as an experiment. These files can be used with the netlogo switch --setup-file, e.g:

netlogo-headless.sh --model model.nlogo --setup-file experiment0.xml

Note that you will probably want to add some additional netlogo switches and options to this command, for instance --table for output. In addition, netlogo is picky with its paths, so you will probably also want to use the full paths of model.nlogo and experiment0.xml .

The generated XML files are always given the name of the experiment plus a sequence number. If you want to prefix the file name for some reason you can use the --output_prefix option when calling split_nlogo_experiment. If you want the XML files output in some other directory than the current use the --output_dir option. For instance:

split_nlogo_experiment --output_dir /tmp --output_prefix my_ model.nlogo experiment

will cause the XML files to be saved in the directory /tmp and be named my_experiment<XYZ>.xml where <XYZ> is, as before, a number from 0 up to N-1. N being the number of possible variable value combinations.

Note that all the output directory must exist and be writable. If not an error is produced and the program exits.

How many XML files are generated?

Short answer: as many as you have unique combinations of variable values in your BehaviorSpace. You can easily compute it by taking the number of runs that Netlogo reports for your experiment and divide this by the number of repetitions you have entered. (Repetitions are not split by the script.)

For example if you have two variables a, and b, and you have configured your BehaviorSpace so that [a 1 2 3] and [b 4 5], That is, there are three possible values for a (1, 2, or 3), and two for b (4 or 5). There are six combinations of individual values for a, and b. (a=1, b=4) (a=1, b=5), (a=2, b=4), et c. split_nlogo_experiment will construct one XML file for each of these combinations and number than from 0 to 5.

Start script templating functionality

Computing clusters usually have a queuing mechanism where some command script is run in order to commit a job. If the BehaviorSpace experiment result in a large number of simulations this can be a very tedious process if one needs an individual script for each simulation.

split_nlogo_experiment has a very basic templating mechanism that may be used to produce an additional file with each simulation XML file. The option --create_script takes a file name as parameter. This file is read and a specialized version having key names replaced with current values are saved for each XML file. Allowed keys are

{job}
Name of the job. Will be the name of the xml-file (minus extension).
{combination}
The value of the parameter combination_nr.
{experiment}
The value of the parameter experiment.
{csv}
File name, including full path, of a experiment-unique csv-file.
{setup}
The value of the parameter csvfile.
{model}
The value of the parameter nlogofile.
{csvfname}
Only the file name part of the {csv} key.
{csvfpath}
Only the path part of the {csv} key.

As an example consider constructing a PBS script for each experiment. This script will issue special PBS commands creating log files, setting the job name, and finally run netlogo-headless with the right commands. To do this create a template file looking like:

#!/bin/bash
#PBS -N {job}
#PBS -o /tmp/{job}.log
#PBS -e /tmp/{job}_error.log
netlogo-headless.sh --model {model} --setup-file {setup} --table {csv}

Assume this file is called template.pbs, then calling the split_nlogo_experiment as:

split_nlogo_experiment --create_script template.pbs model.nlogo experiment

will, in addition to creating the experiment<XYZ>.xml files also create files called experiment_script<XYZ>.pbs (file ending will always be the same as for the template file). In these files the keys {job} will be replaced by experiment<XYZ>, {model} by the absolute path name to model.nlogo, {setup} by the absolute path name to experiment<XYZ>.xml, and {csv} by the absolute path name to the suggested CSV output file name.