Output SAM IRR as 'After-Tax IRR' to avoid potential mixup with 'Project IRR' as unlevered IRR (see https://www.efinancialmodels.com/knowledge-base/financial-metrics/internal-rate-of-revenue-irr/irr-levered-an-internal-rate-of-return-example/)

Author: softwareengineerprogrammer

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
+    real_discount_rate_parameter, after_tax_irr_parameter
 from geophires_x.OptionList import Configuration, WellDrillingCostCorrelation, EconomicModel, EndUseOptions, PlantType, \
     _WellDrillingCostCorrelationCitation
 from geophires_x.Parameter import intParameter, floatParameter, OutputParameter, ReadParameter, boolParameter, \
@@ -1784,6 +1784,8 @@ def __init__(self, model: Model):
             CurrentUnits=PercentUnit.PERCENT
         )
 
+        self.after_tax_irr = self.OutputParameterDict[self.after_tax_irr.Name] = (
+            after_tax_irr_parameter())
         self.real_discount_rate = self.OutputParameterDict[self.real_discount_rate.Name] = (
             real_discount_rate_parameter())
         self.nominal_discount_rate = self.OutputParameterDict[self.nominal_discount_rate.Name] = (
@@ -2775,7 +2777,9 @@ def Calculate(self, model: Model) -> None:
             self.nominal_discount_rate.value = self.sam_economics_calculations.nominal_discount_rate.value
             self.ProjectNPV.value = self.sam_economics_calculations.project_npv.quantity().to(
                 convertible_unit(self.ProjectNPV.CurrentUnits)).magnitude
-            self.ProjectIRR.value = self.sam_economics_calculations.project_irr.quantity().to(
+
+            self.ProjectIRR.value = non_calculated_output_placeholder_val  # SAM calculates After-Tax IRR instead
+            self.after_tax_irr.value = self.sam_economics_calculations.after_tax_irr.quantity().to(
                 convertible_unit(self.ProjectIRR.CurrentUnits)).magnitude
 
             self.ProjectVIR.value = non_calculated_output_placeholder_val  # TODO SAM VIR

src/geophires_x/EconomicsSam.py

@@ -27,7 +27,12 @@
 
 from geophires_x import Model as Model
 from geophires_x.EconomicsSamCashFlow import _calculate_sam_economics_cash_flow
-from geophires_x.EconomicsUtils import BuildPricingModel, wacc_output_parameter, nominal_discount_rate_parameter
+from geophires_x.EconomicsUtils import (
+    BuildPricingModel,
+    wacc_output_parameter,
+    nominal_discount_rate_parameter,
+    after_tax_irr_parameter,
+)
 from geophires_x.GeoPHIRESUtils import is_float, is_int
 from geophires_x.OptionList import EconomicModel, EndUseOptions
 from geophires_x.Parameter import Parameter, OutputParameter, floatParameter
@@ -44,24 +49,22 @@ class SamEconomicsCalculations:
             CurrentUnits=EnergyCostUnit.CENTSSPERKWH,
         )
     )
+
     capex: OutputParameter = field(
         default_factory=lambda: OutputParameter(
             UnitType=Units.CURRENCY,
             CurrentUnits=CurrencyUnit.MDOLLARS,
         )
     )
+
     project_npv: OutputParameter = field(
         default_factory=lambda: OutputParameter(
             UnitType=Units.CURRENCY,
             CurrentUnits=CurrencyUnit.MDOLLARS,
         )
     )
-    project_irr: OutputParameter = field(
-        default_factory=lambda: OutputParameter(
-            UnitType=Units.PERCENT,
-            CurrentUnits=PercentUnit.PERCENT,
-        )
-    )
+
+    after_tax_irr: OutputParameter = field(default_factory=after_tax_irr_parameter)
 
     nominal_discount_rate: OutputParameter = field(default_factory=nominal_discount_rate_parameter)
 
@@ -157,7 +160,7 @@ def sf(_v: float) -> float:
 
     sam_economics: SamEconomicsCalculations = SamEconomicsCalculations(sam_cash_flow_profile=cash_flow)
     sam_economics.lcoe_nominal.value = sf(single_owner.Outputs.lcoe_nom)
