bamengine 0.10.0

A modular Python framework for the BAM agent-based macroeconomic model

A Modular Python Framework for the BAM Agent-Based Macroeconomic Model

A Python implementation of the BAM (Bottom-Up Adaptive Macroeconomics) model from Macroeconomics from the Bottom-up (Delli Gatti et al., 2011). It runs simulations of individual workers, firms, and banks making decisions and interacting in labor, credit and goods markets, letting macroeconomic patterns (growth, unemployment, inflation, business cycles) emerge from the bottom up, instead of assuming them with aggregate equations.

bamengine.org • Documentation • Getting Started • Examples

Note: This release is feature-complete for the core BAM model but APIs may change in future releases before v1.0.0.

Quick Start

pip install bamengine

Requirements: Python 3.11+. NumPy and PyYAML are installed automatically.

import bamengine as bam

# Initialize and run simulation
sim = bam.Simulation.init(n_firms=100, n_households=500, seed=42)
results = sim.run(n_periods=100)

# Access results
results["Economy.inflation"]  # 1D array (n_periods,)
results.Producer.price  # 2D array (n_periods, n_firms)

# Export to pandas DataFrame
df = results.to_dataframe()

# Add extensions with one call
from extensions.rnd import RND

sim = bam.Simulation.init(seed=42)
sim.use(RND)
results = sim.run(n_periods=1000)

See the Getting Started guide for a complete walkthrough.

Features

• Complete BAM Implementation: Baseline model from Macroeconomics from the Bottom-up, Chapter 3 (firms, households, and banks across labor, credit, and goods markets), three built-in extensions (R&D / Growth+, buffer-stock consumption, taxation), and a robustness analysis suite (internal validity, sensitivity, structural experiments).
• Vectorized Performance: Agent state lives in parallel NumPy arrays and behavior is expressed as array transformations, not Python loops over agent objects. Simulations scale to large populations and long horizons.
• Pluggable Extension System: Add custom roles, events, and pipeline hooks via decorators without modifying the engine. The same mechanism powers the built-in extensions.
• Parameter Calibration: Automated pipeline for tuning model parameters against validation targets.

Architecture

BAM Engine uses an ECS (Entity-Component-System) architecture: agents are lightweight entities, state lives in Role components stored as parallel NumPy arrays, and behavior is defined by Event systems composed into a YAML-configurable pipeline. New roles, events, and relationships can be added through decorators, without modifying core code.

The trade-off is a mindset shift: you write agent rules as systems that transform whole arrays of state at once, not as methods on per-agent objects. ECS itself does not demand vectorization, but BAM Engine treats it as the default. Every built-in system processes all agents at once, with the goods market's sequential matching rounds as the deliberate exception where strict per-agent ordering matters.

See the User Guide for a full walkthrough of the model and its architecture.

Documentation

Full documentation is available at bam-engine.readthedocs.io.

Section	Description
Getting Started	Installation, first simulation, data collection
User Guide	Model overview, configuration, custom roles/events, pipelines, best practices
API Reference	Complete reference for all components and operations
Examples	16 runnable examples: basic, advanced, and extensions
Extensions	R&D / Growth+, buffer-stock consumption, taxation
Validation	Scenario validation, scoring, robustness analysis
Calibration	Morris screening, grid search, stability testing

Development

git clone https://github.com/kganitis/bam-engine.git
pip install -e ".[dev]"
pytest
ruff format . && ruff check --fix . && mypy

This project is part of ongoing MSc thesis research at the University of Piraeus, Greece. Code contributions will be welcome after thesis submission. In the meantime, bug reports, feedback, and documentation suggestions are appreciated via the issue tracker.

See the Development Guide for more on testing, linting, benchmarking, and contributing.

Citation

If you use BAM Engine in your research, please cite:

1. This software - Use CITATION.cff or GitHub's "Cite this repository"
2. The original BAM model - Delli Gatti, D., Desiderio, S., Gaffeo, E., Cirillo, P., & Gallegati, M. (2011). Macroeconomics from the Bottom-up. Springer. DOI: 10.1007/978-88-470-1971-3

License

MIT License - see LICENSE for details.