bamengine 0.1.0__py3-none-any.whl

bamengine/__init__.py

@@ -0,0 +1,282 @@
+"""
+BAM Engine - Bottom-Up Adaptive Macroeconomics Simulation Framework
+====================================================================
+
+BAM Engine is a Python implementation of the BAM (Bottom-Up Adaptive
+Macroeconomics) model from Delli Gatti et al. (2011). It provides a
+high-performance, vectorized agent-based macroeconomic simulation framework
+for studying complex economic dynamics.
+
+Quick Start
+-----------
+Basic simulation with default configuration:
+
+>>> import bamengine as bam
+>>> sim = bam.Simulation.init(seed=42)
+>>> sim.run(n_periods=100)
+>>> unemployment = sim.ec.unemp_rate_history[-1]
+>>> print(f"Final unemployment: {unemployment:.2%}")
+
+Custom configuration via kwargs:
+
+>>> sim = bam.Simulation.init(
+...     n_firms=200,
+...     n_households=1000,
+...     n_banks=20,
+...     seed=42
+... )
+>>> sim.run(n_periods=100)
+
+Custom configuration via YAML file:
+
+>>> sim = bam.Simulation.init(config="my_config.yml", seed=42)
+>>> sim.run(n_periods=100)
+
+Key Concepts
+------------
+**Agents and Roles**
+  Agents have multiple roles (components). Firms are Producer + Employer + Borrower.
+  Households are Worker + Consumer. Banks are Lender.
+
+**Event Pipeline**
+  Each period executes 40+ events in fixed order: Planning → Labor Market →
+  Credit Market → Production → Goods Market → Revenue → Bankruptcy → Entry.
+
+**Vectorized Operations**
+  All agent state stored in NumPy arrays for performance. Population-level
+  operations execute in parallel.
+
+**Deterministic RNG**
+  Fixed seed ensures reproducible simulations for scientific research.
+
+Public API
+----------
+**Core Classes**
+
+Simulation
+    Main simulation facade for running BAM simulations.
+Role
+    Base class for defining custom agent components.
+Event
+    Base class for defining custom economic events.
+Relationship
+    Base class for defining agent-to-agent relationships.
+Economy
+    Container for economy-wide state (prices, wages, unemployment).
+
+**Decorators**
+
+role
+    Decorator for defining custom role classes (simplified syntax).
+event
+    Decorator for defining custom event classes (simplified syntax).
+relationship
+    Decorator for defining custom relationship classes.
+
+**Type Aliases**
+
+Float, Int, Bool, AgentId
+    User-friendly type aliases for defining custom roles without NumPy knowledge.
+Rng
+    Type alias for numpy.random.Generator (random number generator).
+
+**Utility Modules**
+
+ops
+    NumPy-free operations for writing custom events (add, multiply, divide, etc.).
+logging
+    Custom logging with TRACE level and per-event log configuration.
+
+**Registry Functions**
+
+get_role, get_event, get_relationship
+    Retrieve registered roles/events/relationships by name.
+list_roles, list_events, list_relationships
+    List all registered roles/events/relationships.
+
+Examples
+--------
+Access time-series data after simulation:
+
+>>> sim = bam.Simulation.init(seed=42)
+>>> sim.run(n_periods=100)
+>>> import matplotlib.pyplot as plt
+>>> plt.plot(sim.ec.inflation_history)
+>>> plt.title("Inflation Over Time")
+
+Define a custom role:
+
+>>> @bam.role
+... class Inventory:
+...     goods_on_hand: bam.Float
+...     reorder_point: bam.Float
+...     supplier_id: bam.AgentId
+
+Define a custom event:
+
+>>> @bam.event
+... class CustomPricing:
+...     def execute(self, sim):
+...         prod = sim.get_role("Producer")
+...         bam.ops.multiply(prod.price, 1.1, out=prod.price)
+
+Step through simulation manually:
+
+>>> sim = bam.Simulation.init(seed=42)
+>>> for period in range(10):
+...     sim.step()
+...     if period % 5 == 0:
+...         unemp = sim.ec.unemp_rate_history[-1]
+...         print(f"Period {period}: Unemployment = {unemp:.2%}")
+
+Module Organization
+-------------------
+**Public API** (stable, documented, recommended for users):
+  - `bamengine.Simulation` : Main simulation class
+  - `bamengine.role`, `bamengine.event`, `bamengine.relationship` : Decorators
+  - `bamengine.ops` : NumPy-free operations
+  - `bamengine.logging` : Custom logging
+  - `bamengine.typing` : Type system definitions
+
+**Internal Modules** (implementation details, subject to change):
+  -  bamengine.simulation : Simulation implementation
+  - `bamengine.core` : ECS infrastructure (registry, pipeline)
+  - `bamengine.roles` : Built-in role implementations (Producer, Worker, etc.)
+  - `bamengine.events` : Built-in event implementations (37 events)
+  - `bamengine.relationships` : Built-in relationships (LoanBook)
+  - `bamengine.economy` : Economy-wide state, scalars and time-series
+  - `bamengine.config` : Configuration and validation
+  - `bamengine.utils` : Internal utilities
+
+References
+----------
+Delli Gatti, D., Desiderio, S., Gaffeo, E., Cirillo, P., & Gallegati, M. (2011).
+The BAM model at work. In Macroeconomics from the Bottom-up (New Economic Windows).
+Springer Milano. https://doi.org/10.1007/978-88-470-1971-3
+
+See Also
+--------
+defaults.yml : Default configuration parameters
+default_pipeline.yml : Default event execution order
+
+Notes
+-----
+- Time scale: 1 period = 1 quarter (4 periods = 1 year)
+- All simulations are deterministic when seed is specified
+- Configuration precedence: config/defaults.yml → user config → kwargs
+- Pipeline events execute in explicit order (no automatic dependency resolution)
+"""
+
+from __future__ import annotations
+
+__version__: str = "0.1.0"
+
+# ============================================================================
+# Standard library imports
+# ============================================================================
+from typing import TypeAlias
+
+import numpy as np
+
+# ============================================================================
+# Type system for user extensions (must be before Simulation import)
+# ============================================================================
+from .typing import Agent as AgentId
+from .typing import Bool, Float, Int
+
+# Type alias for RNG (must be before Simulation import)
+Rng: TypeAlias = np.random.Generator
+
+# ============================================================================
+# User-facing utilities (must be before Simulation import)
+# ============================================================================
+from . import logging, ops  # noqa: E402 (circular‑safe)
+
+
+def make_rng(seed: int | None = None) -> Rng:
+    """Create a new random number generator.
+
+    This is the recommended way to create RNGs for use with BAM Engine.
+    Under the hood, this uses NumPy's `default_rng`, which provides the
+    modern Generator API with better statistical properties than the
+    legacy RandomState.
+
+    Parameters
+    ----------
+    seed : int | None
+        Seed for reproducibility. If `None`, uses a random seed.
+
+    Returns
+    -------
+    Rng
+        A NumPy random number generator (np.random.Generator).
+
+    Examples
+    --------
+    >>> import bamengine as bam
+    >>> rng = bam.make_rng(42)  # Reproducible
+    >>> rng.normal(0, 1, size=10)  # Use standard NumPy methods
+    >>> rng2 = bam.make_rng()  # Random seed
+
+    See Also
+    --------
+    numpy.random.default_rng : The underlying NumPy function
+    """
+    return np.random.default_rng(seed)
+
+
+# ============================================================================
+# ECS extensibility components
+# ============================================================================
+from .core import (  # noqa: E402 (circular‑safe)
+    Agent,
+    AgentType,
+    Event,
+    Relationship,
+    Role,
+    event,
+    get_event,
+    get_relationship,
+    get_role,
+    list_events,
+    list_relationships,
+    list_roles,
+    relationship,
+    role,
+)
+from .economy import Economy  # noqa: E402 (circular‑safe)
+from .simulation import Simulation  # noqa: E402  (circular‑safe)
+
+# ============================================================================
+# Public API exports
+# ============================================================================
+__all__ = [
+    "Simulation",
+    "__version__",
+    # Core ECS components
+    "Agent",
+    "AgentType",
+    "Role",
+    "Economy",
+    "Event",
+    "Relationship",
+    "event",
+    "role",
+    "get_event",
+    "get_role",
+    "get_relationship",
+    "list_events",
+    "list_roles",
+    "list_relationships",
+    "relationship",
+    # Type system
+    "Float",
+    "Int",
+    "Bool",
+    "AgentId",
+    "Rng",
+    # Utilities
+    "make_rng",
+    "ops",
+    "logging",
+]

