diff --git a/CLAUDE.md b/CLAUDE.md index fb1ea4f1..b21bec60 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **Current phase**: Implementation, under a locked pre-registered evaluation gate. -This repository is Populace dynamics: an open longitudinal microsimulation layer (paper at populace.dev/papers/dynamics) plus a working implementation in `src/populace_dynamics/`: +This repository is Microcosm Dynamics: an open longitudinal microsimulation layer (paper at microcosm.institute/dynamics/paper) plus a working implementation in `src/populace_dynamics/`: - `harness/` — the population-view scoring harness (geometry blocks, PanelView trajectory windows, the moment battery in `moments.py`) - `data/` — label-verified PSID readers (`family.py` builds the 1968-2022 head/spouse earnings panel with assignment flags; PSID files staged at `~/PolicyEngine/psid-data`) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 451e30c8..c2852f8d 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -3,7 +3,7 @@ project: output-dir: _book book: - title: "Populace dynamics" + title: "Microcosm Dynamics" subtitle: "An open, scored longitudinal layer for policy microsimulation — validated first on U.S. Social Security" author: - name: Max Ghenis diff --git a/docs/benchmark-model-component-matrix.md b/docs/benchmark-model-component-matrix.md index 83d2638f..fc0a11b9 100644 --- a/docs/benchmark-model-component-matrix.md +++ b/docs/benchmark-model-component-matrix.md @@ -33,7 +33,7 @@ That means: This chapter covers five comparison objects: 1. **Our plan** - longitudinal `populace` plus PolicyEngine-US plus this Social + longitudinal Microcosm plus PolicyEngine-US plus this Social Security application layer 2. **DYNASIM** the main non-governmental dynamic benchmark @@ -65,11 +65,11 @@ modern retirement-outcomes model being used for LTSS policy analysis | Component | Our plan | DYNASIM | MINT | CBO / CBOLT | Morningstar | |---|---|---|---|---|---| -| **Base population** | Public synthetic `populace`, PolicyEngine's ML-first microdata layer, extended longitudinally | SIPP-based starting sample with publicly documented 0.04% core and 0.4% expanded variants [@favreault2015; @urban2024dynasim4] | SIPP plus administrative earnings and program records for strong near-retirement credibility [@smith2010mint; @smith2021mint8; @ssa2024mint] | SSA Continuous Work History Sample foundation, with a 1-in-1,000 representative microsimulation sample and SIPP/CPS imputations for missing demographics and family structure [@cbo2018; @cbo2019replacementrates] | Household-oriented retirement simulation using current resources, projected longevity, healthcare, and retirement assets; public materials emphasize model outputs more than raw starting-file mechanics [@look2024retirementoutcomes; @morningstar2024modelpage] | -| **Historical earnings** | Synthetic reconstruction from panel data, calibrated against `populace`'s registry of administrative targets; benchmarked across candidate model families | Public record shows lifetime economic histories built from survey and linked administrative inputs, with annual updating and alignment [@favreault2015; @urban2024dynasim4] | Strongest public benchmark because administrative earnings are built in for many cohorts [@smith2010mint; @ssa2024mint] | Public record discusses lifetime earnings assumptions and fiscal outputs, but is much less explicit on the micro history-construction machinery [@cbo2004; @cbo2018; @cbo2024finances] | Public papers say the model estimates historical wages for each household member and then simulates accumulation and retirement adequacy; claim age is simplified in the inaugural analysis [@look2024retirementoutcomes] | +| **Base population** | Public synthetic Microcosm, PolicyEngine's ML-first microdata layer, extended longitudinally | SIPP-based starting sample with publicly documented 0.04% core and 0.4% expanded variants [@favreault2015; @urban2024dynasim4] | SIPP plus administrative earnings and program records for strong near-retirement credibility [@smith2010mint; @smith2021mint8; @ssa2024mint] | SSA Continuous Work History Sample foundation, with a 1-in-1,000 representative microsimulation sample and SIPP/CPS imputations for missing demographics and family structure [@cbo2018; @cbo2019replacementrates] | Household-oriented retirement simulation using current resources, projected longevity, healthcare, and retirement assets; public materials emphasize model outputs more than raw starting-file mechanics [@look2024retirementoutcomes; @morningstar2024modelpage] | +| **Historical earnings** | Synthetic reconstruction from panel data, calibrated against Microcosm's registry of administrative targets; benchmarked across candidate model families | Public record shows lifetime economic histories built from survey and linked administrative inputs, with annual updating and alignment [@favreault2015; @urban2024dynasim4] | Strongest public benchmark because administrative earnings are built in for many cohorts [@smith2010mint; @ssa2024mint] | Public record discusses lifetime earnings assumptions and fiscal outputs, but is much less explicit on the micro history-construction machinery [@cbo2004; @cbo2018; @cbo2024finances] | Public papers say the model estimates historical wages for each household member and then simulates accumulation and retirement adequacy; claim age is simplified in the inaugural analysis [@look2024retirementoutcomes] | | **Family structure** | Explicit relationship-history layer with spouse links, widowhood, divorce duration, remarriage, and benefit-facing auxiliary states | Public documentation shows marriage, divorce, family structure, and spouse-related states are part of the annual simulation [@favreault2015; @urban2024dynasim4] | Public methodology supports spouse and survivor benefit analysis, but the public record is less explicit than DYNASIM on relationship-history mechanics [@smith2010mint; @ssa2024mint] | Public record is relatively thin on family-history construction at the record level [@cbo2004; @cbo2018] | Public outputs are household-based and broken out by family status, but the public record does not suggest a fully general spouse-former-spouse-child network like the one needed for detailed auxiliary-benefit analysis [@morningstar2024modelpage; @look2024retirementoutcomes] | | **Disability and health** | Separate impairment, program-pathway, and claiming states, plus mortality and family interactions | Publicly documented health, disability, cognition, and work-limitation modules with yearly transitions [@favreault2015; @urban2024dynasim4] | Includes disability pathways but with publicly documented simplifications around adjudication and return-to-work rules [@ssa2024mint] | Public record is strong on aggregate Social Security finances and disability spending, weaker on record-level disability-state machinery [@cbo2024finances; @cbo2024longterm] | Public papers explicitly include healthcare costs, projected longevity, and LTSS states such as home healthcare and nursing home need, but not a public SSDI-style program pathway [@look2024retirementoutcomes; @look2025ltss] | -| **Wealth, assets, and LTSS** | Not phase-1 core, but preserved as a later extension track through longitudinal `populace` | Major documented strength: wealth, pensions, health spending, LTSS use, payer assignment, and Medicaid interaction [@favreault2015; @urban2024dynasim4; @favreault2020ltss] | Stronger than a Social Security-only model on pensions and SSI interactions, but not positioned publicly as a leading LTSS model [@smith2010mint; @ssa2024mint] | Public emphasis is fiscal outlook rather than household adequacy, wealth depletion, or LTSS risk pathways [@cbo2024finances; @cbo2024longterm] | Major strength: retirement assets, expenses, projected inadequacy, and recent LTSS and WISH analyses using the same model family [@look2024retirementoutcomes; @look2025ltss; @look2025wish] | +| **Wealth, assets, and LTSS** | Not phase-1 core, but preserved as a later extension track through longitudinal Microcosm | Major documented strength: wealth, pensions, health spending, LTSS use, payer assignment, and Medicaid interaction [@favreault2015; @urban2024dynasim4; @favreault2020ltss] | Stronger than a Social Security-only model on pensions and SSI interactions, but not positioned publicly as a leading LTSS model [@smith2010mint; @ssa2024mint] | Public emphasis is fiscal outlook rather than household adequacy, wealth depletion, or LTSS risk pathways [@cbo2024finances; @cbo2024longterm] | Major strength: retirement assets, expenses, projected inadequacy, and recent LTSS and WISH analyses using the same model family [@look2024retirementoutcomes; @look2025ltss; @look2025wish] | ## Matrix 2: benefit logic, behavior, and policy use diff --git a/docs/calibration-targets.md b/docs/calibration-targets.md index f3980f10..04a5b28d 100644 --- a/docs/calibration-targets.md +++ b/docs/calibration-targets.md @@ -2,11 +2,11 @@ ## Overview -Calibration ensures that longitudinal `populace` matches known +Calibration ensures that longitudinal Microcosm matches known population characteristics and that the Social Security application layer matches system aggregates. This chapter specifies the targets the project will use for calibration, their sources, and priority -weighting. `populace` maintains these administrative aggregates as a +weighting. Microcosm maintains these administrative aggregates as a versioned target registry — signed facts with standard errors — so that calibration runs against a single, consistent set of targets and treats them as uncertainty-weighted evidence rather than exact hits. diff --git a/docs/data-sources.md b/docs/data-sources.md index a1214951..fb58bcc3 100644 --- a/docs/data-sources.md +++ b/docs/data-sources.md @@ -3,12 +3,12 @@ ## Overview Building a dynamic Social Security microsimulation model means -extending `populace` longitudinally and then using it for Social +extending Microcosm longitudinally and then using it for Social Security analysis. That requires multiple data sources that capture cross-sectional population characteristics, longitudinal earnings dynamics, and demographic transitions. -PolicyEngine's `populace` stack assembles these primary sources, +PolicyEngine's Microcosm stack assembles these primary sources, along with the administrative aggregates used as calibration targets, and builds a calibrated synthetic population from them. This chapter describes the primary sources that feed that pipeline. @@ -42,7 +42,7 @@ describes the primary sources that feed that pipeline. - Limited earning history (only current year) **Our Use**: -- Core cross-sectional input to the current public `populace` +- Core cross-sectional input to the current public Microcosm population layer - Validation of age-earnings profiles - Calibration targets for population characteristics @@ -75,7 +75,7 @@ describes the primary sources that feed that pipeline. - Public use files have restricted geographic detail **Our Use**: -- **Primary source for longitudinal extension of `populace`** +- **Primary source for longitudinal extension of Microcosm** - Training data for quantile regression forests - Validation of lifetime earnings distributions - Demographic transition modeling @@ -336,7 +336,7 @@ state LTC pilot. One reason LTC is hard to model is that no single public dataset adequately covers household populations, caregivers, and institutional residents at the same time. CPS and many other core household surveys exclude most institutional populations. An LTC-ready architecture therefore needs an explicit blended strategy: -1. Household base population from Populace's calibrated CPS-based core and allied surveys +1. Household base population from Microcosm's calibrated CPS-based core and allied surveys 2. Longitudinal aging and wealth dynamics from PSID and HRS 3. Care-need and caregiving detail from NHATS/NSOC and MCBS 4. Institutional population benchmarks from MDS and Medicaid administrative sources @@ -355,7 +355,7 @@ Rather than treating each survey in isolation, we pursue a multi-survey fusion s Our data integration follows a hierarchical structure: -1. **Base population**: Populace's CPS-based core providing a large sample with calibrated cross-sectional income +1. **Base population**: Microcosm's CPS-based core providing a large sample with calibrated cross-sectional income 2. **Longitudinal structure**: PSID for earnings trajectories and transition dynamics 3. **Income detail**: PUF for tax return variables and high-income tail corrections 4. **Validation**: SIPP for program participation; administrative aggregates diff --git a/docs/evaluation-and-model-selection.md b/docs/evaluation-and-model-selection.md index 676013ef..248f74c4 100644 --- a/docs/evaluation-and-model-selection.md +++ b/docs/evaluation-and-model-selection.md @@ -13,7 +13,7 @@ enough to justify the next stage of the build. This chapter therefore defines the evaluation framework for deciding: - which earnings architecture becomes the production path for - longitudinal `populace` + longitudinal Microcosm - whether the resulting panel is good enough for benefit calculation - whether the full project has earned the right to advance from stage 1 to stage 2 @@ -141,7 +141,7 @@ person-years. ### Cross-sectional anchor tests -Because the final use case starts from a cross-sectional `populace` +Because the final use case starts from a cross-sectional Microcosm record, the project should also simulate that workflow directly: 1. collapse a held-out panel person to a pseudo-cross-section at a @@ -274,7 +274,7 @@ These may include: - zero-fraction error - correlation preservation -They are useful as diagnostics, especially for comparing `populace` +They are useful as diagnostics, especially for comparing Microcosm candidate families, but they are not the final decision rule. ### Operational metrics @@ -317,7 +317,7 @@ For candidates that clear Gate 1, score them on: - policy-output fit - stability - runtime and reproducibility -- architectural alignment with longitudinal `populace` +- architectural alignment with longitudinal Microcosm The scorecard should be reported as a table, not just prose. @@ -330,7 +330,7 @@ The winning architecture should be the one that: 3. is simple enough to explain and maintain publicly That rule leaves open whether the winner is ZI-QDNN, ZI-MAF, a broader -`populace` sequence model, or a more transparent annual-state process. +Microcosm sequence model, or a more transparent annual-state process. ## Suggested numeric thresholds for stage 1 @@ -381,14 +381,14 @@ decision: - which architecture deserves continued investment - what the residual limitations are even if the answer is "yes" -## Relationship to the refreshed Populace evaluations +## Relationship to the refreshed Microcosm evaluations -The `populace` imputation evaluations should feed directly into this +The Microcosm imputation evaluations should feed directly into this chapter, but they should not be the only evidence. The right interpretation is: -- refreshed `populace` evals help narrow the candidate set +- refreshed Microcosm evals help narrow the candidate set - Social-Security-specific benchmarks decide the production winner - the proposal should remain architecture-agnostic until both pieces are in hand diff --git a/docs/funder-summary.md b/docs/funder-summary.md index ff31c9a5..9aa743a9 100644 --- a/docs/funder-summary.md +++ b/docs/funder-summary.md @@ -1,9 +1,9 @@ -# Concept note: Populace dynamics +# Concept note: Microcosm Dynamics ## What this is This concept note describes the design of an open, longitudinal -Dynamics layer for `populace`, PolicyEngine's country-agnostic +Dynamics layer for Microcosm, PolicyEngine's country-agnostic microdata stack — validated first on the U.S. Social Security system, and built so that every claim it makes can be scored against reality. Social Security is the proving ground because it is the @@ -15,7 +15,7 @@ benefit systems as PolicyEngine's country coverage grows. The premise is George Box's, taken literally: all models are wrong, and a model is useful only if it improves predictions. So this project's product is not a brand-name simulator. The machinery lives -in `populace`, PolicyEngine's open microdata stack; the deliverable +in Microcosm, PolicyEngine's open microdata stack; the deliverable is a versioned population artifact with a manifest and a public scorecard; and this repository holds the Social Security application and the validation program that grades it. Models made their names @@ -156,7 +156,7 @@ combination: backtests, and held-out moments — in place of fidelity-only validation - domains of validity as shipped metadata on every output -- a contribution rule inherited from `populace`: changes merge if +- a contribution rule inherited from Microcosm: changes merge if and only if they improve the score on held-out facts, from any contributor - AI-callable interfaces from day one @@ -167,8 +167,8 @@ No equivalent bundle exists for U.S. Social Security analysis. The natural implementation is the PolicyEngine open-source stack. -**Populace** is PolicyEngine's rebuilt, open-source microdata stack -([github.com/PolicyEngine/populace](https://github.com/PolicyEngine/populace), +**Microcosm** is PolicyEngine's rebuilt, open-source microdata stack +([github.com/PolicyEngine/microcosm](https://github.com/PolicyEngine/microcosm), MIT). It builds a calibrated synthetic population entirely from primary-source government data (CPS/ASEC, IRS Public Use File, Survey of Consumer Finances, SIPP, CPS outgoing-rotation groups, @@ -179,7 +179,7 @@ PolicyEngine's enhanced CPS as the certified default U.S. microdata in policyengine.py, after a matched, symmetric-refit comparison on 41,314 households with a 739-target holdout: -| Metric (lower is better) | Populace | enhanced CPS | +| Metric (lower is better) | Microcosm | enhanced CPS | |---|---|---| | Holdout loss (739 held-out targets) | 0.038 | 0.317 | | Training loss | 0.190 | 1.089 | @@ -188,13 +188,13 @@ in policyengine.py, after a matched, symmetric-refit comparison on The asymmetry in the last row is published deliberately: the enhanced CPS wins more individual targets narrowly, while its -largest misses are far larger — Populace's aggregate loss is an +largest misses are far larger — Microcosm's aggregate loss is an order of magnitude lower on held-out targets. Publishing the number that cuts against the headline is the discipline this whole project -runs on. (Source: the release manifest in the Populace repository.) +runs on. (Source: the release manifest in the Microcosm repository.) **The longitudinal extension is designed, not improvised.** -Populace's charter names this project's direction explicitly and +Microcosm's charter names this project's direction explicitly and specifies the kernel rules: one weight per trajectory, with multi-period targets stacked as (target, period) constraint rows over the same weight vector; entry and exit markers (birth, death, @@ -212,12 +212,12 @@ forward are the same operator run in either direction. **PolicyEngine-US** supplies the rules engine — OASDI benefit calculation, benefit taxation, and means-tested interactions — -through Populace's rules-engine adapter, with Axiom's rules layer as +through Microcosm's rules-engine adapter, with Axiom's rules layer as the next adapter: statute encoded declaratively and compiled to Rust, a performance boundary that matters when benefit formulas run over person-periods across hundreds of thousands of trajectories. In that architecture PolicyEngine is a composition — Axiom rules, -Populace population, and a labeled behavioral scenario layer. +Microcosm population, and a labeled behavioral scenario layer. **PolicyEngine-API** and the MCP server are the delivery surface. The deliverable is a versioned artifact — `populace_us_panel_*` — @@ -337,7 +337,7 @@ These are not phase-one commitments. They are reasons to design the core architecture well. The longitudinal machinery itself is generic and lives upstream in -`populace`, whose kernel is country-agnostic. The same extension can +Microcosm, whose kernel is country-agnostic. The same extension can eventually serve other countries' pension and benefit systems; Social Security is the first application, not the boundary. @@ -377,7 +377,7 @@ makes the scorecard, and the case for trusting it, longer. be co-owned through bilateral institutional agreements. - Not a 75-year oracle — the long horizon ships as a sensitivity surface, never a point forecast. -- Not a brand-name simulator — the machinery is Populace's, the +- Not a brand-name simulator — the machinery is Microcosm's, the artifact is versioned, and the scorecard is the product. ## Open invitation diff --git a/docs/index.md b/docs/index.md index c5909cbd..7243bff6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Populace dynamics +# Microcosm Dynamics ::: {.callout-note} **Stage-gated planning document** @@ -17,7 +17,7 @@ go/no-go decisions of clinical trials. ## Executive summary -This project extends `populace` — PolicyEngine's certified, +This project extends Microcosm — PolicyEngine's certified, country-agnostic microdata stack — with an open longitudinal **Dynamics** layer, and validates it first on U.S. Social Security. The layer is built so that every claim it makes can be scored against @@ -47,7 +47,7 @@ through its resolution record One naming note, because it is a design decision: this project does not introduce a named simulator to stand beside DYNASIM or MINT. The -machinery lives in `populace`, PolicyEngine's open microdata stack; +machinery lives in Microcosm, PolicyEngine's open microdata stack; the deliverable is a versioned population artifact with a manifest and a scorecard. Models were branded when the model was the moat. Here the artifact and its track record are the product. @@ -80,7 +80,7 @@ them. At the same time, static tax-benefit modeling has already shown that publicly reproducible microdata can be useful when the pipeline is carefully engineered and aggressively validated. PolicyEngine's -Populace stack demonstrates this at production scale today — built +Microcosm stack demonstrates this at production scale today — built entirely from primary sources, it became the certified default U.S. microdata in policyengine.py in 2026 after beating the prior enhanced CPS on held-out accuracy. The next question is whether that stack can @@ -93,7 +93,7 @@ This project is: - a research and infrastructure effort to build a validated public synthetic longitudinal population -- a global capability: Populace's kernel is country-agnostic, so the +- a global capability: Microcosm's kernel is country-agnostic, so the same Dynamics layer can serve every country PolicyEngine models — pension and benefit systems abroad follow as country coverage expands @@ -112,19 +112,19 @@ This project is not: ## Decisions already made -### 1. Build on PolicyEngine's Populace microdata stack +### 1. Build on PolicyEngine's Microcosm microdata stack -The project extends `populace`, PolicyEngine's ML-first microdata +The project extends Microcosm, PolicyEngine's ML-first microdata layer, rather than building an isolated Social Security-only -dataset. Populace already integrates and calibrates dozens of +dataset. Microcosm already integrates and calibrates dozens of surveys and administrative sources and supports the methodological machinery (synthesis, calibration, sparsification, and authenticity/privacy evaluation) the Social Security extension needs. That choice matters because: -- generic population synthesis belongs in Populace, not in this +- generic population synthesis belongs in Microcosm, not in this repository -- Populace's cross-sectional layer is already validated against +- Microcosm's cross-sectional layer is already validated against large numbers of administrative targets - this repository can focus on Social Security domain validation and policy application rather than rebuilding generic synthesis tools @@ -134,7 +134,7 @@ needs. That choice matters because: ### 2. Social Security first, with adjacent interactions preserved The initial objective is still a Social Security model. That means the -first longitudinal extension of `populace` should include the family +first longitudinal extension of Microcosm should include the family structure, disability, and claiming dynamics needed for serious benefit analysis. It also preserves interactions with taxes, SSI, and other means-tested programs through PolicyEngine-US where possible. @@ -169,7 +169,7 @@ committed leadership alone. This project now has two validation obligations: -- validate longitudinal `populace` as a population asset +- validate longitudinal Microcosm as a population asset - validate Social Security outputs generated from that asset Those are related, but not identical. A population platform can look @@ -191,7 +191,7 @@ domain-of-validity tier as metadata By the end of the full plan, the project should produce: -- a documented longitudinal `populace` suitable for Social Security +- a documented longitudinal Microcosm suitable for Social Security analysis and adjacent reuse - a validated benefit-calculation pipeline integrated with PolicyEngine-US @@ -226,7 +226,7 @@ longitudinal ingredients, especially: family structure matter over time That does not mean those domains belong in phase 1. It means the -project should not lock `populace` into a Social-Security-only design +project should not lock Microcosm into a Social-Security-only design that cannot be extended later. ## Guide to the rest of the book diff --git a/docs/infrastructure.md b/docs/infrastructure.md index 450d6645..9de36b4b 100644 --- a/docs/infrastructure.md +++ b/docs/infrastructure.md @@ -5,7 +5,7 @@ Building a dynamic Social Security microsimulation model requires infrastructure for data processing, synthesis, calibration, and policy simulation. The most important architectural point is now clear: -`populace` should be treated as the population platform and dataset, +Microcosm should be treated as the population platform and dataset, while this repository provides the Social Security-specific application layer on top of it. This chapter describes the tools that make that split possible. @@ -21,11 +21,11 @@ flowchart LR SRC["CPS/ASEC, IRS PUF,
SCF, SIPP, CPS-ORG,
MEPS, ACS + admin targets"] end - subgraph population["Populace (microdata stack)"] - FRAME["populace-frame
(Frame kernel)"] - FIT["populace-fit
(conditional models)"] - CAL["populace-calibrate
(targets to weights)"] - LMPX["Longitudinal Populace
(project target)"] + subgraph population["Microcosm (microdata stack)"] + FRAME["microcosm-frame
(Frame kernel)"] + FIT["microcosm-fit
(conditional models)"] + CAL["microcosm-calibrate
(targets to weights)"] + LMPX["Longitudinal Microcosm
(project target)"] end subgraph application["Policy Application Layer"] @@ -55,22 +55,22 @@ flowchart LR The high-level logic is: -- `populace` builds and calibrates the public cross-sectional +- Microcosm builds and calibrates the public cross-sectional population from primary-source data (shipped; now the certified default U.S. microdata in policyengine.py) -- extend `populace` longitudinally — the project's central work +- extend Microcosm longitudinally — the project's central work - use PolicyEngine-US and this repository to turn that asset into a Social Security policy model This means the project should avoid rebuilding generic synthesis machinery in the Social Security repository when that work properly -belongs in `populace`. +belongs in Microcosm. ## Population layer versus application layer The tooling should be divided intentionally. -### What belongs in Populace +### What belongs in Microcosm - synthetic public population construction - cross-sectional and longitudinal calibration machinery @@ -94,39 +94,39 @@ public population platform plus an open policy application layer. ## Key tools and libraries -### Populace: the microdata stack +### Microcosm: the microdata stack **Purpose**: build and calibrate the public population from primary-source government data, and expose it to a rules engine. **Status**: PolicyEngine's rebuilt open-source microdata stack -([github.com/PolicyEngine/populace](https://github.com/PolicyEngine/populace), +([github.com/PolicyEngine/microcosm](https://github.com/PolicyEngine/microcosm), MIT). Built entirely from primary sources (CPS/ASEC, IRS PUF, SCF, SIPP, CPS-ORG, MEPS, ACS), it replaced PolicyEngine's enhanced CPS as the certified default U.S. microdata in policyengine.py in June 2026, after beating it on a held-out, symmetric-refit comparison. Its -synthesis method (the `populace-fit` shard) is a regime-gated, +synthesis method (the `microcosm-fit` shard) is a regime-gated, sequentially-chained, weight-aware quantile-regression-forest imputer, with a gradient-boosted classifier handling zero inflation. **Architecture**: one kernel datatype — the `Frame`, a weighted sampling frame of entity tables — with operators as separate shards -that share the `populace.*` namespace: +that share the `microcosm.*` namespace: -- `populace-frame`: the kernel (typed weights with conservation +- `microcosm-frame`: the kernel (typed weights with conservation invariants, strata for provenance, links, unit structure, and the rules-engine adapter protocol — policyengine-us today, Axiom's rules layer next). Succeeds microdf and microunit. -- `populace-fit`: weight-aware conditional models for synthesis and +- `microcosm-fit`: weight-aware conditional models for synthesis and imputation. Succeeds microimpute. -- `populace-calibrate`: targets-to-weights calibration (accelerated +- `microcosm-calibrate`: targets-to-weights calibration (accelerated projected gradient and L0 sparse selection). Succeeds microcalibrate. -- `populace-data` / `populace-build`: dataset registry and the +- `microcosm-data` / `microcosm-build`: dataset registry and the gated, no-fallback build pipeline. **Longitudinal status**: the kernel is longitudinal-ready by -design — one weight per trajectory — and Populace's charter names the +design — one weight per trajectory — and Microcosm's charter names the longitudinal extension (person-period keying, cohort entry and exit, household recomposition over time) explicitly as "the social-security-model direction." Those kernel hooks are deliberate @@ -142,12 +142,12 @@ project. ### Predecessor tooling: microimpute, microcalibrate, L0 -Before Populace, PolicyEngine's enhancement pipeline used three +Before Microcosm, PolicyEngine's enhancement pipeline used three standalone packages: `microimpute` (quantile-regression-forest and related imputation), `microcalibrate` (gradient-descent base-population calibration), and `L0` (L0-regularized sparse record selection). -Populace reimplements their capabilities as the `populace-fit` and -`populace-calibrate` shards on the shared `Frame` kernel; the legacy +Microcosm reimplements their capabilities as the `microcosm-fit` and +`microcosm-calibrate` shards on the shared `Frame` kernel; the legacy packages remain available but are no longer the path this project builds on. @@ -156,7 +156,7 @@ builds on. PolicyEngine's earlier Enhanced CPS used QRF imputation and gradient descent calibration against administrative targets [@ghenis2024]. That work is best understood as an important precursor to -`populace`, not as the architecture of this project. Populace +Microcosm, not as the architecture of this project. Microcosm generalizes the conceptual approach into a broader ML-first microdata stack. @@ -538,19 +538,19 @@ Like this document: We leverage a rich ecosystem of open-source tools: **Core tools** (PolicyEngine-developed): -- `populace`: the microdata stack (`populace-frame` kernel, - `populace-fit` synthesis, `populace-calibrate` calibration) +- Microcosm: the microdata stack (`microcosm-frame` kernel, + `microcosm-fit` synthesis, `microcosm-calibrate` calibration) - `policyengine-core`: microsimulation engine **Foundation** (existing): -- `populace` as starting point — shipped, and the certified default +- Microcosm as starting point — shipped, and the certified default U.S. microdata in policyengine.py - proven data construction and calibration pipeline - Social Security rules already implemented in PolicyEngine-US - infrastructure for web/API deployment **Additional methodological approaches** (to evaluate during proof of concept): -- **Baseline (incumbent)**: Populace's production synthesis method is a regime-gated, weight-aware quantile-regression-forest imputer. It is the proven cross-sectional method and the natural baseline for the longitudinal extension to beat. +- **Baseline (incumbent)**: Microcosm's production synthesis method is a regime-gated, weight-aware quantile-regression-forest imputer. It is the proven cross-sectional method and the natural baseline for the longitudinal extension to beat. - **Zero-inflated neural distribution models (e.g. ZI-QDNN)**: candidate for richer earnings-trajectory imputation, with a dedicated zero-inflation head and conditional quantile output — to evaluate against the QRF baseline, not assumed superior. - **Normalizing flows**: candidate for joint multi-year imputation where cross-year correlation structure matters; to evaluate, not committed. - **Multi-survey fusion**: Harmonize CPS, PSID, and PUF into unified datasets using common variable schemas and masked imputation for cross-survey variables diff --git a/docs/methodology.md b/docs/methodology.md index 47cc7d96..998f18b3 100644 --- a/docs/methodology.md +++ b/docs/methodology.md @@ -2,9 +2,9 @@ ## Overview -This chapter describes the technical approach to making `populace` +This chapter describes the technical approach to making Microcosm longitudinal and then using that longitudinal population for Social -Security microsimulation. `populace` is PolicyEngine's rebuilt +Security microsimulation. Microcosm is PolicyEngine's rebuilt open-source microdata stack: it synthesizes populations from primary-source U.S. government survey and administrative data (CPS/ASEC, IRS Public Use File, SCF, SIPP, CPS-ORG, MEPS, ACS) using @@ -28,26 +28,26 @@ MINT, and the public CBO record. ## Methodology flow The following diagram illustrates the high-level data flow through the -synthetic panel construction process. `populace` draws on +synthetic panel construction process. Microcosm draws on primary-source microdata and administrative calibration targets (including SSA aggregates): ```mermaid flowchart TD subgraph inputs["Input Data Sources"] - MPX["Populace
(Cross-sectional population)"] + MPX["Microcosm
(Cross-sectional population)"] PSID["PSID
(Longitudinal)"] SSA["Calibration targets
(SSA, CBO, IRS, Census)"] end subgraph processing["Longitudinal Extension"] - HIST["Add lifetime histories
to Populace"] + HIST["Add lifetime histories
to Microcosm"] TRANS["Add demographic and
family transitions"] CAL["Longitudinal validation
& calibration"] end subgraph outputs["Application Layer"] - PANEL["Longitudinal
Populace"] + PANEL["Longitudinal
Microcosm"] PE["PolicyEngine-US
Benefit Calculations"] WEB["Web Interface
& API"] end @@ -66,7 +66,7 @@ flowchart TD The methodology now has two explicit layers: -1. **Population layer**: make `populace` into a credible longitudinal +1. **Population layer**: make Microcosm into a credible longitudinal synthetic population. 2. **Application layer**: use that longitudinal population for Social Security benefit calculation, validation, and reform analysis. @@ -75,13 +75,13 @@ That split is not just organizational. It determines where methods and code should live. - Generic synthesis, calibration, trajectory construction, and - longitudinal state machinery belong in `populace` or its companion + longitudinal state machinery belong in Microcosm or its companion packages. - Social Security-specific logic, policy validation, and reform workflows belong in this repository and in PolicyEngine-US. Within the population layer, the project should remain baseline-first. -That means the first implementation inside longitudinal `populace` +That means the first implementation inside longitudinal Microcosm should use methods that are simple enough to audit and validate directly. More ambitious joint generative models can be added later if they improve the metrics that matter. @@ -96,7 +96,7 @@ Machine learning is useful inside that system, but it is not the system. This produces a longitudinal public population with: -- representative synthetic records from the `populace` base population +- representative synthetic records from the Microcosm base population - lifetime dynamics learned from panel data and external targets - explicit calibration and validation artifacts - reuse across Social Security and adjacent policy domains @@ -104,7 +104,7 @@ This produces a longitudinal public population with: ### How this differs from existing models **vs. DynaSim**: the comparison object is not this repository alone. It -is longitudinal `populace` plus PolicyEngine-US plus this Social +is longitudinal Microcosm plus PolicyEngine-US plus this Social Security application layer. The differentiator is openness, inspectability, and modularity rather than institutional continuity. @@ -122,10 +122,10 @@ comparison to DynaSim, MINT, CBOLT, and other models. ## Phase 1: Base-year cross-section -### Starting point: Populace's current cross-sectional layer +### Starting point: Microcosm's current cross-sectional layer -The project starts from `populace`, PolicyEngine's rebuilt microdata -stack. Populace builds a calibrated cross-sectional population +The project starts from Microcosm, PolicyEngine's rebuilt microdata +stack. Microcosm builds a calibrated cross-sectional population entirely from primary sources and, in June 2026, replaced PolicyEngine's enhanced CPS as the certified default U.S. microdata in policyengine.py — after beating it on a held-out, symmetric-refit @@ -134,23 +134,23 @@ shipped and won; the longitudinal extension is the open work. Advantages of this starting point: -1. **Proven methodology**: Populace has already solved the +1. **Proven methodology**: Microcosm has already solved the cross-sectional income underreporting problem using the same tools the longitudinal extension will apply 2. **Integration**: seamless connection to PolicyEngine-US's existing tax-benefit calculations 3. **Asset value**: improvements made for this project strengthen - `populace` rather than remaining trapped in a narrow application + Microcosm rather than remaining trapped in a narrow application repository 4. **Credibility**: builds on a demonstrated production stack rather than restarting from scratch 5. **Sample size**: a large synthetic public population provides statistical power for national and subnational analysis -Populace improves upon raw CPS through: +Microcosm improves upon raw CPS through: **Income imputation**: filling missing income components with -weight-aware conditional models (the `populace-fit` shard, succeeding +weight-aware conditional models (the `microcosm-fit` shard, succeeding `microimpute` — quantile regression forests and related methods) **Benefit underreporting correction**: aligning survey-reported @@ -160,10 +160,10 @@ transfer income with administrative aggregates structure **Multi-source calibration**: base-population reweighting (the -`populace-calibrate` shard) against administrative aggregates from +`microcosm-calibrate` shard) against administrative aggregates from CBO, IRS, SSA, Census, and other sources -The proof-of-concept phase should validate that `populace` can be +The proof-of-concept phase should validate that Microcosm can be extended longitudinally, rather than reopening the question of whether the project should start from some entirely different base population. If computational constraints arise with the full @@ -188,13 +188,13 @@ For dynamic modeling, we need variables not in CPS: These "latent" variables will drive longitudinal transitions even when not directly observed. -## Phase 2: Longitudinal extension of Populace +## Phase 2: Longitudinal extension of Microcosm ### The core challenge Social Security benefits depend on 35 highest years of earnings, but the current public population layer only observes a cross-section. We need -to extend `populace` so that it carries: +to extend Microcosm so that it carries: - Past earnings for current workers (ages 18-70) - Future earnings for younger workers (for projections) @@ -206,27 +206,27 @@ to extend `populace` so that it carries: - Realistic variance This is the step where the project becomes more than a static synthetic -dataset. It turns `populace` into a longitudinal population asset. +dataset. It turns Microcosm into a longitudinal population asset. -### Earnings-history approach inside longitudinal Populace +### Earnings-history approach inside longitudinal Microcosm The project should begin with a benchmark set rather than prematurely declaring one model family to be the production architecture. The -current `populace` direction points away from plain sequential QRF as +current Microcosm direction points away from plain sequential QRF as the main design and toward zero-inflated, pathwise generation inside -`populace`. +Microcosm. That means the proposal should distinguish: - **diagnostic comparators** such as QRF and ZI-QRF - **serious production candidates** such as ZI-QDNN and zero-inflated - pathwise `populace` models + pathwise Microcosm models - **the architectural question underneath them**: sequential age-point imputation versus all-at-once trajectory generation The methodological objective is therefore not "use QRF because it is familiar." It is "use the simplest architecture that survives the -Social-Security-specific validation gates." The refreshed `populace` +Social-Security-specific validation gates." The refreshed Microcosm imputation evaluations should help decide whether the leading candidate is ZI-QDNN, a flow-based pathwise model, or another zero-inflated trajectory approach. The proposal should be written to accommodate that @@ -255,7 +255,7 @@ decision rather than forcing it in advance. **Phase-1 comparison approach**: -For each base-year CPS or `populace` individual, the project should +For each base-year CPS or Microcosm individual, the project should compare at least two families: 1. **Age-point benchmark models**: @@ -267,7 +267,7 @@ compare at least two families: The first family is useful because it is interpretable and easy to debug. The second is the more likely production direction because it is -better aligned with the actual `populace` longitudinal architecture and +better aligned with the actual Microcosm longitudinal architecture and preserves cross-age dependence natively. ### Interval-specific training strategy for benchmark models @@ -288,14 +288,14 @@ This approach: - Allows different predictors to matter at different ages - Prevents impossible trajectories (e.g., starting at $200k at age 22) - Provides an interpretable benchmark arm for the more ambitious - `populace` trajectory models + Microcosm trajectory models But it should no longer be described as the expected production architecture. ### Expected production direction: joint trajectory synthesis -The stronger architectural bet is that `populace` should learn full +The stronger architectural bet is that Microcosm should learn full earnings trajectories all at once, with zero-inflation built directly into the model. In practice, that means: @@ -307,13 +307,13 @@ into the model. In practice, that means: careers - preserving cross-age correlations without post-hoc smoothing -This is the design most consistent with making `populace` +This is the design most consistent with making Microcosm longitudinal. It also better matches the actual Social Security decision problem, where the full path matters more than any single age's earnings. The winning model family should still be chosen empirically. The -refreshed `populace` evaluation work should tell us whether ZI-QDNN, a +refreshed Microcosm evaluation work should tell us whether ZI-QDNN, a flow-based pathwise model, or another zero-inflated sequence model is the strongest production candidate. @@ -334,7 +334,7 @@ cohort in the conditioning set for all candidate models birth where sample size permits **Trend adjustment**: Adjust PSID training data to reflect the CPS or -`populace` cohort's economic environment +Microcosm cohort's economic environment ### Validation of imputed histories @@ -354,7 +354,7 @@ We validate imputed earnings histories against multiple benchmarks: This validation step is doing double duty. It decides whether the earnings-history machinery is good enough for Social Security, and it -also decides whether longitudinal `populace` is becoming a credible +also decides whether longitudinal Microcosm is becoming a credible population asset in its own right. ## Phase 3: Demographic transitions @@ -518,9 +518,9 @@ structure this project needs. ### Base-year calibration Weights still matter before longitudinalization. The cross-sectional -`populace` base should be calibrated to demographic, income, tax, and -program targets using `populace`'s existing calibration shard -(`populace-calibrate`) against administrative aggregates. +Microcosm base should be calibrated to demographic, income, tax, and +program targets using Microcosm's existing calibration shard +(`microcosm-calibrate`) against administrative aggregates. Once that base population is converted into a longitudinal population, the representation should be treated as a population scaffold with diff --git a/docs/operationalizing-family-and-auxiliary-benefits.md b/docs/operationalizing-family-and-auxiliary-benefits.md index e1627fb2..5868c7b4 100644 --- a/docs/operationalizing-family-and-auxiliary-benefits.md +++ b/docs/operationalizing-family-and-auxiliary-benefits.md @@ -124,7 +124,7 @@ micro-implementation than the documentation supports. ## Recommended state representation The proposal should specify a family-history layer as a first-class -state block inside longitudinal `populace`. +state block inside longitudinal Microcosm. ### Current marital-status state @@ -279,12 +279,12 @@ auxiliary layer is credible. ## Recommended construction strategy The family-history layer should be built in a way that respects both the -existing `populace` cross section and the needs of Social Security +existing Microcosm cross section and the needs of Social Security benefit logic. ### 1. Start from the base-year household network -`populace` already provides a cross-sectional household and family +Microcosm already provides a cross-sectional household and family structure. That gives the project a real starting point for: - current couples @@ -339,7 +339,7 @@ That mechanism should preserve: - dual-earner versus single-earner household patterns This is one of the strongest reasons to think in terms of longitudinal -`populace` rather than a loose collection of independent hazards. +Microcosm rather than a loose collection of independent hazards. ### 5. Enforce relational consistency @@ -404,7 +404,7 @@ it is likely more fundable and easier to validate in phase 1. ### Higher-upside extension -If longitudinal `populace` advances enough, the project can later move +If longitudinal Microcosm advances enough, the project can later move toward hierarchical or household-first generation that jointly models: - household composition @@ -567,7 +567,7 @@ The proposal should not describe family structure as a few marriage hazards plus a spouse-benefit rule call. It should describe an explicit relationship-history layer inside -longitudinal `populace`, say what phase 1 will and will not include, +longitudinal Microcosm, say what phase 1 will and will not include, benchmark those choices against DYNASIM and MINT, and evaluate the result against the auxiliary-benefit outcomes that policy users actually care about. diff --git a/docs/operationalizing-longitudinal-construction.md b/docs/operationalizing-longitudinal-construction.md index d58528a7..d5d193a0 100644 --- a/docs/operationalizing-longitudinal-construction.md +++ b/docs/operationalizing-longitudinal-construction.md @@ -7,10 +7,10 @@ compute Social Security benefits once the right variables exist. The hard question is whether we can construct a public, person-level panel with plausible lifetime earnings, family histories, disability spells, and claiming-relevant states. That is the part that determines whether -longitudinal `populace` is merely an interesting synthetic dataset or a +longitudinal Microcosm is merely an interesting synthetic dataset or a serious policy-analysis asset. -Throughout this chapter, `populace` is PolicyEngine's rebuilt +Throughout this chapter, Microcosm is PolicyEngine's rebuilt open-source microdata stack — it integrates primary-source U.S. government survey and administrative data and calibrates against administrative targets (CBO, IRS, SSA, Census, and others), and it @@ -41,7 +41,7 @@ For this project to justify a serious build, it needs to do more than generate reasonable average earnings by age. It needs to support the following chain end to end: -1. represent a public cross-sectional population in `populace` +1. represent a public cross-sectional population in Microcosm 2. attach plausible lifetime earnings and family histories to each record 3. transform those histories into quarters of coverage, AIME, and PIA @@ -68,7 +68,7 @@ main benchmark models: | Component | DYNASIM public record | MINT public record | CBO public record | Implication for us | |---|---|---|---|---| -| **Starting sample** | Starts from survey-based representative samples and augments them with multiple public and administrative data sources | Starts from SIPP matched to SSA administrative earnings and benefits | Uses CBOLT as the long-term baseline framework for fiscal and distributional analysis | `populace`, synthesized from primary-source survey data, can play the starting-sample role, but it does not inherit observed earnings histories | +| **Starting sample** | Starts from survey-based representative samples and augments them with multiple public and administrative data sources | Starts from SIPP matched to SSA administrative earnings and benefits | Uses CBOLT as the long-term baseline framework for fiscal and distributional analysis | Microcosm, synthesized from primary-source survey data, can play the starting-sample role, but it does not inherit observed earnings histories | | **Historical earnings** | Older DYNASIM work used statistical matching to attach historical earnings built from PSID and CPS/SER-style sources | Uses observed administrative earnings where available and projects the remainder | Public documentation is sparse on exact record construction | This is the central gap our project must close with public methods | | **Annual labor-market process** | Relies on yearly transition equations, hazard-style modules, and Monte Carlo simulation | Projects labor force participation and earnings from an admin-linked base | Public emphasis is on cohort/quintile outputs and aggregate consistency | Our design should be annual and state-based, not only age-point imputation | | **Alignment and calibration** | Explicitly aligns modules to observed history and future control totals | Uses Trustees assumptions and current-law rules for projections | Integrated to official long-term projections and budget baselines | We need explicit alignment layers, not a one-shot imputation | @@ -179,7 +179,7 @@ systems: | System | What it must do | Benchmark lesson | |---|---|---| -| Starting-file adapter | Convert cross-sectional `populace` into a person-year scaffold with stable IDs, household IDs, tax-unit IDs, and fixed representation factors or replicate counts | CBOLT and DYNASIM both begin with a representative population, not abstract cohorts | +| Starting-file adapter | Convert cross-sectional Microcosm into a person-year scaffold with stable IDs, household IDs, tax-unit IDs, and fixed representation factors or replicate counts | CBOLT and DYNASIM both begin with a representative population, not abstract cohorts | | Historical earnings engine | Reconstruct covered earnings, uncovered earnings, self-employment, zero-earnings years, and taxable-maximum exposure | CBOLT's strength comes from CWHS; our public substitute must be validated hard | | Annual transition engine | Simulate work, earnings, marital status, fertility, disability, mortality, claiming, and household changes year by year | Both benchmark systems are annual transition models | | Family network engine | Maintain current, former, and deceased spouse links plus parent-child links needed for auxiliary benefits | CBOLT explicitly uses family links for benefits | @@ -237,7 +237,7 @@ while still leaving room for more ambitious joint generative methods later. The strongest version of that "more ambitious" path is probably a -zero-inflated all-at-once `populace` trajectory model. But the +zero-inflated all-at-once Microcosm trajectory model. But the proposal should leave room for refreshed evaluation results to decide whether the best implementation is ZI-QDNN, a flow-based model, or another pathwise candidate. @@ -331,7 +331,7 @@ current earnings become a better proxy only around midcareer, and much worse outside that window [@haider2006]. So the first operational task is to define and estimate a latent -earnings-capacity measure that can be attached to each `populace` +earnings-capacity measure that can be attached to each Microcosm person. ### Practical definition @@ -344,7 +344,7 @@ A workable phase-1 target is: currently observed cross-sectional traits The target should be estimated in PSID and similar panel sources, then -mapped back to `populace` using supervised prediction. This is the +mapped back to Microcosm using supervised prediction. This is the right use of tools like QRF or distributional regression: not as the whole earnings engine, but as a way to recover a latent position in the lifetime distribution. @@ -440,7 +440,7 @@ include: - QRF and ZI-QRF as interpretable age-point benchmarks - ZI-QDNN as the most obvious zero-inflated neural candidate -- at least one pathwise `populace` model that generates the earnings +- at least one pathwise Microcosm model that generates the earnings path all at once In other words, the proposal should compare benchmark models against @@ -534,7 +534,7 @@ solve all pension interaction problems on day one. The key operational problem is backward construction. -For a person observed in `populace` at age 52 in 2025, we need a path +For a person observed in Microcosm at age 52 in 2025, we need a path from age 18 to age 52 that is consistent with: - their current observed earnings or benefit state @@ -649,7 +649,7 @@ So the operational plan should treat alignment as a stack: ### Layer 1: Base-population calibration -Calibrate the cross-sectional `populace` population before the dynamic +Calibrate the cross-sectional Microcosm population before the dynamic simulation begins. After longitudinalization, carry fixed representation factors or replicate counts through the relationship network rather than freely changing individual weights every year. @@ -738,7 +738,7 @@ The proposal should explicitly benchmark the following pieces: ### Starting file -- **Our plan**: `populace` cross section, synthesized from +- **Our plan**: Microcosm cross section, synthesized from primary-source survey data - **DYNASIM**: representative survey base, augmented by multiple surveys and matched historical earnings work @@ -800,7 +800,7 @@ The project should compare at least three candidate families: latent rank plus work-state plus conditional earnings plus calibrated residuals 3. **Joint trajectory generator**: - a pathwise zero-inflated generator inside `populace`, with + a pathwise zero-inflated generator inside Microcosm, with ZI-QDNN, ZI-MAF, or related sequence models as candidates The project should precommit that the simplest architecture that clears @@ -849,7 +849,7 @@ At minimum, year one should deliver: earnings-state features 2. a benchmark note comparing the public record on DYNASIM, MINT, and CBO component by component -3. a longitudinal `populace` alpha with historical earnings paths and +3. a longitudinal Microcosm alpha with historical earnings paths and source provenance flags 4. a validation report covering earnings distributions, mobility, taxable-maximum incidence, zero-earnings years, and AIME-sensitive @@ -868,14 +868,14 @@ technical object of the project. The right architecture is not "QRF everywhere." It is a transparent annual state process for covered work and earnings, anchored to current records and disciplined by external calibration, with a likely -production path toward zero-inflated all-at-once `populace` +production path toward zero-inflated all-at-once Microcosm trajectory models. QRF can still play an important role as a benchmark and diagnostic tool, but it should no longer be described as the default destination. The public differentiator remains real: -- `populace` as PolicyEngine's reusable public population layer +- Microcosm as PolicyEngine's reusable public population layer - explicit benchmark comparison to DYNASIM, MINT, and CBO - record-level provenance - published validation gates diff --git a/docs/policy-applications.md b/docs/policy-applications.md index f8e58be4..dab7bb2d 100644 --- a/docs/policy-applications.md +++ b/docs/policy-applications.md @@ -7,7 +7,7 @@ they care how it works. The point of this project is not to create a generic simulator in the abstract. It is to answer concrete policy questions that require lifecycle information and distributional detail. More specifically, this repository should be understood as the first -serious proving ground for longitudinal `populace`: if the population +serious proving ground for longitudinal Microcosm: if the population platform can support Social Security well, it earns the right to support adjacent domains later. @@ -316,7 +316,7 @@ Accessible public modeling supply appears even thinner than in Social Security. The fair claim is not that any one closed model is the sole bottleneck. It is that LTC policy interest is substantial and visible, while LTSS modeling capacity is concentrated in a small number of closed -or proprietary systems. If longitudinal `populace` becomes credible, +or proprietary systems. If longitudinal Microcosm becomes credible, LTC may become one of the highest-value adjacent domains for expansion. The most plausible first adjacent LTC product is not a national dynamic diff --git a/docs/progress.md b/docs/progress.md index 2b60b5aa..2313514c 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -356,4 +356,4 @@ Every block of work moves through the same pipeline before it counts here: a ful - [Amendment 20 draft (PR #405)](https://github.com/PolicyEngine/microcosm-dynamics/pull/405) - [Pre-registered gate contract (gates.yaml)](https://github.com/PolicyEngine/microcosm-dynamics/blob/master/gates.yaml) - [Timeline forecast ledger (machine-readable)](https://github.com/PolicyEngine/microcosm-dynamics/blob/master/docs/forecasts/timeline_ledger.json) -- [The Populace dynamics paper](https://populace.dev/papers/dynamics) +- [The Microcosm Dynamics paper](https://microcosm.institute/dynamics/paper) diff --git a/docs/progress/progress.json b/docs/progress/progress.json index 147d3a55..c6891581 100644 --- a/docs/progress/progress.json +++ b/docs/progress/progress.json @@ -206,8 +206,8 @@ "href": "https://github.com/PolicyEngine/microcosm-dynamics/blob/master/docs/forecasts/timeline_ledger.json" }, { - "text": "The Populace dynamics paper", - "href": "https://populace.dev/papers/dynamics" + "text": "The Microcosm Dynamics paper", + "href": "https://microcosm.institute/dynamics/paper" } ] } diff --git a/docs/public-validation-inventory.md b/docs/public-validation-inventory.md index b5269fd0..183d9bc6 100644 --- a/docs/public-validation-inventory.md +++ b/docs/public-validation-inventory.md @@ -14,9 +14,9 @@ negotiations before it can produce a credible first model. This chapter inventories the main public or low-friction sources we can use to validate the model. It is not an exhaustive bibliography. It is the minimum practical source stack for judging whether longitudinal -`populace` is becoming decision-useful. +Microcosm is becoming decision-useful. -Many of these sources are already assembled inside `populace`, +Many of these sources are already assembled inside Microcosm, PolicyEngine's microdata stack — the primary-source microdata and the calibration targets (from CBO, IRS, SSA, Census, and others) that it draws on. Naming the sources diff --git a/docs/risks-and-stage-gates.md b/docs/risks-and-stage-gates.md index c5bddea8..ce9cb791 100644 --- a/docs/risks-and-stage-gates.md +++ b/docs/risks-and-stage-gates.md @@ -27,7 +27,7 @@ tension is one of the core research problems of the project. ### 3. Platform work expands faster than policy validation -Now that the project is best understood as making `populace` +Now that the project is best understood as making Microcosm longitudinal, there is a new risk: the population platform can become technically interesting without yet being decision-useful for Social Security. That would be real research progress, but it would not by @@ -49,10 +49,10 @@ forward if drift is not controlled explicitly. A public interface is attractive and visible, but it can also amplify weaknesses if the validation record is not ready. -## Stage gate 1: longitudinal Populace quality +## Stage gate 1: longitudinal Microcosm quality The project should advance past stage 1 only if it can show that -longitudinal `populace` is credible on multiple dimensions: +longitudinal Microcosm is credible on multiple dimensions: - age-earnings levels - dispersion and percentiles diff --git a/docs/roadmap.md b/docs/roadmap.md index 11d78efd..4fc177da 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -15,7 +15,7 @@ decision points, not chronological phases. The project has four core workstreams: -1. **Longitudinal Populace construction** +1. **Longitudinal Microcosm construction** 2. **Social Security integration and validation** 3. **Policy analysis products** 4. **Public API and interface** @@ -31,11 +31,11 @@ implementation. ### Deliverables -- Finalized base population platform: `populace`, PolicyEngine's +- Finalized base population platform: Microcosm, PolicyEngine's microdata stack -- Clear boundary between `populace` platform work and +- Clear boundary between Microcosm platform work and Social Security-specific application work -- Benchmark datasets and target tables assembled from `populace`'s +- Benchmark datasets and target tables assembled from Microcosm's primary-source data and its versioned target registry - Initial validation harness for baseline distributions - Implementation team and external review capacity identified @@ -51,16 +51,16 @@ implementation. ## Stage 1: historical earnings reconstruction -**Purpose**: determine whether `populace` can be extended into a +**Purpose**: determine whether Microcosm can be extended into a credible longitudinal population asset for Social Security analysis. ### Core tasks - Harmonize PSID and related longitudinal sources - Build at least one conservative production path for earnings-history - reconstruction inside `populace` + reconstruction inside Microcosm - Add the first longitudinal state variables and transition machinery to - `populace` + Microcosm - Compare alternative model families where justified - Validate age-earnings profiles, percentiles, mobility, AIME, and correlation structure @@ -68,14 +68,14 @@ credible longitudinal population asset for Social Security analysis. ### Deliverables -- Longitudinal `populace` alpha with earnings histories and core +- Longitudinal Microcosm alpha with earnings histories and core longitudinal states - Validation report on held-out data and external benchmarks - Recommendation on the production longitudinal architecture ### Exit criteria -- Longitudinal `populace` is accurate enough to justify downstream +- Longitudinal Microcosm is accurate enough to justify downstream benefit modeling - Validation results are publishable and not merely anecdotal @@ -84,12 +84,12 @@ proceeding mechanically. ## Stage 2: family, disability, claiming, and benefits -**Purpose**: turn longitudinal `populace` into a credible Social +**Purpose**: turn longitudinal Microcosm into a credible Social Security analysis dataset. ### Core tasks -- Freeze the minimal production version of longitudinal `populace` +- Freeze the minimal production version of longitudinal Microcosm chosen at the end of stage 1 - Implement family structure and marital histories needed for auxiliary benefits @@ -113,7 +113,7 @@ Security analysis dataset. ## Stage 3: forward projection and reform analysis -**Purpose**: move from longitudinal `populace` plus a validated Social +**Purpose**: move from longitudinal Microcosm plus a validated Social Security layer to a projected dynamic model that can analyze reform packages. @@ -176,7 +176,7 @@ Throughout the project: - preserve reproducible data-processing pipelines where licensing permits - document model decisions and reversals -- preserve the separation between reusable `populace` infrastructure +- preserve the separation between reusable Microcosm infrastructure and Social Security-specific application code - collect external review from domain experts diff --git a/docs/scoring-and-resolution.md b/docs/scoring-and-resolution.md index f771d79f..61633549 100644 --- a/docs/scoring-and-resolution.md +++ b/docs/scoring-and-resolution.md @@ -48,7 +48,7 @@ useful even to those who treat it as authoritative. Long-horizon dynamics cannot wait decades for a grade, but the past already resolved. The protocol: build the panel from data vintages available at time T, project forward, and score against realized -outcomes at T+k. The `populace` data registry pins source vintages, +outcomes at T+k. The Microcosm data registry pins source vintages, which is what makes "what could the model have known on date X" an enforceable constraint rather than an honor-system claim. Retrodictive scores are necessary but not sufficient — calibration under the @@ -68,7 +68,7 @@ are actually uncertain. ### 5. Held-out panel moments -The population layer itself is scored the way `populace` already +The population layer itself is scored the way Microcosm already scores cross-sections: held-out evaluation against moments the model was not fit to — earnings-mobility matrices, autocorrelation structure and higher-order moments of earnings changes @@ -88,7 +88,7 @@ yet, it says so. ## The contribution rule -Scoring is also the governance mechanism, inherited from `populace`: +Scoring is also the governance mechanism, inherited from Microcosm: **a contribution merges if and only if it improves the population's score on held-out facts.** A better mortality module, a sharper claiming model, a new earnings architecture — from this team or diff --git a/docs/team.md b/docs/team.md index af90b093..0c3c9ed8 100644 --- a/docs/team.md +++ b/docs/team.md @@ -41,7 +41,7 @@ during implementation: ### Technical lead or research engineer -Implementation leadership is needed to own the longitudinal `populace` +Implementation leadership is needed to own the longitudinal Microcosm pipeline, modeling infrastructure, and reproducibility workflow. This capacity should not be treated as optional. @@ -56,7 +56,7 @@ just whether the code runs. The project requires substantial work on harmonization, ingestion, versioning, and reproducibility across the surveys and administrative -sources that `populace` integrates and calibrates against. This is a +sources that Microcosm integrates and calibrates against. This is a real workload, not a background task. ### Research assistance diff --git a/docs/technical-specifications.md b/docs/technical-specifications.md index 69b403a6..c3481531 100644 --- a/docs/technical-specifications.md +++ b/docs/technical-specifications.md @@ -1,7 +1,7 @@ # Technical Specifications This chapter provides technical specifications for longitudinal -`populace` and for the Social Security application layer that will sit +Microcosm and for the Social Security application layer that will sit on top of it. The relevant build is not a standalone Social Security-only dataset. It is a reusable longitudinal population asset plus a policy-analysis layer. @@ -11,7 +11,7 @@ plus a policy-analysis layer. Dynamic microsimulation models begin with a longitudinal sample of the population and age that sample forward through time using stochastic demographic and economic transition equations. In this project, that -sample should be delivered as longitudinal `populace`. The specific +sample should be delivered as longitudinal Microcosm. The specific variables and equations required depend on the modeling goals. For Social Security analysis, we need inputs to both payroll tax and benefit calculations. @@ -38,16 +38,16 @@ A basic Social Security model thus involves simulating year-by-year and person-b - Earnings (combining participation, hours, and wages) - Benefit claiming decisions -## Constructing longitudinal Populace: historical simulation +## Constructing longitudinal Microcosm: historical simulation The input dataset for dynamic microsimulation requires longitudinal histories for all listed variables in a representative sample as of the base year. Creating and validating that dataset is the central task in -making `populace` longitudinal. It proceeds through historical +making Microcosm longitudinal. It proceeds through historical simulation, which is effectively a synthetic data generation exercise using cross-sectional and longitudinal input data, including parameterized stochastic earnings shocks and other transition -equations. `populace` integrates those cross-sectional and +equations. Microcosm integrates those cross-sectional and longitudinal sources, along with the SSA, CBO, IRS, and Census calibration targets the validation steps rely on, from primary-source U.S. government survey and administrative data. @@ -162,7 +162,7 @@ This approach aligns with PolicyEngine's existing strength in detailed tax and t ## Output dataset structure -Longitudinal `populace` should be organized as a relational dataset +Longitudinal Microcosm should be organized as a relational dataset with four linked tables. This structure captures all data elements required for benefit calculation across all beneficiary types, maintains family relationships for auxiliary and survivor benefits, and @@ -265,7 +265,7 @@ For PolicyEngine integration, the 4-table structure will be flattened into the e The technical specifications outlined here provide a roadmap for model development. We start with clearly defined variables and transition equations needed for Social Security analysis, but we place them inside -the broader task of building longitudinal `populace`. Historical +the broader task of building longitudinal Microcosm. Historical simulation creates and validates the base longitudinal population. Forward projections incorporate calibration to address the jump-off problem. Behavioral responses, even if simple, ensure realism.