AMBER (Agent-based Modeling with Blazingly Efficient Records)

AMBER is a Python framework for agent-based modeling that uses Polars for efficient data handling and analysis. AMBER provides a clean, robust API for creating parallel, high-performance simulations in Python.

🚀 Performance

AMBER stores the entire population as a columnar Polars DataFrame and exposes a vectorized view API (agents.where(...), agents.at[ids], scatter_add) that compiles per-step updates down to a handful of columnar operations. Models can provide step_vectorized() and step_oop() for explicit native lanes; legacy models with only step() keep the fallback. The vectorized lane runs on GPU via model.gpu().run().

Headline comparison (committed evidence)

Source of truth for the README table:
benchmarks/results/benchmark_results_snapshot_correct_10run_10m.json
(summary: summary_table_snapshot_correct_10run_10m.md).

Protocol: NVIDIA RTX 5090; 10M agents; 50 steps; 10 runs retained (no outlier deletion); one untimed warm-up per cell; timed scope = construct + setup + step loop + result assembly. AMBER GPU synchronizes after the run; FLAME GPU 2 returns at a simulation-complete boundary. This is an implementation comparison under that protocol — not a claim of byte-identical dynamics across frameworks.

AMBER (GPU) vs FLAME GPU 2 at 10M agents (mean wall-clock):

• Wealth / walk / SIR are the comparable headline class (~1.8–2.1×).
• Schelling includes heavy Python-side setup inside the timed region for the FLAME harness; do not treat ~63× as a pure step-kernel speedup.
• Multi-framework scale-out charts (Mesa, mesa-frames, Agents.jl, …) are exploratory and live under benchmarks/results/; some cells OOM or hit budgets — missing cells are not zeros.
• Reproducer: benchmarks/run_all_frameworks.py.
  Correctness gates: benchmarks/correctness_check.py.
  Details: benchmarks/README.md.

API: implement step_vectorized() (or legacy step()); place with .cpu(mode="vectorized") or .gpu(). GPU is vectorized-only. Private optimized GPU loops require an explicit approve_fast_path(evidence) label (caller-attested provenance; AMBER checks presence of the label, not the evidence content) and contract="off" — see docs/going_faster.rst.

🚀 Quick Start

AMBER supports an AgentPy-shaped OOP lane and a vectorized lane on the same model. Start with whichever feels natural.

AgentPy-shaped (method broadcast, AgentList):

import ambr as am

class WealthAgent(am.Agent):
    def setup(self):
        self.wealth = 1
    def transfer(self):
        if self.wealth > 0:
            other = self.model.agents.by_id(self.model.agents.random())
            other.wealth += 1
            self.wealth -= 1

class WealthModel(am.Model):
    def setup(self):
        self.agents = am.AgentList(self, self.p.n, WealthAgent)
    def step(self):
        self.agents.transfer()
    def update(self):
        self.record_model('total', int(self.agents.wealth.sum()))

results = WealthModel({'n': 50, 'steps': 20, 'seed': 1}).run()
print(results.model)      # also results['model']
print(results.agents.head())

Vectorized (columnar; best at large N):

import ambr as am

class WealthModel(am.Model):
    model_reporters = {'total_wealth': lambda m: int(m.agents.wealth.sum())}

    def setup(self):
        self.add_agents(100, wealth=self.rng.integers(1, 10, size=100))

    def step_vectorized(self):
        xp = self.xp
        wealth = self.agents.array("wealth")
        donors = xp.nonzero(wealth > 0)[0]
        if int(donors.size) == 0:
            return
        wealth[donors] -= 1
        recipients = self.rng.choice(
            self.agents.array("id"), size=int(donors.size)
        )
        self.agents.at[recipients].scatter_add(wealth=1)

# Fluent placement (0.4.4): device + optional mode; run(mode=...) still overrides.
results = WealthModel({'steps': 100, 'seed': 42}).cpu(mode="vectorized").run()
# Vectorized lane on GPU (device-resident columns; needs NVIDIA + CuPy):
# results = WealthModel({'steps': 100, 'seed': 42}).gpu().run()
print(results.model.tail(5))
print(results.agents.head(10))

Coming from AgentPy? See docs/from_agentpy.rst.

Going faster / GPU — same Model class; pick placement and lane hooks (see docs/going_faster.rst):

import ambr as am
am.print_status()                 # GPU? which lane?
print(am.recommend(1_000_000))  # one-line suggestion

# Native path: step_vectorized + .gpu() (or .cpu(mode="vectorized"))
model = WealthModel({"n": 100_000, "steps": 50, "seed": 0})
results = model.gpu().run()                    # or .cpu(mode="vectorized").run()

