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: _space.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
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 (numpy.random._generator.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: _space.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 (repast4py.geometry.BoundingBox) – the global dimensions of the grid.

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

  • occupancy (repast4py.space.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 (mpi4py.MPI.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 (numpy.random._generator.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.