https://github.com/kganitis/bam-engine
Implementation of the BAM macroeconomic agent-based model in Python using ECS architecture.
https://github.com/kganitis/bam-engine
agent-based-modeling agent-based-simulation computational-economics economics economics-models ecs macroeconomics numpy
Last synced: 3 months ago
JSON representation
Implementation of the BAM macroeconomic agent-based model in Python using ECS architecture.
- Host: GitHub
- URL: https://github.com/kganitis/bam-engine
- Owner: kganitis
- License: mit
- Created: 2025-04-24T15:21:48.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-06-11T10:22:19.000Z (4 months ago)
- Last Synced: 2025-06-11T11:39:22.386Z (4 months ago)
- Topics: agent-based-modeling, agent-based-simulation, computational-economics, economics, economics-models, ecs, macroeconomics, numpy
- Language: Python
- Homepage:
- Size: 558 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# BAM-Engine (Work in Progress)
A high-performance Python implementation of the BAM model from *Macroeconomics from the Bottom-Up* (Delli Gatti et al., 2011).
---
### Architecture
**Entity–Component–System (ECS)** architecture optimized for large-scale agent-based modeling:
* **Entities** – Economic actors (firms, households, banks) are represented as integer indices, eliminating object overhead
* **Components** – Immutable NumPy dataclass containers in `bamengine.components` hold pure state (e.g., `Producer`, `Worker`, `Lender`) with zero business logic
* **Systems** – Vectorized functions in `bamengine.systems.*` implement economic behavior through efficient in-place mutations
* **Simulation** – `bamengine.Simulation` orchestrates the simulation lifecycle. Basic public API that enables one-liner usage:
```python
import bamengine as be
# Configure and run simulation
sim = be.Simulation.init(n_firms=100, n_households=500, n_banks=10)
sim.run(n_periods=1000) # or sim.step() for single-period control
```
---
### Technologies
**Minimal, high-performance stack:**
* **Python 3.10+** – Fully type-annotated with `py.typed` for downstream type checking
* **NumPy** – Dense arrays and vectorized operations for maximum computational efficiency
* **PyYAML** – Declarative configuration system (`defaults.yml` + user overrides)
**Zero heavyweight dependencies** – No pandas, no complex frameworks. Pure scientific Python for predictable performance and easy deployment.
---
### Current Status
**Version 0.0.0 – Experimental proof-of-concept**
##### Implemented
* Complete BAM model systems with comprehensive unit tests
* Efficient vectorized kernels handling thousands of agents on standard hardware
* Validated output replicating key results from the original paper
* Extensive logging infrastructure for debugging and analysis
##### Limitations
* Public API restricted to basic `Simulation` interface
* Monolithic simulation design limits extensibility
* Hard-coded logging integration across systems
* Minimal documentation and examples
---
### Roadmap
##### Research
* Replicate **all** figures and empirical results from *Macroeconomics from the Bottom-Up*
* Comprehensive performance profiling and optimization
##### Engineering
* Achieve >95% test coverage across all modules
* Implement structured, configurable logging system
* Refactor monolithic `Simulation` into modular, plugin-based architecture with clean separation of concerns
##### Usage
* Comprehensive API documentation with examples
* End-to-end Jupyter notebook tutorials
* Production-ready packaging and distribution