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 Model: Full Chapter 3 implementation: firms, households, and banks interacting across labor, credit, and goods markets
• ECS Architecture: Entity-Component-System design separates data (Roles) from behavior (Events) for clean extensibility
• Vectorized Performance: All agent operations use NumPy arrays; no Python loops over agents
• Built-in Extensions: R&D / Growth+, buffer-stock consumption, and taxation modules
• Validation Framework: Three scenario validators with scoring and robustness analysis
• Calibration Pipeline: Morris screening, grid search, and tiered stability testing
• Easy Configuration: All parameters configurable without code changes via YAML files

Architecture

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

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.