Merge pull request NREL#364 from softwareengineerprogrammer/main

Add 'Discount Initial Year Cashflow' parameter for Excel-style NPV calculation [v3.8.4]

Author: softwareengineerprogrammer

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.8.0
+current_version = 3.8.4
 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.4
     version_manager: "bump2version"
     website: "https://github.com/NREL"
     year_from: "2023"

CHANGELOG.rst

@@ -124,7 +124,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.4.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.4...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.4'
 
 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.4',
     license='MIT',
     description='GEOPHIRES is a free and open-source geothermal techno-economic simulator.',
     long_description='{}\n{}'.format(

src/geophires_x/Economics.py

@@ -304,12 +304,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 +342,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 +356,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 +880,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,
@@ -1739,18 +1778,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 +2927,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/Outputs.py

@@ -1643,7 +1643,12 @@ def PrintOutputs(self, model: Model):
                 f.write(f'      Accrued financing during construction:            {model.economics.inflrateconstruction.value*100:10.2f} ' + model.economics.inflrateconstruction.CurrentUnits.value + NL)
                 f.write(f'      Project lifetime:                              {model.surfaceplant.plant_lifetime.value:10.0f} ' + model.surfaceplant.plant_lifetime.CurrentUnits.value + NL)
                 f.write(f'      Capacity factor:                                 {model.surfaceplant.utilization_factor.value * 100:10.1f} %' + NL)
-                f.write(f'      Project NPV:                                     {model.economics.ProjectNPV.value:10.2f} ' + model.economics.ProjectNPV.PreferredUnits.value + NL)
+
+                e_npv = model.economics.ProjectNPV
+                npv_field_label = Outputs._field_label('Project NPV', 49)
+                # TODO should use CurrentUnits instead of PreferredUnits
+                f.write(f'      {npv_field_label}{e_npv.value:10.2f} {e_npv.PreferredUnits.value}\n')
+
                 f.write(f'      Project IRR:                                     {model.economics.ProjectIRR.value:10.2f} ' + model.economics.ProjectIRR.PreferredUnits.value + NL)
                 f.write(f'      Project VIR=PI=PIR:                              {model.economics.ProjectVIR.value:10.2f}' + NL)
                 f.write(f'      {model.economics.ProjectMOIC.Name}:                                    {model.economics.ProjectMOIC.value:10.2f}' + NL)

src/geophires_x/OutputsAddOns.py

@@ -41,7 +41,7 @@ def PrintOutputs(self, model) -> tuple:
                 addon_results.append(OutputTableItem('Adjusted Project CAPEX (after incentives, grants, AddOns, etc)', '{0:10.2f}'.format(model.addeconomics.AdjustedProjectCAPEX.value), model.addeconomics.AdjustedProjectCAPEX.PreferredUnits.value))
                 f.write(f"      Adjusted Project OPEX (after incentives, grants, AddOns, etc):    {model.addeconomics.AdjustedProjectOPEX.value:10.2f} " + model.addeconomics.AdjustedProjectOPEX.PreferredUnits.value + NL)
                 addon_results.append(OutputTableItem('Adjusted Project OPEX (after incentives, grants, AddOns, etc)', '{0:10.2f}'.format(model.addeconomics.AdjustedProjectOPEX.value), model.addeconomics.AdjustedProjectOPEX.PreferredUnits.value))
-                f.write(f"      Project NPV   (including AddOns):                                 {model.addeconomics.ProjectNPV.value:10.2f} " + model.addeconomics.ProjectNPV.PreferredUnits.value + NL)
+                f.write(f'      Project NPV   (including AddOns):                                 {model.addeconomics.ProjectNPV.value:10.2f} {model.addeconomics.ProjectNPV.PreferredUnits.value}\n')
                 addon_results.append(OutputTableItem('Project NPV (including AddOns)', '{0:10.2f}'.format(model.addeconomics.ProjectNPV.value), model.addeconomics.ProjectNPV.PreferredUnits.value))
                 f.write(f"      Project IRR   (including AddOns):                                 {model.addeconomics.ProjectIRR.value:10.2f} " + model.addeconomics.ProjectIRR.PreferredUnits.value + NL)
                 addon_results.append(OutputTableItem('Project IRR (including AddOns)', '{0:10.2f}'.format(model.addeconomics.ProjectIRR.value), model.addeconomics.ProjectIRR.PreferredUnits.value))