Glossary#

This glossary defines key terms used throughout the BAM Engine documentation. Terms listed here can be cross-referenced from any page using the :term: role.

Economic Concepts#

actual production#: The quantity of goods actually produced, constrained by available labor and the production function.
agent#: An autonomous decision-making entity in the model. BAM Engine has three agent types: firms, households, and banks.
bad debt#: Losses incurred by banks when borrowers default. Computed as principal - recovery, where recovery depends on the bankrupt firm’s remaining net worth.
bank#: An agent that supplies credit to firms, sets interest rates, and absorbs bad debt losses. Each bank has the Lender role.
bankruptcy#: The exit of a firm or bank from the market when its net worth becomes negative. Bankrupt agents are replaced by new entrants with initial conditions set by configuration parameters.
breakeven price#: The minimum price at which a firm covers its costs. Calculated as wage_bill / expected_output during the planning phase.
buffer stock#: A consumption theory (Carroll, 1997) where households target a wealth-to-income ratio. The buffer-stock extension (Section 3.9.4) replaces the uniform propensity to consume with individual adaptive MPCs.
business cycle#: Endogenous fluctuations in aggregate output, employment, and prices that emerge from agent interactions without exogenous shocks.
consumption budget#: The amount a household plans to spend on goods in a period, determined by the propensity to consume and available wealth.
credit market#: The market where firms apply for loans and banks supply credit based on financial fragility assessments. Matching uses configurable rounds (max_H).
credit supply#: The maximum amount a bank can lend, determined by its equity and regulatory constraints (capital adequacy ratio v).
cross-correlation#: A measure of similarity between two time series as a function of lag. Used in robustness analysis to verify co-movement structure between macroeconomic variables.
desired production#: The quantity of goods a firm plans to produce, based on past production adjusted by a demand signal. Drives hiring and borrowing decisions.
dividend#: The fraction of net profit distributed to shareholders each period, controlled by the dividend payout rate delta.
financial fragility#: A measure of a firm’s leverage, defined as the ratio of debt to net worth. Used by banks to rank loan applications and set interest rates. Related to the Minsky classification.
firm#: An agent that produces consumption goods, hires workers, and borrows from banks. Each firm has three roles: Producer, Employer, and Borrower.
GDP#: Gross Domestic Product. Computed as the sum of firm revenues (price times quantity sold) across all firms.
goods market#: The market where consumers purchase consumption goods from firms. Also called the consumption goods market. Matching uses preferential attachment with configurable rounds (max_Z).
household#: An agent that supplies labor, consumes goods, and receives dividends. Each household has three roles: Worker, Consumer, and Shareholder.
HP filter#: Hodrick-Prescott filter. A statistical method for decomposing a time series into trend and cyclical components. Used in robustness analysis to extract business cycle fluctuations.
inflation#: The rate of change in the price index between periods. An emergent property arising from individual firm pricing decisions.
interest rate#: The rate charged on loans, composed of a base rate plus a risk premium that increases with borrower financial fragility. Each bank also applies an idiosyncratic operational shock.
inventory#: Unsold goods carried over between periods. Affects pricing decisions through the markup adjustment rule.
Kalecki profit equation#: The macroeconomic identity showing that aggregate profits are guaranteed by the circular flow of income. In BAM, this creates the Kalecki trap where firms self-finance and stop borrowing.
Kalecki trap#: A structural issue where high net-worth-to-wage-bill ratios eliminate borrowing demand, causing credit market inactivity. Only the dividend payout rate (delta) is an effective parameter lever.
labor market#: The market where firms post vacancies and unemployed workers search for jobs. Matching uses preferential attachment with configurable rounds (max_M).
labor productivity#: Goods produced per worker (phi). In the base model this is constant; the Growth+ extension makes it endogenous through R&D investment.
markup#: The multiplicative factor applied above breakeven price to set the firm’s selling price. Adjusted adaptively each period based on inventory levels.
matching#: The process of pairing agents in a market. BAM Engine uses interleaved matching where agents are processed one at a time across multiple rounds.
maximum leverage#: The upper bound on a firm’s debt-to-equity ratio, beyond which banks refuse to lend. Configured via max_leverage.
Minsky classification#: Categorization of firms by financial fragility: hedge (cash flow covers all obligations), speculative (covers interest but not principal), Ponzi (cannot cover interest). Based on Hyman Minsky’s Financial Instability Hypothesis.
net worth#: A firm’s or bank’s equity: assets minus liabilities. For firms, accumulates through retained profits. Negative net worth triggers bankruptcy.
operational shock#: A bank-specific idiosyncratic cost shock (phi_k) that affects the interest rate charged on loans, creating heterogeneity among banks.
preferential attachment#: A matching mechanism where agents are more likely to select partners they have interacted with before (loyalty effect). Used in both the labor market and goods market.
price index#: The production-weighted average of firm prices. Used to compute inflation.
production function#: A linear function relating output to labor input: Y = phi * L where phi is labor productivity and L is the number of workers.
propensity to consume#: The fraction of wealth a household allocates to consumption. In the base model this is uniform; the buffer stock extension makes it adaptive.
quantization trap#: A structural issue in the labor market where the ceiling function in the hiring rule creates a one-way ratchet: small firms can increase but never decrease their workforce.
reservation wage#: The minimum wage a worker will accept for employment. Adjusts downward during unemployment and upward during employment.
scenario#: A specific model configuration and set of validation targets corresponding to a section of the reference book. BAM Engine has three scenarios: baseline (3.9.1), Growth+ (3.9.2), and buffer-stock (3.9.4).
unemployment#: The fraction of the labor force without employment. A key emergent property of the model, driven by hiring, firing, and bankruptcy dynamics.
vacancy#: An open position posted by a firm seeking to hire workers. The number of vacancies equals the gap between desired and current labor.
wage bill#: Total wages a firm must pay its workers in a given period. Equals the sum of individual worker wages.

