AMBER Documentation

AMBER (Agent-based Modeling with Blazingly Efficient Records) is a powerful Python framework for building and running agent-based models. It provides a comprehensive toolkit for researchers and practitioners to create complex simulations with ease.

CI Status Coverage PyPI Version Python Versions

Features

  • AgentPy-shaped OOP + vectorized lanes on the same model (see Coming from AgentPy and Going faster (lanes))

  • Vectorized view API: update the whole population in a handful of Polars expressions — no per-agent loops, regardless of population size

  • Snapshot-view contract: opt-in operational monitor at instrumented write/borrow seams (not a schedule proof; zero-overhead default is off)

  • CPU acceleration: optional Numba (pip install 'ambr[perf]') for scatter_add / subset writes — recommended on Mac without CUDA

  • Device placement (0.4.4): Keras-style model.cpu(mode=...).run() / model.gpu().run() with step_vectorized / step_oop hooks (GPU is vectorized-only; device-resident columns); see Going faster (lanes)

  • GPU ensemble: CuPy array helpers with NumPy fallback, plus a batched ensemble that runs B simulations in one device pass for calibration

  • Flexible environments: grid, continuous space, and network topologies

  • Optimization: grid / random / Bayesian (SMAC) search and GPU-batched calibration

  • Declarative reporting & typed params: model_reporters / agent_reporters and a class-level params schema

  • Reproducible: one canonical seeded RNG (self.rng); deterministic runs

  • RunResults: results.agents and results['agents'] both work

Quick Start

Install AMBER using pip:

pip install ambr

Create your first model:

import ambr as am

class WealthModel(am.Model):
    # Declarative per-step metric -> results['model'].
    model_reporters = {'total_wealth': lambda m: int(m.agents.wealth.sum())}

    def setup(self):
        # Bulk-create the population in one columnar write — no per-agent loop.
        self.add_agents(100, wealth=self.rng.integers(1, 10, size=100))

    def step_vectorized(self):
        # Every agent with wealth > 0 gives $1 to a random other agent.
        donors = self.agents.where(self.agents.wealth > 0)
        donors.wealth -= 1
        recipients = self.rng.choice(self.agents.ids.to_numpy(), size=len(donors))
        self.agents.at[recipients].scatter_add(wealth=1)

# Fluent placement (default mode is vectorized; run(mode=...) still overrides)
model = WealthModel({'steps': 50, 'seed': 42})
results = model.cpu(mode="vectorized").run()
# Vectorized lane on GPU (NVIDIA + CuPy):  model.gpu().run()
print(results.model)       # also results['model']
print(am.recommend(10_000))

For more examples, check the examples/ directory in the repository. See Changelog for what is new in 0.4.4 (honest lanes, operational contract, approve_fast_path).

Table of Contents

User Guide

API Reference

Development

Indices and tables