dynamics / learn

How the model works, and how to check it

Microcosm Dynamics is a computer model of Social Security's retirement, survivor and disability benefits that anyone can download, run and check. This page explains how it works, how we test it and what those tests do and do not show, then lets you quiz yourself. It follows the working paper of October 2026. If this page and the paper ever disagree, trust the paper.

Watch it work

A dynamic microsimulation follows people, not averages. The diagram follows 12 made-up people; each line is one person. Left of the dashed line are years for which the Panel Study of Income Dynamics (PSID) recorded earnings; right of it are years the model simulates. Earnings bands grow thicker and darker as a person earns more. Filled violet dots joined by a line mark a marriage, open violet rings mark a birth, bronze rings mark a benefit claim between 62 and 70, and a line ends when the person dies. A line that is thicker overall stands for more people, as survey weights do. Faint dashes mark the odd years from 1997 on, which the model fills in from neighboring years (see missing years). The shaded band marks 2015 to 2019, the years scored by the holdout test; for that test, the model learned only from data through 2014. The strip at the bottom tracks the share of these 12 people who have claimed benefits.

The model

Some questions about Social Security need more than a snapshot of one year, such as which retirees a benefit cut reaches decades from now. Dynamic microsimulation answers them by aging a population of individual people year by year, drawing their earnings, marriages, disabilities, deaths and benefit claims, and applying the program's rules to each life. The Urban Institute's DYNASIM, the Social Security Administration's MINT and the Congressional Budget Office's long-term model, CBOLT, do this for Social Security. Outsiders can read the results these models publish, but CBO does not publish CBOLT's code, and we found no public code with which to rerun DYNASIM or MINT. We publish the code, estimates and tests of Microcosm Dynamics under the MIT license.

The model learns how lives unfold from the Panel Study of Income Dynamics, a University of Michigan survey that has followed a set of American families, and the new families their members form, since 1968. It takes the ages at which people claim benefits from the Social Security Administration's published awards. MINT and CBOLT run on SSA's administrative earnings records, and SSA has a legal obligation to protect the confidentiality of the people in them; anyone can obtain the PSID's data.

The model produces no cost estimates, no measure of Social Security's long-run balance and no date when the trust funds run out. It reports how a reform's effects differ across people, such as benefit changes by age group and poverty at 67.

Three layers

• The starting population. Every projection so far starts from PSID members. The two projection tests, the blind tests of a one-point cut to cost-of-living adjustments and of raising the full retirement age, the age for an unreduced benefit, to 68 (below), start from 11,405 people born in 1980 or earlier, in the families the PSID interviewed in 2011. Their earnings records run from 1968 through 2010, with the earnings the PSID recorded where it has them and filled-in or zero values where it does not. The model is also built to start from Microcosm's frame of 166,302 people, drawn mainly from the Census Bureau's Current Population Survey (CPS), but no projection starts there yet.
• The projection engine. It moves each person through one year at a time, in eight steps (below). For the holdout test, we let it learn only from data through 2014 and compared its projection for 2015 to 2019 with what the PSID recorded.
• The rules layer. Python code turns each simulated life into Social Security benefits. It computes each worker's benefit from average indexed monthly earnings (AIME), adjusts it for claiming age and adds spouse and survivor benefits. It takes Social Security's parameters from PolicyEngine-US, PolicyEngine's model of U.S. tax and benefit rules. The Axiom rules engine, which encodes the statute as machine-readable rules, so far reproduces one piece of that code: AIME computed over the number of years the law sets, for all 7,486 people we tested. The projection tests count a fixed 35 years instead, which gives a different AIME for 251 of those people, all born before 1929.

Which parts pass a gate

A gate is a test on data set aside from what the model learned from, or on outside data, that we register publicly before we run it. Its pass rule is fixed before each scored run and changes only by public amendment (more below).

A candidate is a version of a piece that we register for one scored run. Several gates score each candidate on five seeds: starting numbers for the model's random draws, such as who dies or marries in a given year. "4 of 5 seeds" means the candidate passed on four of the five.

