repast4py.space module

class repast4py.space.BorderType

Bases: object

An enum defining the border types that can be used with a space or grid.

The border type determines an agent’s new location when the assigned location is beyond a grid or space’s bounds. For example, during agent movement, when that movement carries the agent beyond the borders of a grid or space. Valid values are Sticky, and Periodic.

Periodic = 1

Wraps point coordinates when the point coordinate is less than or greater than the grid or spaces maximum or minimum value. For example, if the minimum grid x location is 0, the maximum is 20, and an agent moves to an x of -2, then the new x coordinate is 19.

Sticky = 0

Clips any point coordinate to the maximum or minimum value when the coordinate is less than or greater than the grid or spaces maximum or minimum value. For example, if the minimum grid x location is 0, and an agent moves to an x of -1, then the new coordinate is 0.

class repast4py.space.CartesianTopology

Bases: object

CartesianTopolgy(comm, global_bounds, periodic)

A CartesianTopology is used by a SharedGrid or SharedContinuousSpace to create an efficient communicator over which the grid or space is distributed and to compute the buffer synchronization metadata used to synchronize the buffers between grid and space neighbors.

This class should not typically be created by users, but is rather part of the internal synchronization mechanism used by the shared cartesian spaces. More info on MPI topologies can be found here.

Parameters:

  • comm (mpi4py.MPI.Intracomm) – the communicator to create the cartesian topology communicator from.

  • global_bounds (repast4py.geometry.BoundingBox) – the global size of the shared space or grid that will use this topology.

  • periodic (bool) – whether or not the shared space or grid that will use this topology is periodic.

comm

Gets the mpi communicator created by this CartesianTopology

Type:

mpi4py.MPI.Intracomm

compute_buffer_nghs(buffer_size)

Gets an iterator over the collection of buffer synchronization meta data for the current rank for the specified buffer_size.

This data contains information for each cartesian neighbor of the current rank specifying what subsection of this grid or space should be sent what rank when synchronizing buffers. This method should not typically be called by users, but is rather part of the internal synchronization mechanism.

Parameters:

buffer_size (int) – the size of the buffer.

Returns:

an iterator over tuples of buffer synchronization meta data: (rank, (xmin, xmax, ymin, ymax, zmin, zmax)) where rank is the neighbor’s rank, and the nested tuple specifies what part of this space or grid to send.

Return type:

iterator

coordinates

Gets the cartesian coordinates of the current rank within this CartesianTopology

Type:

tuple(int)

local_bounds

Gets the local bounds of the current rank within this CartesianTopology

Type:

repast4py.geometry.BoundingBox

procs_per_dim

Gets the number of ranks per dimension in x,y,z order

Type:

tuple(int)

class repast4py.space.ContinuousPoint(x, y, z=0)

Bases: object

A 3D point with continuous (floating point) coordinates.

Parameters:

  • x (float) – the x coordinate.

  • y (float) – the y coordinate.

  • z (float, optional) – the z coordinate. Defaults to 0.0

_reset_from_array(np_array)

Resets the coordinate values of this ContinuousPoint from the specified array’s elements. The array must have a single dimension and have at least one element. The x coordinate is set from the first element, y from the second, and z from the 3rd.

This method should ONLY be used in code fully responsible for the point, that is, the point was not returned from any repast4py method or function.

Parameters:

np_array (numpy.array) – the array to reset from.

coordinates

Gets this ContinuousPoint’s coordinates as 3 element numpy array.

Type:

numpy.array

x

Gets this ContinuousPoint’s x coordinate.

Type:

float

y

Gets this ContinuousPoint’s y coordinate.

Type:

float

z

Gets this ContinuousPoint’s z coordinate.

Type:

float

class repast4py.space.ContinuousSpace(name, bounds, borders, occupancy, tree_threshold)

Bases: object

An N-dimensional cartesian continuous space where agents can occupy locations defined by a continuous floating point coordinate.

The ContinuousSpace uses a tree (quad or oct depending on the number of dimensions) to optimize spatial queries. The tree can be tuned using the tree threshold parameter.

Parameters:
add(agent)

Adds the specified agent to this continuous space projection.

Parameters:

agent (repast4py.core.Agent) – the agent to add.

contains(agent)

Gets whether or not this continuous space projection contains the specified agent.

Parameters:

agent (repast4py.core.Agent) – the agent to check.

Returns:

true if this continuous space contains the specified agent, otherwise false

Return type:

bool

get_agent(pt)

Gets the agent at the specified location. If more than one agent exists at the specified location, the first agent to have moved to that location from among those currently at that location will be returned.

Parameters:

pt (repast4py.space.ContinuousPoint) – the location to get the agent at.

Returns:

the agent at that location, or None if the location is empty

Return type:

repast4py.core.Agent

get_agents(pt)

Gets an iterator over all the agents at the specified location.

