Reference 〉Class

Agent( str breed, int id, Helipad model )

The Agent class contains the logic for agent behavior. The bulk of a model’s code will be hooked into agentStep.

Agent is the class used for the default 'agent' primitive. baseAgent is used as a parent class for implementing new primitives, including Agent. Hooking Agent functions, for example agentStep, will hook only the step function for the 'agent' primitive. Hooking baseAgentStep, on the other hand, will hook the function into the step function for agents of all primitives.

Functions in subclasses of baseAgent should call the parent function using super(), and maintain the same signature as the parent function, including on __init__().

Initialization Parameters

  • breed str, required

    The breed of the newly created agent.

  • id int, required

    A globally unique ID for the agent. Unexpected results may occur if non-unique ids are used.

  • model Helipad, required

    The model object.

Methods

Click a method name for more detailed documentation.

  • edgesWith( partner, kind )

    Returns a list of direct connections with another agent. Does not indicate indirect connections.

  • outbound( kind, undirected, obj )

    Returns a list of edges for which the agent is a startpoint.

  • inbound( kind, undirected, obj )

    Returns a list of edges for which the agent is an endpoint.

  • newEdge( partner, kind, direction, … )

    Creates a new Edge object between the current agent and a new agent, for use in graphs and networks.

  • reproduce( inherit, mutate, partners )

    Spawns a new agent, inheriting specified properties from the parent agent. The parent agent is stored in the child's agent.parent, and the child agent is added to the parent agent's agent.children list. Properties not specified in either the inherit or mutate arguments will be instantiated according to the agent.__init__() function.

    NOTE. This function accounts for parents and children by creating a directed network titled 'lineage'.

  • die( )

    Removes the agent from the model's list of active agents and cuts the agent's edges.

    This function also decrements the pseudo-parameter for the agent's primitive population. For this reason it has one optional argument for internal use that should not be used in user code.

  • pay( recipient, amount )

    Unilaterally transfers an amount of the monetary good from the agent to a recipient, or from the recipient to the agent if amount<0. Note that this function will raise a RuntimeError if no monetary good has been specified.

  • buy( partner, good, q, … )

    Purchases a good from another agent and pays for it using the monetary good specified in a model.addGood() command. Similar to agent.trade() except that the second good does not have to be specified. Note that this function will raise a RuntimeError if no monetary good has been specified.

  • trade( partner, good1, amt1, … )

    Exchanges a quantity of one good for a quantity of another good, and records the demand for each. Requires at least two goods to have been registered, but does not require a monetary good. Ordinary usage would be giving up amt1 of good1 to get amt2 of good2, but negative amounts can reverse the direction.

  • step( stage )

    A function that runs for each agent in each period and increments the agent's age by 1. This function should not be called directly, but should be hooked using agentStep or baseAgentStep.

Properties

  • id int

    A globally unique agent ID, assigned when the agent is instantiated.

  • age int

    The number of periods since the agent was initialized. Note that age stops incrementing once the agent dies.

    Initial value: 0

  • dead bool

    Whether the agent remains in the queue to be activated each period. See agent.die().

    Initial value: False

  • stocks dict{str:num}

    Keeps track of agents' stocks of goods. Keys correspond to goods registered with model.addGood().

    Initial value: {}

  • currentDemand dict{str:num}

    Keeps track of how much of each good the agent obtained. Note that selling a good does not register as negative demand, otherwise net demand would always be zero. See agent.trade() and agent.buy().

    Initial value: {}

  • currentShortage dict{str:num}

    Keeps track of unfulfilled demand, i.e. if a trade is initiated beyond the seller's ability to supply. See agent.trade() and agent.buy().

    Initial value: {}

  • balance int

    If a monetary good is registered, this property returns the agent's stock of the monetary good. Equivalent to agent.goods[model.moneyGood].

    Initial value: None

  • parent Agent|list[Agent]

    The agent (if haploid) or a list of agents (if polyploid) from which the current agent was spawned. See agent.reproduce(). Agents created at the initialization of the model have no parent.

    Initial value: None

  • children list[Agent]

    A list of agents spawned from the current agent. See agent.reproduce().

    Initial value: []

  • edges dict{str: list[Edge]}

    Stores the agent's active edges, for use in network and graph models. Keys correspond to the kinds of edges, and values are lists of edges of that type.

    Initial value: {}

  • alledges list[Edge]

    A flat list containing all edges of all kinds connected to the agent.

    Initial value: []

  • primitive str

    The name of the primitive the agent belongs to. Note: the primitive property attaches to the agent class and not the object. It can be accessed like an object property, but should not be modified.

Hooks

Click a hook name for more detailed documentation.

  • checkBalance( agent, balance, model )

    Modifies the value returned by agent.balance. Allows agents' money balances to be filtered, e.g. if they hold money in a form other than the registered money good that ought to be counted toward total balances.

  • agentDie( agent )

    Runs when an agent dies. This hook in fact generalizes to [primitive]Die, e.g. the death of an agent with primitive 'bank' could be hooked with bankDie. To hook the death of agents of all primitives, use baseAgentDie.

  • agentReproduce( parent, child, model )

    Runs when an agent reproduces. This hook generalizes to [primitive]Reproduce, e.g. the death of an agent with primitive 'bank' would be hooked with bankReproduce. To hook the death of agents of all primitives, use baseAgentReproduce.

  • pay( agent, recipient, amount, … )

    Runs when an agent pays another agent. This hook can allow payment to be diverted into forms other than a transfer of the monetary good.

  • buy( agent, partner, good, … )

    Runs when an agent purchases a good with money and allows the quantity passed to the function to be modified.

  • postTrade( agent, partner, good1, … )

    Runs after an agent completes a trade of one good for another. Note that because agent.buy() aliases agent.trade(), this hook will also run when agents buy using the monetary good as well.

  • preTrade( agent, partner, good1, … )

    Runs before an agent completes a trade of one good for another. Note that because agent.buy() aliases agent.trade(), this hook will also run when agents buy using the monetary good as well.

  • agentStep( agent, model, stage )

    Runs when the model activates an agent. The main logic of an agent-based model should be hooked here.

    This hook generalizes to [primitive]Step, e.g. the step function of an agent with primitive 'bank' would be hooked with bankStep. To hook the step function of agents of all primitives, use baseAgentStep.

  • agentInit( agent, model )

    Runs during the initialization of an agent. This hook generalizes to [primitive]Init, e.g. the initialization of an agent with primitive 'bank' would be hooked with bankInit. To hook the death of agents of all primitives, use baseAgentInit.

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.

History