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, seeGrid
.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.
- 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, …).
- 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
orModel.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