None of the four blind tests against DYNASIM3 (below) uses a component that passes a gate. The parts they use include the PSID's recorded earnings, mortality, the SSDI component, claiming and the Python benefit rules.

Inside each simulated year

Each simulated year, the engine takes every person's record through eight steps in a fixed order. Each step is a separate component that does its own calculations. The loop fixes only the order of the steps and the flow of marital status: the childbearing and household steps both read the one result the marital step produces, so every later step works from the same marriage history.

1. Mortality. The model decides at random who dies each year, using death probabilities by age group and sex. No gate tests this step, or how death rates change over time. The projection tests use SSA's 2004 period life table, the death rates by age observed in 2004, scaled each year by the change in death rates that the Social Security Trustees' 2008 report projects.
2. Aging. Everyone grows a year older.
3. Marriage. The marital step updates each person's marital status. The marriage model that passes gate 2 covers marriage, divorce, remarriage and widowhood, but the projection tests do not use it: in them, a person becomes widowed when a linked spouse dies, and no one marries or divorces.
4. Childbearing. This step decides who has a child, reading the marital step's result. Gate 2 scores births along with marriage. The projection tests add no newborns.
5. Disability. This step models who reports a health problem that limits their work: who starts reporting one, who recovers, how many report one at a time, and how people leave near full retirement age. It passes gate m4, which compares it with PSID records set aside from what it learned from, and with the age pattern and mix of exits, but not the levels, of SSA's 2023 disability-insurance statistics. Work limitation is a different measure from receiving Social Security Disability Insurance (SSDI). The projection tests use a separate component, with no gate, that decides who receives SSDI: awards, recoveries and the switch to a retirement benefit at full retirement age, at rates observed through 2008.
6. Earnings. The forward earnings model (the paper calls it the forward earnings law) decides at random, every two years, whether each person works and where they rank among earners. It then converts that rank to dollars using the national average wage index, which it projects by extending the 2005 to 2014 trend. It learned from PSID earnings through 2014 at ages 25 to 64; for anyone older, it reuses the pattern of its oldest age group. It passes gate m6 but fails B2, a registered test that carries it from 2010 to 2014, and no blind test uses it yet: the projection tests include no earnings after 2010 and count every later year as zero in the benefit formula.
7. Claiming. The model picks each person's claim age at random, following SSA's published distribution of retired-worker awards by sex and year of entitlement (Annual Statistical Supplement, Table 6.B5.1). No gate tests this step, and no claim responds to a reform. For years after 2008, the projection tests reuse the 2008 distribution.
8. Household composition. This step works out who lives with whom, reading the marital step's result. It passes gate 2b, but the projection tests do not use the gated household model.

Immigrants enter the population on a schedule, through a separate entry point in the loop. We report that output, no gate scores it, and the projection tests add no immigrants.

The model has three kinds of earnings. Recorded earnings are the labor income the PSID recorded for its family heads and spouses, with the gaps filled in or set to zero (see missing years). Generated earnings come from a backward-looking process that produces earnings careers, which passes gate 1. Projected earnings come from the forward earnings model above. The blind tests use only the recorded kind.

The engine draws its random numbers from separate, repeatable sequences: one for each draw, time period and step, and for each person where a step needs it. The same seed produces an identical projection.

Weights and missing years

• Weights. The PSID began in 1968 by joining a nationally representative sample of families with an extra sample of low-income families, and it publishes weights that account for those unequal chances of being selected. Every blind test weights each PSID person by the PSID's own weight for that person in the survey year it uses, and none adjusts those weights.
• Missing years. The PSID asked about earnings for every year through 1996. Since 1997 it has interviewed every other year, and each interview centers on the year before it. The model's main earnings records read only those years, so the model fills in each odd year from 1997 on from neighboring years, or sets it to zero when no neighboring year was recorded. (The minimum-benefit test instead reads the PSID's reports for those in-between years, 2001 to 2021.) The model also sets other years without a usable record to zero, such as years in which a person lived in no PSID family that responded. For the 7,486 people in the projections who reach 62 between 1979 and 2030, about half of their career years through 2010 hold filled-in or zero values. A registered test, gate_epuf_fill, scores both fill rules against Social Security's earnings records, and both fail it; a learned fill for the years before a career passes, but no blind test uses the learned fills yet.
• No corrections. The model reads the PSID's labor income as the PSID records it, including the values the PSID itself filled in, and takes reported zero earnings at face value. It treats that labor income as the earnings Social Security covers.

