SAM-EM Project Payback Period NatLabRockies#390

Author: softwareengineerprogrammer

docs/SAM-Economic-Models.md

@@ -48,9 +48,7 @@ The following table describes how GEOPHIRES parameters are transformed into SAM
 ### Limitations
 
 1. Only Electricity end-use is supported
-2. Only 1 construction year is supported
-3. The following economic outputs are not calculated:
-    1. Project Payback Period
+2. Only 1 construction year is supported.
 
 ## Using SAM Economic Models with Existing GEOPHIRES Inputs
 

src/geophires_x/Economics.py

@@ -6,7 +6,8 @@
 from geophires_x import EconomicsSam
 from geophires_x.EconomicsSam import calculate_sam_economics, SamEconomicsCalculations
 from geophires_x.EconomicsUtils import BuildPricingModel, wacc_output_parameter, nominal_discount_rate_parameter, \
-    real_discount_rate_parameter, after_tax_irr_parameter, moic_parameter, project_vir_parameter
+    real_discount_rate_parameter, after_tax_irr_parameter, moic_parameter, project_vir_parameter, \
+    project_payback_period_parameter
 from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType, \
     _WellDrillingCostCorrelationCitation
 from geophires_x.Parameter import intParameter, floatParameter, OutputParameter, ReadParameter, boolParameter, \
@@ -1841,12 +1842,8 @@ def __init__(self, model: Model):
         )
         self.ProjectVIR = self.OutputParameterDict[self.ProjectVIR.Name] = project_vir_parameter()
         self.ProjectMOIC = self.OutputParameterDict[self.ProjectMOIC.Name] = moic_parameter()
-        self.ProjectPaybackPeriod = self.OutputParameterDict[self.ProjectPaybackPeriod.Name] = OutputParameter(
-            "Project Payback Period",
-            UnitType=Units.TIME,
-            PreferredUnits=TimeUnit.YEAR,
-            CurrentUnits=TimeUnit.YEAR
-        )
+        self.ProjectPaybackPeriod = self.OutputParameterDict[self.ProjectPaybackPeriod.Name] = (
+            project_payback_period_parameter())
         self.RITCValue = self.OutputParameterDict[self.RITCValue.Name] = OutputParameter(
             Name="Investment Tax Credit Value",
             display_name='Investment Tax Credit',
@@ -2794,12 +2791,10 @@ def Calculate(self, model: Model) -> None:
 
             self.ProjectMOIC.value = self.sam_economics_calculations.moic.value
             self.ProjectVIR.value = self.sam_economics_calculations.project_vir.value
+            self.ProjectPaybackPeriod.value = self.sam_economics_calculations.project_payback_period.value
 
         # Calculate the project payback period
-        if self.econmodel.value == EconomicModel.SAM_SINGLE_OWNER_PPA:
-            # TODO TODO SAM economic models Payback period https://github.com/NREL/GEOPHIRES-X/issues/390
-            self.ProjectPaybackPeriod.value = non_calculated_output_placeholder_val
-        else:
+        if self.econmodel.value != EconomicModel.SAM_SINGLE_OWNER_PPA:
             self.ProjectPaybackPeriod.value = 0.0  # start by assuming the project never pays back
             for i in range(0, len(self.TotalCummRevenue.value), 1):
                 # find out when the cumm cashflow goes from negative to positive

src/geophires_x/EconomicsSam.py

@@ -36,6 +36,7 @@
     after_tax_irr_parameter,
     moic_parameter,
     project_vir_parameter,
+    project_payback_period_parameter,
 )
 from geophires_x.GeoPHIRESUtils import is_float, is_int
 from geophires_x.OptionList import EconomicModel, EndUseOptions
@@ -73,6 +74,7 @@ class SamEconomicsCalculations:
     wacc: OutputParameter = field(default_factory=wacc_output_parameter)
     moic: OutputParameter = field(default_factory=moic_parameter)
     project_vir: OutputParameter = field(default_factory=project_vir_parameter)
+    project_payback_period: OutputParameter = field(default_factory=project_payback_period_parameter)
 
 
 def validate_read_parameters(model: Model):
