Skip to content

IDC and Debt Fee Release [v3.21] - #195

Merged
softwareengineerprogrammer merged 7 commits into
mainfrom
idc-and-debt-fee-release-3
Nov 16, 2026
Merged

softwareengineerprogrammer merged 7 commits into
mainfrom
idc-and-debt-fee-release-3

Conversation

@softwareengineerprogrammer

@softwareengineerprogrammer softwareengineerprogrammer commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Description

Follow-up from:

  1. Rename capitalized interest  NatLabRockies/GEOPHIRES-X#542
  2. Construction loan up front fee NatLabRockies/GEOPHIRES-X#540

Completes the remaining NatLabRockies#529 checklist items (docs, images, CHANGELOG), fixes the construction loan up-front fee funding bug introduced in NatLabRockies#540, and bumps the version to 3.21.0.

The NatLabRockies#540 fee was added to Installed cost [construction] and SAM total_installed_cost, but neither Issuance of equity [construction] nor Issuance of debt [construction] funded it. With multiple construction years, after-tax IRR and NPV combine the construction rows (After-tax net cash flow [construction] = −equity issuance) with SAM Total after-tax returns ($) from Year 1 onward, dropping SAM's Year 0, where equity would implicitly fund it. The fee therefore increased ITC and depreciation basis without ever being paid, so adding a fee raised NPV and IRR. The fee is now paid by equity in the year of each construction debt draw.

TODO

  1. Relabel IDC as "Capitalized interest (IDC)" in docs/_images/sam-em-mcy-design-diagram.png: b017852
  2. Merge NatLabRockies main into this branch (picks up Rename capitalized interest  NatLabRockies/GEOPHIRES-X#542 rename, 451c712)
  3. Re-capture docs/_images/sam-em-mcy-construction-cash-flow-category.png (example_SAM-single-owner-PPA-5, now shows Capitalized interest [construction] ($)): ccba852
  4. docs/SAM-EM_Multiple-Construction-Years.md IDC bullet wording: "Interest on the accumulated debt balance (Capitalized interest [construction]) is calculated using…": 8c8bb6e
  5. Check GTP web interface (and any other consumers) for lookups of the old row name

Construction loan up-front fee (NatLabRockies#540) fix

  1. Confirm bug: with Construction Loan Up-Front Fee, 0.05, example_SAM-single-owner-PPA-5 Project NPV rose from 100.75 to 104.78 MUSD and IRR from 16.28% to 16.55% (see Manual testing)
  2. Open issue in NatLabRockies/GEOPHIRES-X and link here
  3. Fund fee from equity: each year's fee is added to Issuance of equity [construction] (and thus After-tax net cash flow [construction]), consistent with SAM's implicit Year 0 treatment; debt balance, capitalized interest, installed cost and effective_debt_percent unchanged: f477458
  4. Tests: with nonzero fee, equity + debt + capitalized interest = installed cost each year; NPV and IRR with fee < without (same commit)
  5. Rename/reposition Debt up-front fee [construction] ($) → Construction loan up-front fee [construction] ($) (matches the input name; distinct from SAM's operating-period Debt up-front fee ($) / cost_debt_upfront), moved after Capitalized interest [construction] ($). The row was introduced in Construction loan up front fee NatLabRockies/GEOPHIRES-X#540 after v3.20.1, so no released output changes (same commit)
  6. Add fee to design diagram (fee charged on Issuance of debt; feeds Issuance of equity and Installed cost; Capitalized interest ⇄ Debt balance loop moved below): f7b3705
  7. Tooltip (and geophires-request.json): fee is charged on each year's draw, paid by equity, and capitalized (simplification; real up-front fees are usually on the commitment at financial close) (same commit as fee fix)

Release

  1. CHANGELOG 3.21 entry: Changed: Debt interest payment [construction] ($) → Capitalized interest [construction] ($) (Rename capitalized interest  NatLabRockies/GEOPHIRES-X#542, Rename Debt interest payment [construction] cash flow row: it's capitalized interest, not a cash payment NatLabRockies/GEOPHIRES-X#529); up-front fee funding fix: 921b21a
  2. bumpversion minor (3.20.1 → 3.21.0; .bumpversion.cfg auto-commits and tags): 691dc76

Testing & Verification

  1. Unit tests added:
    • test_construction_loan_upfront_fee_sources_equal_uses (test_economics_sam_pre_revenue.py): per-year fee, equity, debt, capitalized interest, installed cost and after-tax net cash flow values for a 3-year, 2% fee case; equity + debt + capitalized interest = installed cost in every construction year.
    • test_construction_loan_upfront_fee_reduces_npv_and_irr (test_economics_sam.py): a 5% fee lowers Project NPV and After-tax IRR for example_SAM-single-owner-PPA-5.
  2. Unit tests updated: test_construction_loan_upfront_fee (test_economics_sam_pre_revenue.py) for the Construction loan up-front fee [construction] ($) row rename.
  3. Manual testing:
    • example_SAM-single-owner-PPA-5 with and without Construction Loan Up-Front Fee, 0.05:

      No fee 5% fee, before fix 5% fee, after fix
      Project NPV (MUSD) 100.75 104.78 92.52
      After-tax IRR 16.28% 16.55% 15.59%
      Total CAPEX (MUSD) 712.75 732.87 732.87

      Results without the fee are unchanged.

    • test_economics_sam.py and test_economics_sam_pre_revenue.py: 49 passed, 2 skipped (pre-existing skips).

    • No example input uses the fee, so no example .out files change.


Change Checklist

Observe the following checklist items before and after merging, as applicable.

Before merging:

  1. I certify that I am a human and I have manually verified the correctness of the changes in this PR.
  2. Add a CHANGELOG entry if your change includes a new version1: 921b21a

After merging:

  1. Push tag(s) to GitHub: git push origin refs/tags/vM.m.P
  2. Post a change announcement to the GEOPHIRES Change Announcements Discussion (example). Markdown template:
 M.m.p: [TITLE](https://github.com/NREL/GEOPHIRES-X/pull/PR-NUMBER) | [release](https://github.com/NREL/GEOPHIRES-X/releases/tag/vM.m.P)

Self-reviewed in #195

Footnotes

  1. See versioning notes and version management docs. ↩

@softwareengineerprogrammer
softwareengineerprogrammer marked this pull request as ready for review November 15, 2026 16:56
@softwareengineerprogrammer
softwareengineerprogrammer marked this pull request as draft November 15, 2026 16:57
@softwareengineerprogrammer softwareengineerprogrammer added the bug Something isn't working label Nov 16, 2026
@softwareengineerprogrammer
softwareengineerprogrammer marked this pull request as ready for review November 16, 2026 18:52
@softwareengineerprogrammer
softwareengineerprogrammer merged commit 0ef23c1 into main Nov 16, 2026
27 of 29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant