Configuration#

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#

Configdataclass

Immutable configuration for simulation parameters.

ConfigValidatorclass

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)

Set log level:

>>> sim = be.Simulation.init(log_level="WARNING")

Advanced logging (per-event levels):

>>> log_config = {
...     "default_level": "DEBUG",
...     "events": {
...         "labor_market_round": "WARNING",
...         "credit_market_round": "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")
ValueError: Config parameter 'n_firms' must be int, got str

>>> sim = be.Simulation.init(h_rho=1.5)
ValueError: Config parameter 'h_rho' must be <= 1.0, got 1.5

See also

Config : Immutable configuration dataclass ConfigValidator : Centralized validation class Simulation.init() : Initialize simulation with configuration

The bamengine.config package provides a three-tier configuration system with centralized validation.

Classes#

Config Submodules#