Skip to content

Hybrid DB-FDC pension system and pension_FOC_linkage (FDC part 5) - #1288

Open
jdebacker wants to merge 5 commits into
PSLmodels:masterfrom
jdebacker:FDC_HYBRID
Open

jdebacker wants to merge 5 commits into
PSLmodels:masterfrom
jdebacker:FDC_HYBRID

Conversation

@jdebacker

Copy link
Copy Markdown
Member

This PR is stacked on #1285 and #1286 (FDC parts 3–4), so their commits appear here too. Review only the last commit, "Add the hybrid DB-FDC pension system and pension_FOC_linkage", until those merge.

This is part 5 of the funded defined contribution (FDC) work. It adds a hybrid defined benefit and funded defined contribution system, with the same structure as the Hybrid DB-NDC system and an FDC account in place of the notional account. It also adds pension_FOC_linkage, a switch for whether households value the pension benefit their labor earns.

Hybrid DB-FDC (pension_system = "Hybrid DB-FDC")

  • Defined benefit band. Labor income up to db_earn_cap_factor × avg_labor_inc_t1_model_units earns a defined benefit (pensions.DB_FDC_hybrid_amount). This is the system's only public pension, and it is scaled by replacement_rate_adjust.
  • FDC band. Labor income between that cutoff and dc_earn_cap_factor × avg_labor_inc_t1_model_units pays fdc_tau into an FDC account. Under this system, pensions.fdc_earn_bands returns these cutoffs and ignores fdc_earn_floor_factor and pension_earn_cap.
  • Shared cutoff check. The cutoff check used by both hybrid systems is now pensions.hybrid_earn_cutoffs. Specifications checks that the cutoffs are ordered for every cohort under both systems. It warns if fdc_tau is zero under the new system, because the system then reduces to a capped DB.
  • Funding. As under Hybrid DB-NDC, tau_payroll applies to all labor income and finances the defined benefit. FDC benefits are paid by the fund, not the government.

pension_FOC_linkage (bool, default false)

  • What it switches. It sets whether the labor first order condition includes the value of the additional pension benefit that an extra unit of labor earns.
  • Current scope. It affects only the FDC pillar. When it is false, household.fdc_labor_wedge drops the accrual term, which is the value of the annuity bought by a marginal contribution. The contribution cost always stays in the FOC, so FDC contributions act on labor supply like a tax on earnings in the FDC band. Benefits are still computed from actual contributions.
  • Consistency with the pay-as-you-go systems. This is how those systems already work: none of them puts an accrual term in the labor FOC. The parameter has a general name so they can use it once they have such terms.
  • ⚠ Behavior change. FDC results change by default, because earlier versions always included the accrual term. Setting pension_FOC_linkage = true reproduces them, and the existing FDC tests now do that.

Solver note

Under Hybrid DB-FDC, contributions start at the DB cutoff. That puts a discrete change in the marginal return to labor at the cutoff, whatever the value of pension_FOC_linkage. The default hybr household root finder does not converge in the steady-state test, but FOC_root_method = "lm" does. The test uses lm, and the docs tell users to do the same when the FDC band starts above zero. A standalone FDC pillar with contributions on all earnings solves with hybr.

Docs

  • The pensions chapter (government.md) has a new section on the hybrid DB-FDC system.
  • The FDC household-problem text now explains pension_FOC_linkage and the solver note.
  • parameters.md and api/pensions.rst are updated.

Tests

  • Pension functions. The hybrid's public pension equals the capped DB benefit. Its FDC band lies between the two cutoffs, and contributions are correct. The cutoff checks and the warning when fdc_tau is zero are tested. The new system is also added to the existing tests of every pension system.
  • Steady state. test_SS_hybrid_db_fdc checks that the steady state solves. It also checks that the steady state matches Defined Benefits with pension_earn_cap and the FDC floor at the DB cap (Y, K, L, r, w, F and pension outlays match within rtol 1e-8).
  • Linkage switch. test_fdc_labor_wedge_linkage checks that setting the switch to false removes only the accrual term.
  • Local results. The full non-local suite gives 870 passed and 1 failed. The failure is test_utils.py::test_not_connected_true, which depends on the network; it is a local timeout and fails the same way without these changes. The docs build passes.

🤖 Generated with Claude Code

jdebacker and others added 5 commits November 16, 2026 17:53
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>
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>
Adds pension_system 'Hybrid DB-FDC': a defined benefit on labor income
up to db_earn_cap_factor times avg_labor_inc_t1_model_units, and funded
defined contribution (FDC) contributions on labor income between that
cutoff and dc_earn_cap_factor times avg_labor_inc_t1_model_units. The
two hybrid systems share pensions.hybrid_earn_cutoffs.

Adds pension_FOC_linkage (default false), which sets whether the labor
first order condition includes the value of the benefit an extra unit
of labor earns. It currently affects only the FDC accrual term; the
contribution cost always enters. FDC tests set it to true, which
reproduces earlier results.

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

codecov-commenter commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.16%. Comparing base (e9c62d9) to head (871be7e).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #1288      +/-   ##
==========================================
+ Coverage   80.10%   80.16%   +0.05%     
==========================================
  Files          24       24              
  Lines        7208     7223      +15     
==========================================
+ Hits         5774     5790      +16     
+ Misses       1434     1433       -1     
Flag Coverage Δ
unittests 80.16% <100.00%> (+0.05%) ⬆️

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

Files with missing lines Coverage Δ
ogcore/fiscal.py 100.00% <ø> (ø)
ogcore/household.py 90.98% <100.00%> (+0.02%) ⬆️
ogcore/parameters.py 90.85% <100.00%> (+0.07%) ⬆️
ogcore/pensions.py 75.11% <100.00%> (+0.31%) ⬆️

... 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.

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