SAM-EM royalties documentation (parameter mapping + dedicated section)

Author: softwareengineerprogrammer

docs/SAM-Economic-Models.md

@@ -22,7 +22,7 @@ The following table describes how GEOPHIRES parameters are transformed into SAM
 | `Net Electricity Generation`                                                                                                                    | AC Degradation                                         | `Annual AC degradation rate` schedule                                                                        | `Utilityrate5`                    | `degradation`                                                | Percentage difference of each year's `Net Electricity Generation` from `Maximum Total Electricity Generation` is input as SAM as the degradation rate schedule in order to match SAM's generation profile to GEOPHIRES                                                                                                    |
 | {`Total CAPEX` before inflation} × (1 + `Accrued financing during construction (%)`/100);                                                       | Installation Costs                                     | `Total Installed Cost`                                                                                       | `Singleowner`                     | `total_installed_cost`                                       | `Accrued financing during construction (%)` = (1+`Inflation Rate During Construction`) × 100 if `Inflation Rate During Construction` is provided or ((1+`Inflation Rate`) ^ `Construction Years`) × 100 if not.                                                                                                           |
 | `Total O&M Cost`, `Inflation Rate`                                                                                                              | Operating Costs                                        | `Fixed operating cost`, `Escalation rate` set to `Inflation Rate` × -1                                       | `Singleowner`                     | `om_fixed`, `om_fixed_escal`                                 | .. N/A                                                                                                                                                                                                                                                                                                                    |
-| `Royalty Rate`                                                                                                                                  | Operating Costs                                        | `Variable operating cost`                                                                                    | `Singleowner`                     | `om_production`                                              | Royalties are treated as a variable operating cost to the owner                                                                                                                                                                                                                                                           |
+| `Royalty Rate`                                                                                                                                  | Operating Costs                                        | `Variable operating cost`                                                                                    | `Singleowner`                     | `om_production`                                              | The royalty is modeled as a tax-deductible variable operating expense. GEOPHIRES calculates a schedule of $/MWh values based on the PPA price and Royalty Rate for each year. This ensures the total annual expense in SAM accurately matches the royalty payment due on gross revenue.                                   |
 | `Plant Lifetime`                                                                                                                                | Financial Parameters → Analysis Parameters             | `Analysis period`                                                                                            | `CustomGeneration`, `Singleowner` | `CustomGeneration.analysis_period`, `Singleowner.term_tenor` | .. N/A                                                                                                                                                                                                                                                                                                                    |
 | `Inflation Rate`                                                                                                                                | Financial Parameters → Analysis Parameters             | `Inflation rate`                                                                                             | `Utilityrate5`                    | `inflation_rate`                                             | .. N/A                                                                                                                                                                                                                                                                                                                    |
 | `Discount Rate`                                                                                                                                 | Financial Parameters → Analysis Parameters             | `Real discount rate`                                                                                         | `Singleowner`                     | `real_discount_rate`                                         | .. N/A                                                                                                                                                                                                                                                                                                                    |
@@ -150,6 +150,27 @@ Total AddOn Profit Gained per year is treated as fixed amount Capacity payment r
 Add-ons CAPEX, OPEX, and profit are supported.
 Add-ons with electricity and heat are not currently supported, but may be supported in the future.
 
+## Royalties
+
+SAM Economic Models can model a royalty agreement where a percentage of the project's gross revenue is paid to a third party (the "royalty holder"). This feature is enabled by providing the `Royalty Rate` parameter.
+
+The royalty payment is modeled as a tax-deductible variable operating expense from the perspective of the project developer (Single Owner).
+This reduces the developer's taxable income and ensures their final after-tax metrics (NPV, IRR, etc.) are calculated accurately.
+
+This is implemented by having GEOPHIRES create a year-by-year schedule for SAM's Variable operating cost (`om_production`) input.
+The value for each year is calculated based on that year's PPA price and the user-provided `Royalty Rate`, ensuring the expense in SAM matches the royalty due on gross revenue.
+
+Input Parameters:
+
+1. `Royalty Rate`: The percentage of the project's gross annual revenue paid to the royalty holder.
+1. `Royalty Holder Discount Rate` (optional): The discount rate used to calculate the Net Present Value (NPV) of the royalty holder's income stream. This is separate from the project's main discount rate to reflect the different risk profiles of the two parties.
+
+Output Parameters:
+
+1. `Average Annual Royalty Cost`: The developer's average annual royalty expense over the project's lifetime after construction is complete (Year 1). The same value is also output as `Royalty Holder Average Annual Revenue`. The individual royalties for each year are included in the cash flow line item `O&M production-based expense ($)`.
+1. `Royalty Holder Total Revenue`: The total undiscounted royalty income over the project's lifetime.
+1. `Royalty Holder NPV`: The Net Present Value of the royalty holder's income stream, calculated using the `Royalty Holder Discount Rate`.
+
 ## Examples
 
 ### SAM Single Owner PPA: 50 MWe