Population Managers

The Population class is the central engine of AMBER’s high-performance architecture. It implements the Structure of Arrays (SoA) memory layout using Polars DataFrames and provides the interface for vectorized state updates.

Population

class ambr.population.Population(schema: Dict[str, Type] = None)

Bases: object

Manages the columnar state of all agents using Polars DataFrames. Acts as the single point of truth for agent data.

add_agent(agent_id: int, step: int = 0, **attributes)

Adds a single agent to the population.

batch_add_agents(count: int, step: int = 0, **attributes)

Adds multiple agents efficiently.

batch_update(updates: Dict[str, ndarray | list], selector: Expr | None = None)

Updates columns for all agents (or a filtered subset).

batch_update_by_ids(ids: list | ndarray, data: Dict[str, list | ndarray | Any])

Updates specific agents identified by IDs.

create_batch_context()

Legacy batched-update context manager.

Deprecated since version Prefer: the vectorized view API: model.agents.at[ids].col = values or model.agents.at[ids].scatter_add(col=delta). The view API flushes through the same hash-join path but is discoverable via attribute access rather than a context manager.

get_agent_value(agent_id: int, column: str) → Any

set_agent_value(agent_id: int, column: str, value: Any)

Sets a value for a single agent. Very slow if used in loops.

property size: int

BatchUpdateContext

class ambr.population.BatchUpdateContext(population: Population)

Bases: object

Context manager for buffering updates to minimize DataFrame copies.

add_update(agent_id: int, col: str, val: Any)