Parameters:

pt (repast4py.space.ContinuousPoint) – the location to get the agents at.

Returns:

an iterator over all the agents at the specified location.

Return type:

iterator

get_agents_within(bbox)

Gets an iterator over all the agents within the specified bounding box.

Parameters:

box (repast4py.geometry.BoundingBox) – the bounding box to get the agents within.

Returns:

an iterator over all the agents within the specified bounding box.

Return type:

iterator

get_location(agent)

Gets the location of the specified agent

Parameters:

agent (repast4py.core.Agent) – the agent whose location we want to get.

Returns:

the location of the specified agent or None if the agent is not in the space.

Return type:

repast4py.space.ContinuousPoint

move(agent, pt)

Moves the specified agent to the specified location, returning the moved to location.

If the agent does not move beyond the continuous space’s bounds, then the returned location will be be the same as the argument location. If the agent does move out of bounds, then the location is determined by the continuous space’s border’s semantics (e.g., a location on the border if using BorderType.Sticky borders.

Parameters:
Returns:

the location the agent has moved to or None if the agent cannot move to the specified location (e.g., if the occupancy type is OccupancyType.Single and the location is occupied.)

Return type:

repast4py.space.ContinuousPoint

name

Gets the name of this continuous space.

Type:

str

remove(agent)

Removes the specified agent from this continuous space projection.

Parameters:

agent (repast4py.core.Agent) – the agent to remove.

class repast4py.space.DiscretePoint(x, y, z=0)

Bases: object

A 3D point with discrete (integer) coordinates.

Parameters:

  • x (int) – the x coordinate.

  • y (int) – the y coordinate.

  • z (int, optional) – the z coordinate. Defaults to 0

_reset_from_array(np_array)

Resets the coordinate values of this DiscretePoint from the specified array’s elements. The array must be of the integer type, have a single dimension and have at least one element. The x coordinate is set from the first element, y from the second, and z from the 3rd.

This method should ONLY be used in code fully responsible for the point, that is, the point was not returned from any repast4py method or function.

Parameters:

np_array (numpy.array) – the array to reset from.

coordinates

Gets this DiscretePoint’s coordinates as 3 element numpy array.

Type:

numpy.array

x

Gets this DiscretePoint’s x coordinate.

Type:

int

y

Gets this DiscretePoint’s y coordinate.

Type:

int

z

Gets this DiscretePoint’s z coordinate.

Type:

int

class repast4py.space.Grid(name, bounds, borders, occupancy)

Bases: object

An N-dimensional cartesian discrete space where agents can occupy locations at a discrete integer coordinate.

Parameters:
add(agent)

Adds the specified agent to this grid projection.

Parameters:

agent (repast4py.core.Agent) – the agent to add.

contains(agent)

Gets whether or not this grid projection contains the specified agent.

Parameters:

agent (repast4py.core.Agent) – the agent to check.

Returns:

true if this grid contains the specified agent, otherwise false

Return type:

bool

get_agent(pt)

Gets the agent at the specified location. If more than one agent exists at the specified location, the first agent to have moved to that location from among those currently at that location will be returned.

Parameters:

pt (repast4py.space.DiscretePoint) – the location to get the agent at.

Returns:

the agent at that location, or None if the location is empty

Return type:

repast4py.core.Agent

get_agents(pt)

Gets an iterator over all the agents at the specified location.

Parameters:

pt (repast4py.space.DiscretePoint) – the location to get the agents at.

Returns:

an iterator over all the agents at the specified location.

Return type:

iterator

get_location(agent)

Gets the location of the specified agent

Parameters:

agent (repast4py.core.Agent) – the agent whose location we want to get.

Returns:

the location of the specified agent or None if the agent is not in the space.

Return type:

repast4py.space.DiscretePoint

move(agent, pt)

Moves the specified agent to the specified location, returning the moved to location.

If the agent does not move beyond the grid’s bounds, then the returned location will be be the same as the argument location. If the agent does move out of bounds, then the location is determined by the grid border’s semantics (e.g., a location on the border if using BorderType.Sticky borders).

Parameters:
Returns:

the location the agent has moved to or None if the agent cannot move to the specified location (e.g., if the occupancy type is OccupancyType.Single and the location is occupied.)

Return type:

repast4py.space.DiscretePoint

name

Gets the name of this grid.

Type:

str

remove(agent)

Removes the specified agent from this grid projection.

Parameters:

agent (repast4py.core.Agent) – the agent to remove.

class repast4py.space.OccupancyType

Bases: object

An enum defining the occupancy type of a location in a space or grid. The occupancy type determines how many agents are allowed at a single location.

Valid values are: Multiple, Single.

Multiple = 0

Any number of agents can inhabit inhabit a location.

Single = 1

Only a single agent can inhabit a location.

class repast4py.space.SharedCSpace(name, bounds, borders, occupancy, buffer_size, comm, tree_threshold)

Bases: SharedContinuousSpace

An N-dimensional cartesian space where agents can occupy locations defined by a continuous floating point coordinate.

The space is shared over all the ranks in the specified communicator by sub-dividing the global bounds into some number of smaller spaces, one for each rank. For example, given a global 2D space size of 100 x 25 and 2 ranks, the global space will be split along the x dimension such that the SharedCSpace in the first MPI rank covers 0-50 x 0-25 and the second rank 50-100 x 0-25.

Each rank’s SharedCSpace contains a buffer of a specified size that duplicates or “ghosts” an adjacent area of the neighboring rank’s SharedCSpace. In the above example, the rank 1 space buffers the area from 50-52 x 0-25 in rank 2, and rank 2 buffers 48-50 x 0-25 in rank 1. Be sure to specify a buffer size appropriate to any agent behavior. For example, if an agent can “see” 3 units away and take some action based on what it perceives, then the buffer size should be at least 3, insuring that an agent can properly see beyond the borders of its own local SharedCSpace. When an agent moves beyond the borders of its current SharedCSpace, it will be transferred from its current rank, and into that containing the section of the global space that it has moved into. The SharedCSpace uses a tree (quad or oct depending on the number of dimensions) to optimize spatial queries. The tree can be tuned using the tree threshold parameter.

Parameters:

  • name (str) – the name of the space.

  • bounds (BoundingBox) – the global dimensions of the space.

  • borders (BorderType) – the border semantics - BorderType.Sticky or BorderType.Periodic.

  • occupancy (OccupancyType) – the type of occupancy in each cell - OccupancyType.Single or OccupancyType.Multiple.

  • buffer_size (int) – the size of this SharedCSpace’s buffered area. This single value is used for all dimensions.

  • comm (Intracomm) – the communicator containing all the ranks over which this SharedCSpace is shared.

  • tree_threshold (int) – the space’s tree cell maximum capacity. When this capacity is reached, the cell splits.

add(agent)

Adds the specified agent to this shared continuous space projection.

Parameters:

agent (repast4py.core.Agent) – the agent to add.

contains(agent)

Gets whether or not the local bounds of this shared continuous space projection contains the specified agent.

Parameters:

agent (repast4py.core.Agent) – the agent to check.

Returns:

true if this shared continuous space contains the specified agent, otherwise false

Return type:

bool

get_agent(pt)

Gets the agent at the specified location. If more than one agent exists at the specified location, the first agent to have moved to that location from among those currently at that location will be returned.

Parameters:

pt (repast4py.space.ContinuousPoint) – the location to get the agent at.

Returns:

the agent at that location, or None if the location is empty

Return type:

repast4py.core.Agent

get_agents(pt)

Gets an iterator over all the agents at the specified location.

Parameters:

pt (repast4py.space.ContinuousPoint) – the location to get the agents at.

Returns:

an iterator over all the agents at the specified location.

Return type:

iterator

get_agents_within(bbox)

Gets an iterator over all the agents within the specified bounding box.

The bounding box is assumed to be within the local bounds of this SharedCSpace.

Parameters:

box (repast4py.geometry.BoundingBox) – the bounding box to get the agents within.

Returns:

an iterator over all the agents within the specified bounding box.

Return type:

iterator

get_local_bounds()

Gets the local bounds of this shared continuous space.

The local bounds are the bounds of this shared continuous space on the current rank. For example, if the global bounds are 100 in the x dimension and 100 in the y dimension, and there are 4 ranks, then the local bounds will be some quadrant of those global bounds, 0 - 50 x 0 - 50 for example.

Returns:

the local bounds as a BoundingBox.

Return type:

repast4py.geometry.BoundingBox

get_location(agent)

Gets the location of the specified agent

Parameters:

agent (repast4py.core.Agent) – the agent whose location we want to get.

Returns:

the location of the specified agent or None if the agent is not in the space.

Return type:

repast4py.space.ContinuousPoint

get_num_agents(pt, agent_type=None)

Gets number of agents at the specified location, optionally fitered by agent type.

Parameters:
Returns:

the number of agents at the specified location.

Return type:

int

get_random_local_pt(rng)

Gets a random location within the local bounds of this SharedCSpace.

Parameters:

rng (Generator) – the random number generator to use to select the point.

Returns:

the random point

Return type:

ContinuousPoint

move(agent, pt)

Moves the specified agent to the specified location, returning the moved to location.

If the agent does not move beyond the shared continuous space’s global bounds, then the returned location will be be the same as the argument location. If the agent does move out of the global bounds, then the location is determined by the shared continuous space’s border semantics (e.g., a location on the border if using BorderType.Sticky borders).

Parameters:
Returns:

the location the agent has moved to or None if the agent cannot move to the specified location (e.g., if the occupancy type is OccupancyType.Single and the location is occupied.)

Return type:

repast4py.space.ContinuousPoint

name

Gets the name of this shared continuous space.

Type:

str

remove(agent)

Removes the specified agent from this shared continuous space projection.

Parameters:

agent (repast4py.core.Agent) – the agent to remove.

class repast4py.space.SharedGrid(name, bounds, borders, occupancy, buffer_size, comm)

Bases: SharedGrid

An N-dimensional cartesian discrete space shared across ranks, where agents can occupy locations defined by a discretete integer coordinate.

The grid is shared over all the ranks in the specified communicator by sub-dividing the global bounds into some number of smaller grids, one for each rank. For example, given a global grid size of (100 x 25) and 2 ranks, the global grid will be split along the x dimension such that the SharedGrid in the first MPI rank covers (0-50 x 0-25) and the second rank (50-100 x 0-25). Each rank’s SharedGrid contains buffers of a specified size that duplicate or “ghosts” an adjacent area of the neighboring rank’s SharedGrid. In the above example, the rank 1 grid buffers the area from (50-52 x 0-25) in rank 2, and rank 2 buffers (48-50 x 0-25) in rank 1. Be sure to specify a buffer size appropriate to any agent behavior. For example, if an agent can “see” 3 units away and take some action based on what it perceives, then the buffer size should be at least 3, insuring that an agent can properly see beyond the borders of its own local SharedGrid. When an agent moves beyond the borders of its current SharedGrid, it will be transferred from its current rank, and into that containing the section of the global grid that it has moved into.

Parameters:

  • name (str) – the name of the grid.

  • bounds (BoundingBox) – the global dimensions of the grid.

  • borders (BorderType) – the border semantics: BorderType.Sticky or BorderType.Periodic

  • occupancy (OccupancyType) – the type of occupancy in each cell: OccupancyType.Multiple.

  • buffer_size (int) – the size of this SharedGrid buffered area. This single value is used for all dimensions.

  • comm (Intracomm) – the communicator containing all the ranks over which this SharedGrid is shared.

add(agent)

Adds the specified agent to this shared grid projection.

Parameters:

agent (repast4py.core.Agent) – the agent to add.

contains(agent)

Gets whether or not the local bounds of this shared grid projection contains the specified agent.

Parameters:

agent (repast4py.core.Agent) – the agent to check.

Returns:

true if this shared grid contains the specified agent, otherwise false

Return type:

bool

get_agent(pt)

Gets the agent at the specified location. If more than one agent exists at the specified location, the first agent to have moved to that location from among those currently at that location will be returned.

Parameters:

pt (repast4py.space.DiscretePoint) – the location to get the agent at.

Returns:

the agent at that location, or None if the location is empty

Return type:

repast4py.core.Agent

get_agents(pt)

Gets an iterator over all the agents at the specified location.

Parameters:

pt (repast4py.space.DiscretePoint) – the location to get the agents at.

Returns:

an iterator over all the agents at the specified location.

Return type:

iterator

get_local_bounds()

Gets the local bounds of this shared grid.

The local bounds are the bounds of this shared grid on the current rank. For example, if the global bounds are 100 in the x dimension and 100 in the y dimension, and there are 4 ranks, then the local bounds will be some quadrant of those global bounds 0 - 50 x 0 - 50 for example.

Returns:

the local bounds as a BoundingBox.

Return type:

repast4py.geometry.BoundingBox

get_location(agent)

Gets the location of the specified agent

Parameters:

agent (repast4py.core.Agent) – the agent whose location we want to get.

Returns:

the location of the specified agent or None if the agent is not in the space.

Return type:

repast4py.space.DiscretePoint

get_num_agents(pt, agent_type=None)

Gets number of agents at the specified location, optionally fitered by agent type.

Parameters:
Returns:

the number of agents at the specified location.

Return type:

int

get_random_local_pt(rng)

Gets a random location within the local bounds of this SharedGrid.

Parameters:

rng (Generator) – the random number generator to use to select the point.

Returns:

the random point

Return type:

DiscretePoint

move(agent, pt)

Moves the specified agent to the specified location, returning the moved to location.

If the agent does not move beyond the shared grid’s global bounds, then the returned location will be be the same as the argument location. If the agent does move out of the global bounds, then the location is determined by the shared grid’s border semantics (e.g., a location on the border if using BorderType.Sticky borders.

Parameters:
Returns:

the location the agent has moved to or None if the agent cannot move to the specified location (e.g., if the occupancy type is OccupancyType.Single and the location is occupied.)

Return type:

repast4py.space.DiscretePoint

name

Gets the name of this shared grid.

Type:

str

remove(agent)

Removes the specified agent from this shared grid projection.

Parameters:

agent (repast4py.core.Agent) – the agent to remove.