How the PSID and the CPS frame fit together

The PSID knows how lives change; the CPS frame knows who the country is. The model is built to use both, and so far they meet in one place, gate w1.

How we test it: gates

Before we score a piece of the model, we post which statistics we will compare, which we call cells, and how close counts as a pass for each, its tolerance. We call such a test a gate: a test on data set aside from what the model learned from (held-out data), or on outside data, that we register publicly before we run it. The term comes from the quality gates that code must clear before it ships, and from the go/no-go decisions of clinical trials. A piece that faces a gate joins the model only after it passes.

• One scored run per candidate. We call each version of a piece that we register for scoring a candidate. Each candidate gets one scored run, and we publish the result in the public repository whatever the verdict. Failed candidates stay on the record next to the one that passed.
• Tolerances from the data's own noise. We set most tolerances from a noise floor: how far apart two halves of the real PSID, with no person in common, land on the same statistic. A seed passes only if every scored cell stays within its tolerance. The gates for marriage and childbearing, household makeup, and marriage by earnings (gates 2, 2b and 2c) each need at least 4 of their 5 seeds to pass.
• Changes only in public. We change a gate's terms only by a public amendment, which must come before the next scored run.

Gate 3 would score near-term outputs, such as beneficiary counts and average benefits, against annual administrative publications. It has no cells or tolerances yet and has never run.

The engine's holdout test

To test the projection engine as a whole, we let it learn only from data through 2014, projected forward and compared the projection with what the PSID recorded. Gate m6 scores projected changes in marital status and in disability for 2015 to 2019, and earnings statistics for 2016 and 2018. It scores only the people the PSID observed in each later round of interviews, and the scored run may use which people those were; an open forward projection, which no gate scores, gets no such information. The model treats 2020 to 2022 as a shock outside its scope; we publish the results for those years but score none of them.

We had already seen the years it scores. What the engine estimates came only from data through 2014, but not every design choice did. We chose the cells gate m6 scores, and the structure of the forward earnings model, with the PSID's records for 2015 onward in view.

Its terms changed after a failure. Candidate 1, the first version of the engine we scored, failed. We then adopted a public amendment with two parts. First, it restricts the earnings cells to people for whom the model estimated a 2014 earnings position; the engine fixes everyone else's earnings at zero instead of projecting them. That took 2,722 of the 13,163 people those cells had scored out of the earnings comparison. Second, it re-derives the noise floors from which those cells' tolerances are set. Candidate 2 failed under the amended terms. Candidate 3 passed, in 4 of 5 seeds.

The new floors loosened the low-earnings tolerance. The re-derived floors raised the tolerance on the 10th percentile of positive earnings at ages 25 to 44 from 0.221 to 0.284, on a log scale. In plain terms, the projection's figure may now fall short of the PSID's by up to about 25 percent, instead of about 20 percent. Three of candidate 3's four passing seeds score between those two values.

The passing version still differs from the PSID. In every seed, its remarriage rate runs 27 to 51 percent higher than the PSID's. At ages 25 to 44, its two-year earnings growth runs 2.7 to 5.2 log points (about 3 to 5 percentage points) lower, and its 10th percentile of positive earnings runs 15 to 24 percent lower. Its earnings also hold steadier: the correlation of a person's earnings four years apart, on a log scale, runs 0.74 to 0.76 in the projection against 0.67 to 0.71 in the PSID.

Gate m6 certifies nothing about how death rates or widowhood change over time, or about the people who enter the population, and no blind test uses the forward earnings model yet.

Four blind tests against DYNASIM3