-    sam_economics.project_irr.value = sf(single_owner.Outputs.project_return_aftertax_irr)
+    sam_economics.after_tax_irr.value = sf(single_owner.Outputs.project_return_aftertax_irr)
     sam_economics.project_npv.value = sf(single_owner.Outputs.project_return_aftertax_npv * 1e-6)
     sam_economics.capex.value = single_owner.Outputs.adjusted_installed_cost * 1e-6
 

src/geophires_x/EconomicsUtils.py

@@ -37,27 +37,39 @@ def BuildPricingModel(plantlifetime: int, StartPrice: float, EndPrice: float,
     return Price
 
 
+def after_tax_irr_parameter() -> OutputParameter:
+    return OutputParameter(
+        Name='After-Tax IRR',
+        UnitType=Units.PERCENT,
+        CurrentUnits=PercentUnit.PERCENT,
+        PreferredUnits=PercentUnit.PERCENT,
+        ToolTipText='The After-Tax IRR (internal rate of return) is the nominal discount rate that corresponds to '
+                    'a net present value (NPV) of zero for PPA SAM Economic models. '
+                    'See https://samrepo.nrelcloud.org/help/mtf_irr.html.'
+    )
+
+
 def real_discount_rate_parameter() -> OutputParameter:
     return OutputParameter(
-            Name="Real Discount Rate",
-            UnitType=Units.PERCENT,
-            CurrentUnits=PercentUnit.PERCENT,
-            PreferredUnits=PercentUnit.PERCENT,
-        )
+        Name="Real Discount Rate",
+        UnitType=Units.PERCENT,
+        CurrentUnits=PercentUnit.PERCENT,
+        PreferredUnits=PercentUnit.PERCENT,
+    )
 
 
 def nominal_discount_rate_parameter() -> OutputParameter:
     return OutputParameter(
-            Name="Nominal Discount Rate",
-            ToolTipText="Nominal Discount Rate is displayed for SAM Economic Models. "
-                        "It is calculated "
-                        "per https://samrepo.nrelcloud.org/help/fin_single_owner.html?q=nominal+discount+rate: "
-                        "Nominal Discount Rate = [ ( 1 + Real Discount Rate ÷ 100 ) "
-                        "× ( 1 + Inflation Rate ÷ 100 ) - 1 ] × 100.",
-            UnitType=Units.PERCENT,
-            CurrentUnits=PercentUnit.PERCENT,
-            PreferredUnits=PercentUnit.PERCENT,
-        )
+        Name="Nominal Discount Rate",
+        ToolTipText="Nominal Discount Rate is displayed for SAM Economic Models. "
+                    "It is calculated "
+                    "per https://samrepo.nrelcloud.org/help/fin_single_owner.html?q=nominal+discount+rate: "
+                    "Nominal Discount Rate = [ ( 1 + Real Discount Rate ÷ 100 ) "
+                    "× ( 1 + Inflation Rate ÷ 100 ) - 1 ] × 100.",
+        UnitType=Units.PERCENT,
+        CurrentUnits=PercentUnit.PERCENT,
+        PreferredUnits=PercentUnit.PERCENT,
+    )
 
 
 def wacc_output_parameter() -> OutputParameter:

src/geophires_x/Outputs.py

@@ -275,8 +275,12 @@ def PrintOutputs(self, model: Model):
                 # TODO should use CurrentUnits instead of PreferredUnits
                 f.write(f'      {npv_field_label}{e_npv.value:10.2f} {e_npv.PreferredUnits.value}\n')
 
-                irr_display_value = f'{econ.ProjectIRR.value:10.2f}' if not math.isnan(econ.ProjectIRR.value) else 'NaN'
-                f.write(f'      {econ.ProjectIRR.display_name}:                                     {irr_display_value} {econ.ProjectIRR.CurrentUnits.value}\n')
+                irr_output_param: OutputParameter = econ.ProjectIRR \
+                    if econ.econmodel.value != EconomicModel.SAM_SINGLE_OWNER_PPA else econ.after_tax_irr
+                irr_field_label = Outputs._field_label(irr_output_param.display_name, 49)
+                irr_display_value = f'{irr_output_param.value:10.2f}' \
+                    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:
                     # VIR, MOIC, and Payback period not currently supported by SAM economic model(s)

