GridDF

class mesa_frames.GridPandas(model: ModelDF, dimensions: Sequence[int], torus: bool = False, capacity: int | None = None, neighborhood_type: str = 'moore')

The GridDF class is an abstract class that defines the interface for all grid classes in mesa-frames.

Inherits from DiscreteSpaceDF.

Attributes:

remaining_capacity	The remaining capacity of the cells in the grid.
agents	Get the ids of the agents placed in the cell set, along with their coordinates or geometries.
available_cells	Get the available cells (cells with at least one spot available) in the grid.
cells	Obtain the properties and agents of the cells in the grid.
dimensions	The dimensions of the grid.
empty_cells	Get the empty cells (cells without any agent) in the grid.
full_cells	Get the full cells (cells without any spot available) in the grid.
model	The model to which the space belongs.
neighborhood_type	The type of neighborhood to consider (moore, von_neumann, hexagonal).
random	The model's random number generator.
torus	If the grid is a torus (wraps around at the edges).

Methods:

__copy__	Create a shallow copy of the AgentContainer.
__deepcopy__	Create a deep copy of the AgentContainer.
__getattr__	Get the properties of the cells.
__getitem__	Get the properties and agents of the specified cells.
__init__	Create a new GridDF.
__repr__	Return a string representation of the SpaceDF.
__setitem__	Set the properties of the specified cells.
__str__	Return a string representation of the SpaceDF.
copy	Create a copy of the Class.
get_cells	Retrieve a dataframe of specified cells with their properties and agents.
get_directions	Return the directions from pos0 to pos1 or agents0 and agents1.
get_distances	Return the distances from pos0 to pos1 or agents0 and agents1.
get_neighborhood	Get the neighborhood cells from the given positions (pos) or agents according to the specified radiuses.
get_neighbors	Get the neighboring agents from given positions or agents according to the specified radiuses.
is_available	Check whether the input positions are available (there exists at least one remaining spot in the cells).
is_empty	Check whether the input positions are empty (there isn't any single agent in the cells).
is_full	Check whether the input positions are full (there isn't any spot available in the cells).
move_agents	Move agents in the Space to the specified coordinates.
move_to_available	Move agents to available cells/positions in the space (cells/positions where there is at least one spot available).
move_to_empty	Move agents to empty cells/positions in the space (cells/positions where there isn't any single agent).
out_of_bounds	Check if a position is out of bounds in a non-toroidal grid.
place_agents	Place agents in the space according to the specified coordinates.
place_to_empty	Place agents in empty cells/positions in the space (cells/positions where there isn't any single agent).
random_agents	Return a random sample of agents from the space.
random_pos	Return a random sample of positions from the space.
remove_agents	Remove agents from the space.
sample_cells	Sample cells from the grid according to the specified cell_type.
set_cells	Set the properties of the specified cells.
swap_agents	Swap the positions of the agents in the space.
torus_adj	Get the toroidal adjusted coordinates of a position.

property remaining_capacity: int

The remaining capacity of the cells in the grid.

Returns:

None if the capacity is infinite, otherwise the remaining capacity

Return type:

int | None

__copy__() → Self

Create a shallow copy of the AgentContainer.

Returns:

A shallow copy of the AgentContainer.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AgentContainer.

Parameters:

memo (dict) – A dictionary to store the copied objects.

Returns:

A deep copy of the AgentContainer.

Return type:

Self

__getattr__(key: str) → DataFrame | DataFrame

Get the properties of the cells.

Parameters:

key (str) – The property to get

Returns:

A DataFrame with the properties of the cells

Return type:

DataFrame

__getitem__(cells: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Get the properties and agents of the specified cells.

Parameters:

cells (DiscreteCoordinate | DiscreteCoordinates) – The cells to get the properties for

Returns:

A DataFrame with the properties and agents of the cells

Return type:

DataFrame

__init__(model: ModelDF, dimensions: Sequence[int], torus: bool = False, capacity: int | None = None, neighborhood_type: str = 'moore')

Create a new GridDF.

Parameters:

• model (ModelDF) – The model to which the space belongs

• dimensions (Sequence[int]) – The dimensions of the grid

• torus (bool, optional) – If the grid is a torus, by default False

• capacity (int | None, optional) – The maximum capacity for cells (default is infinite), by default None

• neighborhood_type (str, optional) – The type of neighborhood to consider, by default “moore”

__repr__() → str

Return a string representation of the SpaceDF.

Return type:

str

__setitem__(cells: int | DataFrame | DataFrame | Collection[int | DataFrame | DataFrame] | Sequence[int] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame], properties: DataFrame | DataFrame)

Set the properties of the specified cells.

Parameters:

• cells (DiscreteCoordinates) – The cells to set the properties for

• properties (DataFrame) – The properties to set

__str__() → str

Return a string representation of the SpaceDF.

Return type:

str

property agents: DataFrame | DataFrame

Get the ids of the agents placed in the cell set, along with their coordinates or geometries.

Return type:

DataFrame

property available_cells: DataFrame | DataFrame

Get the available cells (cells with at least one spot available) in the grid.

Returns:

A DataFrame with the available cells

Return type:

DataFrame

property cells: DataFrame | DataFrame

Obtain the properties and agents of the cells in the grid.

Returns:

A Dataframe with all cells, their properties and their agents

Return type:

DataFrame

copy(deep: bool = False, memo: dict | None = None, skip: list[str] | None = None) → Self

Create a copy of the Class.

Parameters:

• deep (bool, optional) – Flag indicating whether to perform a deep copy of the AgentContainer. If True, all attributes of the AgentContainer will be recursively copied (except attributes in self._copy_reference_only). If False, only the top-level attributes will be copied. Defaults to False.

• memo (dict | None, optional) – A dictionary used to track already copied objects during deep copy. Defaults to None.

• skip (list[str] | None, optional) – A list of attribute names to skip during the copy process. Defaults to None.

Returns:

A new instance of the AgentContainer class that is a copy of the original instance.

Return type:

Self

property dimensions: Sequence[int]

The dimensions of the grid.

They are set uniquely at the creation of the grid.

Returns:

The dimensions of the grid

Return type:

Sequence[int]

property empty_cells: DataFrame | DataFrame

Get the empty cells (cells without any agent) in the grid.

Returns:

A DataFrame with the empty cells

Return type:

DataFrame

property full_cells: DataFrame | DataFrame

Get the full cells (cells without any spot available) in the grid.

Returns:

A DataFrame with the full cells

Return type:

DataFrame

get_cells(coords: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None) → DataFrame | DataFrame

Retrieve a dataframe of specified cells with their properties and agents.

Parameters:

coords (DiscreteCoordinate | DiscreteCoordinates | None, optional) – The cells to retrieve. Default is None (all cells retrieved)

Returns:

A DataFrame with the properties of the cells and the agents placed in them.

Return type:

DataFrame

get_directions(pos0: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, pos1: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, normalize: bool = False) → DataFrame | DataFrame

Return the directions from pos0 to pos1 or agents0 and agents1.

If the space is a Network, the direction is the shortest path between the two nodes. In all other cases, the direction is the direction vector between the two positions. Either positions (pos0, pos1) or agents (agents0, agents1) must be specified, not both and they must have the same length.

Parameters:

• pos0 (SpaceCoordinate | SpaceCoordinates | None, optional) – The starting positions

• pos1 (SpaceCoordinate | SpaceCoordinates | None, optional) – The ending positions

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The starting agents

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The ending agents

• normalize (bool, optional) – Whether to normalize the vectors to unit norm. By default False

Returns:

A DataFrame where each row represents the direction from pos0 to pos1 or agents0 to agents1

Return type:

DataFrame

get_distances(pos0: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, pos1: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None) → DataFrame | DataFrame

Return the distances from pos0 to pos1 or agents0 and agents1.

If the space is a Network, the distance is the number of nodes of the shortest path between the two nodes. In all other cases, the distance is Euclidean/l2/Frobenius norm. You should specify either positions (pos0, pos1) or agents (agents0, agents1), not both and they must have the same length.

Parameters:

• pos0 (SpaceCoordinate | SpaceCoordinates | None, optional) – The starting positions

• pos1 (SpaceCoordinate | SpaceCoordinates | None, optional) – The ending positions

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The starting agents

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The ending agents

Returns:

A DataFrame where each row represents the distance from pos0 to pos1 or agents0 to agents1

Return type:

DataFrame

get_neighborhood(radius: int | Sequence[int] | ndarray | Series | Series | Sequence, pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] = None, include_center: bool = False) → DataFrame | DataFrame

Get the neighborhood cells from the given positions (pos) or agents according to the specified radiuses.

Either positions (pos) or agents must be specified, not both.

Parameters:

• radius (int | float | Sequence[int] | Sequence[float] | ArrayLike) – The radius(es) of the neighborhoods

• pos (DiscreteCoordinate | DiscreteCoordinates | None, optional) – The coordinates of the cell(s) to get the neighborhood from

• agents (IdsLike | AgentContainer | Collection[AgentContainer], optional) – The agent(s) to get the neighborhood from

• include_center (bool, optional) – If the cell in the center of the neighborhood should be included in the result, by default False

Returns:

A dataframe where

• Columns are called according to the coordinates of the space([‘dim_0’, ‘dim_1’, …] in Grids, [‘node_id’, ‘edge_id’] in Networks)

• Rows represent the coordinates of a neighboring cells

Return type:

DataFrame

get_neighbors(radius: int | Sequence[int], pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, include_center: bool = False) → DataFrame | DataFrame

Get the neighboring agents from given positions or agents according to the specified radiuses.

Either positions (pos0, pos1) or agents (agents0, agents1) must be specified, not both and they must have the same length.

Parameters:

• radius (int | float | Sequence[int] | Sequence[float] | ArrayLike) – The radius(es) of the neighborhood

• pos (SpaceCoordinate | SpaceCoordinates | None, optional) – The coordinates of the cell to get the neighborhood from, by default None

• agents (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The id of the agents to get the neighborhood from, by default None

• include_center (bool, optional) – If the center cells or agents should be included in the result, by default False

Returns:

A dataframe with neighboring agents. The columns with ‘_center’ suffix represent the center agent/position.

Return type:

DataFrame

Raises:

ValueError – If both pos and agent are None or if both pos and agent are not None.

is_available(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are available (there exists at least one remaining spot in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “available”

Return type:

DataFrame

is_empty(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are empty (there isn’t any single agent in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “empty”

Return type:

DataFrame

is_full(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are full (there isn’t any spot available in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “full”

Return type:

DataFrame

property model: ModelDF

The model to which the space belongs.

Return type:

‘ModelDF’

move_agents(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], pos: int | DataFrame | DataFrame | Sequence[int] | float | Sequence[float] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | Sequence[float | Sequence[float]] | Collection[float | Sequence[float] | DataFrame | DataFrame], inplace: bool = True) → Self

Move agents in the Space to the specified coordinates.

If some agents are not placed,raises a RuntimeWarning.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move

• pos (SpaceCoordinate | SpaceCoordinates) – The coordinates for each agents. The length of the coordinates must match the number of agents.

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Raises:

• RuntimeWarning – If some agents are not placed in the space.

• ValueError –

  • If some agents are not part of the model.

  • If agents is IdsLike and some agents are present multiple times.

Return type:

Self

move_to_available(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Move agents to available cells/positions in the space (cells/positions where there is at least one spot available).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move to available cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

move_to_empty(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Move agents to empty cells/positions in the space (cells/positions where there isn’t any single agent).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move to empty cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property neighborhood_type: Literal['moore', 'von_neumann', 'hexagonal']

The type of neighborhood to consider (moore, von_neumann, hexagonal).

It is set uniquely at the creation of the grid.

Return type:

Literal[‘moore’, ‘von_neumann’, ‘hexagonal’]

out_of_bounds(pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check if a position is out of bounds in a non-toroidal grid.

Parameters:

pos (GridCoordinate | GridCoordinates) – The position to check

Returns:

A DataFrame with the coordinates and an ‘out_of_bounds’ containing boolean values.

Return type:

DataFrame

Raises:

ValueError – If the grid is a torus

place_agents(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], pos: int | DataFrame | DataFrame | Sequence[int] | float | Sequence[float] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | Sequence[float | Sequence[float]] | Collection[float | Sequence[float] | DataFrame | DataFrame], inplace: bool = True) → Self

Place agents in the space according to the specified coordinates. If some agents are already placed, raises a RuntimeWarning.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to place in the space

• pos (SpaceCoordinate | SpaceCoordinates) – The coordinates for each agents. The length of the coordinates must match the number of agents.

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

Raises:

• RuntimeWarning – If some agents are already placed in the space.

• ValueError –

  • If some agents are not part of the model.

  • If agents is IdsLike and some agents are present multiple times.

place_to_empty(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Place agents in empty cells/positions in the space (cells/positions where there isn’t any single agent).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to place in empty cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property random: Generator

The model’s random number generator.

Return type:

Generator

random_agents(n: int) → DataFrame | DataFrame

Return a random sample of agents from the space.

Parameters:

n (int) – The number of agents to sample

Returns:

A DataFrame with the sampled agents

Return type:

DataFrame

random_pos(n: int) → DataFrame | DataFrame

Return a random sample of positions from the space.

Parameters:

n (int) – The number of positions to sample

Returns:

A DataFrame with the sampled positions

Return type:

DataFrame

remove_agents(agents: AgentContainer | Collection[AgentContainer] | int | Sequence[int], inplace: bool = True) → Self

Remove agents from the space.

Does not remove the agents from the model.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to remove from the space

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Raises:

ValueError – If some agents are not part of the model.

Return type:

Self

sample_cells(n: int, cell_type: Literal['any', 'empty', 'available', 'full'] = 'any', with_replacement: bool = True, respect_capacity: bool = True) → DataFrame | DataFrame

Sample cells from the grid according to the specified cell_type.

Parameters:

• n (int) – The number of cells to sample

• cell_type (Literal["any", "empty", "available", "full"], optional) – The type of cells to sample, by default “any”

• with_replacement (bool, optional) – If the sampling should be with replacement, by default True

• respect_capacity (bool, optional) – If the capacity of the cells should be respected in the sampling. This is only relevant if cell_type is “empty” or “available”, by default True

Returns:

A DataFrame with the sampled cells

Return type:

DataFrame

set_cells(cells: DataFrame | DataFrame | int | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame], properties: DataFrame | DataFrame | dict[str, Any] | None = None, inplace: bool = True) → Self

Set the properties of the specified cells.

This method mirrors the functionality of mesa’s PropertyLayer, but allows also to set properties only of specific cells. Either the cells DF must contain both the cells’ coordinates and the properties or the cells’ coordinates can be specified separately with the cells argument. If the Space is a Grid, the cell coordinates must be GridCoordinates. If the Space is a Network, the cell coordinates must be NetworkCoordinates.

Parameters:

• cells (DataFrame | DiscreteCoordinate | DiscreteCoordinates) – The cells to set the properties for. It can contain the coordinates of the cells or both the coordinates and the properties.

• properties (DataFrame | dict[str, Any] | None, optional) – The properties of the cells, by default None if the cells argument contains the properties

• inplace (bool) – Whether to perform the operation inplace

Return type:

Self

swap_agents(agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Swap the positions of the agents in the space.

agents0 and agents1 must have the same length and all agents must be placed in the space.

Parameters:

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer]) – The first set of agents to swap

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer]) – The second set of agents to swap

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property torus: bool

If the grid is a torus (wraps around at the edges).

Can be set uniquely at the creation of the grid.

Returns:

Whether the grid is a torus

Return type:

bool

torus_adj(pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Get the toroidal adjusted coordinates of a position.

Parameters:

pos (GridCoordinate | GridCoordinates) – The coordinates to adjust

Returns:

The adjusted coordinates

Return type:

DataFrame

class mesa_frames.GridPolars(model: ModelDF, dimensions: Sequence[int], torus: bool = False, capacity: int | None = None, neighborhood_type: str = 'moore')

The GridDF class is an abstract class that defines the interface for all grid classes in mesa-frames.

Inherits from DiscreteSpaceDF.

Attributes:

remaining_capacity	The remaining capacity of the cells in the grid.
agents	Get the ids of the agents placed in the cell set, along with their coordinates or geometries.
available_cells	Get the available cells (cells with at least one spot available) in the grid.
cells	Obtain the properties and agents of the cells in the grid.
dimensions	The dimensions of the grid.
empty_cells	Get the empty cells (cells without any agent) in the grid.
full_cells	Get the full cells (cells without any spot available) in the grid.
model	The model to which the space belongs.
neighborhood_type	The type of neighborhood to consider (moore, von_neumann, hexagonal).
random	The model's random number generator.
torus	If the grid is a torus (wraps around at the edges).

Methods:

__copy__	Create a shallow copy of the AgentContainer.
__deepcopy__	Create a deep copy of the AgentContainer.
__getattr__	Get the properties of the cells.
__getitem__	Get the properties and agents of the specified cells.
__init__	Create a new GridDF.
__repr__	Return a string representation of the SpaceDF.
__setitem__	Set the properties of the specified cells.
__str__	Return a string representation of the SpaceDF.
copy	Create a copy of the Class.
get_cells	Retrieve a dataframe of specified cells with their properties and agents.
get_directions	Return the directions from pos0 to pos1 or agents0 and agents1.
get_distances	Return the distances from pos0 to pos1 or agents0 and agents1.
get_neighborhood	Get the neighborhood cells from the given positions (pos) or agents according to the specified radiuses.
get_neighbors	Get the neighboring agents from given positions or agents according to the specified radiuses.
is_available	Check whether the input positions are available (there exists at least one remaining spot in the cells).
is_empty	Check whether the input positions are empty (there isn't any single agent in the cells).
is_full	Check whether the input positions are full (there isn't any spot available in the cells).
move_agents	Move agents in the Space to the specified coordinates.
move_to_available	Move agents to available cells/positions in the space (cells/positions where there is at least one spot available).
move_to_empty	Move agents to empty cells/positions in the space (cells/positions where there isn't any single agent).
out_of_bounds	Check if a position is out of bounds in a non-toroidal grid.
place_agents	Place agents in the space according to the specified coordinates.
place_to_empty	Place agents in empty cells/positions in the space (cells/positions where there isn't any single agent).
random_agents	Return a random sample of agents from the space.
random_pos	Return a random sample of positions from the space.
remove_agents	Remove agents from the space.
sample_cells	Sample cells from the grid according to the specified cell_type.
set_cells	Set the properties of the specified cells.
swap_agents	Swap the positions of the agents in the space.
torus_adj	Get the toroidal adjusted coordinates of a position.

property remaining_capacity: int

The remaining capacity of the cells in the grid.

Returns:

None if the capacity is infinite, otherwise the remaining capacity

Return type:

int | None

__copy__() → Self

Create a shallow copy of the AgentContainer.

Returns:

A shallow copy of the AgentContainer.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AgentContainer.

Parameters:

memo (dict) – A dictionary to store the copied objects.

Returns:

A deep copy of the AgentContainer.

Return type:

Self

__getattr__(key: str) → DataFrame | DataFrame

Get the properties of the cells.

Parameters:

key (str) – The property to get

Returns:

A DataFrame with the properties of the cells

Return type:

DataFrame

__getitem__(cells: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Get the properties and agents of the specified cells.

Parameters:

cells (DiscreteCoordinate | DiscreteCoordinates) – The cells to get the properties for

Returns:

A DataFrame with the properties and agents of the cells

Return type:

DataFrame

__init__(model: ModelDF, dimensions: Sequence[int], torus: bool = False, capacity: int | None = None, neighborhood_type: str = 'moore')

Create a new GridDF.

Parameters:

• model (ModelDF) – The model to which the space belongs

• dimensions (Sequence[int]) – The dimensions of the grid

• torus (bool, optional) – If the grid is a torus, by default False

• capacity (int | None, optional) – The maximum capacity for cells (default is infinite), by default None

• neighborhood_type (str, optional) – The type of neighborhood to consider, by default “moore”

__repr__() → str

Return a string representation of the SpaceDF.

Return type:

str

__setitem__(cells: int | DataFrame | DataFrame | Collection[int | DataFrame | DataFrame] | Sequence[int] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame], properties: DataFrame | DataFrame)

Set the properties of the specified cells.

Parameters:

• cells (DiscreteCoordinates) – The cells to set the properties for

• properties (DataFrame) – The properties to set

__str__() → str

Return a string representation of the SpaceDF.

Return type:

str

property agents: DataFrame | DataFrame

Get the ids of the agents placed in the cell set, along with their coordinates or geometries.

Return type:

DataFrame

property available_cells: DataFrame | DataFrame

Get the available cells (cells with at least one spot available) in the grid.

Returns:

A DataFrame with the available cells

Return type:

DataFrame

property cells: DataFrame | DataFrame

Obtain the properties and agents of the cells in the grid.

Returns:

A Dataframe with all cells, their properties and their agents

Return type:

DataFrame

copy(deep: bool = False, memo: dict | None = None, skip: list[str] | None = None) → Self

Create a copy of the Class.

Parameters:

• deep (bool, optional) – Flag indicating whether to perform a deep copy of the AgentContainer. If True, all attributes of the AgentContainer will be recursively copied (except attributes in self._copy_reference_only). If False, only the top-level attributes will be copied. Defaults to False.

• memo (dict | None, optional) – A dictionary used to track already copied objects during deep copy. Defaults to None.

• skip (list[str] | None, optional) – A list of attribute names to skip during the copy process. Defaults to None.

Returns:

A new instance of the AgentContainer class that is a copy of the original instance.

Return type:

Self

property dimensions: Sequence[int]

The dimensions of the grid.

They are set uniquely at the creation of the grid.

Returns:

The dimensions of the grid

Return type:

Sequence[int]

property empty_cells: DataFrame | DataFrame

Get the empty cells (cells without any agent) in the grid.

Returns:

A DataFrame with the empty cells

Return type:

DataFrame

property full_cells: DataFrame | DataFrame

Get the full cells (cells without any spot available) in the grid.

Returns:

A DataFrame with the full cells

Return type:

DataFrame

get_cells(coords: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None) → DataFrame | DataFrame

Retrieve a dataframe of specified cells with their properties and agents.

Parameters:

coords (DiscreteCoordinate | DiscreteCoordinates | None, optional) – The cells to retrieve. Default is None (all cells retrieved)

Returns:

A DataFrame with the properties of the cells and the agents placed in them.

Return type:

DataFrame

get_directions(pos0: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, pos1: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, normalize: bool = False) → DataFrame | DataFrame

Return the directions from pos0 to pos1 or agents0 and agents1.

If the space is a Network, the direction is the shortest path between the two nodes. In all other cases, the direction is the direction vector between the two positions. Either positions (pos0, pos1) or agents (agents0, agents1) must be specified, not both and they must have the same length.

Parameters:

• pos0 (SpaceCoordinate | SpaceCoordinates | None, optional) – The starting positions

• pos1 (SpaceCoordinate | SpaceCoordinates | None, optional) – The ending positions

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The starting agents

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The ending agents

• normalize (bool, optional) – Whether to normalize the vectors to unit norm. By default False

Returns:

A DataFrame where each row represents the direction from pos0 to pos1 or agents0 to agents1

Return type:

DataFrame

get_distances(pos0: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, pos1: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None) → DataFrame | DataFrame

Return the distances from pos0 to pos1 or agents0 and agents1.

If the space is a Network, the distance is the number of nodes of the shortest path between the two nodes. In all other cases, the distance is Euclidean/l2/Frobenius norm. You should specify either positions (pos0, pos1) or agents (agents0, agents1), not both and they must have the same length.

Parameters:

• pos0 (SpaceCoordinate | SpaceCoordinates | None, optional) – The starting positions

• pos1 (SpaceCoordinate | SpaceCoordinates | None, optional) – The ending positions

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The starting agents

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The ending agents

Returns:

A DataFrame where each row represents the distance from pos0 to pos1 or agents0 to agents1

Return type:

DataFrame

get_neighborhood(radius: int | Sequence[int] | ndarray | Series | Series | Sequence, pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] = None, include_center: bool = False) → DataFrame | DataFrame

Get the neighborhood cells from the given positions (pos) or agents according to the specified radiuses.

Either positions (pos) or agents must be specified, not both.

Parameters:

• radius (int | float | Sequence[int] | Sequence[float] | ArrayLike) – The radius(es) of the neighborhoods

• pos (DiscreteCoordinate | DiscreteCoordinates | None, optional) – The coordinates of the cell(s) to get the neighborhood from

• agents (IdsLike | AgentContainer | Collection[AgentContainer], optional) – The agent(s) to get the neighborhood from

• include_center (bool, optional) – If the cell in the center of the neighborhood should be included in the result, by default False

Returns:

A dataframe where

• Columns are called according to the coordinates of the space([‘dim_0’, ‘dim_1’, …] in Grids, [‘node_id’, ‘edge_id’] in Networks)

• Rows represent the coordinates of a neighboring cells

Return type:

DataFrame

get_neighbors(radius: int | Sequence[int], pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | None = None, agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer] | None = None, include_center: bool = False) → DataFrame | DataFrame

Get the neighboring agents from given positions or agents according to the specified radiuses.

Either positions (pos0, pos1) or agents (agents0, agents1) must be specified, not both and they must have the same length.

Parameters:

• radius (int | float | Sequence[int] | Sequence[float] | ArrayLike) – The radius(es) of the neighborhood

• pos (SpaceCoordinate | SpaceCoordinates | None, optional) – The coordinates of the cell to get the neighborhood from, by default None

• agents (IdsLike | AgentContainer | Collection[AgentContainer] | None, optional) – The id of the agents to get the neighborhood from, by default None

• include_center (bool, optional) – If the center cells or agents should be included in the result, by default False

Returns:

A dataframe with neighboring agents. The columns with ‘_center’ suffix represent the center agent/position.

Return type:

DataFrame

Raises:

ValueError – If both pos and agent are None or if both pos and agent are not None.

is_available(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are available (there exists at least one remaining spot in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “available”

Return type:

DataFrame

is_empty(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are empty (there isn’t any single agent in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “empty”

Return type:

DataFrame

is_full(pos: int | DataFrame | DataFrame | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check whether the input positions are full (there isn’t any spot available in the cells).

Parameters:

pos (DiscreteCoordinate | DiscreteCoordinates) – The positions to check for

Returns:

A dataframe with positions and a boolean column “full”

Return type:

DataFrame

property model: ModelDF

The model to which the space belongs.

Return type:

‘ModelDF’

move_agents(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], pos: int | DataFrame | DataFrame | Sequence[int] | float | Sequence[float] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | Sequence[float | Sequence[float]] | Collection[float | Sequence[float] | DataFrame | DataFrame], inplace: bool = True) → Self

Move agents in the Space to the specified coordinates.

If some agents are not placed,raises a RuntimeWarning.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move

• pos (SpaceCoordinate | SpaceCoordinates) – The coordinates for each agents. The length of the coordinates must match the number of agents.

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Raises:

• RuntimeWarning – If some agents are not placed in the space.

• ValueError –

  • If some agents are not part of the model.

  • If agents is IdsLike and some agents are present multiple times.

Return type:

Self

move_to_available(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Move agents to available cells/positions in the space (cells/positions where there is at least one spot available).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move to available cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

move_to_empty(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Move agents to empty cells/positions in the space (cells/positions where there isn’t any single agent).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to move to empty cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property neighborhood_type: Literal['moore', 'von_neumann', 'hexagonal']

The type of neighborhood to consider (moore, von_neumann, hexagonal).

It is set uniquely at the creation of the grid.

Return type:

Literal[‘moore’, ‘von_neumann’, ‘hexagonal’]

out_of_bounds(pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Check if a position is out of bounds in a non-toroidal grid.

Parameters:

pos (GridCoordinate | GridCoordinates) – The position to check

Returns:

A DataFrame with the coordinates and an ‘out_of_bounds’ containing boolean values.

Return type:

DataFrame

Raises:

ValueError – If the grid is a torus

place_agents(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], pos: int | DataFrame | DataFrame | Sequence[int] | float | Sequence[float] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame] | Sequence[float | Sequence[float]] | Collection[float | Sequence[float] | DataFrame | DataFrame], inplace: bool = True) → Self

Place agents in the space according to the specified coordinates. If some agents are already placed, raises a RuntimeWarning.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to place in the space

• pos (SpaceCoordinate | SpaceCoordinates) – The coordinates for each agents. The length of the coordinates must match the number of agents.

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

Raises:

• RuntimeWarning – If some agents are already placed in the space.

• ValueError –

  • If some agents are not part of the model.

  • If agents is IdsLike and some agents are present multiple times.

place_to_empty(agents: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Place agents in empty cells/positions in the space (cells/positions where there isn’t any single agent).

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to place in empty cells/positions

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property random: Generator

The model’s random number generator.

Return type:

Generator

random_agents(n: int) → DataFrame | DataFrame

Return a random sample of agents from the space.

Parameters:

n (int) – The number of agents to sample

Returns:

A DataFrame with the sampled agents

Return type:

DataFrame

random_pos(n: int) → DataFrame | DataFrame

Return a random sample of positions from the space.

Parameters:

n (int) – The number of positions to sample

Returns:

A DataFrame with the sampled positions

Return type:

DataFrame

remove_agents(agents: AgentContainer | Collection[AgentContainer] | int | Sequence[int], inplace: bool = True) → Self

Remove agents from the space.

Does not remove the agents from the model.

Parameters:

• agents (IdsLike | AgentContainer | Collection[AgentContainer]) – The agents to remove from the space

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Raises:

ValueError – If some agents are not part of the model.

Return type:

Self

sample_cells(n: int, cell_type: Literal['any', 'empty', 'available', 'full'] = 'any', with_replacement: bool = True, respect_capacity: bool = True) → DataFrame | DataFrame

Sample cells from the grid according to the specified cell_type.

Parameters:

• n (int) – The number of cells to sample

• cell_type (Literal["any", "empty", "available", "full"], optional) – The type of cells to sample, by default “any”

• with_replacement (bool, optional) – If the sampling should be with replacement, by default True

• respect_capacity (bool, optional) – If the capacity of the cells should be respected in the sampling. This is only relevant if cell_type is “empty” or “available”, by default True

Returns:

A DataFrame with the sampled cells

Return type:

DataFrame

set_cells(cells: DataFrame | DataFrame | int | Sequence[int] | Collection[int | DataFrame | DataFrame] | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame], properties: DataFrame | DataFrame | dict[str, Any] | None = None, inplace: bool = True) → Self

Set the properties of the specified cells.

This method mirrors the functionality of mesa’s PropertyLayer, but allows also to set properties only of specific cells. Either the cells DF must contain both the cells’ coordinates and the properties or the cells’ coordinates can be specified separately with the cells argument. If the Space is a Grid, the cell coordinates must be GridCoordinates. If the Space is a Network, the cell coordinates must be NetworkCoordinates.

Parameters:

• cells (DataFrame | DiscreteCoordinate | DiscreteCoordinates) – The cells to set the properties for. It can contain the coordinates of the cells or both the coordinates and the properties.

• properties (DataFrame | dict[str, Any] | None, optional) – The properties of the cells, by default None if the cells argument contains the properties

• inplace (bool) – Whether to perform the operation inplace

Return type:

Self

swap_agents(agents0: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], agents1: int | Collection[int] | Series | Index | Series | AgentContainer | Collection[AgentContainer], inplace: bool = True) → Self

Swap the positions of the agents in the space.

agents0 and agents1 must have the same length and all agents must be placed in the space.

Parameters:

• agents0 (IdsLike | AgentContainer | Collection[AgentContainer]) – The first set of agents to swap

• agents1 (IdsLike | AgentContainer | Collection[AgentContainer]) – The second set of agents to swap

• inplace (bool, optional) – Whether to perform the operation inplace, by default True

Return type:

Self

property torus: bool

If the grid is a torus (wraps around at the edges).

Can be set uniquely at the creation of the grid.

Returns:

Whether the grid is a torus

Return type:

bool

torus_adj(pos: int | Sequence[int] | DataFrame | DataFrame | Sequence[int | slice | Sequence[int]] | Collection[int | Sequence[int] | DataFrame | DataFrame]) → DataFrame | DataFrame

Get the toroidal adjusted coordinates of a position.

Parameters:

pos (GridCoordinate | GridCoordinates) – The coordinates to adjust

Returns:

The adjusted coordinates

Return type:

DataFrame