The second kind of test compares the model with published results from DYNASIM3, the previous generation of the Urban Institute's model. For each test we post a plan, called a registration, in public before the run. A separate workstream, working apart from the model's builders, reads DYNASIM3's published numbers twice, independently, and seals them until we have saved the model's output to the public repository. No test has a pass mark: DYNASIM3 is another model, so each gap measures a disagreement between two models, not an error in either. None of the tests involves DYNASIM4, the current version, and none establishes that our model matches either version.

• The close match is a weak test of how lives change. Once we choose the year from which each person's cost-of-living increases are cut, the cut's effect on benefits already being paid follows by arithmetic, so the match says little about how well the model captures how lives change.
• What the projections leave out. The first two tests project PSID families to 2030. In them, nobody earns, marries or divorces after 2010. Every claimant with earnings on record through 2010 gets a retirement benefit, without a check that they worked long enough to qualify. We do not apply the retirement earnings test, which withholds benefits from early claimants who keep working, and no one changes when they claim in response to the reform. Benefits come from the Python rules, which count a fixed 35 years of earnings for every worker. Leaving out claiming responses or the earnings test could account for the gap at ages 65 to 69.
• Small numbers and rounding. The model's poverty figure rests on 483 people born in odd years from 1937 to 1945, so one person of average weight moves it by about 0.2 points. DYNASIM3's report rounds poverty rates to whole percentages, so its 2-point rise could lie anywhere between 1 and 3 points.
• Who gets the minimum. The headline share hides a split by sex. Under the model's main assumptions, all four versions of the minimum benefit put a larger share of women and a smaller share of men on it than DYNASIM3 does. Three of the six alternative assumptions we registered in advance break that pattern in at least one version.
• Different populations. The last two tests apply each reform to incomes people reported to the PSID, while DYNASIM3's figures come from projections published in 2004 and 2006, so part of each gap can reflect the different populations.
• Blind only as far as the records show. The AI model that coordinated the build saw the cost-of-living test's DYNASIM3 values before that test ran, in a report that may also have held the retirement-age test's. The builders, some of them AI agents, could reach files of DYNASIM3 material, and the records cannot rule out that they opened them. The person who wrote the plan for the 13 percent cut test read a page of DYNASIM3's 2004 report that includes discussion of its results. The person who wrote the first plan for the minimum-benefit test read one sentence that was supposed to be withheld; it describes a table outside that test's targets.

An interactive scorecard publishes every cell of the four tests, each test's timeline and every alternative assumption registered in advance. The benchmark wall is a separate page. It lists figures published by other models, among them DYNASIM, MINT and CBO's, and by SSA and Social Security's Trustees, and it classifies each gap between them and this model. For more than half of its rows, the model does not yet produce a comparable figure. The paper does not draw on the wall. The paper's pass-or-fail verdicts come only from the gates, and the four blind tests report their gaps without grading them.

What the PSID cannot tell us

The PSID's design limits what the model can learn from it:

• Size. In 2023 the PSID interviewed 9,152 families, against about 95,000 households a year in the Current Population Survey, so figures for small groups are noisy, as in the poverty test above.
• Who it covers. It follows the families of 1968 and their descendants, so it covers later immigrants mainly through two small added samples.
• Who stays. Of the original 1968 members still alive in 2015, about 40 percent were still responding, and those who left differ from those who stayed.
• Low earnings. Its records of low earnings have known measurement problems, many of which trace to changes in how it interviewed people and processed their answers in 1993 and 1994. The model reads these records as the PSID gives them and corrects none of these problems.

