Skip to content

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

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

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

Conversation

@jdebacker

@jdebacker jdebacker commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

This PR is stacked on #1283, #1284 and #1285 (FDC parts 1–3), so their commits appear here too. Review only the last commit, "Document the funded defined contribution pillar and add an example", until those merge.

This is part 4 of 4 for the funded defined contribution (FDC) pillar: docs, output metadata, and an example. 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.
  • Output metadata. model_variables.json adds F, fdc_contrib, fdc_benefits and fdc_holdings, so they can be used in output_tables and output_plots.
  • Example. examples/run_ogcore_fdc_example.py: the baseline is an NDC system with tau_p = 0.16. The reform is a carve-out entered through pension_regimes: cohorts aged 40 or younger in the start year get tau_p = 0.12 plus fdc_tau = 0.04, and older cohorts keep the baseline. It prints the macro effects and the fund's assets. A commented-out option sets pension_earn_cap with dc_earn_cap_factor = [1.5, 1.5], which caps the notional and funded accounts at the same wage-indexed level.
  • 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.
  • Example: I ran its table calls on small-model outputs, including F in macro_table, and checked its reform specification: fdc_tau and tau_p expand by cohort as intended, and the final period sits in the reform regime. I did not run the full default-size example, which takes hours.
  • 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

Adds fdc_tau (a cohort pension parameter, default 0), fdc_earn_cap,
fdc_earn_cap_factor, and fdc_earn_floor_factor, and the functions that
compute a household's funded defined contribution account over its
life: contributions, balances earning r_p through the retirement
period, a fair annuity-due priced on income-group mortality and the
r_p path, end-of-period holdings, and the accrual derivatives. Not yet
wired into the household problem or aggregates.

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

codecov-commenter commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.69231% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.94%. Comparing base (9b8a3b4) to head (88e162e).

Files with missing lines Patch % Lines
ogcore/pensions.py 77.83% 41 Missing ⚠️
ogcore/TPI.py 78.57% 6 Missing ⚠️
ogcore/household.py 91.54% 6 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #1286      +/-   ##
==========================================
+ Coverage   79.81%   79.94%   +0.13%     
==========================================
  Files          24       24              
  Lines        6811     7122     +311     
==========================================
+ Hits         5436     5694     +258     
- Misses       1375     1428      +53     
Flag Coverage Δ
unittests 79.94% <83.69%> (+0.13%) ⬆️

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

Files with missing lines Coverage Δ
ogcore/SS.py 92.00% <100.00%> (+0.17%) ⬆️
ogcore/aggregates.py 100.00% <100.00%> (ø)
ogcore/parameters.py 90.75% <100.00%> (+0.10%) ⬆️
ogcore/TPI.py 81.94% <78.57%> (-0.20%) ⬇️
ogcore/household.py 90.90% <91.54%> (+0.12%) ⬆️
ogcore/pensions.py 74.22% <77.83%> (+1.01%) ⬆️
🚀 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
jdebacker and others added 5 commits November 16, 2026 17:12
… accounts

Remove fdc_earn_cap and fdc_earn_cap_factor. With pension_earn_cap true,
FDC contributions are paid only on labor income up to dc_earn_cap_factor
times avg_labor_inc_t1_model_units, the cap shared with the notional
defined contribution system, under any pension_system.

fdc_earn_floor_factor is now a cohort pension parameter entered and
indexed like db_earn_cap_factor and dc_earn_cap_factor (a single value
is value / e^(g_y t); regimes may change it by cohort), so the floor and
the cap move together. fdc_earn_bands returns arrays by period and age,
read down each cohort's diagonal. Specifications checks that the cap is
at least the floor wherever fdc_tau is positive.

Also resolves the leftover conflict markers in default_parameters.json
from the upstream merge and moves the FDC changelog entries to an
Unreleased section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Households pay FDC contributions and receive annuity benefits through
the budget constraint (outside net_taxes and the government budget).
FOC_labor values the annuity a contribution buys via
fdc_labor_wedge. Fund assets F (aggregates.get_F, in next-period
detrended units like b_{s+1}) add to domestic savings in
get_K_splits; pre-retirement balances of the deceased are bequeathed;
immigrants arrive with their age's FDC holdings per survivor. SS
output adds F and FDC profiles. run_TPI raises NotImplementedError
while fdc_tau > 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each cohort's FDC account is computed from the r_p and wage paths it
foresees (pensions.fdc_tpi, household.get_fdc on partial lifetimes),
with the annuity priced on that path. Households alive at t=0 start
from the baseline steady state's FDC holdings (zero if the baseline
had none), scaled for the period-0 population; retirees re-annuitize
on the new path. Fund assets enter get_K_splits in every period,
pre-retirement balances of the deceased are bequeathed, and
immigrants arrive with their age's FDC claims. TPI output adds F and
FDC profiles; SS output adds fdc_R.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>

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