Reference 〉Function

Shocks.register( str name, str|tuple param, func valFunc, func(int)|str timerFunc, bool active = True, str desc = None )

Registers a shock to a parameter value. Associated with a value function, which shocks the variable, and a timer function, which determines when and how often to execute the value function.


  • name str, required

    A unique name for the shock, to be displayed in the GUI beside its checkbox.

  • param str|tuple, required

    A parameter identification string or tuple. 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. param can also be set to None, in which case valFunc behaves somewhat differently. See below.

  • valFunc func, required

    A function that returns a new value for the parameter. valFunc takes three arguments: the name of the variable being shocked, the parameter type (None for global parameters, 'breed' or 'good' for per-breed and per-good parameters, respectively), and (for per-breed or per-good parameters) the breed or the good in question. If var is None, however, valFunc takes one argument, the model object. This can be useful for more complex shocks that do not correspond to a particular parameter.

  • timerFunc func(int)|str, required

    A function that takes the current model time and returns a bool, indicating whether to run valFunc that period or not. timerFunc can also be set to the string 'button', in which case a button will be drawn in the control panel that runs valFunc when the button is pressed.

  • active bool, optional

    Whether the shock is active by default when the control panel launches. This can be toggled on and off in the control panel later.

    Default value: True

  • desc str, optional

    A long description that will display as a tooltip if PMW is installed.

    Default value: None

Notes and Examples

  1. charwick

    Mar 24, 2020 at 4:08

    This example shocks the 'rbd' breed parameter for the dwarf breed of agent-primitives with 2% probability each period by drawing from a normal distribution centered around the current value, and with a standard deviation of 4, bounded from below by 1.

    def rbdShock(v):
    	c = random.normal(v, 4)
    	return c if c >= 1 else 1
    heli.shocks.register('Dwarf real balances', 'rbd', rbdShock, heli.shocks.randn(2), paramType='breed', obj='dwarf', prim='agent')
  2. charwick

    Mar 24, 2020 at 3:45

    The current population of any primitive is stored as a live-updating parameter 'agents_[primitive]' that you can update and shock. Increasing the value will spawn agents, and decreasing the value will cull them at random. See model.nUpdater().

    This code registers a shock that reduces the population of human-primitive agents by half in period 2018.

    def thanos(pop):
    	return pop/2
    model.shocks.register('snap', 'agents_human', thanos, model.shocks.atperiod(2018), desc="I am inevitable.")
  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.