bamengine/config/__init__.py

@@ -0,0 +1,88 @@
+"""
+Configuration system for BAM Engine.
+
+This package provides a three-tier configuration system with centralized
+validation:
+
+1. **Package defaults** (`src/bamengine/config/defaults.yml`)
+2. **User config file** (YAML path or dict)
+3. **Keyword arguments** (highest priority)
+
+The Config dataclass groups all simulation hyperparameters in one immutable
+object. The ConfigValidator performs all validation once at Simulation.init()
+to ensure fail-fast behavior with clear error messages.
+
+Components
+----------
+Config : dataclass
+    Immutable configuration for simulation parameters.
+ConfigValidator : class
+    Centralized validation for all configuration parameters.
+
+Examples
+--------
+Use defaults:
+
+>>> import bamengine as be
+>>> sim = be.Simulation.init()
+
+Override with YAML:
+
+>>> sim = be.Simulation.init(config="my_config.yml")
+
+Override with kwargs (highest priority):
+
+>>> sim = be.Simulation.init(n_firms=200, seed=42)
+
+Mix YAML and kwargs:
+
+>>> sim = be.Simulation.init(config="base.yml", n_firms=200)
+
+Custom pipeline:
+
+>>> sim = be.Simulation.init(
+...     n_firms=100,
+...     pipeline_path="custom_pipeline.yml",
+...     seed=42
+... )
+
+Custom logging:
+
+>>> log_config = {
+...     "default_level": "DEBUG",
+...     "events": {
+...         "workers_send_one_round": "WARNING",
+...         "firms_hire_workers": "INFO",
+...     }
+... }
+>>> sim = be.Simulation.init(logging=log_config)
+
+Validation
+----------
+All configuration parameters are validated at Simulation.init():
+
+- **Type checking**: Ensures correct types (int, float, str, etc.)
+- **Range validation**: Ensures parameters within valid ranges
+- **Relationship constraints**: Validates cross-parameter dependencies
+- **Pipeline validation**: Validates custom pipeline YAML files
+- **Logging validation**: Validates log levels and event names
+
+Invalid configurations are rejected immediately with clear error messages:
+
+>>> sim = be.Simulation.init(n_firms="100")  # doctest: +SKIP
+ValueError: Config parameter 'n_firms' must be int, got str
+
+>>> sim = be.Simulation.init(h_rho=1.5)  # doctest: +SKIP
+ValueError: Config parameter 'h_rho' must be <= 1.0, got 1.5
+
+See Also
+--------
+Config : Immutable configuration dataclass
+ConfigValidator : Centralized validation class
+bamengine.simulation.Simulation.init : Initialize simulation with configuration
+"""
+
+from bamengine.config.schema import Config
+from bamengine.config.validator import ConfigValidator
+
+__all__ = ["Config", "ConfigValidator"]

