Royalty Rate Schedule & Royalty Supplemental Payments

[softwareengineerprogrammer]

Description

1. Implements Custom royalty schedules NatLabRockies/GEOPHIRES-X#466 via Royalty Rate Schedule parameter
2. Adds Royalty Supplemental Payments parameter to support lease/rental/etc. payments

Cashflow CSV example: https://gist.github.com/softwareengineerprogrammer/1365612f73d745312bdb672f8371c81e

TODO

1. 🚧 Support Royalty Supplemental Payments
   1. During Construction in EconomicsSamPreRevenue.py: b7adc72
      1. Cash flow line item: Royalty supplemental payments [construction] ($)
      2. Include construction years supplementary payments in capital costs results: b590d1f
   2. 🚧 During Operations: 898f8df, 898f8df
      1. Cash flow line item: Deferred to new tracking issue: SAM-EM OPEX Line Items NatLabRockies/GEOPHIRES-X#469
      2. 🚧 Include in result OPEX: 898f8df
         1. Average Annual Royalty Cost (excludes supplementary payments during construction years): a258dea
   3. 🚧 Update Royalty Holder economics outputs
      1. Include supplementary payments during construction years in royalty holder NPV, average revenue, and total revenue: a258dea
      2. Add output(s) for Royalty Supplemental Payments (total revenue, maybe others)
   4. Negative value - decide on support and add approprite unit test
2. 🚧 Validate mutually exclusive royalties params (schedule vs. rate-based): 0cc9a55 (Potential follow-up: maybe rate escalation could be applied to terminal schedule value in the future...)
3. Consolidate '*' param read matching logic
4. Unit test that extracts rate-based royalties from cash flow, re-runs as schedule, and verifies results are identical: https://github.com/softwareengineerprogrammer/GEOPHIRES/pull/139/changes#diff-894b10b737d88bd3c08bc3eaf69146781055586f575a582c09b5911feb891b38R1078-R1116
5. Add unit test for Royalty Supplemental Payments without production-based royalties: 17f29bb
6. Documentation updates
   1. tooltip texts - clarification of production-based vs. supplemental royalty payments (some marked TODO in diff)
      1. Royalty Rate Schedule & Royalty Supplemental Payments #139 (comment)
      2. e133b0b
      3. <other TODOs marked in diff>
   2. SAM Economic Models Royalties documentation (https://softwareengineerprogrammer.github.io/GEOPHIRES/SAM-Economic-Models.html#royalties)
7. 🚧 Web interface support
8. 🚧 SAM SME design review

Testing & Verification

1. Unit tests added:
   1. test_expand_schedule
   2. test_royalty_supplemental_payments
   3. example_SAM-single-owner-PPA-4b
2. Unit tests updated:
   1. test_royalty_rate_schedule
3. Manual testing: Describe any additional manual testing steps that were performed, such as running the change on a pre-existing data set you own.

---

Change Checklist:

Observe the following checklist items if your change includes a new version (see versioning notes and version management docs).

Before merging:

1. Add a CHANGELOG entry (example). RST Template:

M.m.P: `TITLE <https://github.com/NREL/GEOPHIRES-X/pull/PR-NUMBER>`__ | `release <https://github.com/NREL/GEOPHIRES-X/releases/tag/vM.m.P>`__

After merging:

1. Push tag(s) to GitHub: git push origin refs/tags/vM.m.P
2. Post a change announcement to the GEOPHIRES Change Announcements Discussion (example). Markdown template:

M.m.p: [TITLE](https://github.com/NREL/GEOPHIRES-X/pull/PR-NUMBER) | [release](https://github.com/NREL/GEOPHIRES-X/releases/tag/vM.m.P)

---

Self-reviewed in #139

[softwareengineerprogrammer]

Might incidentally (partially) resolve outstanding issue re: arbitrary string bools

[softwareengineerprogrammer]

TODO check that tooltip text reflects period this is calculated for (construction +Ops)