[j-bryan]

Refs #56 (part 1: the numbers, the missing loan proceeds, and the regression test. A follow-up docs PR closes it.)

What changed

• tests/test_documented_outputs.py
  • Runs the five README examples and the docs/getting_started.md code block as subprocesses.
  • Parses the documented values from the docs themselves (the README NPV table and the expected-output block) and compares them with the printed output.
  • Tolerances are $1M for the README's approximate values, and $1 and $0.005/MWh for getting_started.md.
  • Fails if a documented row is missing, a doc block is missing, a script prints no NPV, or a script exits nonzero.
  • Runtime is about 0.6s for all six cases, so it has no slow marker.
  • It failed first on the old docs (all 6 cases) before the values were regenerated.
• _midlevel, _builders, _primitives: the examples now book construction debt proceeds as DEBT_FRACTION of each dated cash construction draw, as the EnergyProject compiler does.
• _midlevel and _builders: these now amortize the proceeds plus capitalized interest, as EnergyProject does. Before, they amortized OVERNIGHT_CAPEX * DEBT_FRACTION.
  • Run with identical inputs, the lower-level path matches EnergyProject to the dollar on construction, proceeds and debt service, for both the flat and bell profiles.
  • _primitives has neither escalation nor construction interest, so its principal stays $300M.
• Docs: the README comparison table and the getting_started.md expected output are regenerated. Only the numbers changed.

Result changes

Library code is unchanged. Only the examples and the documented values move.

Output	Documented before	Printed before	After
_simple NPV	~$307M	$375.7M	~$376M (code unchanged)
_full NPV	~$37M	$337.0M	~$337M (code unchanged)
_midlevel NPV	~$186M	$155.7M	$345.2M
_builders NPV	~$162M	$107.5M	$308.2M
_primitives NPV	~−$36M	$7.6M	$257.8M
getting_started NPV	$318,988,351	$387,452,247	$387,452,247
getting_started LCOE	$23.30/MWh	$18.64/MWh	$18.64/MWh

Other printed values:

Example	Debt service	Taxes	LCOE ($/MWh)	Debt proceeds (new)
_midlevel	−$704.8M → −$982.6M	−$911.0M → −$877.5M	$78.21 → $84.82	$337.4M
_builders	−$581.4M → −$789.2M	−$936.9M → −$915.8M	$73.92 → $78.83	$341.1M
_primitives	unchanged	unchanged	unchanged	$300.0M

Deferred to the follow-up docs PR (#56 part 2)

• Rewrite the explanations in examples/README.md "Output comparison" to match the code's assumptions. For example, _midlevel at $345M against _full at $337M should be explained by spend profile, depreciation and debt-service dating.
• Document that the examples now share their financing treatment but still differ in spend profile, tax and incentives.
• The examples pick out capitalized interest as the non-cash construction flows. That is correct for treatment="capitalize", which they use, but not for "pay".
• _midlevel and _builders still date debt service at year-end, while EnergyProject calendarizes it.

🤖 Generated with Claude Code

[dylanjm]

I like the automated testing of examples.