bamengine/config/default_pipeline.yml

@@ -0,0 +1,169 @@
+# ==============================================================================
+# BAM Engine Default Event Pipeline
+# ==============================================================================
+#
+# This file defines the canonical event execution order for BAM simulations.
+# Events are executed in the exact order listed below, implementing the
+# sequential economic phases of the BAM model.
+#
+# EXECUTION ORDER
+# ---------------
+# Events execute in EXPLICIT ORDER (no dependency-based topological sorting).
+# The order below matches the original BAM model specification and has been
+# validated against legacy implementation via golden master testing.
+#
+# SPECIAL SYNTAX
+# --------------
+# 1. Simple event:
+#      - event_name
+#    Executes event once per period.
+#
+# 2. Repeated event:
+#      - event_name x N
+#    Executes event N times (e.g., "consumers_shop_one_round x {max_Z}")
+#
+# 3. Interleaved events:
+#      - event1 <-> event2 x N
+#    Alternates between event1 and event2, N times total.
+#    Example: "workers_send_one_round <-> firms_hire_workers x {max_M}"
+#    Expands to: [send, hire, send, hire, ..., send, hire] (max_M pairs)
+#
+# PARAMETER SUBSTITUTION
+# ----------------------
+# The following parameters are substituted at pipeline load time:
+#   - {max_M} : Number of labor market matching rounds (default: 4)
+#   - {max_H} : Number of credit market matching rounds (default: 2)
+#   - {max_Z} : Number of goods market shopping rounds (default: 2)
+#
+# These values come from the simulation configuration (config/defaults.yml or overrides).
+#
+# CUSTOM PIPELINES
+# ----------------
+# To create a custom pipeline:
+#   1. Copy this file to a new location
+#   2. Modify the event order/structure as needed
+#   3. Pass the custom path to Simulation.init():
+#        sim = be.Simulation.init(pipeline_path="my_pipeline.yml")
+#
+# Custom pipelines can:
+#   - Reorder events (carefully! some orderings may break model logic)
+#   - Remove events (e.g., disable dividends or minimum wage adjustment)
+#   - Add custom events (must be registered in event registry)
+#
+# ECONOMIC PHASES
+# ---------------
+# The pipeline is organized into 8 sequential phases matching the BAM model:
+#
+#   1. Planning: Production targets, pricing, labor needs
+#   2. Labor Market: Wage setting, job search, hiring (max_M rounds)
+#   3. Credit Market: Loan supply/demand, matching (max_H rounds), firing
+#   4. Production: Wage payments, production execution, contract updates
+#   5. Goods Market: Consumption decisions, shopping (max_Z rounds)
+#   6. Revenue: Revenue collection, debt repayment, dividends
+#   7. Bankruptcy: Insolvency detection, firm/bank exit
+#   8. Entry: Replacement firm/bank spawning, statistics
+#
+# See Also
+# --------
+# - bamengine.core.pipeline.Pipeline : Pipeline parser and executor
+# - bamengine.events : All event class definitions
+# - notes/PLAN.md : ECS migration plan with pipeline architecture details
+# - tests/integration/test_pipeline_golden_master.py : Pipeline validation tests
+#
+# ==============================================================================
+
+events:
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 1: PLANNING (7 events)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Firms decide production targets, calculate costs, adjust prices based on
+  # inventory and market conditions. Economy-wide statistics updated.
+
+  - firms_decide_desired_production    # Set production targets based on demand/inventory
+  - firms_calc_breakeven_price         # Calculate minimum profitable price
+  - firms_adjust_price                 # Adjust price based on inventory levels
+  - update_avg_mkt_price               # Update economy-wide average price
+  - calc_annual_inflation_rate         # Calculate annual inflation rate
+  - firms_decide_desired_labor         # Calculate labor needs from production targets
+  - firms_decide_vacancies             # Post vacancies for labor shortfalls
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 2: LABOR MARKET (2 + 2×max_M + 1 = 11 events with default max_M=4)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Minimum wage adjustment, firms set wages, unemployed workers search for jobs,
+  # sequential matching rounds (max_M), then wage bill calculation.
+
+  - adjust_minimum_wage                # Adjust min wage based on inflation
+  - firms_decide_wage_offer            # Firms set wage offers for vacancies
+  - workers_decide_firms_to_apply      # Unemployed workers select firms to apply to
+  - workers_send_one_round <-> firms_hire_workers x {max_M}
+                                       # Interleaved job application/hiring rounds
+                                       # Each worker sends ≤1 application per round
+                                       # Firms hire workers from application queue
+  - firms_calc_wage_bill               # Calculate total wage obligations
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 3: CREDIT MARKET (5 + 2×max_H + 1 = 10 events with default max_H=2)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Banks decide credit supply, firms calculate credit needs, sequential matching
+  # rounds (max_H), then firms fire workers if credit insufficient.
+
+  - banks_decide_credit_supply         # Banks determine lending capacity
+  - banks_decide_interest_rate         # Banks set interest rates
+  - firms_decide_credit_demand         # Firms calculate financing needs
+  - firms_calc_credit_metrics          # Calculate firm financial fragility metrics
+  - firms_prepare_loan_applications    # Firms prepare ranked bank applications
+  - firms_send_one_loan_app <-> banks_provide_loans x {max_H}
+                                       # Interleaved loan application/provision rounds
+                                       # Firms send ≤1 application per round
+                                       # Banks process and approve/reject applications
+  - firms_fire_workers                 # Lay off workers if credit insufficient
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 4: PRODUCTION (4 events)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Firms pay wages to workers, production occurs, contracts updated.
+
+  - firms_pay_wages                    # Firms transfer wages to workers
+  - workers_receive_wage               # Workers receive wages into income
+  - firms_run_production               # Production execution (goods added to inventory)
+  - workers_update_contracts           # Decrement contract duration, handle expiration
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 5: GOODS MARKET (3 + max_Z + 1 = 6 events with default max_Z=2)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Households decide spending based on income/savings, select firms to visit,
+  # sequential shopping rounds (max_Z), then finalize purchases.
+
+  - consumers_calc_propensity          # Calculate consumption propensity from savings
+  - consumers_decide_income_to_spend   # Allocate income for consumption
+  - consumers_decide_firms_to_visit    # Select firms to shop at (price-sorted)
+  - consumers_shop_one_round x {max_Z} # Shopping rounds (buy from one firm per round)
+  - consumers_finalize_purchases       # Update savings with unspent income
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 6: REVENUE (3 events)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Firms collect revenue from sales, repay debts, distribute dividends.
+
+  - firms_collect_revenue              # Collect sales revenue, calculate gross profit
+  - firms_validate_debt_commitments    # Repay loans or default, calculate net profit
+  - firms_pay_dividends                # Distribute dividends from positive profits
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 7: BANKRUPTCY (3 events)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Detect insolvent firms/banks, mark for exit (workers fired, loans purged).
+
+  - firms_update_net_worth             # Add retained profits to firm net worth
+  - mark_bankrupt_firms                # Detect/remove bankrupt firms (net worth < 0)
+  - mark_bankrupt_banks                # Detect/remove bankrupt banks (equity < 0)
+
+  # ────────────────────────────────────────────────────────────────────────────
+  # PHASE 8: ENTRY & STATISTICS (3 events)
+  # ────────────────────────────────────────────────────────────────────────────
+  # Replace bankrupt agents, calculate end-of-period unemployment rate.
+
+  - spawn_replacement_firms            # Create new firms to replace bankrupt ones
+  - spawn_replacement_banks            # Create new banks to replace bankrupt ones
+  - calc_unemployment_rate             # Calculate/record unemployment rate

