Add Cashflow Series Start Year parameter to enable NPV calculation parity with Excel/Google Sheets/etc.

Author: softwareengineerprogrammer

src/geophires_x/Economics.py

@@ -309,7 +309,8 @@ def CalculateFinancialPerformance(plantlifetime: int,
                                   TotalRevenue: list,
                                   TotalCummRevenue: list,
                                   CAPEX: float,
-                                  OPEX: float):
+                                  OPEX: float,
+                                  cashflow_series_start_year: float = 0.):
     """
     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 +326,9 @@ 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
+
     :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,8 +340,19 @@ def CalculateFinancialPerformance(plantlifetime: int,
     :rtype: tuple
     """
     # Calculate financial performance values using numpy financials
-    NPV = npf.npv(FixedInternalRate / 100, TotalRevenue)
-    IRR = npf.irr(TotalRevenue)
+
+    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.:
+        cashflow_series = [0, *cashflow_series]
+
+    NPV = npf.npv(FixedInternalRate / 100, cashflow_series)
+    IRR = npf.irr(cashflow_series)
     if math.isnan(IRR):
         IRR = 0.0
     else:
@@ -859,6 +874,19 @@ 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."
         )
+
+        # TODO add support for float values
+        self.cashflow_series_start_year = self.ParameterDict[self.discountrate.Name] = intParameter(
+            "Cashflow Series Start Year",
+            DefaultValue=0,
+            AllowableRange=[0,1],
+            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
+        )
+
         self.FIB = self.ParameterDict[self.FIB.Name] = floatParameter(
             "Fraction of Investment in Bonds",
             DefaultValue=0.5,
@@ -2881,9 +2909,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.cashflow_series_start_year.value
+            )
 
         # Calculate the project payback period
         self.ProjectPaybackPeriod.value = 0.0   # start by assuming the project never pays back

tests/geophires_x_tests/test_economics.py

@@ -11,21 +11,22 @@
 
 
 class EconomicsTestCase(BaseTestCase):
+    @staticmethod
+    def cumm_revenue(total_revenue):
+        cumm_revenue = [total_revenue[0]] * len(total_revenue)
+        cumm_revenue[1] = total_revenue[1]
+        for i in range(2, len(total_revenue)):
+            cumm_revenue[i] = cumm_revenue[i - 1] + total_revenue[i]
+        return cumm_revenue
+
     def test_irr(self):
         """
         Test cases adapted from https://numpy.org/numpy-financial/latest/irr.html
         """
 
-        def cumm_revenue(total_revenue):
-            cumm_revenue = [total_revenue[0]] * len(total_revenue)
-            cumm_revenue[1] = total_revenue[1]
-            for i in range(2, len(total_revenue)):
-                cumm_revenue[i] = cumm_revenue[i - 1] + total_revenue[i]
-            return cumm_revenue
-
         def calc_irr(total_revenue):
             NPV, IRR, VIR, MOIC = CalculateFinancialPerformance(
-                30, 5, total_revenue, cumm_revenue(total_revenue), 1000, 10
+                30, 5, total_revenue, EconomicsTestCase.cumm_revenue(total_revenue), 1000, 10
             )
 
             return IRR
@@ -36,19 +37,45 @@ def calc_irr(total_revenue):
         self.assertAlmostEqual(6.21, calc_irr([-100, 100, 0, 7]), places=2)
         self.assertAlmostEqual(8.86, calc_irr([-5, 10.5, 1, -8, 1]), places=2)
 
-    def test_numpy_financial_npv(self):
-        # https://www.nrel.gov/docs/legosti/old/5173.pdf, p. 41
+    def test_npv(self):
+        """
+        Includes sanity checks that numpy-financial.npv used by CalculateFinancialPerformance
+        matches reference calculations
+        """
+
         rate = 0.12
+
+        def calc_npv(total_revenue, cashflow_series_start_year=0):
+            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,
+            )
+
+            return NPV
+
+        # https://www.nrel.gov/docs/legosti/old/5173.pdf, p. 41
         cashflow_series = [-10000, 7274, 6558, 6223, 6087, 6259]
-        npv = npf.npv(rate, cashflow_series)
-        self.assertEqual(13572, round(npv))
+
+        npf_npv = npf.npv(rate, cashflow_series)
+        self.assertEqual(13572, round(npf_npv))
+
+        geophires_npv = calc_npv(cashflow_series)
+        self.assertEqual(13572, round(geophires_npv))
 
         # https://support.microsoft.com/en-us/office/npv-function-8672cb67-2576-4d07-b67b-ac28acf2a568
         rate = 0.1
         cashflow_series = [-10000, 3000, 4200, 6800]
         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)
+        self.assertEqual(1188.44, round(geophires_npv, 2))
+
     def test_well_drilling_cost_correlation_tooltiptext(self):
         ec = self._new_model().economics
         self.assertEqual(

tests/test_geophires_x.py

@@ -590,6 +590,25 @@ 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:
+            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,
+                    },
+                )
+            )
+
+        def _npv(r: GeophiresXResult) -> dict:
+            return r.result['ECONOMIC PARAMETERS']['Project NPV']['value']
+
+        self.assertEqual(4561.96, _npv(_get_result(0)))
+        self.assertEqual(4263.51, _npv(_get_result(1)))
+
     def test_transmission_pipeline_cost(self):
         result = GeophiresXClient().get_geophires_result(
             GeophiresInputParameters(