validator#

Centralized configuration validation for BAM Engine.

This module provides the ConfigValidator class, which performs all validation once at Simulation.init() to ensure fail-fast behavior with clear error messages.

Validation Layers#

Type Checking: Ensures all parameters have correct types (int, float, str, etc.)
Range Validation: Ensures parameters are within valid ranges (e.g., 0 <= h_rho <= 1)
Boolean and Enum Validation: Ensures implementation variant parameters have valid values
Relationship Constraints: Validates cross-parameter dependencies (e.g., warns if n_households < n_firms)
Pipeline Validation: Validates custom pipeline YAML files (structure, event names, parameter substitution)
Logging Validation: Validates log levels and event names

Benefits#

Fail-fast: Invalid configurations rejected immediately with clear error messages
Single location: All validation logic in one place (no scattered checks)
No runtime overhead: Validation happens once at initialization, not during simulation
Clear errors: Error messages include parameter name, expected range, and actual value

Examples

Type errors are caught immediately:

>>> from bamengine.config import ConfigValidator
>>> cfg = {"n_firms": "100"}
>>> ConfigValidator._validate_types(cfg)
ValueError: Config parameter 'n_firms' must be int, got str

Range errors provide clear feedback:

>>> cfg = {"h_rho": 1.5}
>>> ConfigValidator._validate_ranges(cfg)
ValueError: Config parameter 'h_rho' must be <= 1.0, got 1.5

Cross-parameter warnings help avoid common mistakes:

>>> cfg = {"n_firms": 100, "n_households": 50}
>>> ConfigValidator._validate_relationships(cfg)
UserWarning: n_households (50) < n_firms (100). This may lead to high unemployment...

Pipeline validation catches unknown events:

>>> ConfigValidator.validate_pipeline_yaml("custom.yml")
ValueError: Event 'nonexistent_event' not found in registry...

Classes#

ConfigValidator

Centralized validation for simulation configuration.