tests/examples/Fervo_Project_Cape-4.out

@@ -5,9 +5,9 @@
 Simulation Metadata
 ----------------------
  GEOPHIRES Version: 3.9.7
- Simulation Date: 2025-05-20
- Simulation Time:  13:06
- Calculation Time:      1.051 sec
+ Simulation Date: 2025-05-21
+ Simulation Time:  09:51
+ Calculation Time:      1.041 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -31,7 +31,7 @@ Simulation Metadata
       Project lifetime:                                      20 yr
       Capacity factor:                                       90.0 %
       Project NPV:                                        1940.10 MUSD
-      Project IRR:                                          24.75 %
+      After-Tax IRR:                                        24.75 %
       Estimated Jobs Created:                                 1190
 
                           ***ENGINEERING PARAMETERS***

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

@@ -5,9 +5,9 @@
 Simulation Metadata
 ----------------------
  GEOPHIRES Version: 3.9.7
- Simulation Date: 2025-05-15
- Simulation Time:  10:13
- Calculation Time:      0.891 sec
+ Simulation Date: 2025-05-21
+ Simulation Time:  09:55
+ Calculation Time:      0.888 sec
 
                            ***SUMMARY OF RESULTS***
 
@@ -31,7 +31,7 @@ Simulation Metadata
       Project lifetime:                                      20 yr
       Capacity factor:                                       90.0 %
       Project NPV:                                        2877.00 MUSD
-      Project IRR:                                          59.73 %
+      After-Tax IRR:                                        59.73 %
       Estimated Jobs Created:                                 976
 
                           ***ENGINEERING PARAMETERS***

tests/test_geophires_x.py

@@ -195,21 +195,8 @@ def get_output_file_for_example(example_file: str):
                 del expected_result.result['metadata']
                 del expected_result.result['Simulation Metadata']
 
-                def sanitize_nan(r: GeophiresXResult) -> None:
-                    """
-                    Workaround for float('nan') != float('nan')
-                    See https://stackoverflow.com/questions/51728427/unittest-how-to-assert-if-the-two-possibly-nan-values-are-equal
-
-                    TODO generalize beyond Project IRR
-                    """
-                    try:
-                        if math.isnan(r.result['ECONOMIC PARAMETERS']['Project IRR']['value']):
-                            r.result['ECONOMIC PARAMETERS']['Project IRR']['value'] = 'NaN'
-                    except TypeError:
-                        pass
-
-                sanitize_nan(geophires_result)
-                sanitize_nan(expected_result)
+                self._sanitize_nan(geophires_result)
+                self._sanitize_nan(expected_result)
 
                 try:
                     self.assertDictEqual(
@@ -261,6 +248,22 @@ def sanitize_nan(r: GeophiresXResult) -> None:
         if len(regenerate_cmds) > 0:
             print(f'Command to regenerate {len(regenerate_cmds)} failed examples:\n{" && ".join(regenerate_cmds)}')
 
+    # noinspection PyMethodMayBeStatic
+    def _sanitize_nan(self, r: GeophiresXResult) -> None:
+        """
+        Workaround for float('nan') != float('nan')
+        See https://stackoverflow.com/questions/51728427/unittest-how-to-assert-if-the-two-possibly-nan-values-are-equal
+
+        TODO generalize beyond After-Tax IRR
+        """
+        irr_key = 'After-Tax IRR'
+        if irr_key in r.result['ECONOMIC PARAMETERS']:
+            try:
+                if math.isnan(r.result['ECONOMIC PARAMETERS'][irr_key]['value']):
+                    r.result['ECONOMIC PARAMETERS'][irr_key]['value'] = 'NaN'
+            except TypeError:
+                pass
+
     def _get_unequal_dicts_approximate_percent_difference(self, d1: dict, d2: dict) -> Optional[float]:
         for i in range(99):
             try: