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
id
s 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'sagent.children
list. Properties not specified in either theinherit
ormutate
arguments will be instantiated according to theagent.__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 aRuntimeError
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 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.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.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
.
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()
andagent.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()
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.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