NatLabRockies · johnjasa · Jun 15, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- **Controller signal naming overhaul**: Standardized controller input/output names across the codebase. SLC outputs are now `{tech}_{commodity}_set_point` (was `{tech}_{commodity}_demand`); technology-level controllers take `{commodity}_set_point` as input and emit `{commodity}_command_value` as output (was `{commodity}_demand`/`{commodity}_set_point`). Storage performance models in feedback mode receive `{commodity}_set_point`; in open-loop mode they receive `{commodity}_command_value`. The SLC's own input (`{commodity}_demand`) and demand component I/O remain unchanged.
 - Change commodity in DRI and EAF model from pig iron to sponge iron based on likely carbon content [PR 670](https://github.com/NatLabRockies/H2Integrate/pull/670)
 - Bugfix for round-trip efficiency handling when calling `check_inputs` around `StoragePerformanceModel` [PR 684](https://github.com/NatLabRockies/H2Integrate/pull/684)
 - Bugfix. Include nuclear in electricity producing tech list and improve error message for zero-length electricity producing techs in model when electricity is specified as the commodity. [PR 685](https://github.com/NatLabRockies/H2Integrate/pull/685)

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -70,10 +70,20 @@ parts:
           - file: resource/tidal_resource
   - caption: Control
     chapters:
-      - file: control/control_overview
-      - file: control/open-loop_controllers
-      - file: control/pyomo_controllers
-      - file: control/controller_demonstrations
+      - file: control/system_level_control/system_level_control
+        sections:
+          - file: control/system_level_control/system_level_control_base
+          - file: control/system_level_control/control_classifier
+          - file: control/system_level_control/controllers
+            sections:
+              - file: control/system_level_control/slc_demand_following
+              - file: control/system_level_control/slc_profit_max
+              - file: control/system_level_control/slc_cost_min
+      - file: control/technology_level_control/technology_control_overview
+        sections:
+          - file: control/technology_level_control/open-loop_controllers
+          - file: control/technology_level_control/pyomo_controllers
+          - file: control/technology_level_control/controller_demonstrations
   - caption: Demand
     chapters:
       - file: demand/demand_components

diff --git a/docs/control/system_level_control/control_classifier.md b/docs/control/system_level_control/control_classifier.md
@@ -0,0 +1,82 @@
+# System Level Control Technology Performance Classifiers
+
+To enable a generic system level control framework we need to classify each technology based on how the model that is included in H2I can operate within the system.
+
+```{note}
+While in real life there are a lot of controllable parameters allowing for ramping production up or down for a particular technology (e.g., wind or solar curtailment), the model of that technology in H2I might not be capable of the same response behavior to input signals.
+These classifications are for specific H2I dispatch formulations and are based on how the models in H2I are implemented, **not always** on how the actual physical subsystem might operate.
+This is a useful and necessary distinction that delineates different model capabilities clearly.
+```
+
+We have identified five key classifiers that are able to represent the different behaviors that we can expect from the models. Each performance model includes a parameter setting the classifier `_control_classifier`.
+
+Classifier | Meaning | Example Technology Models
+-- | -- | --
+fixed | Always produces commodity and cannot be controlled or reduced; does not receive a set-point | classical nuclear
+flexible | Resource-driven; can only be *reduced* (curtailed) below the resource-determined maximum via a set-point | wind, solar
+dispatchable | Can modulate production within bounds in response to a set-point | grid, electrolyzer, NG turbine
+storage | Can modulate consumption/production within bounds while tracking SOC | battery, h2 storage, any storage
+feedstock | Are not directly controlled, but useful for SLC to make dispatch decisions | feedstocks
+
+To add a classifier for a particular model it would look something like this in the class:
+```{python}
+_control_classifier = "flexible"
+```
+
+```{note}
+**Flexible vs. dispatchable.** Both classifiers receive a `{commodity}_set_point` from the system-level controller, so the distinction is about *what the set-point can do*. A flexible model is a strictly more restricted case of a dispatchable one: the set-point can only *cap* the output below whatever the underlying resource (sun, wind, etc.) makes available. A dispatchable model, by contrast, can be ramped up or down anywhere within its operating bounds in direct response to the set-point.
+```
+
+## Fixed
+A fixed performance model represents anything that always produces at its rated capacity and cannot be controlled or reduced by the system level controller. The SLC reads the output from a fixed technology and subtracts it from the demand, but does not send a set-point back to the technology. A good example of this is a classical nuclear plant model: it produces a constant output that the rest of the system must accommodate.
+
+## Flexible
+A flexible performance model represents anything whose production is determined by an external resource (e.g., wind speed, solar irradiance) and that can only be *reduced* below that resource-determined maximum and never increased above it. The system-level controller sends a `{commodity}_set_point` that acts as an upper bound: when the resource-driven output exceeds the set-point, output is curtailed down to the set-point; otherwise, output is left at the resource-driven value. A good example is the PVWatts PySAM solar plant in H2I; its performance is a function of the input solar resource, and we cannot tell the sun to shine more, but we can curtail the panel output below the available solar production.
+
+In other words, flexible is a strictly more restricted case of [dispatchable](#dispatchable): a dispatchable model can be ramped both up and down in response to a set-point, while a flexible model can only be ramped down.
+
+To simplify the implementation of applying this curtailment we added a method, `apply_curtailment()`, to the `PerformanceBaseClass`.
+
+```{figure} figures/curtailable.png
+:width: 70%
+:align: center
+```
+
+### Apply curtailment based on set_point
+Within the `compute()` method in the performance model you can apply the curtailment using the `apply_curtailment()` method.
+```
+self.apply_curtailment(outputs)
+```
+which applies curtailment to `{commodity}_out` based on `{commodity}_set_point`. This adds `uncurtailed_{commodity}_out` and `{commodity}_out` as outputs from the performance model.
+
+(dispatchable)=
+## Dispatchable
+A dispatchable performance model represents anything that can be ramped both *up and down* within its operating bounds in response to a `{commodity}_set_point` from the system-level controller. Unlike a [flexible](#flexible) model, the set-point for a dispatchable model can request any production level within the model's rated capacity (and minimum load, if applicable), and the model will produce at that level. Examples include a grid connection, an electrolyzer, or a natural-gas turbine.
+
+There aren't additional special methods to handle this because the set-point response is internal to each performance model.
+
+```{figure} figures/dispatchable.png
+:width: 70%
+:align: center
+```
+
+## Storage
+Storage is a unique control classifier because it assumes that within the model that energy isn't created or destroyed (minus some efficiency losses). While it's technically "dispatchable" in that it can receive and change its performance based on a set point, its handling within H2I is unique because it's attached to storage performance models, which is handled differently than converter performance models. A converter model only has positive (or zero) `{commodity}_out`, whereas a storage model can have positive or negative `{commodity}_out`.
+
+There are two types of cases for the storage control classifier:
+1. **with a storage controller**
+When the storage performance model is controlled with a storage-level controller (open-loop or feedback controlled), the system-level controller outputs combined demand, that is always positive to the storage-level controller. The demand is `{commodity}_in` from the technologies upstream of the storage that output the same commodity to the storage performance model and the `remaining_demand`.
+
+2. **without a storage controller**
+The system-level controller outputs set points to the storage performance model which can be considered charge (negative) and discharge (positive) commands (storage-level set points) to the storage performance model, directly.
+
+
+```{figure} figures/storage.png
+:width: 85%
+:align: center
+```
+
+## Feedstock
+Feedstocks represent commodity *inputs* to the controllable system: they are consumed by other technologies but their availability is not itself something the controller can adjust. Although feedstocks themselves cannot be dispatched, knowing how much of each feedstock is available is valuable information for more advanced controllers, since feedstock supply can constrain what the controllable technologies are actually able to produce.
+
+For example, consider an ammonia plant that consumes both hydrogen and nitrogen. If the nitrogen feedstock supply is insufficient to meet the ammonia demand, the ammonia output is capped by the nitrogen availability regardless of how much hydrogen and electricity are produced. A controller that is aware of the nitrogen feedstock can recognize that the ammonia demand cannot be met, and can adjust the set-points for the hydrogen and electricity technologies accordingly (e.g., avoiding over-production of hydrogen that would otherwise go unused). This is why feedstocks are classified separately rather than being ignored by the controller: they are uncontrollable, but they are not irrelevant.
diff --git a/docs/control/system_level_control/controllers.md b/docs/control/system_level_control/controllers.md
@@ -0,0 +1,15 @@
+# Control Strategies
+There are several simple control strategies already implemented in the SLC paradigm. While fairly simplistic, they are meant to illustrate how information can be passed from different blocks/components (converters, storage, feedstocks, demand, etc.) and models (performance, cost, finance) to use within the SLC.
+
+The current control strategies are:
+1. [Demand Following](#slc-demand-following)
+2. [Profit Maximization](#slc-profit-max)
+3. [Cost Minimization](#slc-cost-min)
+
+```{note}
+The strategies currently implemented are experimental and will likely require further development for specific analyses.
+```
+
+All control strategies inherit `SystemLevelControlBase`, which is a base class that has common setup logic shared by all system-level control strategies.
+
+See additional information, which is more developer focused, about the [`SystemLevelControlBase`](#slc-base).
diff --git a/docs/control/system_level_control/figures/dispatchable.png b/docs/control/system_level_control/figures/dispatchable.png
diff --git a/docs/control/system_level_control/figures/flexible.png b/docs/control/system_level_control/figures/flexible.png
diff --git a/docs/control/system_level_control/figures/slc_basic.png b/docs/control/system_level_control/figures/slc_basic.png
diff --git a/docs/control/system_level_control/figures/storage.png b/docs/control/system_level_control/figures/storage.png
diff --git a/docs/control/system_level_control/slc_cost_min.md b/docs/control/system_level_control/slc_cost_min.md
@@ -0,0 +1,67 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+kernelspec:
+  display_name: Python 3.11.13 ('h2i_env')
+  language: python
+  name: python3
+---
+
+(slc-cost-min)=
+# Cost Minimization System Level Controller
+
+The cost minimization controller, `CostMinimizationControl`, meets demand at minimum variable cost using merit-order dispatch.
+Unlike the {ref}`demand following controller <slc-demand-following>`, which splits demand evenly across dispatchable technologies, this controller dispatches the cheapest technologies first.
+
+## Dispatch Logic
+
+The controller follows a three-step dispatch process:
+
+1. **Flexible technologies** run at their available capacity (assumed zero marginal cost). Their output is subtracted from the demand.
+2. **Storage technologies** absorb any surplus (charging) or provide the deficit (discharging). Residual demand is split evenly across storage technologies producing the demanded commodity.
+3. **Dispatchable technologies** are dispatched by cheapest marginal cost first, each up to its rated capacity, until the remaining demand is met.
+
+## Marginal Cost Configuration
+
+Marginal costs are specified per dispatchable technology in the `cost_per_tech` dictionary under `system_level_control.control_parameters` in the plant config. Each entry can be:
+
+| Value | Description |
+| --- | --- |
+| Numeric (e.g. `0.05`) | Constant marginal cost in `$/(commodity_amount_units)` |
+| `"buy_price"` | Uses the technology's configured purchase price |
+| `"VarOpEx"` | Derives marginal cost from the technology's variable operating expenditure divided by total production |
+| `"feedstock"` | Sums upstream feedstock `VarOpEx` values and divides by the technology's total production |
+
+```{note}
+The dispatch order is determined by sorting dispatchable technologies by their **mean** marginal cost across all timesteps (cheapest first).
+```
+
+### Example Configuration
+
+```yaml
+system_level_control:
+  control_strategy: CostMinimizationControl
+  control_parameters:
+    cost_per_tech:
+      natural_gas_plant: feedstock
+```
+
+## Inputs and Outputs
+
+In addition to the standard inputs inherited from `SystemLevelControlBase`, the cost minimization controller adds marginal cost inputs based on the `cost_per_tech` configuration (see above).
+
+The base inputs for technologies classified as `flexible`, `dispatchable`, and `storage` are:
+
+- `f"{tech_name}_{tech_output_commodity}_out"`
+- `f"{tech_name}_rated_{tech_output_commodity}_production"`
+- `f"{tech_name}_{tech_output_commodity}_demand"`
+
+## Limitations
+
+- Greedy dispatch: The merit-order approach is greedy - it does not look ahead across timesteps to optimize total cost over the simulation horizon.
+- Even splitting across storage: Residual demand is split evenly across storage technologies regardless of capacity or state of charge.
+- Demand is always met: Unlike the {ref}`profit maximization controller <slc-profit-max>`, this controller always attempts to meet demand regardless of cost.
diff --git a/docs/control/system_level_control/slc_demand_following.md b/docs/control/system_level_control/slc_demand_following.md
@@ -0,0 +1,102 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.18.1
+kernelspec:
+  display_name: Python 3.11.13 ('h2i_env')
+  language: python
+  name: python3
+---
+
+(slc-demand-following)=
+# Demand Following System Level Controller
+
+The demand following controller, `DemandFollowingControl`, aims to fully meet the demand and does not have any inputs related to cost.
+
+The N2 diagram below shows an example system using the demand following controller with wind, natural gas, and battery storage technologies.
+
+```{code-cell} ipython3
+:tags: [remove-input]
+
+from h2integrate.core.h2integrate_model import H2IntegrateModel
+import openmdao.api as om
+import os
+
+import html
+from pathlib import Path
+from h2integrate import EXAMPLE_DIR
+from IPython.display import HTML, display
+
+os.chdir(EXAMPLE_DIR / "35_system_level_control/battery_with_controller/")
+
+h2i_model = H2IntegrateModel("wind_ng_demand.yaml")
+h2i_model.setup()
+
+om.n2(
+    h2i_model.prob,
+    outfile="h2i_n2.html",
+    display_in_notebook=False,
+    show_browser=False,
+)
+
+n2_html = "h2i_n2.html"
+n2_srcdoc = html.escape(Path(n2_html).read_text(encoding="utf-8"))
+display(
+    HTML(
+        f'<div style="width:100%; height:600px; overflow:auto; margin:0; padding:0; border:0;">'
+        f'<iframe srcdoc="{n2_srcdoc}" '
+        'style="display:block; width:200%; height:600px; border:0; margin:0; padding:0; background:transparent;" '
+        'loading="lazy"></iframe>'
+        '</div>'
+    )
+)
+```
+## Dispatch Logic
+
+The demand is satisfied in a fixed three-step priority order, and each step's shortfall or surplus is passed to the next:
+
+1. **Curtailable techs** run at their available capacity. Their total output is subtracted from the demand, which may drive the residual demand negative (surplus).
+
+2. **Storage techs** receive the residual demand (which may be positive or negative). When residual demand is positive the storage is commanded to discharge; when negative it is commanded to charge. If multiple storage techs produce the demanded commodity, the residual demand is
+split **evenly** across them (each receives ``demand / n_storage``).
+
+3. **Dispatchable techs** cover any remaining positive demand after storage. The remaining demand (floored at zero) is split **evenly** across all dispatchable techs that produce the demanded commodity (each receives ``remaining_demand / n_dispatchable``).
+
+### Example Configuration
+
+```yaml
+system_level_control:
+  control_strategy: DemandFollowingControl
+  solver_options: # solver options for resolving feedback
+    solver_name: gauss_seidel
+    max_iter: 20
+    convergence_tolerance: 1.0e-6
+```
+
+## Inputs and Outputs
+
+The inputs for technologies classified as `curtailable`, `dispatchable`, and `storage` are:
+
+- `f"{tech_name}_{tech_output_commodity}_out"`
+- `f"{tech_name}_rated_{tech_output_commodity}_production"`
+- `f"{tech_name}_{tech_output_commodity}_demand"`
+
+The inputs for technologies classified as `feedstock` are:
+- `f"{tech_name}_{commodity}_out"`
+
+## Systems with Heterogeneous Commodities
+
+The `DemandFollowingControl` controller can be used in hybrid systems where technologies produce different commodities.
+For example, in a system where an electrolyzer produces hydrogen and the demand commodity is hydrogen, the controller can set the electricity-generating *curtailable* technologies' set-points to meet the hydrogen demand.
+
+This framework provides a starting point for hybrid energy system control but is intended to be extended with more sophisticated strategies for complex multi-commodity systems.
+
+## Limitations
+
+- No cost awareness: The controller dispatches technologies purely to meet demand without considering operational costs, commodity prices, or economic optimization.
+- Even splitting across storage: When multiple storage technologies produce the demanded commodity, the residual demand is divided evenly among them (`demand / n_storage`), regardless of differences in capacity, state of charge, or efficiency.
+- Even splitting across dispatchable technologies: Similarly, any remaining demand after storage dispatch is split evenly across all dispatchable technologies (`remaining_demand / n_dispatchable`), without accounting for marginal costs or capacity constraints.
+- Fixed priority order: The dispatch order (curtailable → storage → dispatchable) is fixed in the current implementation.