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 Update View: true Update Plots And Monitors: true
Any properties can also be set explicitly to other default values. For code blocks, you can specify "do nothing" with 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:get-experiments
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-update-view
bspace:set-update-plots
bspace:set-parallel-runs
bspace:get-spreadsheet
bspace:get-table
bspace:get-stats
bspace:get-lists
bspace:get-update-view
bspace:get-update-plots
bspace:get-parallel-runs
bspace:goto-behaviorspace-documentation
bspace:goto-bspace-extension-documentation
bspace:get-default-parallel-runs
bspace:get-recommended-max-parallel-runs
Create a new experiment 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.
Example:
bspace:create-experiment "my-experiment" true
Delete the experiment 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. An error will be thrown if no current working experiment has been set.
Example:
bspace:run-experiment
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 new 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 location. 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, and reset all experiments that have been paused after running from the code. The model and all experiments created in the GUI will remain unchanged.
Example:
bspace:clear-experiments
Set the current working experiment to the name specified in the first input.
Example:
bspace:set-current-experiment "my-experiment"
Report a list of all BehaviorSpace experiments created programmatically, followed by all BehaviorSpace experiments created in the GUI.
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.
Example:
bspace:get-parameters "my-experiment"
Sample output:
EXPERIMENT PARAMETERS:
Variable values:
Repetitions:
1
Sequential run order:
true
Metrics:
List("count turtles")
Run metrics every step:
true
Run metrics condition:
Pre experiment commands:
Setup commands:
setup
Go commands:
go
Post run commands:
Post experiment commands:
Stop condtion:
Time limit:
0
RUN OPTIONS:
Spreadsheet:
Table:
Stats:
Lists:
Update view:
true
Update plots:
true
Parallel runs:
6
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.
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.
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. The first input must be a list of string commands.
Example:
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 whether the current working experiment should update the view. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-update-view true
Set whether the current working experiment should update the plots. An error will be thrown if no current working experiment has been set.
Example:
bspace:set-update-view false
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
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 whether the current working experiment will update the view. An error will be thrown if no current working experiment has been set.
Report whether the current working experiment will update the plots. An error will be thrown if no current working experiment has been set.
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 the list of values for the metric specified in the second input for the run number specified in the third input, from the file specified in the first input. The specified file must be a spreadsheet output to ensure proper ordering of values. An error will be thrown if any of the inputs are invalid.
Example:
bspace:get-output-metric "/Users/hacker53/Documents/spreadsheet.csv" "count turtles" 3
Open the BehaviorSpace documentation page in a browser window.
Open the bspace 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.