Merge branch 'main' into AGS-bugs

Author: jeffbourdier

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.8.0
+current_version = 3.8.6
 commit = True
 tag = True
 

.cookiecutterrc

@@ -54,7 +54,7 @@ default_context:
     sphinx_doctest: "no"
     sphinx_theme: "sphinx-py3doc-enhanced-theme"
     test_matrix_separate_coverage: "no"
-    version: 3.8.0
+    version: 3.8.6
     version_manager: "bump2version"
     website: "https://github.com/NREL"
     year_from: "2023"

CHANGELOG.rst

@@ -13,6 +13,12 @@ GEOPHIRES-X (2023-2025)
 Revenue & Cashflow Profile period output aligned with NREL convention used to calculate NPV.
 See https://github.com/NREL/GEOPHIRES-X/discussions/344
 
+3.8.6: Baseline well drilling cost curves updated to NREL's 2025 cost curve update:
+Akindipe, D. and Witter. E. 2025. "2025 Geothermal Drilling Cost Curves Update". https://pangea.stanford.edu/ERE/db/GeoConf/papers/SGW/2025/Akindipe.pdf?t=1740084555.
+
+Intermediate and ideal correlations retain existing values from GeoVision:
+DOE 2019. "GeoVision" p. 163. https://www.energy.gov/sites/prod/files/2019/06/f63/GeoVision-full-report-opt.pdf.
+
 3.7
 ^^^
 
@@ -124,7 +130,7 @@ Major, minor, and notable patch versions are documented above.
 You may also be interested in viewing the list of all PRs merged into the repository `here <https://github.com/NREL/GEOPHIRES-X/pulls?q=is%3Apr+is%3Amerged+>`__.
 
 Each semantic version has a corresponding tag, the full list of which can be viewed `here <https://github.com/NREL/GEOPHIRES-X/tags>`__.
