Reference 〉 Function

Agents.addPrimitive(namestr, classclass, pluralstrNone, dfltint50, lowint1, highint100, stepint1, hiddenboolFalse, priorityint100, orderstrNone)

Registers an agent primitive. A primitive, like a breed, is a way of introducing heterogeneity into a model, but there are several differences.

  1. Breeds do not affect the order of stepping. All agents of a primitive are stepped before any agents of another (this order can be changed with the priority argument).
  2. Breed is set as a property of the agent, which can be used with conditional logic in agent hooks. Building a primitive requires building a new agent class, which allows cleaner separation of logic where different types of agents behave in completely different ways.
  3. A use case of breeds would be different types of consumers. A use case of primitives would be consumers versus stores.


  • name str, required

    The name of the primitive.

  • class class, required

    A class, defined in user code, that re-instantiates the functions of Agent. It is a good idea to have this class inherit from BaseAgent.

  • plural str, optional

    The plural form of name. If plural is not specified, the plural will be constructed by placing an 's' at the end of the name.

    Default value: None

  • dflt int, optional

    Registering a primitive adds a slider to the control panel indicating how many of the primitive to instantiate at the beginning of the model. dflt is the default value on this slider.

    Default value: 50

  • low int, optional

    The slider's lower limit

    Default value: 1

  • high int, optional

    The slider's upper limit

    Default value: 100

  • step int, optional

    The increment in which the slider moves. For example, set to 2 to enforce only an even number of agents of this primitive.

    Default value: 1

  • hidden bool, optional

    Whether to hide the slider for altering the number of agents of this primitive from the control panel. If hidden = True, the initial number instantiated will be dflt.

    Default value: False

  • priority int, optional

    The order in which to step the primitives. Primitives with lower numbers are stepped first.

    Default value: 100

  • order str, optional

    Allows the order of activation to be specified on a per-primitive basis, overriding model.order. Possible values are:

    • 'random', which shuffles the list of agents before each stage
    • 'linear', which preserves the order of activation between periods.
    • 'match-n', which steps agents in groups of n and passes them to the match hook. If order=='match' (without the -n), agents will pair off at random (i.e. n==2).
    More complex orderings can be specified using the [primitive]Order hook. If not specified, defaults to the value of model.order.

    Default value: None

Notes and Examples

  1. 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.