Environments

Default

class Environment(model, agents=None, **kwargs)

Standard environment for agents (no topology).

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

Parameters

• model (Model) – The model instance.

• agents (AgentList, optional) – Agents to be added to the environment (default None).

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

Variables

• model (Model) – The model instance.

• agents (AgentList) – The environments’ agents.

• p (AttrDict) – The models’ parameters.

• key (str) – The environments’ name.

• topology (str) – Topology of the environment.

• log (dict) – The environments’ recorded variables.

add_agents(agents=1, agent_class=<class 'agentpy.objects.Agent'>, **kwargs)

Adds agents to the environment.

Parameters

• agents (int or AgentList, optional) – Either number of new agents to be created or list of existing agents (default 1).

• agent_class (type, optional) – Type of new agents to be created if int is passed for agents (default Agent).

• **kwargs – Forwarded to Agent.setup() if new agents are created (i.e. if an integer number is passed to agents).

Returns

List of the new agents.

Return type

AgentList

property env

The objects first environment.

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)

remove_agents(agents)

Removes agents from the environment.

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 EnvList(iterable=(), /)

List of environments.

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

See AgentList for examples.

add_agents(*args, **kwargs)

Add the same agents to all environments in the list. See Environment.add_agents() for arguments and keywords.

Networks

class Network(model, graph=None, agents=None, **kwargs)

Agent environment with a graph topology. Every node of the network represents an agent in the environment. To add new network environments to a model, use Model.add_network().

This class can be used as a parent class for custom network types. All agentpy model objects call the method setup() after creation, and can access class attributes like dictionary items. See Environment for general properties of all environments.

Parameters

• model (Model) – The model instance.

• graph (networkx.Graph, optional) – The environments’ graph. Agents of the same number as graph nodes must be passed. If none is passed, an empty graph is created.

• agents (AgentList, optional) – Agents of the network (default None). If a graph is passed, agents are mapped to each node of the graph. Otherwise, new nodes will be created for each agent.

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

Variables

graph (networkx.Graph) – The environments’ graph.

add_agents(agents, agent_class=<class 'agentpy.objects.Agent'>, **kwargs)

Adds agents to the network environment as new nodes. See Environment.add_agents() for standard arguments.

property env

The objects first environment.

neighbors(agent, **kwargs)

Returns an AgentList of agents that are connected to the passed agent.

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)

remove_agents(agents)

Removes agents from the environment.

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

Spatial grids

class Grid(model, shape, **kwargs)

Environment that contains agents with a spatial topology. Every location consists of an AgentList that can hold zero, one, or more agents. To add new grid environments to a model, use Model.add_grid().

This class can be used as a parent class for custom network types. All agentpy model objects call the method setup() after creation, and can access class attributes like dictionary items. See Environment for general properties of all environments.

Parameters

• model (Model) – The model instance.

• shape (int or tuple of int) – Size of the grid. If an integer is given, this value is taken as both the height and width for a two-dimensional grid. If a tuple is given, the length of the tuple defines the number of dimensions, and the values in the tuple define the length of each dimension.

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

Variables

• grid (list of lists) – Matrix of AgentList.

• shape (tuple of int) – Length of each grid dimension.

add_agents(agents=1, agent_class=<class 'agentpy.objects.Agent'>, positions=None, random=False, **kwargs)

Adds agents to the grid environment. See Environment.add_agents() for standard arguments. Additional arguments are listed below.

Parameters

• positions (list of tuples, optional) – The positions of the added agents. List must have the same length as number of agents to be added, and each entry must be a tuple with coordinates. If none is passed, agents will fill up the grid systematically.

• random (bool, optional) – If no positions are passed, agents will be placed in random locations instead of systematic filling (default False).

apply(func, *args, **kwargs)

Applies a function to all grid positions, and returns grid with return values.

attribute(attr_key, sum_values=True, empty=nan)

Returns a grid with the value of the attributes of the agents in each position.

Parameters

• attr_key (str) – Name of the attribute.

• sum_values (str, optional) – What to return in a position where there are multiple agents. If True (default), the sum of attributes. If False, a list of attributes.

• empty (optional) – What to return for empty positions without agents (default numpy.nan).

property env

The objects first environment.

get_agents(area=None)

Returns an AgentList with agents in the selected positions or area.

Parameters

area (tuple of integers or tuples) – Area from which agents should be gathered. Can either indicate a single position [x, y, …] or an area [(x_start, x_end), (y_start, y_end), …].

items(area=None)

Returns iterator with tuples of style: (position, agents).

move_agent(agent, position)

Moves agent to new position.

Parameters

• agent (int or Agent) – Id or instance of the agent.

• position (list of int) – New position of the agent.

neighbors(agent, distance=1, diagonal=True)

Returns agent neighbors.

Parameters

• agent (int or Agent) – Id or instance of the agent.

• distance (int, optional) – Number of positions to cover in each direction.

• diagonal (bool, optional) – If True (default), diagonal neighbors are included. If False, only direct neighbors are included (currently only works with distance == 1).

position(agent)

Returns position of a passed agent.

Parameters

agent (int or Agent) – Id or instance of the agent.

positions(area=None)

Returns iterable of all grid positions in area.

Parameters

area (list of tuples, optional) – Area of positions that should be returned. If none is passed, the whole grid is selected. Style: [(x_start, x_end), (y_start, y_end), …]

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)

remove_agents(agents)

Removes agents from the environment.

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