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: where / at / set / scatter_add — do not mutate agents.array(...) in place on CPU

  • Snapshot-view contract: opt-in operational monitor (not a schedule proof; default off)

  • CPU acceleration: optional Numba (pip install 'ambr[perf]') — recommended on Mac / no-CUDA

  • Device placement: Keras-style model.cpu(mode=...).run() / model.gpu().run() (GPU is vectorized-only, NVIDIA + CuPy only — not Apple Metal/MPS); see Going faster (lanes)

  • GPU ensemble: GPUEnsembleRunner for many short runs; parallelism is never automatic from a single .run()

  • OOP activation helpers: activate_agents("random"|"sequential"|"simultaneous")

  • Viz helpers: plot_timeseries / plot_grid (ambr[viz])

  • Environments: grid, continuous space, and network topologies

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

  • RunResults: attribute or dict access; save / load

  • Reproducible: seeded self.rng; see Reproducibility policy

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: GPU when NVIDIA+CuPy available, else CPU vectorized
model = WealthModel({'steps': 50, 'seed': 42, 'show_progress': False})
if am.GPU_AVAILABLE:
    results = model.gpu().run()
else:
    results = model.cpu(mode="vectorized").run()
print(results.info)
print(results.model.tail(3).to_dicts())       # also results['model']
print(am.recommend(10_000))

For more examples, check the examples/ directory in the repository. See Changelog for 0.5.0 (step-data integrity, versioned RunResults, strict optimization, extras / first-run honesty; GPU claims verified locally). Earlier 0.4.x notes: 0.4.7 label scrub; 0.4.6 doc-fence CI / RunResults I/O / 1.0 prep; 0.4.5 ambr[gpu]; 0.4.4 lanes and the operational contract.

Table of Contents

User Guide

API Reference

Development

Indices and tables