The model addresses these limits in two ways, and we have begun a third step: a check against Social Security's own earnings records, which has compared the PSID's recorded earnings with them and scored the model's rules for filling gaps in recorded careers, without yet scoring its generated earnings or whole careers; none removes the limits. It is built to carry the PSID's patterns of change onto Microcosm's calibrated CPS frame, which gate w1 tests, though no projection starts there yet. Its gates set tolerances from the PSID's own sampling noise, which cannot reveal a bias the whole PSID shares. And we plan to check the PSID's earnings careers, and those the model generates, against SSA's 2006 Earnings Public-Use File, which holds annual earnings records for 1951 through 2006 for a 1 percent random sample of all Social Security numbers issued before 2007. So far we have compared the PSID's own earnings for 1998 to 2004 with it and, in a separate registered test, scored the rules that fill the years recorded careers leave out on 878,481 people held back from the file: both rules the blind tests use fail, a learned fill for the years before a career passes, and no blind test uses the learned fills yet. We have registered the rules for the part of that check that covers the earnings the model generates, which overlap the file only in the even years from 1998 to 2004. On that span only two cells met the rules for gating, we have not shown that they would catch anything gate 1 does not, and their bite check fell short of its target. The registration therefore does not lock and gates no cell, and we report how the PSID's own earnings compare with the file, without a pass or fail. We have not yet run it on the model's output, and we have not run the comparison of careers.

The first registered test of carrying earnings forward from 2010, B2, failed in October 2026: the share of people aged 25 to 44 with no earnings in 2012 and 2014 came out about 35 percent higher in the model than in the PSID. A successor, designed on evidence other than that result, has to pass before forward earnings join the projections. We plan to add earnings, marriage and divorce after 2010 to the projections, apply the retirement earnings test and the family maximum (the cap on what one worker's family can collect), let claim ages respond to reforms where the data support it, run the full benefit rules in Axiom, and compare the model with public tables from SSA's actuaries, MINT, the Penn Wharton Budget Model and CBO.

Drill

Tap to flip · arrow keys to move

Glossary

Dynamic microsimulation

A model that ages a population of individual people year by year, drawing their earnings, marriages, disabilities, deaths and claims, and applies a program's rules to each life.

PSID

The Panel Study of Income Dynamics: a University of Michigan survey that has followed a set of American families, and the new families their members form, since 1968.

CPS frame

Microcosm's population of 166,302 people in 57,240 households, drawn mainly from the Census Bureau's Current Population Survey and weighted to official totals.

Gate

A test on data set aside from what the model learned from, or on outside data, that we register publicly before we run it, with its pass rule fixed in advance and changed only by public amendment.

Cell and tolerance

A statistic a gate scores, and how far the model may miss it and still pass.

Noise floor

How far apart two halves of the real PSID, with no person in common, land on the same statistic. We set most tolerances from it.

Candidate

A version of a piece of the model that we register for one scored run against its gate. At gates 1 and w1, the candidate that passed was identical to one that had failed under the old terms.

Seed

The starting number for the model's random draws. The same seed always gives the same result, and several gates score each candidate with five seeds.

Amendment

A public change to a gate's terms, which must come before the next scored run.

Report-only

A cell we publish with no tolerance, so it cannot fail a gate.

Holdout test

Gate m6, which the paper calls a temporal holdout: the engine learned only from data through 2014, and we compared its projection with what the PSID recorded for 2015 to 2019. We chose the scored cells, and the structure of the forward earnings model, with those later years in view, and it passed under an amendment adopted after its first candidate failed. Gates 1, 2, 2b and 2c are holdout tests of a different kind: they score a piece of the model on people left out of what it learned from.

Blind test

A comparison with DYNASIM3's published results in which DYNASIM3's values stay sealed until the model's output is saved to the public repository. A test is blind only as far as its registration's disclosed exposures show.

Retirement earnings test

The Social Security rule that withholds benefits from early claimants who keep working. The model holds its parameters but does not yet apply it.

DYNASIM

The Urban Institute's dynamic microsimulation model. The four blind tests use published results from DYNASIM3; DYNASIM4 is the current generation.

MINT

The Social Security Administration's microsimulation model, which runs on Social Security's administrative records matched to the Survey of Income and Program Participation.

AIME

Average indexed monthly earnings: a worker's average monthly earnings over the highest-earning years, adjusted for wage growth. The benefit formula starts from it.

Covered earnings

Earnings from jobs that Social Security covers. The model treats the labor income the PSID records for family heads and spouses as covered earnings.

Axiom

A rules engine that encodes the Social Security statute as machine-readable rules. So far it reproduces one piece of the model's Python benefit rules: AIME computed over the number of years the law sets, for all 7,486 people we tested. It reproduces nothing else yet.