The BehaviorSpace extension allows you to create and run BehaviorSpace experiments from NetLogo code. You can use the extension alone or in combination with the GUI BehaviorSpace tool, and you can run experiments created in the GUI tool with the extension.
To use the BehaviorSpace extension in a model, include the following line at the top of your code:
extensions [bspace]
If you are already using another extension, you can just add bspace to the list inside the square brackets.
Once the extension is loaded, you can use it to run experiments from anywhere in the code. Note that experiments
created in the code will persist for the duration of the current NetLogo session if not cleared with the
bspace:clear-experiments command (see bspace:clear-experiments).
Experiments created in the code will have the following default values:
- Pre Experiment Commands: empty
- Setup Commands: empty
- Go Commands: empty
- Post Run Commands: empty
- Post Experiment Commands: empty
- Repetitions: 1
- Sequential Run Order: true
- Run Metrics Every Step: true
- Run Metrics Condition: empty
- Time Limit: 0
- Stop Condition: empty
- Metrics: empty
- Variables: empty
- Threads: determined by number of processor cores
- Recommended Max Threads: determined by number of processor cores
- Table: empty
- Spreadsheet: empty
- Stats: empty
- Lists: empty
- Mirror Headless Output: false
All properties can be set explicitly to alternate values. For code blocks, you can specify that no code should be executed by using an empty pair of square brackets.
bspace:create-experiment
bspace:delete-experiment
bspace:run-experiment
bspace:rename-experiment
bspace:duplicate-experiment
bspace:import-experiments
bspace:export-experiment
bspace:clear-experiments
bspace:set-current-experiment
bspace:print-experiments
bspace:get-experiment-list
bspace:get-current-experiment
bspace:get-parameters
bspace:experiment-exists
bspace:valid-experiment-name
bspace:set-variables
bspace:set-repetitions
bspace:set-sequential-run-order
bspace:set-metrics
bspace:set-run-metrics-every-step
bspace:set-run-metrics-condition
bspace:set-pre-experiment-commands
bspace:set-setup-commands
bspace:set-go-commands
bspace:set-stop-condition
bspace:set-post-run-commands
bspace:set-post-experiment-commands
bspace:set-time-limit
bspace:get-variables
bspace:get-repetitions
bspace:get-sequential-run-order
bspace:get-metrics
bspace:get-run-metrics-every-step
bspace:get-run-metrics-condition
bspace:get-pre-experiment-commands
bspace:get-setup-commands
bspace:get-go-commands
bspace:get-stop-condition
bspace:get-post-run-commands
bspace:get-post-experiment-commands
bspace:get-time-limit
bspace:set-spreadsheet
bspace:set-table
bspace:set-stats
bspace:set-lists
bspace:set-parallel-runs
bspace:set-mirror-headless-output
bspace:get-spreadsheet
bspace:get-table
bspace:get-stats
bspace:get-lists
bspace:get-parallel-runs
bspace:get-mirror-headless-output
bspace:goto-behaviorspace-documentation
bspace:goto-bspace-extension-documentation
bspace:get-default-parallel-runs
bspace:get-recommended-max-parallel-runs
Create a new experiment with the name specified in the first input. If an experiment already exists with that name and
the second input is true, that experiment will be overwritten with the default experiment. If an experiment already
exists with that name and the second input is false, an error will be thrown. The newly created experiment will be
stored until NetLogo is closed or the stored experiments are cleared with
bspace:clear-experiments.
Example:
bspace:create-experiment "my-experiment" true
Delete the experiment with the name specified in the first input. An error will be thrown if the specified experiment does not exist.
Example:
bspace:delete-experiment "my-experiment"
Run the current working experiment (see bspace:set-current-experiment). An error
will be thrown if no current working experiment has been set.
Rename the current working experiment to the name specified in the first input. An error will be thrown if no current working experiment has been set.
Example:
bspace:rename-experiment "another-experiment"
Make a copy of the current working experiment and rename the copy to the name specified in the first input, then set the current working experiment to the newly created experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:duplicate-experiment "my-experiment-copy"
Import the experiments contained in the file at the specified path. An error will be thrown for each experiment that has a name that already exists, but the remaining experiments will be succesfully imported.
Example:
bspace:import-experiments "/Users/hacker53/Documents/experiments.xml"
Export the current working experiment to the file specified in the second input. If that file already exists and the second input is true, it will be overwritten with the specified experiment. If that file already exists and the second input is false, an error will be thrown.
Example:
bspace:export-experiment "/Users/hacker53/Documents/my-experiment.xml"
Clear the list of stored experiments that have been created in the code. Any currently running experiments that were created in the code will be aborted, but the model and all experiments created in the GUI will remain unchanged.
Set the current working experiment to the name specified in the first input. If no experiment has been created in the GUI or the code with the specified name, an error will be thrown.
Example:
bspace:set-current-experiment "my-experiment"
Report a formatted string with the names of all BehaviorSpace experiments created programmatically, followed by the names of all BehaviorSpace experiments created in the GUI. Each section is sorted alphabetically.
Report a list of names of all BehaviorSpace experiments, including both GUI and code experiments, sorted alphabetically.
Report the name of the current working experiment.
Report the parameter values for the experiment with the name specified in the first input. An error will be thrown if no experiment exists with the specified name. Any empty or unset values will not be included.
Example:
bspace:get-parameters "my-experiment"
Sample output:
EXPERIMENT PARAMETERS:
Variable values:
Repetitions: 1
Sequential run order: true
Metrics:
count turtles
Run metrics every step: true
Setup commands:
setup
Go commands:
go
Time limit: 0
RUN OPTIONS:
Spreadsheet: /Users/hacker53/Documents/my-spreadsheet.csv
Update view: true
Update plots: true
Parallel runs: 6
Mirror Headless Output: false
Report whether an experiment exists with the name specified in the first input.
Example:
bspace:experiment-exists "my-experiment"
Report whether the specified name is a valid experiment name. An experiment name is valid if it is not empty and if no other experiment currently exists with the specified name.
Example:
bspace:valid-experiment-name "" ; false
bspace:valid-experiment-name "my-experiment" ; true
bspace:create-experiment "my-experiment" true
bspace:valid-experiment-name "my-experiment" ; false
Set the variables to vary for the current working experiment. Each element of the input list should contain one constant or sub-experiment specification. An error will be thrown if no current working experiment has been set. Note that nested double quotes must be escaped, and using single quotes will cause errors.
Example:
bspace:set-variables [ "[ \"var1\" 0 5 20 ]" ]
Set the repetitions for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-repetitions 3
Set whether the current working experiment uses sequential run order. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-sequential-run-order true
Set the metrics commands for the current working experiment. An error will be thrown if no current working experiment has been set. To set only one metric, the primitive can be called as normal with one input, but to set multiple metrics, the entire command must be surrounded with parentheses.
Example:
bspace:set-metrics [ count turtles ]
(bspace:set-metrics [ count turtles ] [ count patches ])
Set whether the current working experiment runs metrics every step. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-run-metrics-every-step false
Set the run metrics condition for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-run-metrics-condition [ count turtles < 5 ]
Set the pre-experiment commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-pre-experiment-commands [ clear-all ]
Set the setup commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-setup-commands [ clear-all create-turtles 50 ]
Set the go commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-go-commands [ myFunction ]
Set the stop condition for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-stop-condition [ ticks > 1000 ]
Set the post-run commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-post-run-commands [ print count turtles ]
Set the post-experiment commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-post-experiment-commands [ ask turtles [ setxy 0 0 ] ]
Set the time limit in ticks for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-time-limit 1500
Report the variables for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the repetitions for the current working experiment. An error will be thrown if no current working experiment has been set.
Report whether the current working experiment uses sequential run order. An error will be thrown if no current working experiment has been set.
Report the metrics for the current working experiment. An error will be thrown if no current working experiment has been set.
Report whether the current working experiment runs metrics every step. An error will be thrown if no current working experiment has been set.
Report the run metrics condition for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the pre-experiment commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the setup commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the go commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the stop condition for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the post-run commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the post-experiment commands for the current working experiment. An error will be thrown if no current working experiment has been set.
Report the time limit for the current working experiment. An error will be thrown if no current working experiment has been set.
Set the path for the spreadsheet file for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-spreadsheet "/Users/hacker53/Documents/exp-sheet.csv"
Set the path for the table file for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-table "/Users/hacker53/Documents/exp-table.csv"
Set the path for the stats file for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-stats "/Users/hacker53/Documents/exp-stats.csv"
Set the path for the lists file for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-lists "/Users/hacker53/Documents/exp-lists.csv"
Set the number of parallel runs for the current working experiment. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-parallel-runs 3
Set whether the current working experiment should display its background output in the Command Center, if running in the GUI.
Example:
bspace:set-mirror-headless-output true
Report the spreadsheet location for the current working experiment. An error will be thrown if no current working experiment has been set. Will report an empty string if no spreadsheet file was specified in the current working experiment, or the string "-" if the output is directed to standard output.
Report the table location for the current working experiment. An error will be thrown if no current working experiment has been set. Will report an empty string if no table file was specified in the current working experiment, or the string "-" if the output is directed to standard output.
Report the stats location for the current working experiment. An error will be thrown if no current working experiment has been set. Will report an empty string if no spreastatsdsheet file was specified in the current working experiment, or the string "-" if the output is directed to standard output.
Report the lists location for the current working experiment. An error will be thrown if no current working experiment has been set. Will report an empty string if no lists file was specified in the current working experiment, or the string "-" if the output is directed to standard output.
Report the number of parallel runs for the current working experiment. An error will be thrown if no current working experiment has been set.
Report whether the current working experiment will display its background output in the Command Center, if running in the GUI.
Open the BehaviorSpace GUI documentation page in a browser window.
Open the BehaviorSpace extension documentation page in a browser window.
Report the default number of parallel runs for the current device.
Report the recommended maximum number of parallel runs for the current device.