bamengine/config/defaults.yml

@@ -0,0 +1,110 @@
+# ==============================================================================
+# BAM Engine Default Configuration
+# ==============================================================================
+#
+# This file provides default parameter values for BAM (Bottom-Up Adaptive
+# Macroeconomics) simulations. All parameters can be overridden via:
+#
+#   1. Custom YAML config file: Simulation.init(config="my_config.yml")
+#   2. Keyword arguments: Simulation.init(n_firms=200, seed=42)
+#
+# Time scale: 1 period = 1 quarter (4 periods = 1 year)
+#
+# Parameter precedence (later overrides earlier):
+#   1. This file (defaults.yml)
+#   2. User config file (if provided)
+#   3. Keyword arguments (highest priority)
+#
+# See Also
+# --------
+# - bamengine.config.schema.Config : Configuration dataclass
+# - bamengine.config.validator.ConfigValidator : Validation logic
+# - bamengine.simulation.Simulation.init : Initialize simulation
+# - notes/CALIBRATION.md : Rationale for parameter choices
+#
+# ==============================================================================
+
+# ── POPULATION SIZES ──────────────────────────────────────────────────────────
+# Number of agents in each population.
+# Recommendation: n_households >= 5 * n_firms for realistic labor markets.
+
+n_firms:              100        # Producer/Employer agents (firms)
+n_households:         500        # Worker/Consumer agents (households)
+n_banks:               10        # Lender agents (commercial banks)
+
+# ── RUN LENGTH ────────────────────────────────────────────────────────────────
+# Default number of periods for Simulation.run() when n_periods not specified.
+
+n_periods:            1000       # Simulation periods (quarters)
+
+# ── STOCHASTIC SHOCK WIDTHS ───────────────────────────────────────────────────
+# Maximum magnitude of random shocks (drawn from uniform distribution).
+# Example: h_rho = 0.10 means production growth shock in [-10%, +10%].
+
+h_rho:                0.10       # Production growth shock cap (firms)
+h_xi:                 0.05       # Wage growth shock cap (firms)
+h_phi:                0.10       # Bank operating expense shock cap (banks)
+h_eta:                0.10       # Price adjustment shock cap (firms)
+
+# ── SEARCH FRICTIONS ──────────────────────────────────────────────────────────
+# Market matching constraints limiting how many partners agents can contact
+# per period. Higher values reduce frictions but increase computation time.
+
+max_M:                4          # Job applications per unemployed worker/period
+max_H:                2          # Loan applications per firm/period
+max_Z:                2          # Shops a household can visit/period
+
+# ── ECONOMY-WIDE STRUCTURAL PARAMETERS ────────────────────────────────────────
+# Behavioral and policy parameters affecting all agents.
+
+theta:                8          # Job contract base length (periods)
+                                 # Actual duration: θ + Poisson(10)
+beta:                 2.50       # Consumption propensity exponent
+                                 # Controls how strongly savings affect spending:
+                                 #   π_j = 1 / (1 + tanh(SA_j / SA_avg)^β)
+                                 # Higher β = stronger response to savings
+delta:                0.40       # Dividend payout ratio (share of profits)
+                                 # Fraction of positive profits paid as dividends
+v:                    0.06       # Bank capital requirement coefficient
+                                 # Max leverage = 1/v (default: ~16.7x)
+r_bar:                0.02       # Baseline interest rate (quarterly)
+                                 # Policy rate used in bank interest calculations
+min_wage:             0.6        # Initial minimum wage floor
+min_wage_rev_period:  4          # Periods between min wage adjustments
+                                 # Adjusts with inflation every 4 quarters (1 year)
+
+# ── INITIAL CONDITIONS ────────────────────────────────────────────────────────
+# Balance sheet values at t=0. Can be scalars (broadcast to all agents) or
+# arrays of length n_firms/n_households for heterogeneous initialization.
+
+net_worth_init:      12.0        # Firm net worth at t=0 (money units)
+production_init:      4.0        # Firm production at t=0 (goods units)
+price_init:           1.0        # Goods price at t=0 (money/goods)
+savings_init:         3.0        # Household savings at t=0 (money units)
+wage_offer_init:      0.9        # Wage offer at t=0 (money/period)
+equity_base_init:     5.0        # Bank equity at t=0 (money units)
+
+# ── RANDOM NUMBER GENERATION ──────────────────────────────────────────────────
+# Seed for deterministic simulations. Use fixed seed for reproducibility,
+# or set to null for non-deterministic behavior.
+
+seed:               12345        # RNG seed (null = random seed)
+
+# ── PIPELINE CONFIGURATION ────────────────────────────────────────────────────
+# Path to custom event pipeline YAML. If null, uses config/default_pipeline.yml.
+# Custom pipelines allow reordering events, removing events, or adding custom
+# events. See config/default_pipeline.yml for syntax.
+
+pipeline_path:      null         # Custom pipeline path (null = use default)
+
+# ── LOGGING CONFIGURATION ─────────────────────────────────────────────────────
+# Control log output verbosity globally and per-event.
+# Levels: TRACE (5), DEBUG (10), INFO (20), WARNING (30), ERROR (40), CRITICAL (50)
+
+logging:
+  default_level:    INFO         # Default log level for all events
+  events:           {}           # Per-event overrides
+                                 # Example:
+                                 #   workers_send_one_round: WARNING
+                                 #   firms_hire_workers: DEBUG
+                                 #   firms_adjust_price: TRACE