diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 84026a742..412331aae 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 3.20.1 +current_version = 3.21.0 commit = True tag = True diff --git a/.cookiecutterrc b/.cookiecutterrc index 50efe2e3d..466de0c15 100644 --- a/.cookiecutterrc +++ b/.cookiecutterrc @@ -54,7 +54,7 @@ default_context: sphinx_doctest: "no" sphinx_theme: "sphinx-py3doc-enhanced-theme" test_matrix_separate_coverage: "no" - version: 3.20.1 + version: 3.21.0 version_manager: "bump2version" website: "https://github.com/NREL" year_from: "2023" diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 4d5025b10..4459e5bc6 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -5,6 +5,11 @@ Changelog GEOPHIRES v3 (2023-2026) ------------------------ +3.21 +^^^^ + +3.21: `Rename Debt interest payment [construction] cash flow row to Capitalized interest [construction] `__; `Construction Loan Up-Front Fee `__ | `release `__ | **Changed:** The SAM Economic Models construction cash flow row ``Debt interest payment [construction] ($)`` has been renamed ``Capitalized interest [construction] ($)``, since it is interest capitalized into the debt balance and installed cost, not a cash payment. Code that reads cash flow rows by name must use the new name. See `the tracking issue `__ for details. The new ``Construction Loan Up-Front Fee`` parameter's fee is paid by equity during construction (``Construction loan up-front fee [construction] ($)``) and capitalized into installed cost. + 3.20 ^^^^ diff --git a/README.rst b/README.rst index abf087db5..ce28fd117 100644 --- a/README.rst +++ b/README.rst @@ -58,9 +58,9 @@ Free software: `MIT license `__ :alt: Supported implementations :target: https://pypi.org/project/geophires-x -.. |commits-since| image:: https://img.shields.io/github/commits-since/softwareengineerprogrammer/GEOPHIRES-X/v3.20.1.svg +.. |commits-since| image:: https://img.shields.io/github/commits-since/softwareengineerprogrammer/GEOPHIRES-X/v3.21.0.svg :alt: Commits since latest release - :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.20.1...main + :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.21.0...main .. |docs| image:: https://readthedocs.org/projects/GEOPHIRES-X/badge/?style=flat :target: https://softwareengineerprogrammer.github.io/GEOPHIRES diff --git a/docs/SAM-EM_Multiple-Construction-Years.md b/docs/SAM-EM_Multiple-Construction-Years.md index 88dc3a644..e8baaf968 100644 --- a/docs/SAM-EM_Multiple-Construction-Years.md +++ b/docs/SAM-EM_Multiple-Construction-Years.md @@ -41,11 +41,16 @@ For each construction year, the `CONSTRUCTION` cash flow is calculated as follow Debt financing can be delayed by specifying `Bond Financing Start Year`. Years prior to this threshold are financed 100% by equity. -1. **IDC (Interest During Construction)**: `Capitalized interest [construction]` on the accumulated debt balance is calculated using - `Inflated Bond Interest Rate During Construction`. This interest is capitalized (added to +1. **IDC (Interest During Construction)**: Interest on the accumulated debt balance (`Capitalized interest [construction]`) + is calculated using `Inflated Bond Interest Rate During Construction`. This interest is capitalized (added to `Debt balance [construction]`) rather than paid out as cash. +1. **Construction Loan Up-Front Fee**: If `Construction Loan Up-Front Fee` is provided, a fee equal to that fraction of + each year's `Issuance of debt [construction]` is paid by equity in that year (included in + `Issuance of equity [construction]` and `After-tax net cash flow [construction]`) and shown as + `Construction loan up-front fee [construction]`. 1. **Annual Installed Cost**: The annual `Installed cost [construction]` is the sum of - `Nominal capital expenditure [construction]` and `Capitalized interest [construction]` (capitalized IDC). + `Nominal capital expenditure [construction]`, `Capitalized interest [construction]` (capitalized IDC), and + `Construction loan up-front fee [construction]` (if any). ![](_images/sam-em-mcy-design-diagram.png) diff --git a/docs/_images/sam-em-mcy-construction-cash-flow-category.png b/docs/_images/sam-em-mcy-construction-cash-flow-category.png index b4a4af163..7ff6bd6c2 100644 Binary files a/docs/_images/sam-em-mcy-construction-cash-flow-category.png and b/docs/_images/sam-em-mcy-construction-cash-flow-category.png differ diff --git a/docs/_images/sam-em-mcy-design-diagram.png b/docs/_images/sam-em-mcy-design-diagram.png index 6453f6203..38a5742e8 100644 Binary files a/docs/_images/sam-em-mcy-design-diagram.png and b/docs/_images/sam-em-mcy-design-diagram.png differ diff --git a/docs/conf.py b/docs/conf.py index 028e2ec9c..3b9eebb5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,7 +18,7 @@ year = '2025' author = 'NREL' copyright = f'{year}, {author}' -version = release = '3.20.1' +version = release = '3.21.0' pygments_style = 'trac' templates_path = ['./templates'] diff --git a/setup.py b/setup.py index a82a83950..de3deb969 100755 --- a/setup.py +++ b/setup.py @@ -13,7 +13,7 @@ def read(*names, **kwargs): setup( name='geophires-x', - version='3.20.1', + version='3.21.0', license='MIT', description='GEOPHIRES is a free and open-source geothermal techno-economic simulator.', long_description='{}\n{}'.format( diff --git a/src/geophires_x/Economics.py b/src/geophires_x/Economics.py index bd762267a..b4ffe95ff 100644 --- a/src/geophires_x/Economics.py +++ b/src/geophires_x/Economics.py @@ -1206,7 +1206,11 @@ def __init__(self, model: Model): UnitType=Units.PERCENT, PreferredUnits=PercentUnit.TENTH, CurrentUnits=PercentUnit.TENTH, - ToolTipText='Up-front fee charged as a percentage of construction debt drawn (for debt/loans)' + ToolTipText="Construction loan up-front fee as a fraction of each construction year's debt draw " + "(Issuance of debt [construction]). The fee is charged on each year's construction debt draw, " + "paid by equity in that year, and capitalized into installed cost. This is a simplification: " + "real up-front fees are typically charged on the full loan commitment at financial close. " + "SAM Economic Models only." ) self.debt_tenor = self.ParameterDict[self.debt_tenor.Name] = intParameter( "Debt Tenor", diff --git a/src/geophires_x/EconomicsSamPreRevenue.py b/src/geophires_x/EconomicsSamPreRevenue.py index 0f3e89cf1..99d8db026 100644 --- a/src/geophires_x/EconomicsSamPreRevenue.py +++ b/src/geophires_x/EconomicsSamPreRevenue.py @@ -177,15 +177,16 @@ def _calculate_pre_revenue_costs_and_cashflow( debt_fraction_this_year = debt_fraction if year_index >= debt_financing_start_year else 0 new_debt_draw_usd = capex_this_year_usd * debt_fraction_this_year - # Equity spend is the cash portion of CAPEX not funded by new debt - equity_spent_this_year_usd = capex_this_year_usd - new_debt_draw_usd + upfront_fee_this_year_usd = new_debt_draw_usd * construction_loan_upfront_fee + + # Equity spend is the cash portion of CAPEX not funded by new debt, plus the construction loan up-front fee + equity_spent_this_year_usd = capex_this_year_usd - new_debt_draw_usd + upfront_fee_this_year_usd capex_spend_vec.append(capex_this_year_usd) equity_spend_vec.append(equity_spent_this_year_usd) debt_draw_vec.append(new_debt_draw_usd) interest_accrued_vec.append(interest_this_year_usd) - upfront_fee_this_year_usd = new_debt_draw_usd * construction_loan_upfront_fee debt_upfront_fee_vec.append(upfront_fee_this_year_usd) total_upfront_fee_usd += upfront_fee_this_year_usd @@ -250,12 +251,6 @@ def _append_row(row_name: str, row_vals: list[float | str]) -> None: debt_draw_vec, ) - if total_upfront_fee_usd > 0: - _append_row( - f'Debt up-front fee ($)', - [-x for x in debt_upfront_fee_vec], - ) - _append_row( f'Debt balance ($)' # 'Size of debt ($)' @@ -265,6 +260,12 @@ def _append_row(row_name: str, row_vals: list[float | str]) -> None: _append_row(_IDC_CASH_FLOW_ROW_NAME, interest_accrued_vec) + if total_upfront_fee_usd > 0: + _append_row( + f'Construction loan up-front fee ($)', + [-x for x in debt_upfront_fee_vec], + ) + pre_revenue_cf_profile.append(blank_row.copy()) # --- Total installed cost & Returns --- diff --git a/src/geophires_x/__init__.py b/src/geophires_x/__init__.py index ff398e4c6..64b38b01c 100644 --- a/src/geophires_x/__init__.py +++ b/src/geophires_x/__init__.py @@ -1 +1 @@ -__version__ = '3.20.1' +__version__ = '3.21.0' diff --git a/src/geophires_x_schema_generator/geophires-request.json b/src/geophires_x_schema_generator/geophires-request.json index f62a07c09..8ce8383db 100644 --- a/src/geophires_x_schema_generator/geophires-request.json +++ b/src/geophires_x_schema_generator/geophires-request.json @@ -1848,7 +1848,7 @@ "maximum": 1.0 }, "Construction Loan Up-Front Fee": { - "description": "Up-front fee charged as a percentage of construction debt drawn (for debt/loans)", + "description": "Construction loan up-front fee as a fraction of each construction year's debt draw (Issuance of debt [construction]). The fee is charged on each year's construction debt draw, paid by equity in that year, and capitalized into installed cost. This is a simplification: real up-front fees are typically charged on the full loan commitment at financial close. SAM Economic Models only.", "type": "number", "units": "", "category": "Economics", diff --git a/tests/geophires_x_tests/test_economics_sam.py b/tests/geophires_x_tests/test_economics_sam.py index b904c676d..3b09740ba 100644 --- a/tests/geophires_x_tests/test_economics_sam.py +++ b/tests/geophires_x_tests/test_economics_sam.py @@ -517,6 +517,27 @@ def _assert_debt_issuance_cash_flow_reflects_bond_financing_start_year(_r, _fina with self.assertRaises(RuntimeError): _get_result_(1) # Bond financing start year is negative year indexed, so value must be less than 0 + def test_construction_loan_upfront_fee_reduces_npv_and_irr(self): + def _get_result_(_params: dict[str, Any]) -> GeophiresXResult: + return GeophiresXClient().get_geophires_result( + ImmutableGeophiresInputParameters( + from_file_path=self._get_test_file_path('../examples/example_SAM-single-owner-PPA-5.txt'), + params=_params, + ) + ) + + def _npv(_r: GeophiresXResult) -> float: + return _r.result['ECONOMIC PARAMETERS']['Project NPV']['value'] + + def _irr(_r: GeophiresXResult) -> float: + return _r.result['ECONOMIC PARAMETERS']['After-tax IRR']['value'] + + r_no_fee = _get_result_({}) + r_fee = _get_result_({'Construction Loan Up-Front Fee': 0.05}) + + self.assertLess(_npv(r_fee), _npv(r_no_fee)) + self.assertLess(_irr(r_fee), _irr(r_no_fee)) + def test_debt_tenor(self): def _debt_balance(params: dict) -> list[float]: r = self._get_result(params) diff --git a/tests/geophires_x_tests/test_economics_sam_pre_revenue.py b/tests/geophires_x_tests/test_economics_sam_pre_revenue.py index 54f483ed6..3681bda52 100644 --- a/tests/geophires_x_tests/test_economics_sam_pre_revenue.py +++ b/tests/geophires_x_tests/test_economics_sam_pre_revenue.py @@ -95,10 +95,41 @@ def _get_row(profile: list[list[float | str]], row_name: str) -> list[float]: return next(row for row in profile if row[0] == row_name)[1:] upfront_fee_row = _get_row( - pre_rev_with_fee.pre_revenue_cash_flow_profile, 'Debt up-front fee [construction] ($)' + pre_rev_with_fee.pre_revenue_cash_flow_profile, 'Construction loan up-front fee [construction] ($)' ) # Year 0 has 0 debt draw, Year 1 and 2 draw debt and incur fee self.assertEqual(upfront_fee_row[0], 0.0) self.assertLess(upfront_fee_row[1], 0.0) self.assertLess(upfront_fee_row[2], 0.0) self.assertAlmostEqual(sum([-x for x in upfront_fee_row]), pre_rev_with_fee.upfront_fee_usd, delta=1.0) + + def test_construction_loan_upfront_fee_sources_equal_uses(self) -> None: + _log = _get_logger() + pre_rev: PreRevenueCostsAndCashflow = _calculate_pre_revenue_costs_and_cashflow( + 100_000_000.0, 3, [0.25, 0.25, 0.5], 0.1, 0.05, 0.5, 1, _log, construction_loan_upfront_fee=0.02 + ) + + def _get_row(row_name: str) -> list[float]: + return next(row for row in pre_rev.pre_revenue_cash_flow_profile if row[0] == row_name)[1:] + + upfront_fee = _get_row('Construction loan up-front fee [construction] ($)') + equity = _get_row('Issuance of equity [construction] ($)') + debt = _get_row('Issuance of debt [construction] ($)') + capitalized_interest = _get_row('Capitalized interest [construction] ($)') + installed_cost = _get_row('Installed cost [construction] ($)') + after_tax_net_cash_flow = _get_row('After-tax net cash flow [construction] ($)') + + self.assertListEqual([0, -275625, -578813], upfront_fee) + self.assertListEqual([26250000, 14056875, 29519438], equity) + self.assertListEqual([0, 13781250, 28940625], debt) + self.assertListEqual([0, 0, 1378125], capitalized_interest) + self.assertListEqual([-26250000, -27838125, -59838188], installed_cost) + self.assertListEqual([-it for it in equity], after_tax_net_cash_flow) + + # Sources (equity + debt + capitalized interest) equal uses (installed cost) in each construction year + for year_index in range(3): + self.assertAlmostEqual( + equity[year_index] + debt[year_index] + capitalized_interest[year_index], + -installed_cost[year_index], + delta=1.0, + )