Merge branch 'royalty-rate-schedule' into royalty-economics

Author: softwareengineerprogrammer

src/geophires_x/Economics.py

@@ -975,11 +975,37 @@ def __init__(self, model: Model):
             UnitType=Units.PERCENT,
             PreferredUnits=PercentUnit.TENTH,
             CurrentUnits=PercentUnit.TENTH,
-            ToolTipText="The percentage of the project's gross annual revenue paid to the royalty holder. "
+            ToolTipText="The fraction of the project's gross annual revenue paid to the royalty holder. "
                         "This is modeled as a variable production-based operating expense, reducing the developer's "
                         "taxable income."
         )
 
+        self.royalty_escalation_rate = self.ParameterDict[self.royalty_escalation_rate.Name] = floatParameter(
+            'Royalty Rate Escalation',
+            DefaultValue=0.,
+            Min=0.0,
+            Max=1.0,
+            UnitType=Units.PERCENT,
+            PreferredUnits=PercentUnit.TENTH,
+            CurrentUnits=PercentUnit.TENTH,
+            ToolTipText="The additive amount the royalty rate increases each year. For example, a value of 0.001 "
+                        "increases a 4% rate (0.04) to 4.1% (0.041) in the next year."
+        )
+
+        self.maximum_royalty_rate = self.ParameterDict[self.maximum_royalty_rate.Name] = floatParameter(
+            'Royalty Rate Maximum',
+            DefaultValue=1.0,  # Default to 100% (no effective cap)
+            Min=0.0,
+            Max=1.0,
+            UnitType=Units.PERCENT,
+            PreferredUnits=PercentUnit.TENTH,
+            CurrentUnits=PercentUnit.TENTH,
+            ToolTipText="The maximum royalty rate after escalation, expressed as a fraction (e.g., 0.06 for a 6% cap)."
+        )
+
+        # TODO support custom royalty rate schedule as a list parameter
+        #  (as an alternative to specifying rate/escalation/max)
+
         self.royalty_holder_discount_rate = self.ParameterDict[self.royalty_holder_discount_rate.Name] = floatParameter(
             'Royalty Holder Discount Rate',
             DefaultValue=0.05,
@@ -3189,6 +3215,34 @@ def build_price_models(self, model: Model) -> None:
                                                    self.CarbonEscalationStart.value, self.CarbonEscalationRate.value,
                                                    self.PTCCarbonPrice)
 
