Spaces

Grid Space

class econsimulacra.spaces.base.GridSpace(config, registered_classes, prng)

Bases: object

Grid space containing agents and extensible cell information.

Parameters:

• config (dict[str, Any])

• registered_classes (list[Type])

• prng (Random)

get_space_size()

Get the shape of the grid space.

Parameters:

None.

Returns:

The dimensions of the grid space.

Return type:

tuple[int, …]

Note

The returned tuple is immutable.

get_cell(pos)

Get cell information at a position.

Parameters:

pos (tuple[int, ...]) – Position whose cell information is requested.

Returns:

A safe copy of the effective cell information.

Return type:

Cell

Note

Positions without explicit overrides inherit default_cell.

get_cell_attrs(pos)

Get arbitrary attributes at a position.

Parameters:

pos (tuple[int, ...]) – Position whose attributes are requested.

Returns:

A shallow copy of the cell attribute mapping.

Return type:

dict[str, Any]

Note

Mutating the returned dictionary does not mutate the grid. Use update_cell_attrs for runtime interventions.

update_cell_access(pos, traversable=None, spawnable=None)

Update built-in access controls at a position.

Parameters:

• pos (tuple[int, ...]) – Position to update.

• traversable (Optional[bool]) – New traversal permission, or None to keep the current value.

• spawnable (Optional[bool]) – New initial-placement permission, or None to keep the current value.

Returns:

None.

Return type:

None

Note

This method supports interventions such as temporary road closures. Existing agents at the position are not displaced.

update_cell_attrs(pos, updates)

Merge arbitrary attributes into a cell.

Parameters:

• pos (tuple[int, ...]) – Position to update.

• updates (Mapping[str, Any]) – Attribute names and replacement values.

Returns:

None.

Return type:

None

Note

Attribute values are deliberately not interpreted by GridSpace.

can_spawn(agent_id, pos)

Determine whether an agent may initially spawn at a position.

Parameters:

• agent_id (int) – ID of the agent being placed.

• pos (tuple[int, ...]) – Candidate initial position.

Returns:

Whether the cell permits initial placement.

Return type:

bool

Note

The base implementation only checks CellAccess.spawnable. Subclasses may use agent_id and arbitrary attributes to add rules.

can_enter(agent_id, current_pos, new_pos)

Determine whether an agent may enter a position.

Parameters:

• agent_id (Optional[int]) – ID of the moving agent when available.

• current_pos (tuple[int, ...]) – Position from which the agent moves.

• new_pos (tuple[int, ...]) – Candidate destination position.

Returns:

Whether the candidate cell permits traversal.

Return type:

bool

Note

The base implementation only checks CellAccess.traversable. The other arguments are extension points for agent-specific rules.

iter_neighbors(agent_id, pos)

Yield positions reachable by one geometric movement.

Parameters:

• agent_id (Optional[int]) – ID of the moving agent when available.

• pos (tuple[int, ...]) – Position whose neighbors are requested.

Returns:

In-bounds neighboring positions.

Return type:

Iterable[tuple[int, …]]

Note

The base implementation uses a Moore neighborhood to preserve the existing diagonal movement behavior. Subclasses may override it for mobility-specific neighborhoods.

get_spawnable_positions(agent_id)

Collect valid initial-position candidates for an agent.

Parameters:

agent_id (int) – ID of the agent being placed.

Returns:

Spawnable cells satisfying colocation settings.

Return type:

list[tuple[int, …]]

Note

When initial colocation is disabled, occupied positions are excluded.

get_pos(agent_id)

Get an agent’s current position.

Parameters:

agent_id (int) – ID of the agent whose position is requested.

Returns:

The agent’s current position.

Return type:

tuple[int, …]

Note

ValueError is raised when the agent is not in this space.

get_agents(pos)

Get agent IDs at a position.

Parameters:

pos (tuple[int, ...]) – Position to inspect.

Returns:

A copy of the agent IDs at the position.

Return type:

set[int]

Note

Returning a copy prevents callers from mutating spatial indexes.

place_agent(agent_id, pos)

Place an agent at an explicit or randomly selected initial position.

Parameters:

• agent_id (int) – ID of the agent to place.

• pos (Optional[tuple[int, ...]]) – Explicit position, or None to choose uniformly from currently valid spawnable candidates.

Returns:

None.

Return type:

None

Note

Both explicit and random placement respect spawnable and allowInitialColocatedAgents.

get_colocated_agents(agent_id)

Get other agents sharing an agent’s current position.

Parameters:

agent_id (int) – ID of the reference agent.

Returns:

IDs of other agents at the same position.

Return type:

set[int]

Note

The reference agent is excluded from the returned set.

get_near_agents(center_pos, max_distance=1)

Get agent IDs within a Manhattan-distance radius.

Parameters:

• center_pos (tuple[int, ...]) – Center of the query.

• max_distance (int) – Inclusive maximum Manhattan distance.

Returns:

IDs of agents within the specified radius.

Return type:

set[int]

Note

For compatibility, the center must currently contain at least one agent. max_distance must be non-negative.

get_nearby_info(agent_id, max_distance=1)

Get a mapping of nearby positions to their cell information.

Parameters:

• agent_id (int) – ID of the reference agent.

• max_distance (int) – Inclusive maximum Manhattan distance.

Returns:

Mapping from positions to cell information.

Return type:

dict[Position, Cell]

Note

The reference agent’s position is included. max_distance must be non-negative.

remove_agent(agent_id)

Remove an agent from the grid space.

Parameters:

agent_id (int) – ID of the agent to remove.

Returns:

None.

Return type:

None

Note

The recorded initial position is retained for compatibility with movement-history consumers.

move_agent(agent_id, new_pos)

Move an agent directly to a traversable position.

Parameters:

• agent_id (int) – ID of the agent to move.

• new_pos (tuple[int, ...]) – Position to enter.

Returns:

None.

Return type:

None

Note

This low-level operation validates bounds and traversal access but does not require adjacency and does not reject colocated agents.

move_many_agents(agent_id2new_pos)

Move multiple agents after validating every target position.

Parameters:

agent_id2new_pos (dict[int, tuple[int, ...]]) – Mapping from agent IDs to direct movement targets.

Returns:

None.

Return type:

None

Note

Validation occurs before mutation to avoid partial updates. Colocation is intentionally allowed during movement.

calc_next_pos(current_pos, destination_pos, velocity=1, agent_id=None)

Calculate the next position along a shortest traversable path.

Parameters:

• current_pos (tuple[int, ...]) – Current agent position.

• destination_pos (tuple[int, ...]) – Requested destination position.

• velocity (int) – Maximum number of path edges traversed this step.

• agent_id (int, optional) – ID used by custom access and neighbor rules.

Returns:

The position reached this step, or None

when no traversable path exists.

Return type:

Optional[tuple[int, …]]

Note

velocity must be a positive integer. Intermediate cells remain part of the path, so higher velocity cannot skip over obstacles.

calc_next_path(current_pos, destination_pos, velocity=1, agent_id=None)

Calculate the path segment traversed during the current step.

Parameters:

• current_pos (tuple[int, ...]) – Current agent position.

• destination_pos (tuple[int, ...]) – Requested destination position.

• velocity (int) – Maximum number of path edges traversed this step.

• agent_id (int, optional) – ID used by custom access and neighbor rules.

Returns:

Path segment including the current

position, or None when no traversable path exists.

Return type:

Optional[list[tuple[int, …]]]

Note

Returning the segment lets callers calculate exact per-cell resource consumption while calc_next_pos preserves its existing interface.