Framework Concepts#

auto-registration#: See decorator registration.
Borrower#: The firm role holding credit-related state: loan applications and projected fragility.
collect flag#: The collect parameter of sim.run() (defaults to True). Pass collect=False to skip data recording for benchmarks or profiling.
Config#: The configuration dataclass holding all simulation parameters. Constructed from three tiers: package defaults (defaults.yml), user YAML file, and keyword arguments.
Consumer#: The household role holding consumption-related state: consumption budget, preferred firm, and spending behavior.
decorator registration#: The mechanism by which @role, @event, and @relationship decorators automatically register classes in a global registry via __init_subclass__. This enables lookup by name at runtime.
default_pipeline.yml#: The YAML file (src/bamengine/config/default_pipeline.yml) defining the default event execution order.
defaults.yml#: The YAML file (src/bamengine/config/defaults.yml) containing default values for all simulation parameters.
economy#: The Economy object holding aggregate state variables (GDP, unemployment, price index, etc.) that are updated each period by economy-level events.
economy data#: Time series of aggregate variables (GDP, unemployment, inflation, etc.), always collected automatically. Access via results["Economy.inflation"].
ECS#: Entity-Component-System. An architectural pattern where entities are lightweight IDs, components hold data (see role), and systems contain behavior (see event). BAM Engine adapts this pattern from game development for agent-based modeling.
Employer#: The firm role holding employment-related state: wage offers, vacancies, and labor demand.
event#: A system in the ECS architecture. A class with an execute(sim) method that reads and modifies role data. Defined with the @event decorator. Events are executed in sequence by the pipeline.
extension#: A package that adds new roles, events, and configuration to the base model. Extensions export *_EVENTS lists and *_CONFIG dicts, activated via sim.use_role(), sim.use_events(), and sim.use_config().
fail escalation#: A mechanism where high-weight metrics have stricter PASS/FAIL thresholds. Formula: clamp(5 - 2*weight, 0.5, 5.0). At weight 2.0, the escalation multiplier is 1.0 (neutral).
Lender#: The bank role holding credit-related state: credit supply, interest rate, equity, bad debt exposure, and operational shock.
metric#: A computed statistic from simulation results (e.g., mean unemployment, GDP growth rate) that is compared against a target during validation.
pipeline#: The ordered sequence of events executed each simulation period. Defined in YAML (default_pipeline.yml) with special syntax for repetition, interleaving, and parameter substitution.
pipeline hook#: Metadata on an event class (set via @event(after=...), before=..., or replace=...) that positions it relative to another event in the pipeline. Applied explicitly via sim.use_events().
Producer#: The firm role holding production-related state: price, markup, production levels, inventory, net worth, and financial metrics.
relationship#: A many-to-many connection between agents stored in COO sparse format. The primary relationship is the LoanBook tracking active loans between firms and banks.
results#: The SimulationResults object returned by sim.run(). Contains per-period role data, economy data, and relationship snapshots. Access via results["Producer.production"] or results.Producer.production.
role#: A component in the ECS architecture. A dataclass whose fields are parallel NumPy arrays, one element per agent. Defined with the @role decorator. Examples: Producer, Worker, Lender.
scoring#: The validation system that assigns a 0-1 score to each metric based on how close it is to its target. Scores are weighted and aggregated into a total_score.
Shareholder#: A built-in household role tracking per-period dividend income. Added in v0.3.0 to support buffer-stock MPC adjustment.
simulation#: The top-level object (Simulation) that manages agent populations, roles, relationships, the pipeline, configuration, and RNG state.
target#: A validation reference value (with bounds) from the reference book, defined in scenario-specific targets.yaml files. Used to assess whether simulation output matches expected behavior.
use_config#: The Simulation.use_config(config_dict) method that applies extension default configuration with “don’t overwrite” semantics.
use_events#: The Simulation.use_events(*event_classes) method that applies pipeline hooks from event classes, inserting them into the pipeline at the specified positions.
use_role#: The Simulation.use_role(cls, n_agents=N) method that registers a new role with the simulation. The n_agents parameter sets the array size (defaults to n_firms).
vectorized operations#: NumPy-based array computations that process all agents simultaneously instead of looping. The ops module provides safe wrappers (e.g., ops.divide() handles division by zero).
weight#: A numeric value (0.5-5.0) assigned to each validation metric, indicating its relative importance. Affects both the weighted total_score and fail escalation.
Worker#: The household role holding labor-related state: employment status, employer ID, wage, and reservation wage.