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 the name of an event in order to stop the model at an open-ended stop condition.

Parameters

  • 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:

  • vars: A dict with 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 t.
  • events: A list of truncated Event objects containing the name, triggered, and data properties. The latter corresponds to a row of the whole dataframe at the time represented by triggered.

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.param('stopafter',1000)
    heli.paramSweep(['dist', ('rbd', 'breed', 'dwarf', 'agent')], ['rbalDemand-dwarf', 'ngdp'])
  2. charwick

    Jan 01, 2021 at 20:45

    Any parameters you want to hold fixed at values other than the default value, should be set in the modelPostSetup hook, 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:

    from helipad import Helipad
    heli = Helipad()
    
    heli.addParameter('dim','Dimensions','slider',dflt=2,opts={'low':1,'high':3,'step':1}, runtime=False)
    heli.param('num_agent', 500) #This will not work
    
    @heli.hook
    def modelPostSetup(model):
    	model.param('num_agent', 500) #This will work
    
    heli.paramSweep(['dim'])
  3. 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.

History