SAM-EM: Support all End-Use Options and Absorption Chiller Surface Application [v3.13]

[softwareengineerprogrammer]

Description

1. Implements SAM-EM support for all End-Use Options (Direct-Use Heat, CHP) and Surface Applications/Power Plant Types (AC, HP, DH) NatLabRockies/GEOPHIRES-X#475 except for Heat Pump (HP) and District Heating (DH)
2. Partially addresses SAM-EM Carbon Credits Enhancements NatLabRockies/GEOPHIRES-X#476
3. Partially addresses SAM-EM: Show Add Ons as line items NatLabRockies/GEOPHIRES-X#467

TODO

1. 🚧 SAM SME design review: Deferring until main repo PR due to availability limitations
   1. Documentation:
      1. https://github.com/softwareengineerprogrammer/GEOPHIRES/blob/sam-em-all-end-uses/docs/SAM-EM_End-Uses-and-Surface-Applications.md (note that example links are not live yet)
      2. https://github.com/softwareengineerprogrammer/GEOPHIRES/blob/sam-em-all-end-uses/docs/SAM-Economic-Models.md#end-uses-and-surface-applications
      3. SAM Parameters Mapping entries:
         1. 
         2. 
   2. Cash flow examples:
      1. example_SAM-single-owner-PPA-7_chp_cash-flow_2026-04-12.csv
      2. example_SAM-single-owner-PPA-8_heat_cash-flow_2026-04-12.csv
      3. example_SAM-single-owner-PPA-9_cooling_cash-flow_2026-04-12.csv
   3. Key implementation question: is parameterization for direct-use heat with 0 electricity generation in _get_max_total_generation_kW the appropriate/best approach?

      GEOPHIRES/src/geophires_x/EconomicsSam.py

      Lines 897 to 916 in 47d564a

      	def _get_max_total_generation_kW(model: Model) -> float:
      	max_total_kw = np.max(model.surfaceplant.ElectricityProduced.quantity().to(convertible_unit('kW')).magnitude)
      	if not model.surfaceplant.enduse_option.value.has_electricity_component:
      	# SAM requires a non-zero nameplate capacity, so we must provide a value even if there is no electricity
      	# component. The stub value is both accepted/processed by SAM and results in
      	# zero electricity production/revenue in the cash flow due to rounding.
      	# This logic should be revisited if SAM adds support for combined energy-heat models per
      	# https://github.com/softwareengineerprogrammer/GEOPHIRES/pull/142#pullrequestreview-3999949844
      	non_electricity_end_use_stub_value = 0.0001
      	max_total_kw = max(non_electricity_end_use_stub_value, max_total_kw)
      	if max_total_kw != non_electricity_end_use_stub_value:
      	# Shouldn't happen
      	model.logger.warning(
      	f'Unexpected non-zero maximum total electricity generation for heat end-use option: {max_total_kw} kW. '
      	f'This may be a result of an internal bug in GEOPHIRES or an invalid parameter configuration.'
      	)
      	return max_total_kw

Done

1. Support Direct-Use Heat per FIXME: e47a9c5, 797f00c, 6df5a63, cee4edd
2. LCOH & LCOC SAM cash flow #144
3. Cash flow
   1. Heat provided and Cooling provided values should be blank during pre-revenue years, not 0: 335fff9
   2. Heat price: a1fc61e
   3. Heat price should not be shown for pre-revenue years: 9b39280
   4. Heat produced: a1fc61e
   5. Render price line items as $/ (not USD/): cb3a41d
   6. Electricity to/from grid for heat/cooling end-uses: 2246382
   7. Electricity purchase ($) where applicable (Electricity Rate for cooling, maybe others): 2246382
   8. Fuel expense ($) where applicable: only applies to DH & SUTRA
   9. plus:/equals: delineators to indicate summation to capacity payment revenue line item: a1386a6, 351eb74
   10. Cooling provided should be in kWh, not kWh/yr (eventually/deferred: GWh): a37f5b3
4. Validate CHP options correctness
   1. CAPEX_heat_electricity_plant_ratio must be calculated for all configurations if {Electricity, HEAT} CAPEX ($/kW{e, th}) are to be displayed; including various capex (inc. surface plant) parameterizations: 2ba6f9e
   2. Assess overall correctness/accuracy of CAPEX_heat_electricity_plant_ratio approach - can we get away with just applying the fraction to PV of costs?: 6df3596. A: yes, as long as we document assumptions.
   3. example_SAM-single-owner-PPA-7b_chp-cc - verify LCOE/LCOH correctness...
5. Account for Average Reservoir Pumping Cost with INDUSTRIAL surface application: 13fe524, 9e7c5c0

   1. GEOPHIRES/src/geophires_x/Outputs.py

      Line 605 in 13fe524

      f.write(f' {econ.Coam.display_name}: {(econ.Coam.value + econ.averageannualpumpingcosts.value + econ.averageannualheatpumpelectricitycost.value):10.2f} {econ.Coam.CurrentUnits.value}\n')

6. End Use- & Surface Application-specific case report outputs: 2f203ed, bf21060
   1. LCOH: 2195473
   2. LCOC: 0548958
   3. Total CAPEX ($/kW): 5619b04, 519eaa6
      1. audit applicability (5619b04, 519eaa6)
      2. tooltip text update: N/A
   4. Surface power plant costs for CHP: de4298c
