Environments

Environment implementations for AMBER framework. Supports different types of spatial and network topologies.

class ambr.environments.Environment(model)

Bases: ABC

Base class for all environments.

property df: DataFrame

The model’s current agent DataFrame (always fresh).

abstractmethod get_distance(agent1_id: int, agent2_id: int) → float

Calculate distance between two agents.

abstractmethod get_neighbors(agent_id: int) → List[int]

Get neighboring agents for a given agent.

abstractmethod move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new position.

class ambr.environments.GridEnvironment(model, size: int | Tuple[int, ...], torus: bool = False, wrap: bool | None = None)

Bases: Environment

N-dimensional grid environment with discrete positions.

add_agent(agent, pos) → None

Place an Agent (or raw id) at pos.

add_agent_from_id(agent_id: int, pos) → None

Place (or move) agent agent_id onto pos (must be empty or same agent).

empty_positions() → List[Tuple[int, int]]

Return a list of empty positions.

get_agent_at_pos(pos) → int | None

Return the agent id at pos, or None if empty / unknown.

get_distance(pos1_or_agent1, pos2_or_agent2) → float

Calculate Manhattan distance between two positions or agents.

get_empty_cells_in_radius(pos, radius: int) → List[Tuple]

Empty cells within Chebyshev distance radius of pos (excl. pos).

get_neighbors(position_or_agent_id, include_diagonal=False, distance=1, radius: int | None = None)

Get neighboring positions or agents.

Parameters:

• position_or_agent_id – Either a position tuple or agent ID

• include_diagonal – Whether to include diagonal neighbors

• distance – Maximum Chebyshev/orthogonal distance for neighbors

• radius – Alias for distance; when set, also enables diagonal (Moore) neighbourhood — common Schelling-style usage.

get_random_empty_cell() → Tuple[int, ...] | None

Return a random unoccupied cell, or None if the grid is full.

property height

Get grid height (second dimension if it exists).

is_valid_position(position)

Check if a position is valid in the grid.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new grid position.

property positions

Get all possible positions in the grid.

random_position()

Get a random position in the grid.

remove_agent_from_pos(pos) → int | None

Clear occupancy at pos. Returns the agent id that was there, if any.

property width

Get grid width (first dimension).

property wrap

Deprecated alias for torus.

class ambr.environments.NetworkEnvironment(model, graph: Graph | None = None)

Bases: Environment

Graph-based network environment.

add_edge(node1_or_agent1, node2_or_agent2, **attr) → None

Add an edge between two nodes or agents.

add_node(node_id, **attr)

Add a node to the network.

property edges

Get all edges in the network.

get_clustering(node_or_agent_id=None)

Get clustering coefficient for a node, agent, or the entire network.

get_degree(node_or_agent_id)

Get the degree of a node or agent.

get_distance(node1_or_agent1, node2_or_agent2) → float

Calculate shortest path distance between two nodes or agents.

get_neighbors(node_or_agent_id) → List[int]

Get neighboring nodes or agents in the network.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new node in the network.

property nodes

Get all nodes in the network.

random_node()

Get a random node from the network.

remove_edge(node1_or_agent1, node2_or_agent2) → None

Remove an edge between two nodes or agents.

remove_node(node_id)

Remove a node from the network.

class ambr.environments.Position(coordinates: Tuple[float, ...], topology_type: str)

Bases: object

Represents a position in any topology.

coordinates: Tuple[float, ...]

topology_type: str

class ambr.environments.SpaceEnvironment(model, bounds: List[Tuple[float, float]], torus: bool = False)

Bases: Environment

N-dimensional continuous space environment.

get_distance(pos1_or_agent1, pos2_or_agent2) → float

Calculate Euclidean distance between two positions or agents.

get_neighbors(pos_or_agent_id, radius: float) → List[int]

Get agents within radius of a position or an agent (vectorized).

Replaces the former per-row Python loop / map_elements scan with a single numpy pass, plus an optional scipy KD-tree for large populations. Semantics are preserved: the queried agent is included (distance 0 <= radius) and agents without a position are skipped.

is_valid_position(position)

Check if a position is within bounds.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new continuous position.

positions_array()

Return (ids, positions) over agents that have a position set.

ids is shape (M,), positions is (M, d). The single place the tuple-valued space_position column is unpacked into a contiguous matrix for vectorized distance queries.

random_position()

Get a random position within bounds.

set_position(agent_ids, coords) → None

Vectorized position write for many agents at once.

agent_ids is shape (M,); coords is (M, d) (or (d,) for a single agent). A bulk alternative to repeated move_agent().

AMBER provides several built-in environment types for different spatial and network topologies.

Grid Environment

class ambr.GridEnvironment(model, size: int | Tuple[int, ...], torus: bool = False, wrap: bool | None = None)

Bases: Environment

N-dimensional grid environment with discrete positions.

