Environments

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

class ambr.environments.Environment(model)[source]

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[source]: Calculate distance between two agents.

abstractmethod get_neighbors(agent_id: int) → List[int][source]: Get neighboring agents for a given agent.

abstractmethod move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new position.

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

Bases: Environment

N-dimensional grid environment with discrete positions.

empty_positions() → List[Tuple[int, int]][source]: Return a list of empty positions.

get_distance(pos1_or_agent1, pos2_or_agent2) → float[source]: Calculate Manhattan distance between two positions or agents.

get_neighbors(position_or_agent_id, include_diagonal=False, distance=1)[source]

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 distance for neighbors

property height: Get grid height (second dimension if it exists).

is_valid_position(position)[source]: Check if a position is valid in the grid.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new grid position.

property positions: Get all possible positions in the grid.

random_position()[source]: Get a random position in the grid.

property width: Get grid width (first dimension).

class ambr.environments.NetworkEnvironment(model, graph: Graph | None = None)[source]

Bases: Environment

Graph-based network environment.

add_edge(node1_or_agent1, node2_or_agent2, **attr) → None[source]: Add an edge between two nodes or agents.

add_node(node_id, **attr)[source]: Add a node to the network.

property edges: Get all edges in the network.

get_clustering(node_or_agent_id=None)[source]: Get clustering coefficient for a node, agent, or the entire network.

get_degree(node_or_agent_id)[source]: Get the degree of a node or agent.

get_distance(node1_or_agent1, node2_or_agent2) → float[source]: Calculate shortest path distance between two nodes or agents.

get_neighbors(node_or_agent_id) → List[int][source]: Get neighboring nodes or agents in the network.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new node in the network.

property nodes: Get all nodes in the network.

random_node()[source]: Get a random node from the network.

remove_edge(node1_or_agent1, node2_or_agent2) → None[source]: Remove an edge between two nodes or agents.

remove_node(node_id)[source]: Remove a node from the network.

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

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)[source]

Bases: Environment

N-dimensional continuous space environment.

get_distance(pos1_or_agent1, pos2_or_agent2) → float[source]: Calculate Euclidean distance between two positions or agents.

get_neighbors(pos_or_agent_id, radius: float) → List[int][source]: Get neighboring agents within radius.

is_valid_position(position)[source]: Check if a position is within bounds.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new continuous position.

random_position()[source]: Get a random position within bounds.

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)[source]

Bases: Environment

N-dimensional grid environment with discrete positions.

empty_positions() → List[Tuple[int, int]][source]: Return a list of empty positions.

get_distance(pos1_or_agent1, pos2_or_agent2) → float[source]: Calculate Manhattan distance between two positions or agents.

get_neighbors(position_or_agent_id, include_diagonal=False, distance=1)[source]

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 distance for neighbors

property height: Get grid height (second dimension if it exists).

is_valid_position(position)[source]: Check if a position is valid in the grid.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new grid position.

property positions: Get all possible positions in the grid.

random_position()[source]: Get a random position in the grid.

property width: Get grid width (first dimension).

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)[source]

Bases: Environment

N-dimensional continuous space environment.

get_distance(pos1_or_agent1, pos2_or_agent2) → float[source]: Calculate Euclidean distance between two positions or agents.

get_neighbors(pos_or_agent_id, radius: float) → List[int][source]: Get neighboring agents within radius.

is_valid_position(position)[source]: Check if a position is within bounds.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new continuous position.

random_position()[source]: Get a random position within bounds.

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)[source]

Bases: Environment

Graph-based network environment.

add_edge(node1_or_agent1, node2_or_agent2, **attr) → None[source]: Add an edge between two nodes or agents.

add_node(node_id, **attr)[source]: Add a node to the network.

property edges: Get all edges in the network.

get_clustering(node_or_agent_id=None)[source]: Get clustering coefficient for a node, agent, or the entire network.

get_degree(node_or_agent_id)[source]: Get the degree of a node or agent.

get_distance(node1_or_agent1, node2_or_agent2) → float[source]: Calculate shortest path distance between two nodes or agents.

get_neighbors(node_or_agent_id) → List[int][source]: Get neighboring nodes or agents in the network.

move_agent(agent_id: int, new_position: Position) → None[source]: Move an agent to a new node in the network.

property nodes: Get all nodes in the network.

random_node()[source]: Get a random node from the network.

remove_edge(node1_or_agent1, node2_or_agent2) → None[source]: Remove an edge between two nodes or agents.

remove_node(node_id)[source]: 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)