7. Update data center example to be CHP: 57f04d2, 6890082, 6df3596, 7a1dfd5, e7227d5, 20f2e9d
   1. account for $562M AC CAPEX (shifted from AddOn capex): a06d8b6, 6df3596, 7a1dfd5
8. Minor version bump (v3.13.x): 22a777a
   1. CHANGELOG entry: 6e166a8
9. Verify Bottoming & parallel cycles: 709193b
10. Documentation (https://github.com/softwareengineerprogrammer/GEOPHIRES/blob/sam-em-all-end-uses/docs/SAM-EM_End-Uses-and-Surface-Applications.md): 80bd29e, etc.
    1. SAM-EM end-use limitations
       1. Account for absorption chiller, heat pump, dh, etc.: 13fe524
    2. Document/clarify and/or bug fix: Lowering injection temperature for cogen topping cycle increases heat production but does not affect electricity production (current behavior allegedly might be is correct despite being counterintuitive...): e200dd7
    3. example*.txt descriptions: 5bd7fa4, 098a18c, 699edef, 709193b
       1. Reword "yielding an estimated $107 million in annual operating cost savings" - to 'calculated average' or similar: 4acfeab
    4. Decide whether to designate current support as 'beta'/'preview' or similar (in light of incomplete surface application support and relatively limited development/review bandwidth invested at this point in time): will merge into fork and designate relevant examples with [Preview] tag in web interface until main repo PR is reviewed/merged
    5. Electricity to/from grid and electricity purchase for heat/cooling end-uses - line-item removal explanation
    6. CAPEX_heat_electricity_plant_ratio: The pv_costs_year_0 includes OPEX, taxes, and debt service. By applying a CAPEX-derived ratio to this number, you are mathematically forcing the assumption that thermal OPEX scales exactly proportionally to thermal CAPEX. If the electrical power plant has a high O&M burden and the direct-use heat component has a low O&M burden, applying the CAPEX ratio to the total PV will artificially inflate the LCOH and artificially lower the LCOE.
    7. README examples list update: f294752

Optional & Follow-up items

1. Deduplicate calls to calculate_pre_revenue_costs_and_cashflow NatLabRockies/GEOPHIRES-X#452
2. Ignore default Ending {End-Use} Sale Price if not provided NatLabRockies/GEOPHIRES-X#449
3. Remove Injection Temperature parameter for electricity end-use examples
4. clean up EXTRA_{HEAT, ELECTRICITY} redundancy
5. All surface applications (✅AC, HP, DH, etc.)
   1. (maybe/optional) add cooling cogen end-uses equivalent to existing heat options (and switch data center example to cogen cooling)
6. Validate surface application for direct-use heat-only end use (ORC/flash plants are not applicable) NatLabRockies/GEOPHIRES-X#477
7. Cooling provided should eventually probably be in GWh (not kWh)
8. S-DAC capacity payment revenue source S-DAC does not calculate carbon revenue NatLabRockies/GEOPHIRES-X#341
9. SAM-EM: Support all End-Use Options and Absorption Chiller Surface Application [v3.13] #143 (comment)
10. Carbon price should be in USD/tonne, not USD/lb: moved to SAM-EM Carbon Credits Enhancements NatLabRockies/GEOPHIRES-X#476
11. Saved Carbon Production (pound) units honor total saved carbon emissions output unit or similar: moved to SAM-EM Carbon Credits Enhancements NatLabRockies/GEOPHIRES-X#476

Testing & Verification

1. Unit tests added:
   1. example_SAM-single-owner-PPA-7_chp
   2. example_SAM-single-owner-PPA-7b_chp-cc
   3. example_SAM-single-owner-PPA-7c
   4. example_SAM-single-owner-PPA-7d_chp-bottoming
   5. example_SAM-single-owner-PPA-7e_chp-parallel
   6. example_SAM-single-owner-PPA-8_heat
   7. example_SAM-single-owner-PPA-9_cooling
2. Unit tests updated:
   1. test_only_electricity_end_use_supported → test_direct_use_heat_end_use_supported
   2. example_SAM-single-owner-PPA-6_carbon-revenue
   3. example14_data-center
   4. All SAM-EM examples regenerated to add Present value of annual energy costs ($) line item
   5. test_chp_output
   6. test_is_cogeneration_and_has_electricity_component
   7. test_has_quantity_as_units
   8. test_chp_fixed_plant_cost_requires_electrical_plant_cost_allocation_ratio
3. Manual testing:
   1. Self-review
   2. 🚧 Web interface (pending deployment after fork PR merge)
      1. 
      2. 
      3. 
      4. 
      5. 

---

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: 6e166a8 (TODO/deferred to update for main repo PR/final semantic version)

After merging:

1. Push tag(s) to GitHub: git push fork refs/tags/v3.13.0: https://github.com/softwareengineerprogrammer/GEOPHIRES/releases/tag/v3.13.0
2. 🚧 Post a change announcement to the GEOPHIRES Change Announcements Discussion (example). Markdown template:

3.13: [SAM-EM: Support all End-Use Options and Absorption Chiller Surface Application](https://github.com/softwareengineerprogrammer/GEOPHIRES/pull/143) | [release](https://github.com/NREL/GEOPHIRES-X/releases/tag/v3.13.P)

---

Self-reviewed in #143

[softwareengineerprogrammer]

Note this substantial increase to $4.225B is more correctly aligned with reference case study