-The latest patch version in this repository and patch versions explicitly mentioned in this changelog are always suitable for public consumption;
+The patch version displayed on the package badge in the README and patch versions explicitly mentioned in this changelog are always suitable for public consumption;
 but note that not all patch version tags in the list are meant for public consumption
 as intermediate internal-only patch versions are sometimes introduced during the development process.
 (Improved designation and distribution of releases for public consumption may eventually be addressed by

README.rst

@@ -56,9 +56,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.8.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/softwareengineerprogrammer/GEOPHIRES-X/v3.8.6.svg
     :alt: Commits since latest release
-    :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.8.0...main
+    :target: https://github.com/softwareengineerprogrammer/GEOPHIRES-X/compare/v3.8.6...main
 
 .. |docs| image:: https://readthedocs.org/projects/GEOPHIRES-X/badge/?style=flat
     :target: https://nrel.github.io/GEOPHIRES-X

docs/conf.py

@@ -18,7 +18,7 @@
 year = '2025'
 author = 'NREL'
 copyright = f'{year}, {author}'
-version = release = '3.8.0'
+version = release = '3.8.6'
 
 pygments_style = 'trac'
 templates_path = ['./templates']

setup.py

@@ -13,7 +13,7 @@ def read(*names, **kwargs):
 
 setup(
     name='geophires-x',
-    version='3.8.0',
+    version='3.8.6',
     license='MIT',
     description='GEOPHIRES is a free and open-source geothermal techno-economic simulator.',
     long_description='{}\n{}'.format(

src/geophires_x/Economics.py

@@ -4,7 +4,8 @@
 import numpy as np
 import numpy_financial as npf
 import geophires_x.Model as Model
-from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType
+from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType, \
+    _WellDrillingCostCorrelationCitation
 from geophires_x.Parameter import intParameter, floatParameter, OutputParameter, ReadParameter, boolParameter, \
     coerce_int_params_to_enum_values
 from geophires_x.Units import *
@@ -304,12 +305,29 @@ def CalculateCarbonRevenue(model, plant_lifetime: int, construction_years: int,
     return cash_flow_musd, cumm_cash_flow_musd, carbon_that_would_have_been_produced_annually_lbs, carbon_that_would_have_been_produced_total_lbs
 
 
+def calculate_npv(
+    discount_rate_tenths: float,
+    cashflow_series: list,
+    discount_initial_year_cashflow: bool
+) -> float:
+    # TODO warn/raise exception if discount rate > 1 (i.e. it's probably not converted from percent to tenths)
+
+    npv_cashflow_series = cashflow_series.copy()  # Copy to guard against unintentional mutation of consumer field
+
+    if discount_initial_year_cashflow:
+        # Enable Excel-style NPV calculation - see https://github.com/NREL/GEOPHIRES-X/discussions/344
+        npv_cashflow_series = [0, *npv_cashflow_series]
+
+    return npf.npv(discount_rate_tenths, npv_cashflow_series)
+
+
 def CalculateFinancialPerformance(plantlifetime: int,
                                   FixedInternalRate: float,
                                   TotalRevenue: list,
                                   TotalCummRevenue: list,
                                   CAPEX: float,
-                                  OPEX: float):
+                                  OPEX: float,
+                                  discount_initial_year_cashflow: bool = False):
     """
     CalculateFinancialPerformance calculates the financial performance of the project.  It is used to calculate the
     financial performance of the project. It is used to calculate the revenue stream for the project.
@@ -325,6 +343,9 @@ def CalculateFinancialPerformance(plantlifetime: int,
     :type CAPEX: float
     :param OPEX: The total annual operating cost of the project in MUSD
     :type OPEX: float
+    :param discount_initial_year_cashflow: Whether to discount the initial year of cashflow used to calculate NPV
+    :type discount_initial_year_cashflow: bool
+
     :return: NPV: The net present value of the project in MUSD
     :rtype: float
     :return: IRR: The internal rate of return of the project in %
@@ -336,7 +357,8 @@ def CalculateFinancialPerformance(plantlifetime: int,
     :rtype: tuple
     """
     # Calculate financial performance values using numpy financials
-    NPV = npf.npv(FixedInternalRate / 100, TotalRevenue)
+
+    NPV = calculate_npv(FixedInternalRate / 100, TotalRevenue.copy(), discount_initial_year_cashflow)
     IRR = npf.irr(TotalRevenue)
     if math.isnan(IRR):
         IRR = 0.0
@@ -859,6 +881,24 @@ def __init__(self, model: Model):
                         "Discount Rate is synonymous with Fixed Internal Rate. If one is provided, the other's value "
                         "will be automatically set to the same value."
         )
+
+
+        self.discount_initial_year_cashflow = self.ParameterDict[self.discount_initial_year_cashflow.Name] = boolParameter(
+            'Discount Initial Year Cashflow',
+            DefaultValue=False,
+            UnitType=Units.NONE,
+            ToolTipText='Whether to discount cashflow in the initial project year when calculating NPV '
+                        '(Net Present Value). '
+                        'The default value of False conforms to NREL\'s standard convention for NPV calculation '
+                        '(Short W et al, 1995. https://www.nrel.gov/docs/legosti/old/5173.pdf). '
+                        'A value of True will, by contrast, cause NPV calculation to follow the convention used by '
+                        'Excel, Google Sheets, and other common spreadsheet software. '
+                        'Although NREL\'s NPV convention may typically be considered more technically correct, '
+                        'Excel-style NPV calculation might be preferred for familiarity '
+                        'or compatibility with existing business processes. '
+                        'See https://github.com/NREL/GEOPHIRES-X/discussions/344 for further details.'
+        )
+
         self.FIB = self.ParameterDict[self.FIB.Name] = floatParameter(
             "Fraction of Investment in Bonds",
             DefaultValue=0.5,
@@ -965,9 +1005,15 @@ def __init__(self, model: Model):
             UnitType=Units.NONE,
             ErrMessage="assume default well drilling cost correlation (10)",
             ToolTipText="Select the built-in well drilling and completion cost correlation: " +
-                        '; '.join([f'{it.int_value}: {it.value}' for it in WellDrillingCostCorrelation])
-        )
+                        '; '.join([f'{it.int_value}: {it.value}'
+                                   for it in WellDrillingCostCorrelation]) +
+                        f'. '
+                        f'Baseline correlations (1-4) are from '
+                        f'{_WellDrillingCostCorrelationCitation.NREL_COST_CURVE_2025.value}.'
+                        f' Intermediate and ideal correlations (6-17) are from '
+                        f'{_WellDrillingCostCorrelationCitation.GEOVISION.value}.'
 
+        )
         self.DoAddOnCalculations = self.ParameterDict[self.DoAddOnCalculations.Name] = boolParameter(
             "Do AddOn Calculations",
             DefaultValue=False,
@@ -1739,18 +1785,25 @@ def __init__(self, model: Model):
             PreferredUnits=PercentUnit.PERCENT,
             CurrentUnits=PercentUnit.PERCENT
         )
+
+        # TODO this is displayed as "Project Net Revenue" in Revenue & Cashflow Profile which is probably not an
+        #   accurate synonym for annual revenue
         self.TotalRevenue = self.OutputParameterDict[self.TotalRevenue.Name] = OutputParameter(
             Name="Annual Revenue from Project",
             UnitType=Units.CURRENCYFREQUENCY,
             PreferredUnits=CurrencyFrequencyUnit.MDOLLARSPERYEAR,
             CurrentUnits=CurrencyFrequencyUnit.MDOLLARSPERYEAR
         )
+
+        # TODO this is displayed as "Project Net Cashflow" in Revenue & Cashflow Profile which is probably not an
+        #   accurate synonym for cumulative revenue
         self.TotalCummRevenue = self.OutputParameterDict[self.TotalCummRevenue.Name] = OutputParameter(
             Name="Cumulative Revenue from Project",
             UnitType=Units.CURRENCY,
             PreferredUnits=CurrencyUnit.MDOLLARS,
             CurrentUnits=CurrencyUnit.MDOLLARS
         )
+
         self.ProjectNPV = self.OutputParameterDict[self.ProjectNPV.Name] = OutputParameter(
             "Project Net Present Value",
             UnitType=Units.CURRENCY,
@@ -2881,9 +2934,15 @@ def Calculate(self, model: Model) -> None:
 
         # Calculate more financial values using numpy financials
         self.ProjectNPV.value, self.ProjectIRR.value, self.ProjectVIR.value, self.ProjectMOIC.value = \
-            CalculateFinancialPerformance(model.surfaceplant.plant_lifetime.value, self.FixedInternalRate.value,
-                                          self.TotalRevenue.value, self.TotalCummRevenue.value, self.CCap.value,
-                                          self.Coam.value)
+            CalculateFinancialPerformance(
+                model.surfaceplant.plant_lifetime.value,
+                self.FixedInternalRate.value,
+                self.TotalRevenue.value,
+                self.TotalCummRevenue.value,
+                self.CCap.value,
+                self.Coam.value,
+                self.discount_initial_year_cashflow.value
+            )
 
         # Calculate the project payback period
         self.ProjectPaybackPeriod.value = 0.0   # start by assuming the project never pays back

src/geophires_x/EconomicsAddOns.py

@@ -347,7 +347,12 @@ def Calculate(self, model: Model) -> None:
 
         # Now calculate a new "NPV", "IRR", "VIR", "Payback Period", and "MOIC"
         # Calculate more financial values using numpy financials
-        self.ProjectNPV.value = npf.npv(self.FixedInternalRate.value / 100, self.ProjectCashFlow.value)
+        self.ProjectNPV.value = Economics.calculate_npv(
+            self.FixedInternalRate.value / 100,
+            self.ProjectCashFlow.value.copy(),
+            self.discount_initial_year_cashflow.value
+        )
+
         self.ProjectIRR.value = npf.irr(self.ProjectCashFlow.value)
         if math.isnan(self.ProjectIRR.value):
             self.ProjectIRR.value = 0.0

src/geophires_x/GeoPHIRESUtils.py

@@ -252,7 +252,7 @@ def density_water_kg_per_m3(Twater_degC: float, pressure: Optional[PlainQuantity
 
     except (NotImplementedError, ValueError) as e:
         raise ValueError(f'Input temperature & pressure ({Twater_degC}, {pressure}) '
-                         f'are out of range or otherwise could not be used to calculate') from e
+                         f'are out of range or otherwise could not be used to calculate water density.') from e
 
 
 def celsius_to_kelvin(celsius: float) -> float:
@@ -298,7 +298,7 @@ def viscosity_water_Pa_sec(
 
     except (NotImplementedError, ValueError) as e:
         raise ValueError(f'Input temperature & pressure ({Twater_degC}, {pressure}) '
-                         f'are out of range or otherwise could not be used to calculate') from e
+                         f'are out of range or otherwise could not be used to calculate water viscosity.') from e
 
 
 @lru_cache
@@ -334,7 +334,7 @@ def heat_capacity_water_J_per_kg_per_K(
 
     except (NotImplementedError, ValueError) as e:
         raise ValueError(f'Input temperature & pressure ({Twater_degC}, {pressure}) '
-                         f'are out of range or otherwise could not be used to calculate') from e
+                         f'are out of range or otherwise could not be used to calculate heat capacity of water.') from e
 
 
 @lru_cache