Repeatedly runs the model while systematically varying one or more parameter values. This function can generate a great deal of data, and is intended to be used without the control panel.
ParamSweep, therefore, should be used instead of launching the control panel.
The possible values to be swept are specified when the parameter is registered. The values will differ according to their type, even though they will not be displayed in the GUI. A checkbox parameter will run with the parameter set to
False; a menu parameter will run with all the options specified in the
opts parameter, and a slider parameter will run in increments of the step value between the minimum and the maximum. See
The function allows multiple parameters to be swept in an n-dimensional space. This can entail very large numbers of runs. For example, specifying a checkbox and two slider parameters with 50 possible values each will run the model for every combination of the three parameters, or 5,000 times (2×50×50).
Each run will go until the model time equals the value of
model.param('stopafter'), which can either be an integer (in which case each run will be that many periods), or the name of an event in order to stop the model at an open-ended stop condition.
param — str|tuple|list, required
A parameter or list of parameters to sweep. A string value indicates a global parameter. Per-good parameters can be indicated with a three-item tuple,
('paramName', 'good', 'goodName'). A per-breed parameter can be indicated with a three- or four-item tuple,
('paramName', 'breed', 'breedName', 'primitive'), with the last element optional if there is only one primitive. The argument can also take a list of these strings and/or tuples to sweep across multiple parameter dimensions.
reporters — list, optional
A list of reporter names to be included in the data output. If not specified, all data columns will be included.
Default value: None
Return Value — list[Item]
A list of the results of each run. Each
Item object has three properties:
dictwith the parameter values under which that run was conducted.
data: A Pandas dataframe with the data from that run, with rows totaling either
len(reporters)or the number of total reporters, and columns totaling
events: A list of truncated
Eventobjects containing the
dataproperties. The latter corresponds to a row of the whole dataframe at the time represented by
Notes and Examples
charwickJun 25, 2020 at 0:19
This example sweeps the
'dist'global parameter and the
'rbd'parameter for the dwarf breed of the agent primitive, and returns data on each run from the
'rbd'parameter has 50 possible values (1-50), and the
'dist'parameter has two (
'lump'). The parameter sweep will therefore run the model 100 times for 1,000 periods each.
charwickJan 01, 2021 at 20:45
Any parameters you want to hold fixed at values other than the default value, should be set in the
modelPostSetuphook, and not in the main level; otherwise it gets reset between runs. E.g. if you want to set the number of agents to 500 while you sweep another parameter: