run_experiment
Run a BehaviorSpace experiment headlessly to collect metrics and per-combination results. Specify an experiment by name or define variables, metrics, and repetitions inline.
Instructions
Run a BehaviorSpace experiment headlessly and return summarized results.
Two ways to specify the experiment:
By name — pass
experiment_namematching a saved experiment in the loaded model (.nlogox<experiments>section). All other experiment-shape args are ignored.Inline — omit
experiment_name. Required:metrics. Optional:variables(list of{"name", "values"}or{"name", "first", "step", "last"}),repetitions,time_limit,setup_commands,go_commands,stop_condition.
Variable shapes (Cartesian product of all expanded values is run for each repetition)::
[{"name": "density", "values": [50, 60, 70]},
{"name": "growth-rate", "first": 0.1, "step": 0.05, "last": 0.3}]Long-run controls:
- max_total_runs — refuse to start if total_runs exceeds this.
- timeout_seconds — kill the launcher after this many seconds.
Partial results in the table CSV are preserved.
- threads — parallel runs (0 = let NetLogo decide; default ~75% of CPUs).
The launcher runs in a SEPARATE JVM, so the GUI workspace this server is hosting is unaffected. Run before calling this only matters insofar as the model file must be saved on disk (it is, after open_model / create_model / open_comses_model).
Returns JSON with: output_csv, runs, metrics_summary,
per_combination, duration_seconds, command, timed_out. The
full per-tick data is in output_csv for offline analysis.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| metrics | No | ||
| threads | No | ||
| variables | No | ||
| model_path | No | ||
| time_limit | No | ||
| go_commands | No | go | |
| output_name | No | ||
| repetitions | No | ||
| max_total_runs | No | ||
| setup_commands | No | setup | |
| stop_condition | No | ||
| experiment_name | No | ||
| timeout_seconds | No | ||
| sequential_run_order | No | ||
| run_metrics_every_step | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |