Reference 〉Function

Helipad.paramSweep( str|tuple|list param, list reporters = None )

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 initialized, either with model.addParam(), model.addBreedParam(), or model.addGoodParam(). 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 True and 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 Param.range.

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 a function that takes the model object as an argument and outputs True when a stop condition is met.


  • 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[tuple(dict, Pandas.DataFrame)]

A list of the results of each run. The first element of each tuple is a dict with the parameter values under which that run was conducted. The second element is a Pandas dataframe with the data from that run, with rows totaling either len(reporters) or the number of total reporters, and columns totaling t.

Notes and Examples

  1. charwick

    Jun 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 'rbalDemand-dwarf' and 'ngdp' reporters.

    The 'rbd' parameter has 50 possible values (1-50), and the 'dist' parameter has two ('prop' and 'lump'). The parameter sweep will therefore run the model 100 times for 1,000 periods each.

    heli.addBreedParam('rbd', 'Demand for Real Balances', 'slider', dflt={'hobbit':7, 'dwarf': 35}, opts={'low':1, 'high': 50, 'step': 1}, prim='agent')
    heli.addParameter('dist', 'Distribution', 'menu', dflt='prop', opts={
    	'prop': 'Proportional',
    	'lump': 'Lump Sum'
    }, runtime=False)
    heli.paramSweep(['dist', ('rbd', 'breed', 'dwarf', 'agent')], 1000, ['rbalDemand-dwarf', 'ngdp'])
  2. Contribute a Note

    Your email address will not be published. Required fields are marked *

    You may use limited HTML for formatting. Please embed blocks of code in <pre><code> </code></pre> tags.