dynamics / learn

How the model works — and how to check it

microcosm-dynamics is a dynamic microsimulation of Social Security built on the PSID panel. This page explains the machine, the validation discipline around it, and how to read the benchmark wall — then lets you quiz yourself.

Watch it work

A dynamic microsimulation follows people, not averages. Below: a small synthetic cohort moves through time — observed panel history on the left, module-driven simulation on the right of the seam. Earnings ribbons thicken and fade with age; marriages link lines; children start new ones; claiming rings fire between 62 and 70; lines end when mortality fires. Line weight is survey weight — heavier lines stand for more of the population — and the hatched patch is an imputed stretch of history. The strip underneath shows the calibration step: an aggregate of the simulated cohort landing against an external reference — compared, never tuned.

1968

earnings (darker = more) marriage / birth benefit claiming death simulated years imputed gap

Illustrative synthetic cohort — generated for teaching. PSID microdata is restricted and never displayed.

The model

Dynamic microsimulation is the method behind DYNASIM (Urban Institute) and MINT (Social Security Administration): start from real people's longitudinal records, age each person forward through estimated transition models — work, marriage, children, disability, death, benefit claiming — then run program rules over the projected lifepaths and add them up. It's how you answer questions that cross decades and generations: who gains from a benefit formula change in 2050, and what it does to payroll revenue on the way there.

microcosm-dynamics builds on the Panel Study of Income Dynamics — the longest-running household panel in the world, following the same families since 1968. The choice trades the administrative earnings precision of MINT's matched frame for something the field has never had: a Social Security microsimulation whose data, code, and validation record are fully public and reproducible end to end.

The pipeline

Histories: PSID individual and family records, 1968–2023 — marriage, fertility, and earnings histories read directly from the panel.
Transition modules: differential mortality, marriage and survivorship, fertility and caregiving, disability, and claiming-age behavior — each gated before use.
Projection engine: a wave-loop composing the modules year by year, certified by a pre-registered temporal holdout: fit on early waves, scored blind on held-out later years, against thresholds locked before any candidate ran. The first candidate engine failed 6 of 11 checks — published as a fail. The third passed.
Policy layer: benefit rules and payroll revenue over the projected lifepaths.

Inside the annual loop

Each projection year runs the modules in a fixed order, and each module reads only the prior year's panel plus the current-year state already resolved above it — the order is a directed acyclic graph, not a convention:

Mortality. Death draws from hazards that anchor NCHS period life tables and apply differentials estimated from the PSID's own 1968–2023 death file, by age band and sex. Decedents leave the risk set before anything else happens that year.
Aging. Ages advance; indexing series and the wage base roll forward.
Marriage — one core. A single certified hazard state machine covers first marriage, divorce, remarriage, and widowhood, plus the spousal age gap. A gated modifier reweights who marries first by career-earnings tercile without changing how many marry. Every downstream module reads this one marital state; nothing re-simulates it.
Fertility. Births draw from the fertility component; paternal attribution reads the married state; new children enter the panel as people.
Disability. A forward Markov model over the PSID's self-reported work-limitation panel — incidence and recovery by age band and sex — with the statutory DI-to-retirement conversion applied at full retirement age.
Earnings. A chained quantile-regression-forest generator: each year's draw conditions on age and a person-level permanent component, with ranks mapped to dollars through a wage-indexed age profile. Fitted only on data through 2014 — the leakage cutoff the holdout gate enforces.
Claiming. Claim ages draw from the SSA Statistical Supplement's observed claim-age distribution by sex and entitlement year, vintage-frozen to the cutoff. Calibrated, not behavioral — it reproduces current-law claiming patterns; a behavioral claiming model is on the roadmap.
Household composition. A reconciliation pass — cohabitation, parental-home exits, multigenerational households, household size — consuming the marital state read-only.

Every random draw comes from a per-(draw, module, year, person) stream registry, so a run reproduces exactly and no module can perturb another's randomness.

Weights, imputation, and calibration

No survey arrives ready. Three standard repairs make a panel usable, and the visualization above encodes the first two:

