How the Simulator Works
This page documents model scope, simulation workflow, and the scenario-testing protocol. The goal is to compare policy responses using reproducible runs rather than editorial conclusions.
1. Model Scope
The simulator is an agent-based macro model with monthly time steps. It tracks households, firms, government, banks, housing, and labor interactions. Aggregate outcomes emerge from micro decisions, not from a representative-agent shortcut.
Core entities
Households, firms, government, banks, and market subsystems are explicitly modeled with state updates each step.
Core outputs
Unemployment (U3/U6), GDP path, inflation, debt ratios, firm survival, wages, housing metrics, and balance-sheet diagnostics.
2. Run Workflow
- Initialize from configured defaults, profiles, or checkpoint state.
- Run monthly step phases (production, labor, fiscal, credit, housing, markets).
- Record per-step metrics and compute run summaries.
- Compare scenario paths using shared seeds and identical horizons.
Practical rule: compare trajectories, not only end-of-run values.
3. What You Can Change
UI controls
Household/firm scale, run length, warmup period, seed, and selected initialization overrides on the simulator page.
Runtime overrides
Parameter overrides via API/scripts for targeted hypothesis tests.
Profiles and regimes
Structured scenario setup through YAML parameter profiles and regime schedules.
Registry links
Parameter, rule, entity, flow, invariant, and evidence objects are linked for auditability and validation.
4. Scenario Families to Test
Use one baseline and compare policy families by changing one block at a time.
Baseline Reference
Hypothesis: Default policy settings provide a stable reference trajectory.
Primary metrics: U3/U6, GDP path, inflation, active firm count, debt/GDP.
Stabilizer Strength
Hypothesis: Stronger automatic stabilizers reduce crash depth at potential fiscal cost.
Primary metrics: Peak unemployment, recovery speed, fiscal deficit persistence.
Transfer Mix Design
Hypothesis: Different transfer compositions change demand support efficiency.
Primary metrics: Consumption recovery, labor participation, distribution outcomes.
Ownership & Revenue Design
Hypothesis: Alternative revenue channels can change long-run distribution and stability.
Primary metrics: Employment, productivity gains, fiscal sustainability, wealth concentration.
5. Reproducibility Protocol
- Fix seed list and run duration for all compared scenarios.
- Keep initialization mode and warmup constant across variants.
- Change one policy block per comparison pass.
- Run directionality/invariant checks before interpreting outcomes.
- Record command outputs and scenario config in PR notes.
6. Realism Registry
The Realism Registry is the model’s audit layer for semantics and validation.
Use the registry tooling and tests to keep code behavior, accounting logic, and evidence links synchronized.