@@ -174,6 +176,7 @@ def sf(_v: float, num_sig_figs: int = 5) -> float:
     )
     sam_economics.moic.value = _calculate_moic(cash_flow, model)
     sam_economics.project_vir.value = _calculate_project_vir(cash_flow, model)
+    sam_economics.project_payback_period.value = _calculate_project_payback_period(cash_flow, model)
 
     return sam_economics
 
@@ -247,6 +250,28 @@ def _calculate_project_vir(cash_flow: list[list[Any]], model) -> float | None:
         return None
 
 
+def _calculate_project_payback_period(cash_flow: list[list[Any]], model) -> float | None:
+    try:
+        after_tax_cash_flow = _cash_flow_profile_row(cash_flow, 'Total after-tax returns ($)')
+        cumm_cash_flow = np.zeros(len(after_tax_cash_flow))
+        cumm_cash_flow[0] = after_tax_cash_flow[0]
+        for year in range(1, len(after_tax_cash_flow)):
+            cumm_cash_flow[year] = cumm_cash_flow[year - 1] + after_tax_cash_flow[year]
+            if cumm_cash_flow[year] >= 0:
+                year_before_full_recovery = year - 1
+                payback_period = (
+                    year_before_full_recovery
+                    + abs(cumm_cash_flow[year_before_full_recovery]) / after_tax_cash_flow[year]
+                )
+
+                return float(payback_period)
+
+        return float('nan')  # never pays back
+    except Exception as e:
+        model.logger.error(f'Encountered exception calculating Project Payback Period: {e}')
+        return None
+
+
 def get_sam_cash_flow_profile_tabulated_output(model: Model, **tabulate_kw_args) -> str:
     """
     Note model must have already calculated economics for this to work (used in Outputs)

src/geophires_x/EconomicsUtils.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from geophires_x.Parameter import OutputParameter
-from geophires_x.Units import Units, PercentUnit
+from geophires_x.Units import Units, PercentUnit, TimeUnit
 
 
 def BuildPricingModel(plantlifetime: int, StartPrice: float, EndPrice: float,
@@ -59,6 +59,18 @@ def project_vir_parameter() -> OutputParameter:
     )
 
 
+def project_payback_period_parameter() -> OutputParameter:
+    return OutputParameter(
+        "Project Payback Period",
+        UnitType=Units.TIME,
+        PreferredUnits=TimeUnit.YEAR,
+        CurrentUnits=TimeUnit.YEAR,
+        ToolTipText='The time at which cumulative cash flow reaches zero. '
+                    'For projects that never pay back, the calculated value will be "N/A". '
+                    'For SAM Economic Models, total after-tax returns are used to calculate cumulative cash flow.',
+    )
+
+
 def after_tax_irr_parameter() -> OutputParameter:
     return OutputParameter(
         Name='After-tax IRR',

src/geophires_x/Outputs.py

@@ -288,13 +288,12 @@ def PrintOutputs(self, model: Model):
                 f.write(f'      {econ.ProjectVIR.display_name}:                              {econ.ProjectVIR.value:10.2f}\n')
                 f.write(f'      {econ.ProjectMOIC.display_name}:                                    {econ.ProjectMOIC.value:10.2f}\n')
 
-                if econ.econmodel.value != EconomicModel.SAM_SINGLE_OWNER_PPA:
-                    # TODO TODO SAM economic models Payback period https://github.com/NREL/GEOPHIRES-X/issues/390
-                    payback_period_val = model.economics.ProjectPaybackPeriod.value
-                    project_payback_period_display = f'{payback_period_val:10.2f} {econ.ProjectPaybackPeriod.PreferredUnits.value}' \
-                        if payback_period_val > 0.0 else 'N/A'
-                    project_payback_period_label = Outputs._field_label(model.economics.ProjectPaybackPeriod.display_name, 56)
-                    f.write(f'      {project_payback_period_label}{project_payback_period_display}\n')
+                payback_period_val = model.economics.ProjectPaybackPeriod.value
+                project_payback_period_display = (f'{payback_period_val:10.2f} '
+                                                  f'{econ.ProjectPaybackPeriod.PreferredUnits.value}') \
+                    if payback_period_val > 0.0 else 'N/A'
+                project_payback_period_label = Outputs._field_label(model.economics.ProjectPaybackPeriod.display_name, 56)
+                f.write(f'      {project_payback_period_label}{project_payback_period_display}\n')
 
                 if model.surfaceplant.enduse_option.value in [EndUseOptions.COGENERATION_TOPPING_EXTRA_HEAT,
                                                               EndUseOptions.COGENERATION_BOTTOMING_EXTRA_HEAT,

src/geophires_x_schema_generator/geophires-result.json

@@ -121,7 +121,7 @@
         "Fixed Charge Rate (FCR)": {},
         "Project Payback Period": {
           "type": "number",
-          "description": "",
+          "description": "The time at which cumulative cash flow reaches zero. For projects that never pay back, the calculated value will be \"N/A\". For SAM Economic Models, total after-tax returns are used to calculate cumulative cash flow.",
           "units": "yr"
         },
         "CHP: Percent cost allocation for electrical plant": {},

tests/examples/Fervo_Project_Cape-4.out

@@ -6,8 +6,8 @@ Simulation Metadata
 ----------------------
  GEOPHIRES Version: 3.9.15
  Simulation Date: 2025-06-04
- Simulation Time:  11:49
- Calculation Time:      1.057 sec
+ Simulation Time:  12:20
+ Calculation Time:      1.066 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -35,6 +35,7 @@ Simulation Metadata
       After-tax IRR:                                        25.85 %
       Project VIR=PI=PIR:                                    1.39
       Project MOIC:                                          2.98
+      Project Payback Period:                                       2.53 yr
       Estimated Jobs Created:                                 1299
 
                           ***ENGINEERING PARAMETERS***

tests/examples/example_SAM-single-owner-PPA-2.out

@@ -6,8 +6,8 @@ Simulation Metadata
 ----------------------
  GEOPHIRES Version: 3.9.15
  Simulation Date: 2025-06-04
- Simulation Time:  11:49
- Calculation Time:      0.878 sec
+ Simulation Time:  12:20
+ Calculation Time:      0.882 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -35,6 +35,7 @@ Simulation Metadata
       After-tax IRR:                                        59.73 %
       Project VIR=PI=PIR:                                    4.58
       Project MOIC:                                         12.36
+      Project Payback Period:                                       1.13 yr
       Estimated Jobs Created:                                 976
 
                           ***ENGINEERING PARAMETERS***

tests/examples/example_SAM-single-owner-PPA.out

@@ -6,8 +6,8 @@ Simulation Metadata
 ----------------------
  GEOPHIRES Version: 3.9.15
  Simulation Date: 2025-06-04
- Simulation Time:  11:49
- Calculation Time:      1.042 sec
+ Simulation Time:  12:20
+ Calculation Time:      1.061 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -35,6 +35,7 @@ Simulation Metadata
       After-tax IRR:                                        22.33 %
       Project VIR=PI=PIR:                                    1.79
       Project MOIC:                                          4.15
+      Project Payback Period:                                       4.32 yr
       Estimated Jobs Created:                                 125
 
                           ***ENGINEERING PARAMETERS***

tests/geophires_x_tests/test_economics_sam.py

@@ -500,6 +500,17 @@ def _irr(_r: GeophiresXResult) -> float:
         self.assertFalse(math.isnan(r_irr))
         self.assertAlmostEqual(npf_irr, r_irr, places=2)
 
+    def test_nan_project_payback_period(self):
+        def _payback_period(_r: GeophiresXResult) -> float:
+            return _r.result['ECONOMIC PARAMETERS']['Project Payback Period']['value']
+
+        never_pays_back_params = {
+            'Starting Electricity Sale Price': 0.00001,
+            'Ending Electricity Sale Price': 0.00002,
+        }
+        r: GeophiresXResult = self._get_result(never_pays_back_params)
+        self.assertIsNone(_payback_period(r))
+
     @staticmethod
     def _new_model(input_file: Path, additional_params: dict[str, Any] | None = None, read_and_calculate=True) -> Model:
         if additional_params is not None: