Royalty escalation rate + max (WIP to add unit tests, implement full schedule support)

Author: softwareengineerprogrammer

src/geophires_x/Economics.py

@@ -975,11 +975,34 @@ 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 Escalation Rate',
+            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(
+            'Maximum Royalty Rate',
+            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)."
+        )
+
         self.royalty_holder_discount_rate = self.ParameterDict[self.royalty_holder_discount_rate.Name] = floatParameter(
             'Royalty Holder Discount Rate',
             DefaultValue=0.05,

src/geophires_x/EconomicsSam.py

@@ -417,20 +417,19 @@ 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
+        variable_om_schedule_per_mwh = [
+            (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'.
-        ret['om_production'] = variable_om_schedule_per_MWh
+        ret['om_production'] = variable_om_schedule_per_mwh
 
     # Debt/equity ratio ('Fraction of Investment in Bonds' parameter)
     ret['debt_percent'] = _pct(econ.FIB)
@@ -481,5 +480,26 @@ def _ppa_pricing_model(
     )
 
 
+def _get_royalty_rate_schedule(model: Model) -> list[float]:
+    """
+    Builds a year-by-year schedule of royalty rates based on escalation and cap.
+    Returns a list of rates as fractions (e.g., 0.05 for 5%).
+    """
+
+    econ = model.economics
+    plant_lifetime = model.surfaceplant.plant_lifetime.value
+
+    escalation_rate = econ.royalty_escalation_rate.value
+    max_rate = econ.maximum_royalty_rate.value
+
+    schedule = []
+    current_rate = econ.royalty_rate.value
+    for _ in range(plant_lifetime):
+        schedule.append(min(current_rate, max_rate))
+        current_rate += escalation_rate
+
+    return schedule
+
+
 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 Escalation Rate": {
+      "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
+    },
+    "Maximum Royalty Rate": {
+      "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",