Peak load management heuristic control by jaredthomas68 · Pull Request #641 · NatLabRockies/H2Integrate

jaredthomas68 · 2026-03-31T19:30:44Z

Peak load management heuristic control

This PR adds Peak load management heuristic control to H2I. This does not do demand dispatch, but rather dispatches based on peaks in the provided load and rules defined by the user.

It also adds a time series generation utility that can be called directly with time step, simulation length, etc or with a plant_config dict.

Section 1: Type of Contribution

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 7: New Model Checklist (if applicable)

TODO:

Step 1
Step 2

Type of Reviewer Feedback Requested (on Draft PR)

This PR is ready for full detailed review.

Structural feedback:

Implementation feedback:

Other feedback:

Section 3: General PR Checklist

Section 3: Related Issues

Section 4: Impacted Areas of the Software

Section 4.1: New Files

examples/33_peak_load_management/: example to demonstrate peak load controller
h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py: new control for peak load management
h2integrate/control/control_strategies/storage/test/data/lmp_month_1.csv testing input file
h2integrate/control/control_strategies/storage/test/data/lmp_peaks_month_1.csv testing input file
h2integrate/control/control_strategies/storage/test/test_plm_openloop_storage_controller.py: tests for peak load management control

Section 4.2: Modified Files

docs/control/control_overview.md: include mention of peak load control
docs/control/open-loop_controllers.md: add detailed description for peak load control
h2integrate/control/control_strategies/storage/demand_openloop_storage_controller.py: move some shared code to base class
h2integrate/control/control_strategies/storage/openloop_storage_control_base.py: include optional parameters and post-attr actions for some child classes
h2integrate/core/inputs/plant_schema.yaml: add default time zone`:
h2integrate/core/test/test_utilities.py: tests for time series utility function
h2integrate/core/utilities.py: add time series generation utility function

Section 5: Additional Supporting Information

Section 6: Test Results, if applicable

Section 7 (Optional): New Model Checklist

elenya-grant

just left some initial comments/questions - haven't done a deep dive yet (so some of my questions/comments may be silly or I'll be able to answer during a deep-dive) but plan to do a deeper review by Thursday morning. I only looked at the changes and additions to the control classes but will review the tests in the second review I do.

Overall looks like a great start - most of my comments were small or were questions!

elenya-grant · 2026-03-31T19:52:43Z

+        # determine demand_profile peaks using defaults of daily peaks inside peak_range
+        # for the full simulation but respecting the peak range specified in the config
+        self.secondary_peaks_df = self.get_peaks(
+            demand_profile=self.condig.demand_profile,


should this be inputs[f"{self.config.commodity}_demand"] instead of the demand from the config?

Some of the reasoning for this is in my comment here: #641 (comment). I guess I can split up demand and time stamp as separate inputs so we can use the input like the other controllers.

I have split up demand and date_time

elenya-grant

Howdy! I gave this more of a deeper look! I think I'm a little confused on how this method works (I didn't try to understand it super hard yet) - so most of my comments were nitpicks or questions. My only blocking comment is about the error being removed from load_plant_yaml - I don't think that error message should be removed at this time.

I think a visual (or two) may be nice to explain some of the inputs to the controller - I think if a doc page with some visuals and explanation on the inputs would be super helpful in making it easier for users to understand how to change the control input parameters based on their use-case.

elenya-grant · 2026-04-02T16:36:12Z

+    dt_seconds = int(simulation_cfg["dt"])
+
+    # Optional start_time in config; default to a fixed reference timestamp.
+    start_time = simulation_cfg.get("start_time", "2000-01-01 00:00:00")


the start-time format in the plant config is defined as being: mm/dd/yyyy HH:MM:SS or mm/dd HH:MM:SS and defaults to 01/01 00:30:00 (doesn't include a year because it was initially going to be used with resource data and the year may change based on the resource year). The format here does not match - do you think we could make sure that the format is consistent mm/dd/yyyy instead of yyyy-mm-dd?

I made a similar function when I was starting on the resource models (it never made it in) but it handles whether a year was added or not:

from datetime import datetime, timezone, timedelta def make_time_profile( start_time: str, dt: float | int, n_timesteps: int, time_zone: int | float, start_year: int | None = None, ): """Generate a time-series profile for a given start time, time step interval, and number of timesteps, with a timezone signature. Args: start_time (str): simulation start time formatted as 'mm/dd/yyyy HH:MM:SS' or 'mm/dd HH:MM:SS' dt (float | int): time step interval in seconds. n_timesteps (int): number of timesteps in a simulation. time_zone (int | float): timezone offset from UTC in hours. start_year (int | None, optional): year to use for start-time. if start-time is formatted as 'mm/dd/yyyy HH:MM:SS' then will overwrite original year. If None, the year will default to 1900 if start-time is formatted as 'mm/dd HH:MM:SS'. Defaults to None. Returns: list[datetime]: list of datetime objects that represents the time profile """ tz_utc_offset = timedelta(hours=time_zone) tz = timezone(offset=tz_utc_offset) tz_str = str(tz).replace("UTC", "").replace(":", "") if tz_str == "": tz_str = "+0000" # timezone formatted as ±HHMM[SS[.ffffff]] start_time_w_tz = f"{start_time} ({tz_str})" if len(start_time.split("/")) == 3: if start_year is not None: start_time_month_day_year, start_time_time = start_time.split(" ") start_time_month_day = "/".join(i for i in start_time_month_day_year.split("/")[:-1]) start_time_w_tz = f"{start_time_month_day}/{start_year} {start_time_time} ({tz_str})" t = datetime.strptime(start_time_w_tz, "%m/%d/%Y %H:%M:%S (%z)") elif len(start_time.split("/")) == 2: if start_year is not None: start_time_month_day, start_time_time = start_time.split(" ") start_time_w_tz = f"{start_time_month_day}/{start_year} {start_time_time} ({tz_str})" t = datetime.strptime(start_time_w_tz, "%m/%d/%Y %H:%M:%S (%z)") else: # NOTE: year will default to 1900 t = datetime.strptime(start_time_w_tz, "%m/%d %H:%M:%S (%z)") time_profile = [None] * n_timesteps time_step = timedelta(seconds=dt) for i in range(n_timesteps): time_profile[i] = t t += time_step return time_profile

Thanks for the extended function. I personally much prefer the international format "yyyy-mm-dd", but I understand their being an existing approach. I went ahead and changed the function to handle timezone and added a function to make the time series with direct inputs rather than a config. I do not have much use for the second value of a timestamp, but I did adjust to return python datetime format. We can continue to discuss exact desired format, but I would prefer to make the timeseries in a standard date-time format and allow users and developers to adjust to lists of integers or whatever other format they need from there.

elenya-grant · 2026-04-02T16:52:28Z

+
+        self.get_allowed_discharge()
+
+    @staticmethod


why is this a staticemethod rather than just a normal method? (same with _normalize_peak_range?)

These are static methods because they need to be called with different attributes of the class rather than the exact same attributes in order each time. This also means the output does not have a consistent target.

elenya-grant · 2026-04-02T16:53:12Z

+        # Dispatch strategy outline:
+        # - Discharge: Starting when time_to_peak <= advance_discharge_period
+        #   * Discharge at max rate (or less to reach targets)
+        #   * Stop discharging only when SOC reaches min_soc


could these inline comments get moved closer to where that logic is represented in the code?

I moved them to the docstring as I think that makes more sense.

vijay092 · 2026-04-02T20:59:31Z

Very exciting work @jaredthomas68! Thanks for putting this together in such a short time! I did a full pass through h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py and left comments wherever I spotted small issues. Feel free to address them as you see fit.

vijay092 · 2026-04-02T18:06:57Z

+    dispatch_priority_demand_profile: str = field(
+        validator=contains(["demand_profile", "demand_profile_supervisor"]),
+    )
+    max_supervisor_events: int | None = (field(default=None),)


Is this supposed to be a tuple?

Nope, thanks for the catch. Fixed

vijay092 · 2026-04-02T18:08:58Z

+    charge_efficiency: float | None = field(default=None, validator=range_val_or_none(0, 1))
+    discharge_efficiency: float | None = field(default=None, validator=range_val_or_none(0, 1))
+    round_trip_efficiency: float | None = field(default=None, validator=range_val_or_none(0, 1))
+    demand_profile_supervisor: int | float | list | None = field()


default = None

I intentionally left off the default because I want the user to be very aware of how they are using this controller and if they are excluding a supervisory demand profile or not.

vijay092 · 2026-04-02T18:22:09Z

+
+            self.max_discharge_rate = self.max_charge_rate
+
+        # make sure peak_range is in correct format because yaml


Same problem for advance_discharge_period, right?

No, advance_discharge_period uses a unit, val paradigm instead of time stamps.

vijay092 · 2026-04-02T18:32:59Z

+            )
+
+        # Store simulation parameters for later use
+        self.dt = self.options["plant_config"]["plant"]["simulation"]["dt"]


Never used.

Thanks. Removed

vijay092 · 2026-04-02T18:35:56Z

+
+        # Store simulation parameters for later use
+        self.dt = self.options["plant_config"]["plant"]["simulation"]["dt"]
+        self.time_index = build_time_series_from_plant_config(self.options["plant_config"])


I think it is worth adding a length check against self.n_timesteps somewhere.

I don't think so. The time series builds on the same config that self.n_timesteps comes from, so they should be the same by default.

I went ahead and added a check just in case. Won't hurt.

Sounds good. There are a few time-tracking variables in the code. Just wanted to make sure they all correspond to the same index and length. Still getting used to the framework, so apologies if that caused additional work.

vijay092 · 2026-04-02T19:03:58Z

+                day_df = supervisory_peaks_df[
+                    supervisory_peaks_df["date_time"].dt.floor("D") == day
+                ]
+                # If supervisor has peaks on the day, use supervisor's flags for all rows that day


Good to add check for when supervisor is None.

Supervisor should never be none in this function because the first argument is always treated as the most important peaks. I changed the naming and doc string to make this more clear.

I also added the check you suggested

vijay092 · 2026-04-02T19:39:05Z

+                    next_peak_time - self.peaks_df.loc[idx, "date_time"]
+                )
+
+    def get_allowed_discharge(self):


Method name is misleading. It actually computes "allow_charge"?

Great point. I've changed the name.

vijay092 · 2026-04-02T20:05:55Z

+            soc_array[i] = deepcopy(soc)
+
+            # stay in discharge mode until the battery is fully discharged
+            if soc <= soc_min:


Note for future:
discharging is only set to False when soc <= soc_min. If the battery doesn't fully drain during the event duration, discharging will continue to stay True

That is by design. The intended operation is to fully charge and then fully discharge, not try to meet a demand, so the battery should fully discharge. If you have suggestions for catching corner cases on this I'm all ears.

I think this should be documented in the docpage on the peak load management, I would have expected the battery to stop discharging once the event is over.

The event period is pretty loose. We find the exact peak, but discharge leading up to and after that peak. I will include more in a docs page.

vijay092 · 2026-04-02T20:15:29Z

+            # start discharging when we approach a peak and have some charge
+            if time_to_peak <= advance_discharge_period and soc > soc_min:
+                discharging = True
+


Suggest adding charging = False here in case charging hasn't been set to False in the previous timestep.

vijay092 · 2026-04-02T20:36:01Z

+                # Note: discharge_needed is internal (storage view), max_discharge_rate is external
+                discharge_needed = max_discharge_rate / discharge_eff
+                discharge = min(
+                    discharge_needed, available_discharge, max_discharge_rate / discharge_eff


The first and third terms are the same.

Yes, I was trying to lean into code reuse and hoping I could find a good way, but I went ahead and removed the duplicate.

elenya-grant

Mostly just small questions and comments! Really awesome tests! Love to see the thorough testing!

elenya-grant · 2026-04-16T15:49:29Z

 - `examples/19_simple_dispatch/`
+
+(peak-load-management-open-loop-storage-controller)=
+### Peak Load Management Open-Loop Storage Controller


this is very detailed documentation! Since this section is so detailed - should this be moved to a separate file that's linked in this file? Non-blocking, just a thought!

I think it is getting close, but not enough to warrant a separate file. I'm open for discussion, but am leaving as is unless I hear more desire for the additional file.

elenya-grant · 2026-04-16T15:51:16Z

+    start_time: 2025/07/01 00:00:00
+technology_interconnections:
+  # - [battery, grid_buy, [storage_electricity_charge, electricity_out]]
+  - [battery, electrical_load_demand, [electricity_out, electricity_in]]


could you add comments here? like "subtract battery power from the load demand" and "buy power from the grid to fulfill remaining demand"?

elenya-grant · 2026-04-16T15:52:37Z

+        charge_equals_discharge: true  # enforce symmetric charge and discharge power limits
+        max_discharge_rate: 300.0  # kW/time step; defaults to battery power limit when matched to max_charge_rate
+        demand_profile: !include demand_profiles/demand_profile.yaml
+      control_parameters:


thanks for the comments here! they're helpful!

elenya-grant · 2026-04-16T15:56:48Z

+                    "model": "SimpleStorageOpenLoopController",
+                },
+                "performance_model": {
+                    "model": "StorageAutoSizingModel",


replace StorageAutoSizingModel with StoragePerformanceModel?

elenya-grant · 2026-04-16T15:58:34Z

lots of awesome unit tests! Thanks for the comprehensive testing here!

elenya-grant · 2026-04-16T17:00:11Z

+            raise ValueError(
+                "max_discharge_rate must be provided when charge_equals_discharge is False."
+            )
+


I think these changes to the baseclass make sense given that another component is using them - but why not just have the PLM controller inherit the demand open-loop controller and make modifications to the demand open-loop controller? I guess I'm curious about the reasoning for all the changes to the base-class that are mostly relevant to the demand open-loop controller (not asking for changes - just wanting to understand)

After a discussion with John, Gen, and others (in dev meeting I think) we decided to take this approach to avoid duplicate code while also limiting inheritance depth. Also see comments here..

elenya-grant · 2026-04-16T17:10:43Z

          timezone:
            type: number
            description: timezone as UTC offset corresponding to start_time
+            default: 0


love this change - thank you!

kbrunik

This is super cool! Thank you for putting so much effort into this dispatch strategy!! I'm really excited to get this into H2I. Just a few small things I'd like to work through before bringing it in

kbrunik · 2026-04-20T12:40:43Z

+1. Peak load management dispatch open loop control with two demand profiles of interest
+2. Battery charging without an input stream, assuming purchase from the grid
+
+In this example, two load profiles are provided. It is assumed that demand_profile is a


I appreciate all of the text included here! It really helps to have good explanation about what's happening in the examples

kbrunik · 2026-04-20T12:44:02Z

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


This isn't rendering in the docs.

I checked in the CI tests and I see the figure render just fine. Let me know if you still can't see it.

kbrunik · 2026-04-20T13:14:19Z

+
+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)**


After reading all of the docstrings, I think it could be helpful to expand this a bit more based on all of the methods getting employed to calculate this. I appreciate the simplicity of Discharge, Charge and Idle but maybe after this logic you could include a bit more?

I'm happy to add more, but after reviewing it I'm not sure what else would be helpful at this level. Can you be more specific about what details you would like to see at the high-level docs rather than left in the doc strings?

…c string descriptions. add key validator

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

kbrunik

Thanks for the speedy changes! I think this looks great to come into H2I :)

aditiegarg9

The definitions of the classes look good.

aditiegarg9 · 2026-04-20T19:52:57Z

+
+    Attributes:
+        demand_profile_2 (int | float | list | None, optional): Demand values for
+            additional connected system for each timestep, in the same units as


Is this a local load demand storage will be dispatched if the system load (the priority load) is not peaking? I'm raising this to understand what do we mean by additional connected load.

elenya-grant

Thanks for iterating on this PR so much!

(Honestly, I'm having trouble viewing all the recent changes since this PR has so many commits and comments - but I trust that all my concerns were addressed (or there was a good reason they weren't) (and if not, I'll make an issue).)

Thanks for adding in this functionality and iterating on the PR! Very cool to have a heuristic method for peak shaving! Nicely done!

jaredthomas68 and others added 6 commits March 27, 2026 10:10

begin open loop peak load management control

933ae89

Merge branch 'develop' into peakload

90b82d8

peak finding working as expected

d338cce

peak merging working

e8a2dfb

all elements present

7276db6

Merge branch 'develop' into peakload

226f0a4

elenya-grant self-requested a review March 31, 2026 19:43

jaredthomas68 added 2 commits March 31, 2026 14:10

update comments and doc strings

6fc22a7

Merge remote-tracking branch 'myfork/peakload' into peakload

ecc0abd

elenya-grant reviewed Mar 31, 2026

View reviewed changes

jaredthomas68 requested review from bayc, genevievestarke, johnjasa and kbrunik March 31, 2026 21:22

jaredthomas68 added 9 commits March 31, 2026 16:18

seperate the demand and time series to separate config inputs

db0c72a

regression tests working

d5b4250

move time series method to a utility function

b7b2573

wip: add example

9b021ee

Merge branch 'develop' into peakload

ad97f44

remove debug statements

b4508be

remove defaults and add input of min_proximity

4473244

exclude example 33 demand profile yamls from yamlfix

4b6e25f

example runs

d7774d2

jaredthomas68 requested a review from vijay092 April 2, 2026 16:11

elenya-grant requested changes Apr 2, 2026

View reviewed changes

jaredthomas68 added 3 commits April 2, 2026 11:38

example complete

74fc2ed

remove n_timesteps since it comes from base class

b456d75

remove erroneous changes to example 32

a624bd4

vijay092 reviewed Apr 2, 2026

View reviewed changes

resolve merge conflicts in CHANGELOG.md

8d3d82a

jaredthomas68 marked this pull request as ready for review April 10, 2026 19:26

jaredthomas68 and others added 7 commits April 13, 2026 12:32

resolve merge conflicts

15d178a

Merge branch 'develop' into peakload

983d770

merge from develop

b65478e

update changelog

6cfc269

add test for example 33 and add grid purchase profile to plot

71d9737

merge develop

840304d

update to be compatible with demand components (from PR 666)

2867695

elenya-grant requested changes Apr 16, 2026

View reviewed changes

jaredthomas68 added 2 commits April 16, 2026 12:26

fix merge conflicts

5a81860

Merge branch 'develop' into peakload

01d44c5

johnjasa added the ready for review This PR is ready for input from folks label Apr 17, 2026

kbrunik requested changes Apr 20, 2026

View reviewed changes

kbrunik reviewed Apr 20, 2026

View reviewed changes

Comment thread docs/control/open-loop_controllers.md Outdated

jaredthomas68 and others added 9 commits April 20, 2026 10:14

resolve merge conflicts

7c878cb

add comments. simplify documentation. remove meta data in favor of do…

617f819

…c string descriptions. add key validator

update docs and example to demarcate override peaks

30484e3

update docs

a1bab83

add doc comment

9d7b7a3

move static method to after compute

c0a1561

Update docs/control/open-loop_controllers.md

515557d

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

Merge remote-tracking branch 'myfork/peakload' into peakload

2e2820a

minor update

e103abe

jaredthomas68 requested review from elenya-grant and kbrunik April 20, 2026 18:11

kbrunik approved these changes Apr 20, 2026

View reviewed changes

jaredthomas68 requested a review from aditiegarg9 April 20, 2026 19:13

aditiegarg9 reviewed Apr 20, 2026

View reviewed changes

elenya-grant approved these changes Apr 20, 2026

View reviewed changes


		self.max_discharge_rate = self.max_charge_rate

		# make sure peak_range is in correct format because yaml


		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)


		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)

Conversation

jaredthomas68 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Peak load management heuristic control

Section 1: Type of Contribution

Section 2: Draft PR Checklist

TODO:

Type of Reviewer Feedback Requested (on Draft PR)

Section 3: General PR Checklist

Section 3: Related Issues

Section 4: Impacted Areas of the Software

Section 4.1: New Files

Section 4.2: Modified Files

Section 5: Additional Supporting Information

Section 6: Test Results, if applicable

Section 7 (Optional): New Model Checklist

Uh oh!

elenya-grant left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elenya-grant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vijay092 commented Apr 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaredthomas68 Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaredthomas68 Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaredthomas68 commented Mar 31, 2026 •

edited

Loading

jaredthomas68 Apr 8, 2026 •

edited

Loading

jaredthomas68 Apr 8, 2026 •

edited

Loading

vijay092 Apr 2, 2026 •

edited

Loading