SAM-EM Project VIR NREL#390

Author: softwareengineerprogrammer

docs/SAM-Economic-Models.md

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

src/geophires_x/Economics.py

@@ -6,7 +6,7 @@
 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
+    real_discount_rate_parameter, after_tax_irr_parameter, moic_parameter, project_vir_parameter
 from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType, \
     _WellDrillingCostCorrelationCitation
 from geophires_x.Parameter import intParameter, floatParameter, OutputParameter, ReadParameter, boolParameter, \
@@ -1839,13 +1839,7 @@ def __init__(self, model: Model):
             CurrentUnits=PercentUnit.PERCENT,
             PreferredUnits=PercentUnit.PERCENT,
         )
-        self.ProjectVIR = self.OutputParameterDict[self.ProjectVIR.Name] = OutputParameter(
-            "Project Value Investment Ratio",
-            display_name='Project VIR=PI=PIR',
-            UnitType=Units.PERCENT,
-            PreferredUnits=PercentUnit.TENTH,
-            CurrentUnits=PercentUnit.TENTH
-        )
+        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",
@@ -2799,9 +2793,7 @@ def Calculate(self, model: Model) -> None:
                 convertible_unit(self.ProjectIRR.CurrentUnits)).magnitude
 
             self.ProjectMOIC.value = self.sam_economics_calculations.moic.value
-
-            # TODO SAM economic models VIR https://github.com/NREL/GEOPHIRES-X/issues/390
-            # self.ProjectVIR.value = non_calculated_output_placeholder_val
+            self.ProjectVIR.value = self.sam_economics_calculations.project_vir.value
 
         # Calculate the project payback period
         if self.econmodel.value == EconomicModel.SAM_SINGLE_OWNER_PPA:

src/geophires_x/EconomicsSam.py

@@ -35,6 +35,7 @@
     nominal_discount_rate_parameter,
     after_tax_irr_parameter,
     moic_parameter,
+    project_vir_parameter,
 )
 from geophires_x.GeoPHIRESUtils import is_float, is_int
 from geophires_x.OptionList import EconomicModel, EndUseOptions
@@ -68,12 +69,10 @@ class SamEconomicsCalculations:
     )
 
     after_tax_irr: OutputParameter = field(default_factory=after_tax_irr_parameter)
-
     nominal_discount_rate: OutputParameter = field(default_factory=nominal_discount_rate_parameter)
-
     wacc: OutputParameter = field(default_factory=wacc_output_parameter)
-
     moic: OutputParameter = field(default_factory=moic_parameter)
+    project_vir: OutputParameter = field(default_factory=project_vir_parameter)
 
 
 def validate_read_parameters(model: Model):
@@ -173,8 +172,8 @@ def sf(_v: float, num_sig_figs: int = 5) -> float:
     sam_economics.nominal_discount_rate.value, sam_economics.wacc.value = _calculate_nominal_discount_rate_and_wacc(
         model, single_owner
     )
-
     sam_economics.moic.value = _calculate_moic(cash_flow, model)
+    sam_economics.project_vir.value = _calculate_project_vir(cash_flow, model)
 
     return sam_economics
 
@@ -229,6 +228,25 @@ def _calculate_moic(cash_flow: list[list[Any]], model) -> float | None:
         return None
 
 
+def _calculate_project_vir(cash_flow: list[list[Any]], model) -> float | None:
+    """
+    VIR = PV(Future Cash Flows) / |CF_0|
+    Where CF_0 is the cash flow at Year 0 (the initial investment).
+    NPV = CF_0 + PV(Future Cash Flows)
+    PV(Future Cash Flows) = NPV - CF_0
+    """
+    try:
+        npv_USD = Decimal(_cash_flow_profile_row(cash_flow, 'After-tax cumulative NPV ($)')[-1])
+        cf_0_USD = Decimal(_cash_flow_profile_row(cash_flow, 'Total after-tax returns ($)')[0])
+        pv_of_future_cash_flows_USD = npv_USD - cf_0_USD
+        vir = pv_of_future_cash_flows_USD / abs(cf_0_USD)
+
+        return float(vir)
+    except Exception as e:
+        model.logger.error(f'Encountered exception calculating Project VIR: {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

@@ -49,6 +49,16 @@ def moic_parameter() -> OutputParameter:
     )
 
 
+def project_vir_parameter() -> OutputParameter:
+    return OutputParameter(
+        "Project Value Investment Ratio",
+        display_name='Project VIR=PI=PIR',
+        UnitType=Units.PERCENT,
+        PreferredUnits=PercentUnit.TENTH,
+        CurrentUnits=PercentUnit.TENTH
+    )
+
+
 def after_tax_irr_parameter() -> OutputParameter:
     return OutputParameter(
         Name='After-tax IRR',

src/geophires_x/Outputs.py

@@ -285,10 +285,7 @@ def PrintOutputs(self, model: Model):
                     if not math.isnan(irr_output_param.value) else 'NaN'
                 f.write(f'      {irr_field_label}{irr_display_value} {irr_output_param.CurrentUnits.value}\n')
 
-                if econ.econmodel.value != EconomicModel.SAM_SINGLE_OWNER_PPA:
-                    # TODO SAM economic models VIR https://github.com/NREL/GEOPHIRES-X/issues/390
-                    f.write(f'      {econ.ProjectVIR.display_name}:                              {econ.ProjectVIR.value:10.2f}\n')
-
+                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:

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:  08:45
- Calculation Time:      1.041 sec
+ Simulation Time:  11:49
+ Calculation Time:      1.057 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -33,6 +33,7 @@ Simulation Metadata
       Capacity factor:                                       90.0 %
       Project NPV:                                         428.92 MUSD
       After-tax IRR:                                        25.85 %
+      Project VIR=PI=PIR:                                    1.39
       Project MOIC:                                          2.98
       Estimated Jobs Created:                                 1299
 

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

@@ -4,10 +4,10 @@
 
 Simulation Metadata
 ----------------------
- GEOPHIRES Version: 3.9.14
- Simulation Date: 2025-06-03
- Simulation Time:  08:48
- Calculation Time:      0.875 sec
+ GEOPHIRES Version: 3.9.15
+ Simulation Date: 2025-06-04
+ Simulation Time:  11:49
+ Calculation Time:      0.878 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -33,6 +33,7 @@ Simulation Metadata
       Capacity factor:                                       90.0 %
       Project NPV:                                        2877.00 MUSD
       After-tax IRR:                                        59.73 %
+      Project VIR=PI=PIR:                                    4.58
       Project MOIC:                                         12.36
       Estimated Jobs Created:                                 976
 

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

@@ -4,10 +4,10 @@
 
 Simulation Metadata
 ----------------------
- GEOPHIRES Version: 3.9.14
- Simulation Date: 2025-06-03
- Simulation Time:  08:48
- Calculation Time:      1.039 sec
+ GEOPHIRES Version: 3.9.15
+ Simulation Date: 2025-06-04
+ Simulation Time:  11:49
+ Calculation Time:      1.042 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -33,6 +33,7 @@ Simulation Metadata
       Capacity factor:                                       90.0 %
       Project NPV:                                         124.91 MUSD
       After-tax IRR:                                        22.33 %
+      Project VIR=PI=PIR:                                    1.79
       Project MOIC:                                          4.15
       Estimated Jobs Created:                                 125