Switch from integer 'Cashflow Series Start Year' to boolean 'Discount Initial Year Cashflow' to match Excel's (simpler) convention, which does not treat cash outlays spread over multiple initial years differently.

Author: softwareengineerprogrammer

src/geophires_x/Economics.py

@@ -310,7 +310,7 @@ def CalculateFinancialPerformance(plantlifetime: int,
                                   TotalCummRevenue: list,
                                   CAPEX: float,
                                   OPEX: float,
-                                  cashflow_series_start_year: float = 0.):
+                                  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.
@@ -326,8 +326,8 @@ def CalculateFinancialPerformance(plantlifetime: int,
     :type CAPEX: float
     :param OPEX: The total annual operating cost of the project in MUSD
     :type OPEX: float
-    :param cashflow_series_start_year: The starting year of the cashflow series used to calculate NPV
-    :type cashflow_series_start_year: 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
@@ -343,12 +343,7 @@ def CalculateFinancialPerformance(plantlifetime: int,
 
     cashflow_series = TotalRevenue.copy()
 
-    if cashflow_series_start_year not in [0., 1.]:
-        param_name = 'Cashflow Series Start Year'  # TODO reference name defined in parameter dict
-        raise NotImplementedError(f'Unsupported value for {param_name}: {cashflow_series_start_year}')
-
-
-    if cashflow_series_start_year == 1.:
+    if discount_initial_year_cashflow:
         cashflow_series = [0, *cashflow_series]
 
     NPV = npf.npv(FixedInternalRate / 100, cashflow_series)
@@ -875,16 +870,22 @@ def __init__(self, model: Model):
                         "will be automatically set to the same value."
         )
 
-        # TODO add support for float values
-        self.cashflow_series_start_year = self.ParameterDict[self.cashflow_series_start_year.Name] = intParameter(
-            "Cashflow Series Start Year",
-            DefaultValue=0,
-            AllowableRange=[0, 1],
+
+        self.discount_initial_year_cashflow = self.ParameterDict[self.discount_initial_year_cashflow.Name] = boolParameter(
+            'Discount Initial Year Cashflow',
+            DefaultValue=False,
             UnitType=Units.NONE,
-            ErrMessage=f'assume default Cashflow Series Start Year ({0})',
-            ToolTipText="Cashflow Series Start Year used to calculate NPV"
-                        # "in the Standard Levelized Cost Model." # (?)
-                        # TODO documentation re: values/conventions
+            ToolTipText='Whether to discount cashflow in the initial project year when calculating NPV. '
+                        '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 '
+                        'from a financial mathematics perspective, '
+                        'Excel-style NPV calculation may be preferred by some for familiarity, '
+                        'compliance with de-facto organizational standards, or comparison of '
+                        'GEOPHIRES with independent financial calculations. '
+                        'See https://github.com/NREL/GEOPHIRES-X/discussions/344 for discussion and further details.'
         )
 
         self.FIB = self.ParameterDict[self.FIB.Name] = floatParameter(
@@ -2916,7 +2917,7 @@ def Calculate(self, model: Model) -> None:
                 self.TotalCummRevenue.value,
                 self.CCap.value,
                 self.Coam.value,
-                self.cashflow_series_start_year.value
+                self.discount_initial_year_cashflow.value
             )
 
         # Calculate the project payback period

src/geophires_x/Parameter.py

@@ -144,7 +144,7 @@ class boolParameter(Parameter):
 
     def __post_init__(self):
         if self.value is None:
-            self.value:bool = self.DefaultValue
+            self.value: bool = self.DefaultValue
 
     value: bool = None
     DefaultValue: bool = value

tests/geophires_x_tests/test_economics.py

@@ -45,15 +45,15 @@ def test_npv(self):
 
         rate = 0.12
 
-        def calc_npv(total_revenue, cashflow_series_start_year=0):
+        def calc_npv(total_revenue, discount_initial_year_cashflow=False):
             NPV, IRR, VIR, MOIC = CalculateFinancialPerformance(
                 len(total_revenue) + 1,
                 rate * 100,
                 total_revenue,
                 EconomicsTestCase.cumm_revenue(total_revenue),
                 total_revenue[0],
                 10,
-                cashflow_series_start_year=cashflow_series_start_year,
+                discount_initial_year_cashflow=discount_initial_year_cashflow,
             )
 
             return NPV
@@ -73,7 +73,7 @@ def calc_npv(total_revenue, cashflow_series_start_year=0):
         excel_npv = npf.npv(rate, [0, *cashflow_series])
         self.assertEqual(1188.44, round(excel_npv, 2))
 
-        geophires_npv = calc_npv(cashflow_series, cashflow_series_start_year=1)
+        geophires_npv = calc_npv(cashflow_series, discount_initial_year_cashflow=True)
         self.assertEqual(1188.44, round(geophires_npv, 2))
 
     def test_well_drilling_cost_correlation_tooltiptext(self):

tests/test_geophires_x.py

@@ -590,24 +590,24 @@ def assertHasLogRecordWithMessage(logs_, message):
                 logs2, 'Set Discount Rate to 0.042 because Fixed Internal Rate was provided (4.2 percent)'
             )
 
-    def test_cashflow_series_start_year(self):
-        def _get_result(series_start_year: int) -> GeophiresXResult:
+    def test_discount_initial_year_cashflow(self):
+        def _get_result(do_discount: bool) -> GeophiresXResult:
             return GeophiresXClient().get_geophires_result(
                 GeophiresInputParameters(
                     # TODO switch over to generic EGS case to avoid thrash from example updates
                     # from_file_path=self._get_test_file_path('geophires_x_tests/generic-egs-case.txt'),
                     from_file_path=self._get_test_file_path('examples/Fervo_Project_Cape-3.txt'),
                     params={
-                        'Cashflow Series Start Year': series_start_year,
+                        'Discount Initial Year Cashflow': do_discount,
                     },
                 )
             )
 
         def _npv(r: GeophiresXResult) -> dict:
             return r.result['ECONOMIC PARAMETERS']['Project NPV']['value']
 
-        self.assertEqual(4580.36, _npv(_get_result(0)))
-        self.assertEqual(4280.71, _npv(_get_result(1)))
+        self.assertEqual(4580.36, _npv(_get_result(False)))
+        self.assertEqual(4280.71, _npv(_get_result(True)))
 
     def test_transmission_pipeline_cost(self):
         result = GeophiresXClient().get_geophires_result(