API Reference

This section provides detailed documentation for all AMBER classes, functions, and modules.

Core Components

• Model
  • Write architecture (single source of truth = Polars agents_df)
  • Model
  • Basic Usage
  • Key Methods
• Agent
  • Agent
  • Basic Usage
  • Custom Agent Classes
  • Agent Properties
• Population Managers
  • Population
  • BatchUpdateContext
• Environments
  • Environment
  • GridEnvironment
  • NetworkEnvironment
  • Position
  • SpaceEnvironment
  • Grid Environment
  • Space Environment
  • Network Environment
• Sequences
  • AgentList
  • FilteredAgentList
  • ScatterAgentList
  • Features

Utilities

• Optimization
  • MultiObjectiveSMAC
  • ParameterSpace
  • SMACOptimizer
  • SMACParameterSpace
  • bayesian_optimization()
  • grid_search()
  • objective_function()
  • random_search()
  • Parameter Space
  • Optimization Functions
• Experiment
  • Experiment
  • IntRange
  • Sample
  • Experiment Class
  • Sample Class
  • IntRange Class
• Base Classes
  • AttrDict
  • BaseAgent
  • BaseModel
  • NPRandomCompat
  • BaseModel
  • BaseAgent
• Run results
  • RunResults
• Performance utilities
  • Flags
  • Scatter helpers (vectorized write path)
  • Spatial & parallel

Advanced (0.4 / 0.4.1 / 0.4.3 / 0.4.4)

• Snapshot-view contract
  • Write paths the monitor sees
• Tensor lane
  • Design goals
  • Version invariance
  • TensorLane
  • borrow_numeric()
  • commit_columns()
• Speed lanes
  • Status & recommendations
  • Array kernel model
• GPU backend
  • Native placement
  • Array module
• GPU batched ensemble
  • BatchedWellMixedSIR
  • GPUEnsembleRunner
  • smac_batch_calibrate()

Quick Reference

Core Classes:

• ambr.Model - Base class for all agent-based models

• ambr.Agent - Individual agent with behaviors and properties

• ambr.BaseAgent - Abstract base class for custom agents

• ambr.BaseModel - Abstract base class for custom models

• ambr.Population - SoA memory manager for high-performance state handling

• ambr.RunResults - Dict-like model.run() result with attribute access

Environments:

• ambr.GridEnvironment - 2D grid-based spatial environment

• ambr.SpaceEnvironment - Continuous 2D space environment

• ambr.NetworkEnvironment - Graph/network-based environment

Data Structures:

• ambr.AgentList - List-like container for agents with additional functionality

Optimization:

• ambr.grid_search() - Exhaustive parameter space search

• ambr.random_search() - Random parameter sampling

• ambr.bayesian_optimization() - Bayesian optimization of model parameters

Experiments:

• ambr.Experiment - Framework for running multiple model configurations

• ambr.Sample - Parameter sampling for experiments

• ambr.IntRange - Integer range specification for parameters

Snapshot-view contract (0.4 / 0.4.4):

• ambr.contract.ContractCertificate - Per-step operational monitor record from model.run(contract=...) (not a schedule proof)

Tensor lane (0.4):

• ambr.tensor_lane.borrow_numeric() - Zero-copy borrow of a numeric column

• ambr.tensor_lane.commit_columns() - Atomic write-back of derived columns

Speed lanes (0.4.1):

• ambr.print_status() / ambr.recommend() - machine/lane status and hints

• ambr.ArrayKernelModel - single-run CuPy/NumPy array model

• Optional pip install 'ambr[perf]' (Numba) for CPU scatter JIT

Device placement & lanes (0.4.3 / 0.4.4):

• ambr.Model.cpu() / ambr.Model.gpu() - Keras-style placement; step_vectorized / step_oop dispatch (GPU is vectorized-only; see GPU backend, Going faster (lanes))

• ambr.Model.approve_fast_path() / ambr.Model.revoke_fast_path_approval() - opt-in private GPU loop with caller-supplied evidence label

• ambr.EXECUTION_DEVICES / EXECUTION_MODES / ExecutionConfig - placement constants (package exports)

GPU & calibration (0.4):

• ambr.gpu.get_array_module() - Resolve the CuPy/NumPy array module

• ambr.GPUEnsembleRunner - Batched (B × N) ensemble runner (NumPy fallback in CI)

• ambr.BatchedWellMixedSIR - Reference well-mixed SIR batched model

• ambr.smac_batch_calibrate() - SMAC calibration over a batched ensemble