Skip to content

Credit NDC balances through the retirement period - #1287

Open
jdebacker wants to merge 2 commits into
PSLmodels:masterfrom
jdebacker:ndc_credit_R
Open

jdebacker wants to merge 2 commits into
PSLmodels:masterfrom
jdebacker:ndc_credit_R

Conversation

@jdebacker

Copy link
Copy Markdown
Member

This PR changes the NDC crediting window so that notional balances are credited through the retirement period R, not through R − 1. It also fixes the NDC labor-supply derivative in the docs. It bumps the version to 0.24.7. Model results change for the Notional Defined Contribution and Hybrid DB-NDC systems.

It came up while reviewing the funded defined contribution (FDC) pillar (#1283–#1286). Those PRs credit FDC accounts through R, and merging this first makes NDC and FDC use the same timing.

The problem

Under the old formula, a contribution at working age s grew by (1 + g_NDC) in periods s + 1 … R − 1 only. The conversion coefficient, however, values the balance in period R: its annuity factor dir_R doesn't discount the first payment, made in R, and discounts later payments from R. So the balance was one period short of the date it is valued at. With the discount rate equal to the credited rate, k_ret = 0, and indR = 0, the expected present value of benefits at R was the notional balance divided by (1 + g_NDC,R), not the balance itself.

Crediting through R also matches the household's problem. There, a stock carried from R − 1 into R earns period R's return, just as private savings b do. A funded account has to use this timing, because its assets earn a return in period R that must go to someone.

Changes

  • Crediting through R. NDC_1dim_loop, NDC_2dim_loop and NDC_3dim_loop start the growth factor at 1 + g_NDC in the retirement period. Each loop reads that rate from the same calendar path and clipping it uses for the other periods. The hybrid system's notional band uses these loops, so it changes the same way.
  • Labor-supply derivative. deriv_NDC_loop now uses (1 + g_NDC)^(R − s), consistent with the benefit formula.
  • Docs (government.md).
    • The NDC and hybrid benefit formulas now take the product over a = u+1 … R.
    • The text explains the timing and why it makes benefits fair at the notional rate.
    • Fixes eqn:ndc_deriv. It showed the exponent (u − s) and the condition s < R − 1, which matched neither the benefit formula nor the code. It now reads τ_p w e (1 + g_NDC)^(R − s) δ_R for every s < R, with a note that the code evaluates it at a single credited rate and conversion coefficient. The same fix is in the deriv_NDC docstring.
  • Docstrings. NDC_amount, NDC_1dim_loop and NDC_3dim_loop describe the new window.
  • Release. CHANGELOG entry for 0.24.7, with the version bumped in ogcore/__init__.py, pyproject.toml and uv.lock.

Tests

  • Updated expected values. The nine NDC tests that hard-code values were updated. I checked that each new value is exactly one more period of the credited rate, not just whatever the code now outputs:

    • ratio 1.03 or 1.04 where the test sets g directly;
    • ratio e^{0.03} − 1 = 0.030455 or e^{0.04} − 1 = 0.040811 under 'LR GDP'.

    The hand calculation in test_NDC_1dim_loop_time_varying_credit now multiplies through t_birth + R.

  • New test. test_NDC_fair_at_credited_rate sets the conversion coefficient to the inverse of the survival-weighted annuity factor at the credited rate. It checks that the expected present value of benefits at R equals contributions accumulated through R. The old timing fails this test by exactly 1 + g.

  • Unit tests: test_pensions.py, test_household.py, test_aggregates.py, test_parameters.py and test_tax.py pass (286 tests).

  • Local tests: test_run_TPI_pension_regime, all four cases including the two NDC regime cases, passes.

  • Non-local test_SS.py and test_TPI.py: 57 pass. The 5 failures are test_SS_fsolve cases that also fail on master; they don't use NDC.

  • Docs: the API reference builds with -W.

Size of the change

In the small test model (tests/testing_params.json, S = 40, so 2-year periods), an NDC steady state with tau_p = 0.16 changes as follows:

Old timing New timing
Aggregate pension outlays 0.03953 0.04197 (+6.2%, about two years of ~3% growth)
r 0.08625 0.08570
K 1.2905 1.2947
L 0.49842 0.49768

The resource constraint error is about 1e-9 under both. With the default one-year periods, benefits rise by about one period's credited rate, roughly 3% under the default 'LR GDP' rate.

🤖 Generated with Claude Code

jdebacker and others added 2 commits November 17, 2026 21:38
A contribution at working age s now grows by (1 + g_NDC) in each period
from s + 1 through the retirement period R, in which the first benefit
is paid, rather than through R - 1. This matches the timing of private
savings (a stock carried into a period earns that period's return) and
the timing the conversion coefficient already assumed: dir_R values the
balance in period R without discounting the first payment, so with the
discount rate equal to the credited rate the benefits are now
actuarially fair at the notional rate.

Applies to NDC_1dim_loop, NDC_2dim_loop, NDC_3dim_loop (and so to the
notional band of the hybrid system) and to deriv_NDC_loop. Updates the
NDC test expectations (each by exactly one period of the credited rate)
and adds a fairness test.

Also fixes the NDC labor-supply derivative in the docs and in the
deriv_NDC docstring, which had the exponent u - s and the condition
s < R - 1; it is (1 + g_NDC)^(R - s) for every s < R. Bumps the version
to 0.24.7.

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

codecov-commenter commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 25.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.81%. Comparing base (9b8a3b4) to head (5aaf174).

Files with missing lines Patch % Lines
ogcore/pensions.py 0.00% 3 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##           master    #1287   +/-   ##
=======================================
  Coverage   79.81%   79.81%           
=======================================
  Files          24       24           
  Lines        6811     6811           
=======================================
  Hits         5436     5436           
  Misses       1375     1375           
Flag Coverage Δ
unittests 79.81% <25.00%> (ø)

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/pensions.py 73.21% <0.00%> (ø)
🚀 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