add_agent(agent, pos) → None

Place an Agent (or raw id) at pos.

add_agent_from_id(agent_id: int, pos) → None

Place (or move) agent agent_id onto pos (must be empty or same agent).

empty_positions() → List[Tuple[int, int]]

Return a list of empty positions.

get_agent_at_pos(pos) → int | None

Return the agent id at pos, or None if empty / unknown.

get_distance(pos1_or_agent1, pos2_or_agent2) → float

Calculate Manhattan distance between two positions or agents.

get_empty_cells_in_radius(pos, radius: int) → List[Tuple]

Empty cells within Chebyshev distance radius of pos (excl. pos).

get_neighbors(position_or_agent_id, include_diagonal=False, distance=1, radius: int | None = None)

Get neighboring positions or agents.

Parameters:

• position_or_agent_id – Either a position tuple or agent ID

• include_diagonal – Whether to include diagonal neighbors

• distance – Maximum Chebyshev/orthogonal distance for neighbors

• radius – Alias for distance; when set, also enables diagonal (Moore) neighbourhood — common Schelling-style usage.

get_random_empty_cell() → Tuple[int, ...] | None

Return a random unoccupied cell, or None if the grid is full.

property height

Get grid height (second dimension if it exists).

is_valid_position(position)

Check if a position is valid in the grid.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new grid position.

property positions

Get all possible positions in the grid.

random_position()

Get a random position in the grid.

remove_agent_from_pos(pos) → int | None

Clear occupancy at pos. Returns the agent id that was there, if any.

property width

Get grid width (first dimension).

property wrap

Deprecated alias for torus.

The GridEnvironment provides a 2D grid-based space where agents can be positioned and move around.

Usage:

# Create a 10x10 grid
grid = am.GridEnvironment(model, size=(10, 10))

# Place an agent
position = grid.random_position()
agent.position = position

# Get neighbors
neighbors = grid.get_neighbors(position)

Space Environment

class ambr.SpaceEnvironment(model, bounds: List[Tuple[float, float]], torus: bool = False)

Bases: Environment

N-dimensional continuous space environment.

get_distance(pos1_or_agent1, pos2_or_agent2) → float

Calculate Euclidean distance between two positions or agents.

get_neighbors(pos_or_agent_id, radius: float) → List[int]

Get agents within radius of a position or an agent (vectorized).

Replaces the former per-row Python loop / map_elements scan with a single numpy pass, plus an optional scipy KD-tree for large populations. Semantics are preserved: the queried agent is included (distance 0 <= radius) and agents without a position are skipped.

is_valid_position(position)

Check if a position is within bounds.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new continuous position.

positions_array()

Return (ids, positions) over agents that have a position set.

ids is shape (M,), positions is (M, d). The single place the tuple-valued space_position column is unpacked into a contiguous matrix for vectorized distance queries.

random_position()

Get a random position within bounds.

set_position(agent_ids, coords) → None

Vectorized position write for many agents at once.

agent_ids is shape (M,); coords is (M, d) (or (d,) for a single agent). A bulk alternative to repeated move_agent().

The SpaceEnvironment provides continuous 2D space with configurable boundaries.

Usage:

# Create continuous space
space = am.SpaceEnvironment(model, bounds=[(0, 100), (0, 100)])

# Place an agent
position = (25.5, 37.2)
agent.position = position

# Get neighbors within radius
neighbors = space.get_neighbors(position, radius=5.0)

Network Environment

class ambr.NetworkEnvironment(model, graph: Graph | None = None)

Bases: Environment

Graph-based network environment.

add_edge(node1_or_agent1, node2_or_agent2, **attr) → None

Add an edge between two nodes or agents.

add_node(node_id, **attr)

Add a node to the network.

property edges

Get all edges in the network.

get_clustering(node_or_agent_id=None)

Get clustering coefficient for a node, agent, or the entire network.

get_degree(node_or_agent_id)

Get the degree of a node or agent.

get_distance(node1_or_agent1, node2_or_agent2) → float

Calculate shortest path distance between two nodes or agents.

get_neighbors(node_or_agent_id) → List[int]

Get neighboring nodes or agents in the network.

move_agent(agent_id: int, new_position: Position) → None

Move an agent to a new node in the network.

property nodes

Get all nodes in the network.

random_node()

Get a random node from the network.

remove_edge(node1_or_agent1, node2_or_agent2) → None

Remove an edge between two nodes or agents.

remove_node(node_id)

Remove a node from the network.

The NetworkEnvironment provides graph-based topology for agent interactions.

Usage:

import networkx as nx

# Create network from NetworkX graph
G = nx.erdos_renyi_graph(100, 0.1)
network = am.NetworkEnvironment(model, G)

# Place agent on node
agent.node = 42

# Get connected neighbors
neighbors = network.get_neighbors(42)