Add initial_wealth_ratio to calibrate initial household wealth

[marcelolafleur]

Addresses #1188.

Adds initial_wealth_ratio (default 0.0 = disabled, current behavior unchanged): aggregate household wealth in the initial period, relative to steady-state GDP. Initial wealth is a predetermined state, so the anchor is static within the solve: a baseline run scales the steady-state wealth profile once, before the outer loop, so aggregate initial wealth equals initial_wealth_ratio × the steady-state Y that the SS solve has already pinned down exactly. Reform runs ignore the parameter and clone the baseline's initial wealth (read from the baseline's saved transition) — the initial state is history, so baseline and reform always share the same initial condition, to machine precision.

Changes: the parameter, a scale_initial_wealth helper in TPI.py applied once at initialization, tests (the existing get_initial_SS_values parameterizations pass unchanged), and a CHANGELOG entry.

Two designs were tried and rejected, documented here for reviewers: anchoring to initial-period GDP requires either updating the anchor inside the outer loop (both raw and nu-damped updates drove the initial cohorts' root-finding into infeasible negative-consumption roots that satisfy the extended FOCs — and pass the constraint checker, which watches a different consumption object; that checker gap may deserve its own issue) or iterating whole solves. Anchoring to steady-state GDP is exact, static, and robust; calibrations map their data target with one solve iteration and report the delivered initial wealth-to-GDP ratio.

Demonstration on a real country model

OG-PHL baseline transition (2025 start, no policy change), both runs on this branch, converged with transition resource-constraint errors ~0.0014:

• Disabled (legacy): the imposed condition amounts to a starting wealth-to-GDP of 4.49 — every initial household holds far more than its steady-state counterpart, retirees consume the windfall (aggregate consumption +45% for a year), domestic investment collapses to ~2% of its long-run level, and the debt ratio is paid down to 49.6% against a 60% target.
• Calibrated (delivered wealth-to-GDP = 3.35, from the PWT capital stock less the IMF public capital stock, the BSP IIP domestic share, and domestically held government debt): consumption smooth (−1.5% in the same year), investment trough at 72% of long-run, debt flat on target through the consolidation window — and the model's primary balance lands exactly on the government's programmed 2025 stance (−2.51 vs −2.51). Calibrate remittances and the full revenue side to Philippine data, and close the budget identity at the debt target EAPD-DRB/OG-PHL#85 carries the full calibration.

cc: @rickecon @jdebacker

[codecov-commenter]

Codecov Report

❌ Patch coverage is 37.50000% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.57%. Comparing base (b9b33ac) to head (3258f7b).

Files with missing lines	Patch %	Lines
ogcore/TPI.py	37.50%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1189      +/-   ##
==========================================
- Coverage   72.66%   72.57%   -0.10%     
==========================================
  Files          22       22              
  Lines        5726     5742      +16     
==========================================
+ Hits         4161     4167       +6     
- Misses       1565     1575      +10     

Flag	Coverage Δ
unittests	72.57% <37.50%> (-0.10%)	⬇️

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

Files with missing lines	Coverage Δ
ogcore/TPI.py	36.33% <37.50%> (+0.03%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.