Peak load management heuristic control (#641)

* add peak load management control

* add time series generation method as a utility function

* added common compute checks and parameters to baseclass for openloop controllers

Co-authored-by: John Jasa <johnjasa11@gmail.com>
Co-authored-by: kbrunik <102193481+kbrunik@users.noreply.github.com>

Author: 3 people

.pre-commit-config.yaml

@@ -27,7 +27,7 @@ repos:
       - id: yamlfix
         # Exclude YAML files that are used as inputs for testing or examples, or ones for desired schedule in HOPP as they
         # expect misformatted YAML files.
-        exclude: ^(h2integrate/core/test/inputs/.*|examples/11_hybrid_energy_plant/tech_inputs/desired_schedules/.*)$
+        exclude: ^(h2integrate/core/test/inputs/.*|examples/11_hybrid_energy_plant/tech_inputs/desired_schedules/.*|examples/33_peak_load_management/demand_profiles/.*)$
   - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
     rev: v0.8.1

CHANGELOG.md

@@ -5,6 +5,7 @@
 - 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)
 - Added electricity and water consumption profiles as outputs to the `ECOElectrolyzerPerformanceModel` [PR 690](https://github.com/NatLabRockies/H2Integrate/pull/690)
+- Add `PeakLoadManagementHeuristicOpenLoopStorageController` as a storage control strategy. [PR 641](https://github.com/NatLabRockies/H2Integrate/pull/641)
 
 ## 0.8 [April 15, 2026]
 - Updated README and docs intro page with expanded H2I description, reorganized sections, and streamlined installation instructions [PR 677](https://github.com/NatLabRockies/H2Integrate/pull/677)

docs/control/control_overview.md

@@ -9,8 +9,7 @@ The first approach, [open-loop control](#open-loop-control), assumes no feedback
 Supported controllers:
 - [`SimpleStorageOpenLoopController`](#pass-through-controller)
 - [`DemandOpenLoopStorageController`](#demand-open-loop-storage-controller)
-
-
+- [`PeakLoadManagementHeuristicOpenLoopStorageController`](#peak-load-management-open-loop-storage-controller)
 
 (pyomo-control-framework)=
 ## Pyomo control framework
@@ -20,3 +19,4 @@ In the pyomo control framework in H2Integrate, each technology can have control
 
 Supported controllers:
 - [`HeuristicLoadFollowingStorageController`](#heuristic-load-following-controller)
+- [`OptimizedDispatchController`](#optimized-load-following-controller)

docs/control/figures/example_peak_load_dispatch.png

@@ -2,9 +2,10 @@
 # Open-Loop Controllers
 
 ## Open-Loop Storage Controllers
-The open-loop storage controllers can be attached as the control strategy in the `tech_config` for various storage converters (e.g., battery or hydrogen storage). There are two controller types for storage:
-1. Pass-through Controller - passes the commodity flow to the output without any modification
-2. Demand Open-Loop Storage Controller - uses simple logic to attempt to meet demand using the storage technology.
+The open-loop storage controllers can be attached as the control strategy in the `tech_config` for various storage components (e.g., battery or hydrogen storage). There are three controller types for storage:
+1. [Simple Open-Loop Storage Controller](#pass-through-controller) — passes the commodity flow to the output with only minimal or no modifications.
+2. [Demand Open-Loop Storage Controller](#demand-open-loop-storage-controller) — uses simple logic to attempt to meet demand using the storage technology.
+3. [Peak Load Management Open-Loop Storage Controller](#peak-load-management-open-loop-storage-controller) — computes a peak-shaving dispatch schedule to reduce demand peaks, supporting one or two demand profiles with configurable event limits and time windows.
 
 (pass-through-controller)=
 ### Simple Open-Loop Storage Controller
@@ -26,3 +27,33 @@ An example of an N2 diagram for a system using the open-loop control framework f
 For examples of how to use the `DemandOpenLoopStorageController` open-loop control framework, see the following:
 - `examples/14_wind_hydrogen_dispatch/`
 - `examples/19_simple_dispatch/`
+
+(peak-load-management-open-loop-storage-controller)=
+### Peak Load Management Open-Loop Storage Controller
+The `PeakLoadManagementHeuristicOpenLoopStorageController` computes and executes a peak-shaving dispatch schedule assuming perfect forecasting. It is designed for reducing peak loads, not meeting a specific demand, using either one or two loads for determining peaks.
+
+```{note}
+The algorithm currently only supports daily cycles, but could be adjusted to accommodate alternate cycle rates.
+```
+
+The controller supports two demand profiles:
+
+- **`demand_profile`** — the local or sub-system demand. Peaks within a configurable daily time window (`peak_range`) are identified as candidate discharge targets.
+- **`demand_profile_upstream`** — an optional upstream or supervisory demand. When provided, an operator can override the local peak schedule up to a configurable number of events per period (e.g., three times per week). Peaks are determined as the highest n peaks in each period.
+
+The `dispatch_priority_demand_profile` parameter selects which profile acts as the override schedule. On days where the priority profile flags a peak (up to n override instances in the given time period), the controller follows that schedule; on all other days it falls back to the other profile.
+
+**Dispatch logic (state machine)**
+
+1. **Discharge** — begins `advance_discharge_period` before the next scheduled peak and runs until `min_soc_fraction` is reached.
+2. **Charge** — resumes after `delay_charge_period` has elapsed since the end of discharge, subject to the `allow_charge_in_peak_range` flag which can block recharging during the peak windows.
+3. **Idle** — all other timesteps; set-point is zero.
+
+An example output for the first week of a one-year simulation is shown below. Orange shading marks the 12:00–19:00 daily peak window. The top panel shows both demand profiles; the second panel shows battery state of charge; the third shows battery charge/discharge power; the fourth shows the resulting net demand. Periods where `demand_profile_upstream` takes precedence are marked with vertical dashed lines (three occurrences in the week shown). Note that where `demand_profile_upstream` does not override, the peaks in `demand_profile` are reduced.
+
+![](./figures/example_peak_load_dispatch.png)
+
+For an example of how to use the `PeakLoadManagementHeuristicOpenLoopStorageController`, see:
+- `examples/33_peak_load_management/`
+
+For API details, see the [`PeakLoadManagementHeuristicOpenLoopStorageController` API documentation](../_autosummary/h2integrate.control.control_strategies.storage.plm_openloop_storage_controller).

docs/control/open-loop_controllers.md

@@ -285,6 +285,7 @@ Below summarizes the available performance, cost, and financial models for each
     - `'SimpleStorageOpenLoopController'`: open-loop control; manages resource flow based on demand and input commodity
     - `'DemandOpenLoopStorageController'`: open-loop control; manages resource flow based on demand and storage constraints
     - `'HeuristicLoadFollowingStorageController'`: open-loop control that works on a time window basis to set dispatch commands; uses Pyomo
+    - `'PeakLoadManagementHeuristicOpenLoopStorageController'`: open-loop control that reduces peaks rather than trying to meet a load
 - Optimized Dispatch:
     - `'OptimizedDispatchStorageController'`: optimization-based dispatch using Pyomo
 

docs/user_guide/model_overview.md

@@ -0,0 +1,5 @@
+name: H2Integrate_config
+system_summary: Peak load management dispatch
+driver_config: driver_config.yaml
+technology_config: tech_config.yaml
+plant_config: plant_config.yaml