Agents

class Agent(model, **kwargs)[source]

Individual agent of an agent-based model.

This class can be used as a parent class for custom agent types. All agentpy model objects call the method setup() after creation, and can access class attributes like dictionary items. To add new agents to a model, use Model.add_agents() or Environment.add_agents().

Parameters

  • model (Model) – Instance of the current model.

  • **kwargs – Will be forwarded to Agent.setup().

Variables

  • model (Model) – Model instance.

  • p (AttrDict) – Model parameters.

  • envs (EnvList) – Environments of the agent.

  • log (dict) – Recorded variables of the agent.

  • id (int) – Unique identifier of the agent.

delete()[source]

Remove agent from all environments and the model.

enter(env)[source]

Adds agent to passed environment.

Parameters

env (int or Environment, optional) – Instance or id of environment that should be used. If none is given, the first environment in Agent.envs is used.

property env

The objects first environment.

exit(env=None)[source]

Removes agent from chosen environment.

Parameters

env (int or Environment, optional) – Instance or id of environment that should be used. If none is given, the first environment in Agent.envs is used.

move_by(path, env=None)[source]

Changes the agents’ location in the selected environment, relative to the current position.

Parameters

  • path (list of int) – Relative change of position.

  • env (int or Environment, optional) – Instance or id of environment that should be used. Must have topology ‘grid’. If none is given, the first environment of that topology in Agent.envs is used.

move_to(position, env=None)[source]

Changes the agents’ location in the selected environment.

Parameters

  • position (list of int) – Position to move to.

  • env (int or Environment, optional) – Instance or id of environment that should be used. Must have topology ‘grid’. If none is given, the first environment of that topology in Agent.envs is used.

neighbors(env=None, distance=1, diagonal=True)[source]

Returns the agents’ neighbor’s from an environment, by calling the environments neighbors() function.

Parameters

  • env (int or Environment, optional) – Instance or id of environment that should be used. Must have topology ‘grid’ or ‘network’. If none is given, the first environment of that topology in Agent.envs is used.

  • distance (int, optional) – Distance from agent in which to look for neighbors.

  • diagonal (bool, optional) – Whether to include diagonal neighbors (only for Grid).

Returns

Neighbors of the agent.

Return type

AgentList

position(env=None)[source]

Returns the agents’ position from a grid.

Parameters

env (int or Environment, optional) – Instance or id of environment that should be used. Must have topology ‘grid’. If none is given, the first environment of that topology in Agent.envs is used.

record(var_keys, value=None)

Records an objects variables.

Parameters

  • var_keys (str or list of str) – Names of the variables to be recorded.

  • value (optional) – Value to be recorded. The same value will be used for all var_keys. If none is given, the values of object attributes with the same name as each var_key will be used.

Examples

Record the existing attributes x and y of an object a:

a.record(['x', 'y'])

Record a variable z with the value 1 for an object a:

a.record('z', 1)

Record all variables of an object:

a.record(a.var_keys)
setup(**kwargs)

This empty method is called automatically at the objects’ creation. Can be overwritten in custom sub-classes to define initial attributes and actions.

Parameters

**kwargs – Keyword arguments that have been passed to Agent or Model.add_agents(). If the original setup method is used, they will be set as attributes of the object.

Examples

The following setup initializes an object with three variables:

def setup(self, y):
    self.x = 0  # Value defined locally
    self.y = y  # Value defined in kwargs
    self.z = self.p.z  # Value defined in parameters
property type

Class name of the object (str).

property var_keys

The object’s variables (list of str).

class AgentList(iterable=(), /)[source]

List of agents.

Attribute calls and assignments are applied to all agents and return an AttrList with attributes of each agent. This also works for method calls, which returns a list of return values. Arithmetic operators can further be used to manipulate agent attributes, and boolean operators can be used to filter list based on agent attributes.

Examples

Prepare an AgentList with three agents:

>>> model = ap.Model()
>>> agents = model.add_agents(3)
>>> agents
AgentList [3 agents]

The assignment operator can be used to set a variable for each agent. When the variable is called, an AttrList is returned:

>>> agents.x = 1
>>> agents.x
AttrList of attribute 'x': [1, 1, 1]

One can also set different variables for each agent by passing another AttrList:

>>> agents.y = ap.AttrList([1, 2, 3])
>>> agents.y
AttrList of attribute 'y': [1, 2, 3]

Arithmetic operators can be used in a similar way. If an AttrList is passed, different values are used for each agent. Otherwise, the same value is used for all agents:

>>> agents.x = agents.x + agents.y
>>> agents.x
AttrList of attribute 'x': [2, 3, 4]

>>> agents.x *= 2
>>> agents.x
AttrList of attribute 'x': [4, 6, 8]

Boolean operators can be used to select a subset of agents:

>>> subset = agents(agents.x > 5)
>>> subset
AgentList [2 agents]

>>> subset.x
AttrList of attribute 'x': [6, 8]
append(object, /)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)

Insert object before index.

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

random(n=1, generator=None)

Returns a new AgentList with a random subset of agents.

Parameters

  • n (int, optional) – Number of agents (default 1).

  • generator (random.Random, optional) – Random number generator. If none is passed, the hidden instance of random is used.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

select(selection)

Returns a new AgentList based on selection.

Parameters

selection (list of bool) – List with same length as the agent list. Positions that return True will be selected.

shuffle(generator=None)

Shuffles the list randomly and returns itself.

Parameters

generator (random.Random, optional) – Random number generator. If none is passed, the hidden instance of random is used.

sort(var_key, reverse=False)

Sorts the list based on the var_key of its agents and returns itself.