Model

class ambr.model.Model(parameters: Dict[str, Any])

Bases: BaseModel

Base class for all simulation models, using DataFrames for data storage.

add_agent(agent: Agent)

Add a single agent. Prefer add_agents() for bulk creation.

add_agents(n: int, *, agent_class: Type | None = None, **columns: Any)

Bulk-create n agents with columnar initial state:

self.add_agents(100, wealth=self.nprandom.integers(1, 10, 100),
                     status='S')

Scalar kwargs broadcast; list / np.ndarray / pl.Series values must have length n. Pass agent_class= to also spin up Python instances so AgentList.call and per-agent iteration work.

property agents_df: DataFrame

batch_update_agents(agent_ids: list, data: dict)

Batch update multiple agents at once for better performance.

Parameters:

• agent_ids – List of agent IDs to update

• data – Dictionary of column names and values (or lists of values)

end()

get_agent_data(agent_id: Any) → DataFrame

Return a 1-row DataFrame with the current state of agent_id.

record(key: str, value: Any)

AgentPy compatibility alias for record_model.

record_model(key: str, value: Any)

Record a model-level variable for the current step.

run(steps: int | None = None) → Dict[str, DataFrame]

run_step() → None

Execute one simulation step. The first call also runs setup.

setup()

step()

update()

Update model state after each step.

update_agent_data(agent_id: int, data: Dict[str, Any])

Update data for a single agent.

The Model class is the foundation of any AMBER simulation. It provides the framework for:

• Managing simulation time and execution

• Storing and updating agent data

• Recording model-level metrics

• Coordinating agent behaviors

Basic Usage

import ambr as am

class MyModel(am.Model):
    def setup(self):
        # Initialize agents and environment
        pass

    def step(self):
        # Define what happens each time step
        pass

# Run the model
model = MyModel({'steps': 100, 'seed': 42})
results = model.run()

Key Methods

Lifecycle Methods:

• setup() - Called once at the beginning to initialize the model

• step() - Called each time step to update agent states

• update() - Called after step() to update model state

• end() - Called once at the end of the simulation

Data Management:

• add_agent(agent) - Add a new agent to the model

• update_agent_data(agent_id, data) - Update data for a specific agent

• get_agent_data(agent_id) - Retrieve data for a specific agent

• record_model(name, value) - Record a model-level metric

Execution:

• run() - Execute the full simulation and return results

• run_step() - Execute a single time step