Reference 〉 Class


A dict-like container class for storing, retrieving, and manipulating agents. Agents can be accessed by primitive using the dict index, i.e. model.agents['store'] will return a list of 'store'-primitive agents. Individual agents can also be retrieved by ID by passing an int to the dict index, i.e. model.agents[12] will return agent ID=12.

Each dict key is a Primitive object, which stores data on different types of agents, as well as the agents themselves. Primitives are ordered in the order set by the priority argument of Agents.addPrimitive().

The Agents object is stored in model.agents, but should not be instantiated by user code.

Initialization Parameters

  • model Helipad, required

    The model object.


Click a method name for more detailed documentation.

  • addBreed( name, color, prim )

    Registers an agent breed, useful for heterogeneity within agent primitives.

    This function aliases Breeds.add(), but because Breeds is instantiated in Primitive.breeds, this function can be used for convenience without specifying a primitive if the model only has one primitive, as in the default setup.

  • addPrimitive( name, class, plural, … )

    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.

  • createNetwork( density, kind, prim )

    Creates a random undirected and unweighted network of a certain density among agents.

    This function can only be called once agents are created, so it will generally be called in the modelPostSetup hook.

  • network( kind, prim )

    Exports the model's graph structure to a NetworkX object; useful for further network analysis. Agent breed, primitive, and (if a spatial model) position are also stored as metadata.

  • removePrimitive( name )

    Removes a previously added primitive. See also Agents.addPrimitive().

  • summary( var, prim, breed )

    A function, generally used in the debug console, that prints summary statistics (length, mean, standard deviation, variance, maximum, minimum, and sum) for an agent property.

  • initialize( val, prim, model, … )

    Creates and/or destroys agents to get a population number. This function is used as a setter function for agent population parameters, and also at the beginning of a model to create the initial agent set.

Object Properties

  • all list[Object]

    A flat list of all elements (Agent or Edge) within the MultiDict.

    Initial value: []

  • order str|list[str]

    Determines the order in which agents activate. 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).
    order can also be set to a list of these values whose length corresponds to the number of stages, in order to use a different ordering in different stages of the model. Use the order hook for more complex ordering. Can be overridden on a per-primitive basis; see Agents.addPrimitive().

    Initial value: 'linear'

  • edges dict{str: list[Edge]}

    A collection of all active connections in the model, sorted by edge kind. Used to generate A list of all edges of all types can be retrieved with Agents.edges.all.

    Initial value: {}

Notes and Examples

  1. charwick

    Mar 24, 2020 at 3:24

    A few examples of retrieving agents:

    a = model.agents['agent'] #A list of all `agent`-primitive agents
    b = model.agents['agent'][3] #The third element of the list of 'agent'-primitive agents. If Agents.order=='random', the list is shuffled and this will not return the same agent each time.
    c = model.agents['agent']['hobbit'] #A list of all 'agent'-primitive agents with breed 'hobbit'
    d = model.agents[32] #The agent whose id==32, regardless of the primitive
    e = model.agents.all #A dict with all agents of all primitives, keyed by agent ID
  2. charwick

    Mar 28, 2020 at 1:52

    Agents.order=='random' will shuffle agents at the beginning of every stage, not just the beginning of each period. To shuffle agents only at the beginning of each period and maintain step order within periods, only set the first stage to 'random'.

    heli.stages = 3
    heli.agents.order = ['random', 'linear', 'linear']
  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.