Continuous spaces (Space)

class Space(model, shape, torus=False, **kwargs)[source]

Environment that contains agents with a continuous spatial topology. To add new space environments to a model, use Model.add_space(). For a discrete spatial topology, see Grid.

This class can be used as a parent class for custom space types. All agentpy model objects call the method setup() after creation, and can access class attributes like dictionary items.

Parameters

  • model (Model) – The model instance.

  • shape (tuple of float) – Size of the space. The length of the tuple defines the number of dimensions, and the values in the tuple define the length of each dimension.

  • torus (bool, optional) – Whether to connect borders (default False). If True, the space will be toroidal, meaning that agents who move over a border will re-appear on the opposite side. If False, they will remain at the edge of the border.

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

Variables

  • agents (AgentIter) – Iterator over all agents in the space.

  • positions (dict of Agent) – Dictionary linking each agent instance to its position.

  • shape (tuple of float) – Length of each spatial dimension.

  • ndim (int) – Number of dimensions.

  • kdtree (scipy.spatial.cKDTree or None) – KDTree of agent positions for neighbor lookup. Will be recalculated if agents have moved. If there are no agents, tree is None.

add_agents(agents, positions=None, random=False)[source]

Adds agents to the space environment.

Parameters

  • agents (Sequence of Agent) – Instance or iterable of agents to be added.

  • positions (Sequence of positions, optional) – The positions of the agents. Must have the same length as ‘agents’, with each entry being a position (array of float). If none is passed, all positions will be either be zero or random based on the argument ‘random’.

  • random (bool, optional) – Whether to choose random positions (default False).

move_by(agent, path)[source]

Moves agent to new position, relative to current position.

Parameters

  • agent (Agent) – Instance of the agent.

  • path (array_like) – Relative change of position.

move_to(agent, pos)[source]

Moves agent to new position.

Parameters

  • agent (Agent) – Instance of the agent.

  • pos (array_like) – New position of the agent.

neighbors(agent, distance)[source]

Select agent neighbors within a given distance. Takes into account wether space is toroidal.

Parameters

  • agent (Agent) – Instance of the agent.

  • distance (float) – Radius around the agent in which to search for neighbors.

Returns

Iterator over the selected neighbors.

Return type

AgentIter

record(var_keys, value=None)

Records an object’s variables at the current time-step. Recorded variables can be accessed via the object’s log attribute and will be saved to the model’s output at the end of a simulation.

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.

Notes

Recording mutable objects like lists can lead to wrong results if the object’s content will be changed during the simulation. Make a copy of the list or record each list entry seperately.

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.vars)
record_positions(label='p')

Records the positions of each agent.

Parameters

label (string, optional) – Name under which to record each position (default p). A number will be added for each coordinate (e.g. p1, p2, …).

remove_agents(agents)[source]

Removes agents from the space.

select(center, radius)[source]

Select agents within a given area.

Parameters

  • center (array_like) – Coordinates of the center of the search area.

  • radius (float) – Radius around the center in which to search.

Returns

Iterator over the selected agents.

Return type

AgentIter

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