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. Other primitives can be created by subclassing baseAgent
.
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
id
s 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 toagent.trade()
except that the second good does not have to be specified. Note that this function will raise aRuntimeError
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 aRuntimeError
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'sagent.children
list. Properties not specified in either theinherit
ormutate
arguments will be instantiated according to theagent.__init__()
function (and therefore after theagentInit
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 byangle
, which will be understood as either degrees or radians depending on the value ofbaseAgent.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
ofgood1
to getamt2
ofgood2
, 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
orbaseAgentStep
.
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 withGoods.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()
andagent.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 toAgents.addPrimitive()
.Initial value: False
overdraft — str
Controls agent behavior when
agent.trade()
oragent.pay()
have the agent giving up more stocks of a good than he possesses. Available options are:'allow'
: Allow agents to run negative balances of goods.'continue-silent'
: Continues the trade with the available stock, leaving the payer with 0.'continue-warn'
: Continues the trade with the available stock and emits a warning.'fail-silent'
: Cancels the trade.'fail-warn'
: Cancels the trade and emits a warning.'stop'
: Raises aValueError
.
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 usingbaseAgent.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 withworkerTransfer
. To hook the moving of agents of all primitives, usebaseAgentTransfer
.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 withbankDie
. To hook the death of agents of all primitives, usebaseAgentDie
.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 withbankReproduce
. To hook the reproduction of agents of all primitives, usebaseAgentReproduce
.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()
aliasesagent.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()
aliasesagent.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 withbankStep
. To hook the step function of agents of all primitives, usebaseAgentStep
.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 withbankInit
. To hook the death of agents of all primitives, usebaseAgentInit
.
Notes and Examples