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.

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)

I am primarily looking for high-level structural and implementation feedback at this point
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

path/to/file.extension
- method1: What and why something was changed in one sentence or less.

Section 4.2: Modified Files

path/to/file.extension
- method1: What and why something was changed in one sentence or less.

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!

h2integrate/control/control_strategies/storage/openloop_storage_control_base.py

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

h2integrate/core/utilities.py

+    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

elenya-grant · 2026-04-02T16:37:32Z

h2integrate/core/utilities.py

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


if the plant config is loaded using load_plant_yaml(), then the start time should always be included. Aka - I don't think we should have default values in both the modeling schema and this function. But - I'm happy to see a function like this get in!

examples/32_multivariable_streams/driver_config.yaml

elenya-grant · 2026-04-02T16:39:34Z

examples/33_peak_load_management/plant_config.yaml

@@ -0,0 +1,11 @@
+name: plant_config
+description: Demonstrates multivariable streams with a gas combiner


update description in plant config

elenya-grant · 2026-04-02T16:40:33Z

examples/33_peak_load_management/tech_config.yaml

+        commodity: electricity
+        commodity_rate_units: kW
+        max_charge_rate: 2500.0  # kW/time step, 1, 2.5, or 5 MW
+        max_capacity: 10000.0  # kWh, 80 MWh


comment for max_capacity is wrong, should say 10 MWh

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+        max_supervisor_events: (int | None, optional): The maximum number of discharge events
+            allowed for the supervisor in the period specified in max_supervisor_event_period,
+            or across all time steps if max_supervisor_event_period is None.
+


could you add in the other attributes to the doc string? Like peak_range, advance_discharge_period, delay_charge_period, allow_charge_in_peak_range, and min_peak_proximity?

elenya-grant · 2026-04-02T16:49:33Z

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+        },
+    )
+
+    def __attrs_post_init__(self):


should the dictionary inputs be checked I the __attrs_post_init__ method to check that they have the right keys?

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+
+        self.get_allowed_discharge()
+
+    @staticmethod


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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+        # 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?

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+
+        This method applies an open-loop storage control strategy to balance the
+        commodity demand and input flow. When input exceeds demand, excess commodity
+        is used to charge storage (subject to rate, efficiency, and SOC limits). When


The description of this compute method makes it seem really similar to the DemandOpenLoopStorageController and the HeuristicLoadFollowingControl - could you update the doctoring to explain the peak-shaving novelty of this?

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+    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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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


Never used.

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+
+        # 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.

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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


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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+            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

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

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

h2integrate/control/control_strategies/storage/plm_openloop_storage_controller.py

+                # 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.

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

johnjasa added 2 commits April 6, 2026 11:25

Merge branch 'develop' into peakload

0aa1ee2

Merge branch 'develop' into peakload

767eab2

		@@ -0,0 +1,11 @@
		name: plant_config
		description: Demonstrates multivariable streams with a gas combiner


		self.max_discharge_rate = self.max_charge_rate

		# make sure peak_range is in correct format because yaml

Conversation

jaredthomas68 commented Mar 31, 2026

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!

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!

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!

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!

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!

vijay092 Apr 2, 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!

Reviewers

Assignees

Labels

vijay092 Apr 2, 2026 •

edited

Loading