baseAgent(breedstr, idint, modelHelipad)

baseAgent is used as a parent class for implementing new primitives, including Agent, MultiLevel, and Patch.

For agent hooks, the name of the primitive can be replaced with baseAgent to hook all primitives rather than just the agent primitive. For example, where agentStep will hook only the step function for the 'agent' primitive, hooking baseAgentStep will hook the function into the step function for agents of all primitives.

Subclasses of baseAgent can be registered as primitives using Agents.addPrimitive(). Methods 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.

• buy( partner, good, q, … )

  Purchases a good from another agent and pays for it using the monetary good specified in a Goods.add() 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.

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

  This function can be hooked with agentDie.

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

• reproduce( inherit, mutate, partners )

  Spawns a new agent, inheriting specified properties from the parent agent(s). 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 (and therefore after the agentInit hook runs on the child agent).

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

• rotate( angle )

  Rotates the agent's orientation clockwise by angle, which will be understood as either degrees or radians depending on the value of baseAgent.angleUnit.

  Agents of any primitive can be rotated, except patches, which have no orientation and will raise a RuntimeError.

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

• transfer( dest )

  In a multi-level model, this function allows an agent of a sub-model to move to a different sub-model. Agents can also move to and from the top-level model, for example if agents can join firms or exit them to compete as independent contractors. Note that the agent's primitive must have been registered in the destination agent as well.

  This function can be hooked with agentTransfer.

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

Object 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}

  Stores agents' stocks of goods. Keys correspond to goods registered with Goods.add(), and values correspond to the amount of the good owned. Goods properties registered with Goods.add() can be accessed with a second dict key, e.g. agent.stocks['goodname', 'propertyname'].

  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: {}

• balance — int

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

  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 — Edges{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. A list of all edges connected to the agent in all network types can be retrieved with Agent.edges.all.

  Initial value: {}

• orientation — float

  The orientation of the agent on the spatial grid. This property returns and can be set in either degrees or radians, depending on the value of baseAgent.angleUnit.
  
  This property is unused until a spatial model is initialized. Patches have no orientation.

  Initial value: 0

• patch — Patch

  If a spatial model has been initialized, the patch under the agent's current position. If there is no patch at the current position, the property is None.

  Initial value: None

Static Properties

• primitive — str

  The name of the primitive the agent belongs to.

• fixed — bool

  If True, the agent population is fixed and cannot reproduce or die. Patches in a spatial model are a fixed primitive, for example. It should be set as a static property of the class passed to Agents.addPrimitive().

  Initial value: False

• overdraft — str

  Controls agent behavior when agent.trade() or agent.pay() have the agent giving up more stocks of a good than he possesses. Available options are:

  1. 'allow': Allow agents to run negative balances of goods.
  2. 'continue-silent': Continues the trade with the available stock, leaving the payer with 0.
  3. 'continue-warn': Continues the trade with the available stock and emits a warning.
  4. 'fail-silent': Cancels the trade.
  5. 'fail-warn': Cancels the trade and emits a warning.
  6. 'stop': Raises a ValueError.
  This static property can be set on a per-primitive basis. Setting baseAgent.overdraft will set it for all primitives unless a primitive has specifically overridden the value.

  Initial value: 'continue-silent'

• angleUnit — str

  Controls whether Agent.orientation should take and return an angle in radians or degrees. Possible values are 'deg' and 'rad'. This should be set using baseAgent.angleUnit to avoid inconsistency between primitives.

  Initial value: 'deg'

Hooks

Click a hook name for more detailed documentation.

• agentPosition( agent, model )

  Determines agent position on the launch of a spatial model. If not specified, agents are randomly positioned. In a spatial model, this hook runs for every primitive except patches, which have a fixed position.

• agentTransfer( agent, origin, dest )

  Runs when an agent transfers from one model to another in a multi-level model. This hook generalizes to [primitive]Transfer, e.g. an agent of primitive 'worker' could be hooked with workerTransfer. To hook the moving of agents of all primitives, use baseAgentTransfer.

• 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 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( parents, 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 reproduction 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 function will be executed n×s times per period, where n is the number of agents and s is the number of model stages, unless the period is cut short.

  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.

  The list of agents to be stepped is finalized at the beginning of each stage, so any agent who is alive at the beginning of the stage will be stepped, even in the unusual case that it dies between then and its actual stepping. If this is undesired, if agent.dead: return at the beginning of the hook will prevent this.

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