Peak load management heuristic control

.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

@@ -53,6 +53,7 @@
 - Modified CI setup so Windows is temporarily disabled and also so unit, regression, and integration tests are run in separate jobs to speed up testing and provide more information on test failures. [PR 668](https://github.com/NatLabRockies/H2Integrate/pull/668)
 - Added infrastructure for running models with non-hourly time steps via a class attribute `_time_step_bounds` and sets new time step bounds of 5-minutes to 1-hour for the grid components. [PR 653](https://github.com/NatLabRockies/H2Integrate/pull/653) and [PR 671](https://github.com/NatLabRockies/H2Integrate/pull/671)
 - Remove demand-related outputs from storage performance models and replace usage with demand components [PR 666](https://github.com/NatLabRockies/H2Integrate/pull/666)
+- Adds `PeakLoadManagementOpenLoopStorageController` as a storage control strategy. [PR 641](https://github.com/NatLabRockies/H2Integrate/pull/641)
 
 ## 0.7.2 [April 9, 2026]
 

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)
-
-
+- [`PeakLoadManagementOpenLoopStorageController`](#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:
 - [`HeuristicLoadFollowingController`](#heuristic-load-following-controller)
+- [`OptimizedDispatchController`](#optimized-load-following-controller)

docs/control/open-loop_controllers.md

@@ -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 converters (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,98 @@ 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 `PeakLoadManagementOpenLoopStorageController` 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.
+
+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_2`** — 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, 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.
+
+![](./figures/example_peak_load_dispatch.png)
+
+For an example of how to use the `PeakLoadManagementOpenLoopStorageController`, see:
+- `examples/33_peak_load_management/`
+
+#### Configuration
+The controller is defined within the `tech_config` and requires the shared storage parameters plus a `control_parameters` block:
+
+**Storage system parameters used by the controller**
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `commodity` | `str` | Commodity name (e.g., `electricity`). |
+| `commodity_rate_units` | `str` | Rate units (e.g., `kW`). |
+| `demand_profile` | scalar or list | Local demand timeseries. |
+| `max_capacity` | `float` | Storage capacity in commodity amount units. |
+| `max_charge_rate` | `float` | Maximum charge rate. |
+| `max_discharge_rate` | `float` | Maximum discharge rate (required if `charge_equals_discharge: false`). |
+| `charge_equals_discharge` | `bool` | If `true`, discharge rate equals `max_charge_rate`. |
+| `max_soc_fraction` | `float` | Upper SOC limit as a fraction (0–1). |
+| `min_soc_fraction` | `float` | Lower SOC limit as a fraction (0–1). |
+| `init_soc_fraction` | `float` | Initial SOC as a fraction (0–1). |
+| `charge_efficiency` | `float` | Charging efficiency (0–1). |
+| `discharge_efficiency` | `float` | Discharging efficiency (0–1). |
+
+**Control-specific parameters**
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `demand_profile_2` | scalar, list, or `null` | Optional supervisory/upstream demand timeseries. |
+| `dispatch_priority_demand_profile` | `str` | Which profile controls scheduling: `demand_profile` or `demand_profile_2`. |
+| `n_override_events` | `int \| null` | Maximum supervisory dispatch events allowed per `override_events_period`. |
+| `override_events_period` | `str \| null` | Pandas period alias for resetting the event counter (e.g., `W` for weekly, `M` for monthly). |
+| `peak_range` | `dict` | Daily window for local peak detection. Keys `start` and `end` as `HH:MM:SS` strings. |
+| `advance_discharge_period` | `dict` | Lead time before a peak to start discharging. Keys `units` (e.g., `h`) and `val`. |
+| `delay_charge_period` | `dict` | Wait after discharge before recharging. Keys `units` and `val`. |
+| `allow_charge_in_peak_range` | `bool` | If `false`, charging is blocked during `peak_range`. |
+| `min_peak_proximity` | `dict` | Minimum separation between retained peak events. Keys `units` and `val`. |
+
+```yaml
+control_strategy:
+  model: PeakLoadManagementOpenLoopStorageController
+model_inputs:
+  shared_parameters:
+    commodity: electricity
+    commodity_rate_units: kW
+    max_charge_rate: 300.0
+    max_capacity: 1200.0
+    max_soc_fraction: 0.9
+    min_soc_fraction: 0.1
+    init_soc_fraction: 0.9
+    demand_profile: !include demand_profile.yaml
+    charge_efficiency: 1.0
+    discharge_efficiency: 1.0
+  control_parameters:
+    max_discharge_rate: 300.0
+    charge_equals_discharge: true
+    demand_profile_2: !include demand_profile_2.yaml
+    dispatch_priority_demand_profile: demand_profile_2
+    n_override_events: 3
+    override_events_period: W
+    peak_range:
+      start: "12:00:00"
+      end: "19:00:00"
+    advance_discharge_period:
+      units: h
+      val: 1
+    delay_charge_period:
+      units: h
+      val: 4
+    allow_charge_in_peak_range: false
+    min_peak_proximity:
+      units: h
+      val: 4
+```

docs/user_guide/model_overview.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
     - `'HeuristicLoadFollowingController'`: open-loop control that works on a time window basis to set dispatch commands; uses Pyomo
+    - `'PeakLoadManagementOpenLoopStorageController'`: open-loop control that reduces peaks rather than trying to meet a load
 - Optimized Dispatch:
     - `'OptimizedDispatchController'`: optimization-based dispatch using Pyomo
 

examples/33_peak_load_management/33_peak_load_management.yaml

@@ -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