+    def get_royalty_rate_schedule(self, model: Model) -> list[float]:
+        """
+        Builds a year-by-year schedule of royalty rates based on escalation and cap.
+
+        :type model: :class:`~geophires_x.Model.Model`
+        :return: schedule: A list of rates as fractions (e.g., 0.05 for 5%).
+        """
+
+        def r(x: float) -> float:
+            """Ignore apparent float precision issue"""
+            _precision = 8
+            return round(x, _precision)
+
+        plant_lifetime = model.surfaceplant.plant_lifetime.value
+
+        escalation_rate = r(self.royalty_escalation_rate.value)
+        max_rate = r(self.maximum_royalty_rate.value)
+
+        schedule = []
+        current_rate = r(self.royalty_rate.value)
+        for _ in range(plant_lifetime):
+            current_rate = r(current_rate)
+            schedule.append(min(current_rate, max_rate))
+            current_rate += escalation_rate
+
+        return schedule
+
+
     def calculate_cashflow(self, model: Model) -> None:
             """
             Calculate cashflow and cumulative cash flow

src/geophires_x/EconomicsSam.py

@@ -417,16 +417,15 @@ def _get_single_owner_parameters(model: Model) -> dict[str, Any]:
     )
     ret['ppa_price_input'] = ppa_price_schedule_per_kWh
 
-    if hasattr(econ, 'royalty_rate') and econ.royalty_rate.Provided:
-        royalty_rate_fraction = econ.royalty_rate.quantity().to(convertible_unit('dimensionless')).magnitude
-
+    royalty_rate_schedule = _get_royalty_rate_schedule(model)
+    if model.economics.royalty_rate.Provided:
         # For each year, calculate the royalty as a $/MWh variable cost.
         # The royalty is a percentage of revenue (MWh * $/MWh). By setting the
         # variable O&M rate to (PPA Price * Royalty Rate), SAM's calculation
         # (Rate * MWh) will correctly yield the total royalty payment.
         variable_om_schedule_per_MWh = [
-            (price_per_kWh * 1000) * royalty_rate_fraction  # TODO pint unit conversion (kWh -> MWh)
-            for price_per_kWh in ppa_price_schedule_per_kWh
+            (price_kwh * 1000) * royalty_fraction  # TODO use pint unit conversion instead
+            for price_kwh, royalty_fraction in zip(ppa_price_schedule_per_kWh, royalty_rate_schedule)
         ]
 
         # The PySAM parameter for variable operating cost in $/MWh is 'om_production'.
@@ -481,5 +480,9 @@ def _ppa_pricing_model(
     )
 
 
+def _get_royalty_rate_schedule(model: Model) -> list[float]:
+    return model.economics.get_royalty_rate_schedule(model)
+
+
 def _get_max_total_generation_kW(model: Model) -> float:
     return np.max(model.surfaceplant.ElectricityProduced.quantity().to(convertible_unit('kW')).magnitude)

src/geophires_x_schema_generator/geophires-request.json

@@ -1639,14 +1639,32 @@
       "maximum": 1.0
     },
     "Royalty Rate": {
-      "description": "The percentage of the project's gross annual revenue paid to the royalty holder. This is modeled as a variable production-based operating expense, reducing the developer's taxable income.",
+      "description": "The fraction of the project's gross annual revenue paid to the royalty holder. This is modeled as a variable production-based operating expense, reducing the developer's taxable income.",
       "type": "number",
       "units": "",
       "category": "Economics",
       "default": 0.0,
       "minimum": 0.0,
       "maximum": 1.0
     },
+    "Royalty Rate Escalation": {
+      "description": "The additive amount the royalty rate increases each year. For example, a value of 0.001 increases a 4% rate (0.04) to 4.1% (0.041) in the next year.",
+      "type": "number",
+      "units": "",
+      "category": "Economics",
+      "default": 0.0,
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
+    "Royalty Rate Maximum": {
+      "description": "The maximum royalty rate after escalation, expressed as a fraction (e.g., 0.06 for a 6% cap).",
+      "type": "number",
+      "units": "",
+      "category": "Economics",
+      "default": 1.0,
+      "minimum": 0.0,
+      "maximum": 1.0
+    },
     "Royalty Holder Discount Rate": {
       "description": "The discount rate used to calculate the Net Present Value (NPV) of the royalty holder's income stream. This rate should reflect the royalty holder's specific risk profile and is separate from the main project discount rate.",
       "type": "number",

tests/geophires_x_tests/test_economics_sam.py

@@ -21,6 +21,7 @@
     _ppa_pricing_model,
     _get_fed_and_state_tax_rates,
     SamEconomicsCalculations,
+    _get_royalty_rate_schedule,
 )
 from geophires_x.GeoPHIRESUtils import sig_figs, quantity
 
@@ -662,6 +663,48 @@ def get_row(name: str):
         # Note the above assertion assumes royalties are the only production-based O&M expenses. If this changes,
         # the assertion will need to be updated.
 
+    def test_royalty_rate_schedule(self):
+        royalty_rate = 0.1
+        escalation_rate = 0.01
+        max_rate = royalty_rate + 5 * escalation_rate
+        m: Model = EconomicsSamTestCase._new_model(
+            self._egs_test_file_path(),
+            additional_params={
+                'Royalty Rate': royalty_rate,
+                'Royalty Rate Escalation': escalation_rate,
+                'Royalty Rate Maximum': max_rate,
+            },
+        )
+
+        schedule: list[float] = _get_royalty_rate_schedule(m)
+
+        self.assertListAlmostEqual(
+            [
+                0.1,
+                0.11,
+                0.12,
+                0.13,
+                0.14,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+                0.15,
+            ],
+            schedule,
+            places=3,
+        )
+
     @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:

tests/test_geophires_x.py

@@ -1309,6 +1309,7 @@ def test_redrilling_costs(self):
     def test_royalty_rate(self):
         royalties_output_name = 'Average Annual Royalty Cost'
 
+        zero_royalty_npv = None
         for royalty_rate in [0, 0.1]:
             result = GeophiresXClient().get_geophires_result(
                 ImmutableGeophiresInputParameters(
@@ -1345,6 +1346,9 @@ def test_royalty_rate(self):
                 self.assertEqual(58.88, opex_result[royalties_output_name]['value'])
                 self.assertGreater(royalty_holder_npv_MUSD, 0)
 
+                # Owner NPV is lower when royalty rate is non-zero
+                self.assertGreater(zero_royalty_npv, result.result['ECONOMIC PARAMETERS']['Project NPV']['value'])
+
                 royalties_cash_flow_MUSD = [
                     it * 1e-6
                     for it in _cash_flow_profile_row(
@@ -1362,3 +1366,65 @@ def test_royalty_rate(self):
             if royalty_rate == 0.0:
                 self.assertEqual(0, opex_result[royalties_output_name]['value'])
                 self.assertEqual(0, royalty_holder_npv_MUSD)
+                zero_royalty_npv = result.result['ECONOMIC PARAMETERS']['Project NPV']['value']
+
+    def test_royalty_rate_escalation(self):
+        royalties_output_name = 'Average Annual Royalty Cost'
+
+        base_royalty_rate = 0.05
+        escalation_rate = 0.01
+
+        for max_rate in [0.08, 1.0]:
+            result = GeophiresXClient().get_geophires_result(
+                ImmutableGeophiresInputParameters(
+                    from_file_path=self._get_test_file_path(
+                        'geophires_x_tests/generic-egs-case-2_sam-single-owner-ppa.txt'
+                    ),
+                    params={
+                        'Royalty Rate': base_royalty_rate,
+                        'Royalty Rate Escalation': escalation_rate,
+                        'Royalty Rate Maximum': max_rate,
+                    },
+                )
+            )
+            opex_result = result.result['OPERATING AND MAINTENANCE COSTS (M$/yr)']
+
+            self.assertIsNotNone(opex_result[royalties_output_name])
+            self.assertEqual('MUSD/yr', opex_result[royalties_output_name]['unit'])
+
+            total_opex_MUSD = opex_result['Total operating and maintenance costs']['value']
+
+            opex_line_item_sum = 0
+            for line_item_names in [
+                'Wellfield maintenance costs',
+                'Power plant maintenance costs',
+                'Water costs',
+                royalties_output_name,
+            ]:
+                opex_line_item_sum += opex_result[line_item_names]['value']
+
+            self.assertAlmostEqual(opex_line_item_sum, total_opex_MUSD, places=4)
+
+            project_lifetime_yrs = result.result['ECONOMIC PARAMETERS']['Project lifetime']['value']
+
+            royalties_cash_flow_MUSD = [
+                it * 1e-6
+                for it in _cash_flow_profile_row(
+                    result.result['SAM CASH FLOW PROFILE'], 'O&M production-based expense ($)'
+                )
+            ][1:]
+
+            ppa_revenue_MUSD = [
+                it * 1e-6 for it in _cash_flow_profile_row(result.result['SAM CASH FLOW PROFILE'], 'PPA revenue ($)')
+            ][1:]
+
+            actual_royalty_rate = [None] * len(ppa_revenue_MUSD)
+            for i in range(len(ppa_revenue_MUSD)):
+                actual_royalty_rate[i] = royalties_cash_flow_MUSD[i] / ppa_revenue_MUSD[i]
+
+            max_expected_rate = (
+                max_rate if max_rate < 1.0 else base_royalty_rate + escalation_rate * (project_lifetime_yrs - 1)
+            )
+
+            expected_last_year_revenue = ppa_revenue_MUSD[-1] * max_expected_rate
+            self.assertAlmostEqual(expected_last_year_revenue, royalties_cash_flow_MUSD[-1], places=3)