System level control framework

.github/workflows/ci.yml

@@ -1,5 +1,10 @@
 name: Testing
 on:
+  push:
+    branches:
+      - main
+      - develop
+      - system_level_control
   pull_request:
     branches:
       - main

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

docs/control/system_level_control/control_classifier.md

@@ -0,0 +1,69 @@
+# 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., turbine yaw). The particular model in H2I might not be capable of simulating a modulated response based on an input signal.
+These classifications are for how the models in H2I are implemented, **not** 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 | Produces based on resource; can only reduce (curtail) | wind, solar
+dispatchable | Can modulate consumption/production within bounds; receives a commodity 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 know about 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"
+```
+
+## 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 that can have the output reduced based on a given set point from the system level controller. A good example of this is the PVWatts PySAM solar plant in H2I, the performance of the system is based on the input solar resource. The solar performance does not change based on, for example, an updated set point to the tracking software, but we could limit the power output from the solar performance model based on a given demand set point. To simplify the implementation of applying this curtailment or reduction based on a set point 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`. There is then `uncurtailed_{commodity}_out` and `{commodity}_out` as outputs from the performance model.
+
+## Dispatchable
+A dispatchable performance model represents anything that can receive a set point. Any model that has the "dispatchable" control classifier tag is able to receive a set point and change it's behavior based on that set point. There aren't additional special methods to handle this because it's 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 it's 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
+Another category of control classifiers are feedstocks. The unique thing about feedstocks is that they are considered outside of the controllable system within H2I. While they can't be controlled it can be helpful for controllers to know how much feedstock is available within the system, hence their classification.

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).

docs/control/system_level_control/slc_cost_min.md

@@ -0,0 +1,72 @@
+---
+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. **Curtailable technologies** run at their full rated 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_unit*h)` |
+| `"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 `curtailable`, `dispatchable`, and `storage` are:
+
+- `f"{tech_name}_{tech_output_commodity}_out"`
+- `f"{tech_name}_rated_{tech_output_commodity}_production"`
+
+The outputs for `curtailable`, `dispatchable`, or `storage` technologies *without* a storage controller are:
+- `f"{tech_name}_{tech_output_commodity}_set_point"`
+
+The outputs for `storage` technologies *with* a storage controller are:
+- `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.

docs/control/system_level_control/slc_demand_following.md

@@ -0,0 +1,108 @@
+---
+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 full rated 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 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"`
+
+The inputs for technologies classified as `feedstock` are:
+- `f"{tech_name}_{commodity}_out"`
+
+
+The outputs for technologies classified as `curtailable`, `dispatchable`, or `storage` and *without a storage controller* are:
+- `f"{tech_name}_{tech_output_commodity}_set_point"`
+
+The outputs for technologies classified as `storage` that *have a storage controller* are:
+- `f"{tech_name}_{tech_output_commodity}_demand"`
+
+## 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.