# Array-kernel lane (CuPy if available, else NumPy) for pure array state:
class Drift(am.ArrayKernelModel):
    def init_state(self, xp, n, rng, p):
        return {"x": rng.random(n, dtype=xp.float32)}
    def step_state(self, xp, state, rng, p):
        state["x"] = state["x"] + 0.01
        return state
    def metrics(self, xp, state):
        return {"mean_x": float(am.to_host(state["x"].mean()))}

print(Drift({"n": 100_000, "steps": 20}).run().info)

self.rng is the canonical seeded RNG (a NumPy Generator); self.random is the stdlib one. Both are seeded from the seed parameter. Progress printing is off by default (show_progress=True to re-enable).

New in 0.4.4: honest execution lanes (step_vectorized / step_oop; GPU is vectorized-only), operational contract wording (monitor, not schedule proof), and opt-in approve_fast_path(evidence) for private GPU loops. See the changelog.

0.4.3: Keras-style model.cpu(mode=...) / model.gpu() placement with device-resident columns for the vectorized view API.

0.4.1: AgentPy-shaped UX (RunResults, agents.random()), progressive speed lanes (am.print_status(), am.recommend(n), ArrayKernelModel), optional Numba CPU path (pip install 'ambr[perf]' — great on Mac), contract / write-path hardening, SMAC install pin, and Schelling grid helpers.

0.4: runtime snapshot-view contract, GPU backend + batched calibration, one canonical verb per task (legacy spellings still work), declarative model_reporters, and a typed params schema.

0.3.0: Setting agent.wealth = 5 on a Python Agent automatically syncs to the DataFrame. You can freely mix OOP-style and vectorized access without desync.

⚡ Vectorized View API

The view API compiles per-step updates to a handful of Polars expressions — regardless of population size:

def step(self):
    # Bulk columnar reads/writes over the entire population
    self.agents.x = self.agents.x + self.rng.uniform(-1, 1, len(self.agents))

    # Filtered writes: only agents matching a condition
    infected = self.agents.where(self.agents.status == 1)
    infected.infection_time += 1

    # scatter_add: flow-of-resources with duplicate-id safety
    self.agents.at[[1, 1, 3]].scatter_add(wealth=1)  # agent 1 gets +2, agent 3 gets +1

🧭 Canonical API (0.4)

AMBER 0.4 settles on one obvious verb per task. The legacy spellings still work (they emit a DeprecationWarning and are scheduled for removal in 1.0); set AMBER_SUPPRESS_DEPRECATIONS=1 to silence them in benchmark / reproducibility runs. Batch performance comes from these verbs (columnar writes), not from extra public batch_* helpers.

update() is a pure hook — overriding it no longer requires super().update(). Declare model_reporters / agent_reporters for declarative metrics, and set record_initial = True to capture a t=0 row.

🔒 Snapshot-view contract

Whether a vectorized refactor preserves an intended update schedule is a semantic question. AMBER's runtime monitor reports selected operational hazards at instrumented API seams; it does not prove schedule equivalence for arbitrary NumPy, CuPy, or user-kernel code. Run with a contract mode and inspect the per-step records:

results = model.run(steps=100, contract="check")   # "off" | "check" | "warn" | "raise"
for cert in results["contract"]:
    if not cert.ok:
        print(cert.step, cert.violations)

check records a ContractCertificate per step; warn also emits a warning per violation; raise stops on the first error. Mode off (default) adds no monitor bookkeeping. cert.clean means that no monitored error or warning was observed, not that every possible activation order is equivalent.

The monitor watches two write paths (and combinations):

• Buffered (OOP) — agent.col = … / queued cell writes
• Lane / view — agents.col = …, agents.set(...), borrow/commit
• Cross-path — same column via both OOP and view in one step → cross_path_write
• Mutable raw arrays — agents.array(...) → uncertified_mutable_borrow

scatter_add is the sanctioned multi-write reducer (not treated as a conflicting ordinary commit). Prefer those APIs over assigning population.data directly.

🎮 GPU backend & batched calibration

Single-run (native, 0.4.4): place a vectorized model on device with model.gpu().run(). Prefer step_vectorized() (legacy step() still works). Numeric columns stay device-resident for the run. Contract modes use the instrumented general path; private model-specific fast loops run only with contract="off" and an explicit per-instance approve_fast_path(evidence) declaration. The evidence string is a caller-supplied provenance label, not something AMBER verifies. Without it, gpu().run() uses the general path. Private loops are not covered by the monitor. OOP agents use cpu(mode="oop") — not GPU.

# Same WealthModel as the vectorized quickstart
results = WealthModel({"n": 1_000_000, "steps": 50, "seed": 0}).gpu().run()
# Switch back: model.cpu(mode="vectorized").run(...)
# Private fast loop (only if the model defines one; evidence is not verified):
# model.approve_fast_path("my-bench-label").gpu().run(contract="off")

