Skip to content

Funded defined contribution pillar, part 4: documentation and example - #1286

Open
jdebacker wants to merge 7 commits into
PSLmodels:masterfrom
jdebacker:FDC_DOCS
Open

jdebacker wants to merge 7 commits into
PSLmodels:masterfrom
jdebacker:FDC_DOCS

Conversation

@jdebacker

@jdebacker jdebacker commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Parts 1–3 of the FDC work (#1283, #1284 and #1285) have merged, and this branch is synced with master, so the diff now shows only the part 4 changes. The example script the PR first added (examples/run_ogcore_fdc_example.py) has since been removed: its reform is shown in the docs instead (see below).

This is part 4 of 4 for the funded defined contribution (FDC) pillar: docs and output metadata. Model code is unchanged.

Changes

  • Theory docs, pensions chapter (government.md): a new "Funded defined contribution pillar" section covering contributions and the earnings band, accumulation and timing, the fair annuity and the annuity pool, initial holdings on the transition path, the labor-FOC accrual term, and the aggregates. The chapter intro and the cohort-parameter paragraph now mention the pillar, and the "Aggregate Pension Spending" section notes that FDC benefits are not government outlays.
  • Modeling choices. The new section lists them explicitly:
    1. The bequest motive is over private savings only, so households don't value FDC balances bequeathed on death before retirement.
    2. Contributions are paid from after-tax income, and fund returns and benefits are untaxed.
    3. Fund returns are not in before-tax income or in the factor calibration.
    4. K_d includes the fund's holdings.
    5. The FDC earnings cap is the shared dc_earn_cap_factor, applied when pension_earn_cap is true, so under NDC both pillars are credited on the same capped earnings. The floor fdc_earn_floor_factor is indexed like the shared cutoffs: a single value is fixed in real terms.
    6. Contributions stop at the retirement age.
    7. initial_wealth_ratio does not rescale initial FDC holdings.
  • Households and market clearing. households.md notes the FDC terms in the budget constraint, and market_clearing.md notes that the domestic capital constraint becomes K^d + D^d = B + F.
  • FDC return wedge and fund reserve. The FDC section documents r_fdc_wedge (the return r_fdc credited to the accounts and used to price the annuity) and the fund's spread and temporary FDC fund reserve: its law of motion, the ceiling fdc_fund_reserve_max_GDPratio, the payout to the government at tG1, and the steady state with no reserve. Net FDC fund revenue is added to the government budget constraint and its stationarized form, and the reserve to domestic savings in the capital market clearing section.
  • Reform example in the docs. The FDC section shows how to enter, through pension_regimes, a reform that moves 4 of 16 percentage points of NDC contributions into funded accounts for cohorts aged 40 or younger in the start year.
  • Output metadata. model_variables.json adds F, fdc_contrib, fdc_benefits, fdc_holdings, fdc_spread, fdc_fund_reserves, fdc_fund_revenue and fdc_fund_transfer, so they can be used in output_tables and output_plots.
  • Release 0.25.0. The version is bumped to 0.25.0 in ogcore/__init__.py, pyproject.toml and uv.lock, and the CHANGELOG's Unreleased section, which holds all four FDC parts, becomes [0.25.0] - 2026-11-21.
  • Test. New local test test_run_TPI_fdc_introduced_for_younger_cohorts: FDC is introduced by pension_regimes for cohorts aged 40 or younger only. Older cohorts never contribute, younger working cohorts contribute from t=0, the fund starts empty, and the path converges with the resource constraint within RC_TPI.

Checks

  • New local test: passes.
  • Other tests: tests/test_constants.py, test_output_tables.py and test_output_plots.py pass.
  • Docs build: passes in the docs-check workflow. The API reference failed at first because FDCLifetime and FDCPath both have a holdings field, which made the Returns label holdings in fdc_holdings an ambiguous cross-reference. Funded defined contribution pillar, part 3: transition path #1285 now relabels those Returns entries.

🤖 Generated with Claude Code

@codecov-commenter

codecov-commenter commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.09%. Comparing base (fcdc037) to head (d1aaac6).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #1286      +/-   ##
==========================================
- Coverage   80.10%   80.09%   -0.02%     
==========================================
  Files          24       24              
  Lines        7208     7208              
==========================================
- Hits         5774     5773       -1     
- Misses       1434     1435       +1     
Flag Coverage Δ
unittests 80.09% <100.00%> (-0.02%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
ogcore/__init__.py 100.00% <100.00%> (ø)
ogcore/fiscal.py 100.00% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jdebacker
jdebacker marked this pull request as ready for review November 15, 2026 08:07
Adds an FDC section to the pensions chapter of the theory docs
(contributions, timing, annuity, labor FOC, aggregates, and the
modeling choices), notes in the household budget constraint and
capital market clearing sections, FDC output metadata in
model_variables.json, an example carving funded accounts out of an
NDC system for younger cohorts via pension_regimes, and a local TPI
test introducing FDC for younger cohorts only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jdebacker and others added 3 commits November 20, 2026 13:55
Brings in the FDC return wedge, the fdc_fund_* renaming, the zero
reserve cap, and the FDC fund reserve paid to the government at tG1.
Resolves conflicts in CHANGELOG.md (keeps both entries, with the
documentation entry updated for the wedge and reserve) and in
tests/test_TPI.py (keeps the FDC_TPI _fdc_tpi_run helper with its tag
argument and both the younger-cohorts and return-wedge tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds the FDC return r_fdc = r_p - r_fdc_wedge to the FDC pillar section
(accumulation, bequests, and annuity pricing use it) and a section on
the fund's spread and reserve: its law of motion, the ceiling
fdc_fund_reserve_max_GDPratio, the payout to the government at the end
of tG1 - 1, and the steady state with no reserve. Adds net FDC fund
revenue to the government budget constraint and its stationarized
form, and the reserve to domestic savings in capital market clearing.
Adds fdc_spread, fdc_fund_reserves, fdc_fund_revenue, and
fdc_fund_transfer to model_variables.json, updates the fiscal
docstrings that still described a reserve floor, and fixes two broken
links to the FDC pillar section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in upstream/master (with the merged FDC_SS, PSLmodels#1284) through
FDC_TPI. Resolves the conflict in the get_G_ss and get_TR docstrings in
ogcore/fiscal.py by keeping the upstream wording, with the payout at
the end of tG1 - 1 and without the note that the time path is not yet
implemented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jdebacker
jdebacker requested a review from rickecon November 21, 2026 20:25
The carve-out reform it ran is now a short snippet in the FDC section of
the pensions chapter. The script is kept locally but no longer tracked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants