[johnjasa]

SLC: Heterogeneous-commodity example, dispatch guide, and integration regression

Adds the end-to-end example, documentation, and regression tests for heterogeneous-commodity system-level control (SLC). This is the last PR of the stack and closes out #741.

• Example: examples/35_system_level_control/heterogeneous_commodity/ models wind and solar feeding a generation combiner, a battery, and an electricity splitter that serves both an electrolyzer and a Haber-Bosch loop (with a nitrogen feedstock), all following an ammonia demand through DemandFollowingControl. The runner script plots a week of electricity, hydrogen, ammonia, and battery dispatch and reports the measured upstream requirements (about 10.9 kWh electricity and 0.20 kg hydrogen per kg ammonia).
• Solver settings: the example uses scale_control_variables: true (Add opt-in scale_control_variables solver option for system-level control #957), aggregate conversion ratios with plain Gauss-Seidel (max_iter: 150, rtol: 1e-8), and err_on_non_converge: true. rtol: 1e-10 does not converge within 150 iterations and disabling Aitken stalls, so neither is used.
• Docs: a new executable page, slc_heterogeneous_commodity.md, walks through the dispatch and measured ratios with plots. slc_demand_following.md and system_level_control_base.md link to it and include its convergence results.
• Regression: test_slc_heterogeneous_commodity runs the full 8760-hour example with strict convergence, checks ammonia demand limits and the Haber-Bosch hydrogen balance hourly, pins annual physical and economic anchors (1% tolerance), and re-runs after a technology rename and a connection reorder to confirm hourly set-point profiles match (0.1% tolerance). test_slc_grid_backs_haber_bosch_only covers a grid wired only to Haber-Bosch.

This is part 6 of 6 (#962) in a stack that splits up #844 (topology-aware heterogeneous-commodity SLC dispatch). It depends on all of the earlier PRs. Once the stack has merged, #844 can be closed.

#	Branch	Content
#957	slc_hetero_A	Optional control-variable scaling
#958	slc_hetero_B	Extract SLC marginal-cost helpers
#959	slc_hetero_C	Pure topology and conversion libraries
#960	slc_hetero_D	Bus-aware heterogeneous dispatch
#961	slc_hetero_E	Controller-managed splitters
#962	slc_hetero_F (this PR)	Heterogeneous example, docs, regression tests

Type of Contribution

• Feature Enhancement
  • Other (please describe): New example, documentation, and regression tests
• Documentation Update

General PR Checklist

• PR description thoroughly describes the new feature, bug fix, etc.
• Tests
  • All tests pass locally
  • Added tests for new functionality or bug fixes
  • Modified tests have been outlined in the impacted areas section
• Documentation
  • Docstrings are up-to-date
  • Related docs/ files are up-to-date, or added when necessary
  • Documentation has been rebuilt successfully
  • Examples have been updated (if applicable)
• CHANGELOG.md
  • At least one complete sentence has been provided to describe the changes made in this PR
  • After the above, a hyperlink has been provided to the PR

Related Issues

Resolves #741: commodity-path supplier tracing, converter detection, and aggregated conversion ratios to the demand technology, including the grid-to-ammonia, fuel-cell, and splitter cases listed in the issue (with #959 to #961). Related: #747. Supersedes #816.

Impacted Areas of the Software

New Files

• examples/35_system_level_control/heterogeneous_commodity/
  • heterogeneous_commodity.yaml, plant_config.yaml, tech_config.yaml, driver_config.yaml: wind, solar, battery, combiners, electricity splitter, electrolyzer, Haber-Bosch, nitrogen feedstock, and ammonia demand under DemandFollowingControl.
  • run_heterogeneous.py: runs the example, prints the measured conversion ratios, and plots the dispatch.

Modified Files

• h2integrate/control/control_strategies/system_level/test/test_slc_examples.py
  • Added test_slc_heterogeneous_commodity and test_slc_grid_backs_haber_bosch_only; test_slc_upstream_demand compares the wind set point to rated production with a tight tolerance (rtol=atol=1e-8) instead of exact equality.

Additional Supporting Information

• The hourly profile checks use a 0.1% tolerance and the annual anchors 1% because small floating-point differences remain across iteration paths. The solver's global output-change norm is not treated as an independent physical balance check.
• The example runner is exercised by the integration test; it is not added to test_all_examples.py because the dedicated SLC test already runs the same model.
• Expected values were generated on Windows with Python 3.11; CI on Ubuntu (3.11 and 3.13) will confirm them.

Test Issues

• Full local suite (pytest . -m "unit or regression or integration"): 972 passed, 2 skipped, 2 xfailed, 5 xpassed, and 1 failure, test/test_docs_consistency.py::test_yaml_model_references_are_registered. That test passes when run on its own (3 passed); it fails only in the full run, where an earlier test (windIO, imported by the Ard example) registers a global YAML !include constructor. It is unrelated to this stack.
• test_slc_examples.py and test_docs_consistency.py (all markers): 13 passed.
• Documentation build (docs/build_book.sh, warnings as errors): succeeded.

[tully9000]

After the example is run, I am seeing all of the set points from the SLC have the same value for the whole 8760. Why is this?

Will this always be the case or should the SLC set points change according to wind/solar resource or other time-varying inputs?