Many short runs (calibration): the ensemble axis (B simulations × N agents) batches into one device pass — the natural fit when you evaluate thousands of small replicate runs:

from ambr.gpu_ensemble import GPUEnsembleRunner, BatchedWellMixedSIR, smac_batch_calibrate

# Evaluate B parameter sets in one (B, N) GPU pass
runner = GPUEnsembleRunner(BatchedWellMixedSIR())
traj = runner.run(n_agents=100_000, steps=60,
                  params={"beta": betas, "gamma": gammas, "i0_frac": i0})  # -> {metric: (B, steps)}

# SMAC ask -> one batched GPU evaluation -> tell
best, history = smac_batch_calibrate(BatchedWellMixedSIR(), bounds, loss_fn,
                                     n_agents=100_000, steps=60)

ambr.gpu provides the array-module abstraction (get_array_module, to_device, to_host) and falls back to NumPy when CuPy is unavailable. Requires NVIDIA GPU + CuPy (not Apple Metal/MPS).

🔬 Optimization

AMBER includes powerful optimization capabilities for parameter tuning:

from ambr.optimization import ParameterSpace, grid_search

# Define parameter space
parameter_space = ParameterSpace({
    'agents': [10, 50, 100],
    'initial_value': [1, 5, 10],
    'steps': 100
})

# Run optimization
results = grid_search(MyModel, parameter_space, 'some_metric')
best_params = results[0]['parameters']

Beyond grid_search, AMBER ships random_search, bayesian_optimization (SMAC Gaussian-process), and SMACOptimizer (random-forest surrogate) — plus the GPU batched ensemble above for derivative-free calibration at scale.

📦 Installation

pip install ambr

# Optional extras
pip install 'ambr[perf]'       # Numba CPU scatter (recommended on Mac)
pip install 'ambr[advanced]'   # SMAC optimization

import ambr as am
print(am.__version__)   # 0.4.4+
am.print_status()

🏗️ Features

• Simple API: AgentPy-shaped OOP lane + vectorized columnar views on one model
• High Performance: Polars DataFrames; optional Numba (ambr[perf]) for scatters
• Device placement: Keras-style model.cpu(mode=...) / model.gpu() with step_vectorized / step_oop hooks (GPU is vectorized-only)
• Speed lanes: am.print_status() / am.recommend(n) / ArrayKernelModel
• Snapshot-view monitor: operational diagnostics for observed write/borrow conflicts and uncertified mutable arrays (not a schedule proof)
• GPU backend: native vectorized path + optional approved private loops + CuPy helpers + batched ensemble for calibration
• Optimization: grid / random / Bayesian (SMAC) search, plus GPU-batched calibration
• Declarative reporting: model_reporters / agent_reporters and a typed params schema
• Environments: Support for grid, network, and continuous space environments
• Experiments: Run multiple simulations with parameter sampling
• Random Number Generation: Reproducible simulations with controlled randomness
• RunResults: results.agents and results['agents'] both work

📚 Examples

Working examples are available in the examples/ directory:

• Schelling (grid) — examples/schelling_vectorized.py (canonical occupancy helpers)
• Wealth Transfer — economic inequality / dual-lane quickstart
• Virus Spread — epidemiological SIR model
• Flocking — Boids + optional tensor-lane variant
• Forest Fire — cellular automata fire spread
• GPU quickstart — model.gpu().run() on a view-API model, or ArrayKernelModel
• SMAC calibration — basic / advanced Schelling multi-objective

📖 Documentation

• Docs: https://ambr.readthedocs.io/
• Paper: https://arxiv.org/abs/2601.16292
• Going faster (lanes / Numba / GPU): docs/going_faster.rst
• Environments & Schelling: docs/environments_schelling.rst
• From AgentPy: docs/from_agentpy.rst
• Deprecations (→ 1.0): docs/deprecations.rst
• Changelog: CHANGELOG.md

📝 How to cite?

If you use AMBER in academic work, please cite the paper:

@article{pham2026amber,
  title={AMBER: A Columnar Architecture for High-Performance Agent-Based Modeling in Python},
  author={Pham, Anh-Duy},
  journal={arXiv preprint arXiv:2601.16292},
  year={2026}
}

Paper: https://arxiv.org/abs/2601.16292

For the software, this repository also ships CITATION.cff (GitHub “Cite this repository”). Manuscript drafts and build artifacts are not kept in the library tree — only the public paper citation and software metadata.

🤝 Contributing

We welcome contributions! See docs/contributing.rst (or the Contributing page on Read the Docs).

📄 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.