WIP: Heterogeneous-Commodity System-Level Control (Static and Measured Conversion Ratios)

[johnjasa]

Heterogeneous-Commodity System-Level Control (Static and Measured Conversion Ratios)

This PR teaches the system-level control (SLC) framework to handle heterogeneous commodity systems, where the demand is for one commodity (for example ammonia) but the technologies that ultimately satisfy it produce and consume other commodities upstream (for example electricity into hydrogen into ammonia). The controller now translates demand for the demand commodity into set-points for each upstream technology by walking backward across converters using per-technology conversion ratios. Ratios are measured from each converter's consumed and produced streams when available and fall back to static ratios defined in the tech config.

Summary of changes:

1. Add backward demand propagation to SystemLevelControlBase so demand for one commodity is translated into derived demand for upstream input commodities.
2. Detect converters robustly from the technology graph, including converter chains such as electricity to hydrogen to ammonia.
3. Prefer measured conversion ratios computed from each converter's {commodity}_consumed and produced streams per timestep, falling back to a static ratio from the tech config, and emit a one-time warning only when neither a measurement nor a static ratio is available.
4. Register and connect the converters' {commodity}_consumed outputs to the controller so measured ratios are available during dispatch.
5. Refactor the three concrete controllers onto a shared per-commodity dispatch path with strategy-specific dispatchable hooks.

Section 1: Type of Contribution

• Feature Enhancement
  • Framework
  • New Model
  • Updated Model
  • Tools/Utilities
  • Other (please describe):
• Bug Fix
• Documentation Update
• CI Changes
• Other (please describe):

Section 2: Draft PR Checklist

• Open draft PR
• Describe the feature that will be added
• Fill out TODO list steps
• Describe requested feedback from reviewers on draft PR
• Complete Section 8: New Model Checklist (if applicable)

TODO:

• Add converter detection and backward demand propagation to the base class
• Read static conversion ratios from the tech config
• Compute measured conversion ratios from converter consumed and produced streams
• Register and connect converter {commodity}_consumed outputs to the controller
• Keep propagation opt-in with a one-time warning when no ratio is available
• Refactor the three controllers onto the shared dispatch path
• Add unit tests for propagation, chaining, mixed sources, measured ratios, and fallbacks
• Update CHANGELOG

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback:
Confirm the static-ratio location in the tech config
(technologies.<tech>.model_inputs.control_parameters.conversion_ratios.<in>_per_<out>)
is the right home for these values.

Implementation feedback:
Confirm that the opt-in, warn-and-skip fallback for missing ratios is the desired
backward-compatibility behavior versus a hard error.

Section 3: General PR Checklist

• PR description thoroughly describes the new feature, bug fix, etc.
• Added tests for new functionality or bug fixes
• Tests pass (If not, and this is expected, please elaborate in the Section 6: Test Results)
• 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 using the following format:
    "A complete thought. PR XYZ", where
    XYZ should be replaced with the actual number.

Section 4: Related Issues

Section 5: Impacted Areas of the Software

Section 5.1: New Files

Section 5.2: Modified Files

Section 6: Additional Supporting Information

Backward propagation is opt-in. A converter whose input commodity has no controller-managed producer (for example a feedstock-supplied stream) is skipped without a ratio. A converter whose input commodity does have controllable producers but no configured ratio is also skipped, leaving upstream techs at their default dispatch (the legacy behavior), and emits a one-time warning so the missing ratio is discoverable. This keeps existing single-commodity and electricity-to-hydrogen examples unchanged.

Ratios are interpreted so that input_rate = output_rate * ratio in each commodity's rate units (for example a 51 electricity-per-hydrogen ratio translates a hydrogen production rate in kg/h into an electricity demand in kW). When a converter's {commodity}_consumed output is connected, the controller measures the ratio per timestep as consumed over produced, guards the divide where production is zero, and falls back to the static or nominal ratio there. This captures nonlinear and time-varying efficiencies without requiring a hand-tuned static ratio.

Section 7: Test Results, if applicable

Section 8 (Optional): New Model Checklist

N/A