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.

Prefer writing through the model/view API (model.agents.col = ..., agents.set(...), agents.commit(...), or Model._set_frame) so the snapshot-view contract can observe commits. Assigning population.data = ... still works but is deprecated and invisible to Model.run(contract=...); use the view API instead.

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)

Deprecated: use agents.set(**cols) or agents.where(...).set(...).

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

Deprecated: use agents.at[ids].set(**data).

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.

property data: DataFrame

Read the agent table (single system of record).

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

replace_frame(df: DataFrame) → None

Replace the table without deprecation (Model write path only).

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

Deprecated: use agent.<col> = value or agents.at[id].col = value.

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)