Simulation#

Main simulation facade for BAM Engine.

This module provides the Simulation class, the primary interface for running BAM (Bottom-Up Adaptive Macroeconomics) simulations. The Simulation class manages the economy state, agent roles, event pipeline, and provides methods for stepping through periods.

Key Features#

Three-tier configuration precedence (defaults → user config → kwargs)
Deterministic random number generation with seed control
Event pipeline with explicit ordering and YAML configuration
Getter methods for roles, events, and relationships (case-insensitive)
In-place state mutation for memory efficiency
Built-in logging configuration at global and per-event levels

Classes#

Simulation: Main simulation facade for initializing and running BAM simulations.

See also

config: Configuration dataclass and validation
core: Event and Pipeline infrastructure
roles: Agent role components (Producer, Worker, etc.)
events: Event classes wrapping system functions

Examples

Basic simulation with default configuration:

>>> import bamengine as bam
>>> sim = bam.Simulation.init(seed=42)
>>> sim.run(n_periods=100)
>>> unemployment = np.mean(~sim.wrk.employed)

Custom configuration via YAML file:

>>> sim = bam.Simulation.init(config="my_config.yml", seed=42)
>>> sim.run(n_periods=100)

Override specific parameters via kwargs:

>>> sim = bam.Simulation.init(n_firms=200, n_households=1000, seed=42)
>>> sim.run(n_periods=100)

Step-by-step execution with intermediate analysis:

>>> sim = bam.Simulation.init(seed=42)
>>> for period in range(100):
...     sim.step()
...     if period % 10 == 0:
...         print(f"Period {period}: Unemployment = {np.mean(~sim.wrk.employed):.2%}")

The bamengine.simulation module provides the main interface for running BAM simulations.

Classes#

`Simulation`	Main simulation facade for BAM Engine.
`SimulationResults`	Container for simulation results with convenient data access methods.

Key Methods#

Simulation Methods

`Simulation.init`	Create a new Simulation instance with validated configuration.
`Simulation.run`	Run the simulation for multiple periods.
`Simulation.step`	Execute one simulation period through the event pipeline.
`Simulation.get_role`	Get role instance by name.
`Simulation.get_event`	Get event instance from pipeline by name.
`Simulation.get_relationship`	Get relationship instance by name.
`Simulation.use`	Apply an extension bundle to the simulation.
`Simulation.use_role`	Instantiate and attach a custom role to the simulation.
`Simulation.use_relationship`	Register a custom relationship class.
`Simulation.use_events`	Apply event hooks to the simulation pipeline.
`Simulation.use_config`	Apply extension default configuration.

Results Methods

`SimulationResults.to_dataframe`	Export results to a pandas DataFrame.
`SimulationResults.get_role_data`	Get data for a specific role as a DataFrame.
`SimulationResults.get_array`	Deprecated: use `get()` instead.
`SimulationResults.data`	Unified access to all data (roles + economy + relationships).
`SimulationResults.get_relationship_data`	Get data for a specific relationship as a DataFrame.
`SimulationResults.economy_metrics`	Get economy-wide metrics as a DataFrame.
`SimulationResults.summary`	Get summary statistics for key metrics.