Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .bumpversion.cfg
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[bumpversion]
current_version = 3.20.1
current_version = 3.21.0
commit = True
tag = True

Expand Down
2 changes: 1 addition & 1 deletion .cookiecutterrc
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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] <https://github.com/NatLabRockies/GEOPHIRES-X/pull/542>`__; `Construction Loan Up-Front Fee <https://github.com/NatLabRockies/GEOPHIRES-X/pull/540>`__ | `release <https://github.com/NREL/GEOPHIRES-X/releases/tag/v3.21.0>`__ | **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 <https://github.com/NatLabRockies/GEOPHIRES-X/issues/529>`__ 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
^^^^

Expand Down
4 changes: 2 additions & 2 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ Free software: `MIT license <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
Expand Down
11 changes: 8 additions & 3 deletions docs/SAM-EM_Multiple-Construction-Years.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Binary file modified docs/_images/sam-em-mcy-construction-cash-flow-category.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/_images/sam-em-mcy-design-diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
6 changes: 5 additions & 1 deletion src/geophires_x/Economics.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
19 changes: 10 additions & 9 deletions src/geophires_x/EconomicsSamPreRevenue.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 ($)'
Expand All @@ -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 ---
Expand Down
2 changes: 1 addition & 1 deletion src/geophires_x/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = '3.20.1'
__version__ = '3.21.0'
2 changes: 1 addition & 1 deletion src/geophires_x_schema_generator/geophires-request.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
21 changes: 21 additions & 0 deletions tests/geophires_x_tests/test_economics_sam.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
33 changes: 32 additions & 1 deletion tests/geophires_x_tests/test_economics_sam_pre_revenue.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Loading