Events#

Event classes for BAM Engine simulation.

This package contains 37 event classes organized into 8 modules representing different phases of the BAM economic model. Events are auto-registered via __init_subclass__ hook and composed into a Pipeline for execution.

Event Organization#

Events are organized by economic phase:

  1. Planning (6 events): Firms plan production targets, breakeven price, price adjustment

  2. Labor Market (6 events): Wage setting, job applications, matching

  3. Credit Market (7 events): Credit supply/demand, loan matching, layoffs

  4. Production (5 events): Wage payments, production, price update, contracts

  5. Goods Market (5 events): Consumption decisions, shopping

  6. Revenue (3 events): Revenue collection, debt repayment, dividends

  7. Bankruptcy (5 events): Insolvency detection, agent replacement

Total: 37 events across 7 modules

Event Execution#

Events execute in order specified by Pipeline (see config/default_pipeline.yml). Each event wraps a system function from events._internal/ modules.

Key Design Patterns#

  • Auto-registration: All events inherit from Event base class with __init_subclass__

  • Event-System separation: Event classes (public API) wrap system functions (internal)

  • Pipeline composition: Events composed via YAML configuration

  • Stateless execution: Events receive Simulation object, operate on roles/relationships

  • Batch matching: Market matching uses vectorized NumPy operations with conflict resolution and grouped cumsum

Event Naming Convention#

  • Agent action: FirmsDecideWageOffer, WorkersReceiveWage

  • State update: UpdateAvgMktPrice, CalcInflationRate

  • Market round: LaborMarketRound, CreditMarketRound, GoodsMarketRound

Examples

Access event by name:

>>> import bamengine as bam
>>> sim = bam.Simulation.init(seed=42)
>>> event = sim.get_event("firms_decide_desired_production")
>>> event.execute(sim)

Execute full pipeline:

>>> sim.step()  # Executes all events in default order

See also

Event

Event base class

Pipeline

Pipeline composition

_internal

System function implementations

The bamengine.events package contains 37 event classes organized into 8 modules representing different phases of the BAM economic model.

Event Modules#