Weights — two systems, two jobs. The PSID deliberately oversampled low-income families at its start, so each family carries a survey weight — in the diagram, heavier lines are people who stand for more of the population. PSID weights do two things: they make the fitted transition rates representative (every model is estimated weighted), and they weight the published survey-frame estimates (children inherit the mother's weight). The national projection is a different run: there the units are the microcosm frame's people and the weights are the frame's calibrated weights, carried forward under a pinned rule — PSID contributes laws, not people, to that run. In short: PSID weights make the rates representative; frame weights make the people representative.
Imputation. Panels have holes — missed interviews, questions a wave never asked. Where a history has a gap, values are filled by models estimated from everything that was observed, and marked as imputed rather than passed off as data (the hatched segment in the diagram).
Calibration — on the cross-sectional side. The microcosm program builds the calibrated national microdata: reweighting to administrative totals and imputing what surveys never ask. The division of labor is deliberate: the panel supplies transitions — who moves between work, marriage, disability, claiming — while calibrated cross-sections supply representativeness. The dynamics side never calibrates to the benchmarks it validates against; levels are checked against SSA, Trustees, and CBO series and divergences are explained on the wall.

How the panel and the cross-section fit together

Two datasets, two jobs. The panel knows how lives change; the cross-section knows who the country is. The projection needs both, and they meet at exactly one seam:

The panel — microcosm-dynamics

PSID: the same families, 1968–2023. Supplies transitions — the estimated modules of the annual loop (mortality, marriage, disability, earnings, claiming), each certified on a temporal holdout.

Knows how lives change. Its sample is small and its weights are survey weights.

The cross-section — microcosm

Calibrated national microdata (CPS frame). Reweighted to administrative totals, with imputations for what surveys never ask.

Knows who the country is in one year — but not what happens to anyone next year.

↘ ↙

The seam — transport, period 0

The panel-estimated generators are deployed onto the pinned national frame — 166,302 people in 57,240 households, hash-pinned. Each frame adult gets a seeded entry state (marital, disability, earnings position), and where the policy rules need a career — AIME needs 35 years of earnings — a synthetic history is transported: one persistent earnings rank drawn per person and threaded through the certified age-indexed quantile maps, so a 55-year-old at the 80th percentile has been near the 80th percentile their whole career. A dedicated pre-registered gate scored whether the transported states and histories reproduce the right joint distributions on the new frame, separately from whether the dynamics are right.

↓

Projection — transitions only, no annual re-calibration

The annual loop runs forward on the national frame, year over year → a projected national panel → the policy layer computes benefits and payroll revenue over the projected lifepaths. Calibration happens once, at the seam: weights carry forward under a pinned rule, deaths remove people, births add them, and no year is re-aligned to external demographic or economic totals. (DYNASIM and MINT align projected aggregates to the Trustees' assumptions year by year; here annual levels stay free so validating against those series means something.)

↓ (one-way)

Benchmark wall — validation only

Levels and shares are compared against SSA, Trustees, CBO, DYNASIM, and MINT. Nothing flows back: the model never calibrates to the benchmarks it is judged against.

The division of labor in one line: the panel supplies transitions, the calibrated cross-section supplies representativeness. The first estimates published so far are survey-frame — scored on the panel's own held-out years, isolating the dynamics from transport error; the transport seam is how the same machinery produces national-frame estimates, and it carries its own gate so error can't hide between the two.

How the engine earned certification

The projection engine's gate is the clearest picture of the whole method. The loop:

Pre-register the gate. The temporal-holdout checks and their pass thresholds were locked before any engine candidate existed.
One blind shot per candidate. A candidate gets a single scored run against the held-out years. No candidate ever iterates against the holdout — that's the line between validation and tuning.
Publish the verdict either way. Candidate 1 failed 6 of 11 checks, on the record.
Forensics, not fitting. Each failed check got a diagnosis ceremony — what mechanism the miss implicates — reviewed adversarially like everything else.
Amend the design, re-register, repeat. Candidate 2 was built from the first round of diagnoses and re-registered; candidate 3 was built on the levers the accumulated forensics had proven out, and passed. The holdout was never touched between shots.

That loop — gate first, blind scoring, published failures, diagnosed causes, amended designs — is the general recipe here, and it's what makes the passing result mean something.

The discipline

The defining commitment is that generation is cheap and verification carries the weight. Three mechanisms:

Pre-registration. Evaluation gates and their pass thresholds are committed before candidates run. Failures are published alongside passes.
Adversarial review. Design documents and results go through independent referee rounds whose explicit job is to break them; ratification requires an affirmative verdict on exact bytes. Major changes get two referees in parallel, because independent reviews reliably find different defects.
A graded forecast ledger. The schedule itself is forecast in public — append-only entries with 50% and 80% confidence dates, graded when they resolve. Revisions never overwrite history; they supersede it with stated evidence, so a missed date can't be laundered.

Reading the wall

The benchmark wall registers every quantity the model shares with an external source — SSA administrative data, the Trustees, CBO, DYNASIM, MINT — and shows the comparison, including the misses. Two laws govern it:

Validation-only. Benchmark rows are never tuning targets. Nothing in estimation reads them, and expected values come from independent references — so agreement means something, and divergence gets explained rather than optimized away.

No unexplained gaps. Every divergence carries a classification and a written explanation. A gap without one fails the build.

Results so far

Claiming-age shares (NRA-to-70) vs published DYNASIM3 resultswithin ±0.4pp, all quintiles

Payroll revenue share vs CBO−1.1% to +0.2%

COLA −0.4pp reform vs external estimate+0.3% to +0.7%

Price-indexing reform±1.6%

Labor-income proxy vs true covered earnings+22% to +34%

The gap census

module_missing 59 unverified_source 20 concept_mismatch 18 label_mismatch 3 frame_no_alignment 1 unexplained 0

Most of the wall's 101 rows are open gaps today — quantities the model doesn't yet compute, each with a written reason. That's deliberate: the wall doubles as the public roadmap, and progress is measured by gaps closing on the record, run over run.

The correction program

The first estimates labeled their earnings input honestly as a labor-income proxy. True FICA-covered earnings — what Social Security actually taxes and credits — differ from labor income by 22–34% in aggregate across the projection. Replacing the proxy properly turned into a research program of its own:

Hand annotation of all 81 PSID instrument documents, 1968–2023, page by page, under a sealed per-document protocol — the last of the 81 seals landed August 4, 2026;
Independent re-derivation of every codebook and data dictionary, and a complete classification of all 89,599 raw fields — with fields that can't be lawfully interpreted recorded as closed failures rather than silently dropped;
Capture of the underlying statute — the SECA amendment chain, coverage law, wage-base determinations — as 112 primary legal documents with cryptographic provenance, and the remaining source gaps documented openly;
A design contract amended only through adversarial referee rounds, each amendment triggered by raw evidence contradicting a ratified assumption.

Status — August 4, 2026. The annotation corpus closed today: all 81 instrument documents now carry sealed annotations, each one an adversarial adjudication of machine-generated candidates against the actual page bytes. The unit-authority amendment is in its fifth referee round; in the latest round, two independent reviewers re-derived the classification from the raw PDFs and converged on the same two residual defects. An earlier round struck 209 readings where the pipeline had inferred U.S. dollars from monetary context — descriptions like "hourly earnings" with no currency stated. The contract forbids invented units, so those fields stand as explicitly unit-less rather than carrying an assumed currency.

The corrected series publishes when the whole chain passes its gates — the current forecast is on the ledger, where it will be graded.

Drill

Tap to flip · arrow keys to move

Glossary

Dynamic microsimulation: Project a population person-by-person through estimated transition models, then run policy rules over the simulated lifepaths.
PSID: Panel Study of Income Dynamics — US household panel following the same families since 1968; the model's estimation frame.
DYNASIM: The Urban Institute's dynamic microsimulation, in its fourth generation. Published DYNASIM3 claiming results are the model's closest external comparator.
MINT: Modeling Income in the Near Term — SSA's microsimulation, built on survey records matched to administrative earnings.
Temporal holdout: Certification by fitting on early panel waves and scoring blind on held-out later years, with thresholds locked in advance.
Validation-only: The rule that benchmark comparisons never feed back into estimation — the wall measures the model; it never trains it.
Gap classes: Every benchmark divergence is classified: a missing module, an unverified source, a concept or label mismatch, a frame that can't align — or unexplained, which is required to be zero.
Forecast ledger: Append-only public schedule forecasts with p50/p80 dates, graded at resolution; superseded entries stay on the record.
Covered earnings: Earnings subject to FICA — what Social Security credits and taxes. The correction program replaces the model's labor-income proxy with this concept.