Getting Started#

BAM Engine is a high-performance Python implementation of the BAM (Bottom-Up Adaptive Macroeconomics) agent-based model. It simulates three types of agents (households, firms, banks) interacting in three markets (labor, credit, consumption goods).

The purpose of this guide is to illustrate the main features of BAM Engine. Please refer to our installation instructions to install BAM Engine, or jump to the Next steps section for additional resources.

Running your first simulation#

BAM Engine provides a simple API for running macroeconomic simulations. The main entry point is the Simulation class, which can be initialized with init():

>>> import bamengine as bam
>>> sim = bam.Simulation.init(seed=42)
>>> sim
<Simulation: 100 firms, 500 households, 10 banks>

The init() method accepts various parameters to configure the simulation. The seed parameter ensures reproducibility.

Once initialized, run the simulation for a number of periods using run():

>>> results = sim.run(n_periods=100)
>>> import numpy as np
>>> print(f"Final unemployment rate: {np.mean(~sim.wrk.employed):.2%}")
Final unemployment rate: 4.20%

The simulation executes a sequence of events each period: firms plan production, workers seek jobs, banks provide credit, goods are produced and sold, and bankrupt agents are replaced.

Collecting and analyzing results#

The run() method returns a SimulationResults object by default, containing time series data collected during the simulation:

>>> results.n_periods
100
>>> results["Economy.unemployment_rate"]  # array of unemployment rates
array([0.052, 0.048, 0.044, ...])

If you have pandas installed, you can export results to DataFrames for analysis:

>>> df_economy = results.to_dataframe("economy")
>>> df_economy[["unemployment_rate", "avg_price"]].head()
   unemployment_rate  avg_price
0              0.052      1.024
1              0.048      1.031
2              0.044      1.028
...

You can also export agent-level data:

>>> df_firms = results.to_dataframe("firms")
>>> df_households = results.to_dataframe("households")

Configuration#

Simulations can be customized through parameters passed to init():

>>> sim = bam.Simulation.init(
...     n_firms=200,
...     n_households=1000,
...     n_banks=15,
...     seed=42
... )

For more complex configurations, you can use a YAML file:

# config.yml
n_firms: 200
n_households: 1000
n_banks: 15
h_rho: 0.10  # production growth shock cap

>>> sim = bam.Simulation.init(config="config.yml", seed=42)

Keyword arguments always take precedence over YAML configuration, allowing you to override specific parameters:

>>> sim = bam.Simulation.init(config="config.yml", n_firms=200, seed=42)

See the Configuration Guide for a full list of parameters.

Accessing simulation state#

The simulation maintains agent state in roles - data structures holding arrays of agent attributes. You can access roles directly or via getter methods:

>>> # Direct access via shortcuts
>>> sim.prod.price       # firm prices (Producer role)
>>> sim.wrk.wage         # worker wages (Worker role)
>>> sim.lend.equity_base # bank equity (Lender role)

>>> # Or via getter method
>>> producer = sim.get_role("Producer")
>>> producer.price
array([1.02, 0.98, 1.05, ...])

Available role shortcuts:

  • sim.prod - Producer (firms): prices, inventory, production

  • sim.emp - Employer (firms): wages, labor, vacancies

  • sim.bor - Borrower (firms): net worth, debt, credit demand

  • sim.wrk - Worker (households): wages, employment status

  • sim.con - Consumer (households): income, savings

  • sim.sh - Shareholder (households): dividend tracking

  • sim.lend - Lender (banks): equity, interest rates, credit supply

Economy-wide metrics are available through sim.ec:

>>> sim.ec.avg_mkt_price          # average market price
>>> np.mean(~sim.wrk.employed)    # unemployment rate (from Worker.employed)

Next steps#

This guide covered the basics of running simulations, collecting results, configuring parameters, and accessing agent state. There is much more to BAM Engine!

  • User Guide - Detailed documentation on all features

  • Extensions - R&D, buffer-stock, and taxation extensions

  • Examples - Worked examples demonstrating various use cases

  • API Reference - Complete API documentation