Runtime availability mask for deferrable loads

[BrainDancer99]

Hi,
would you consider exposing an optional runtime availability mask for deferrable loads?

At the moment, start_timesteps_of_each_deferrable_load and end_timesteps_of_each_deferrable_load only allow one continuous operating window.

A common use case is a temporary lockout in the middle of the planning horizon:

available → unavailable → available

For a 15-minute horizon, the desired availability could look like:

[1, 1, 0, 0, 0, 1, 1, 1]

In my case, this is used for a thermal load. During a user-defined lockout period, the load must not run, but it should still remain visible to the optimizer before and after that period. Otherwise, the later energy demand is missing from battery, PV and grid planning.

From what I can see, much of the required structure already exists: the optimizer uses horizon-length internal window masks to constrain deferrable-load power. It seems that the main missing part is a validated runtime input for supplying such a mask directly.

Would it be possible to expose an optional mask per deferrable load, while keeping the current start/end parameters as the default and fully backward compatible?

The mask could accept only 0/1 values and must match the prediction horizon length. Minimum on/off times near mask boundaries may need some additional validation.

Thanks for considering it.

Best regards
Markus

[LesIT1]

Hey, thanks for raising this. I dug into the optimizer code to check your read on the internals, and you're basically right.

There genuinely is a horizon-length per-timestep mask already: param_window_masks[k] is a CVXPY Parameter sized to the full horizon (one array per deferrable load, defaults to all-ones) and it's what directly caps p_deferrable[k] each timestep, see optimization.py around line 3676 (p_deferrable[k] <= nominal_power * self.param_window_masks[k]) and where it's initialised around line 422. So the mechanism you're describing is real, not something that would need building from scratch.

The gap is exactly what you guessed: the only user-facing input that shapes that mask is the single contiguous [start, end) window derived from start_timesteps_of_each_deferrable_load / end_timesteps_of_each_deferrable_load (see the mask-build loop around optimization.py:4564-4617, and validate_def_timewindow around line 5654). The optimizer does tweak the mask internally after that (more on this below), but there's no code path today that ANDs in an externally-supplied per-timestep array. That part really would need to be added.

A minimal version would look like: an optional new runtime param, list of lists (one sublist per deferrable load, each length == horizon), default None so nothing changes if you don't pass it. Validate/pad it the way check_def_loads already pads other per-load lists, thread it through treat_runtimeparams. There's already a precedent for a per-load per-timestep runtime override in desired_temperatures/heater_desired_temperatures for thermal loads, so this wouldn't be a new pattern for the codebase. Then in the mask-build step, elementwise-multiply the existing start/end-derived mask by the runtime mask before it gets assigned to the parameter. Should be fully backward compatible.

Worth noting this is basically the same ask as #391 from back in Dec 2024 (list of eligible timesteps to allow more than one operating window per day), and David actually responded there already that it's "a nice option... more intuitive... a matter of improving the ease of use of the code." So there seems to be maintainer appetite for this in principle, it's just never landed. Might be worth treating these two threads as the same feature rather than tracking separately.

A couple of things that'd need thought if this gets built, not blockers, just wrinkles:

• The feasibility check that warns when the window is too short to meet operating_hours_of_each_deferrable_load currently compares raw window width, not the actual count of available (1) slots. With holes in the mask, width alone isn't the right check anymore, it'd need to sum the mask instead.
• The min-on/off logic already has an opinion about mask conflicts, and it's "forced-on wins": when a load is mid-run at the start of the horizon, the carryover pin deliberately widens the window mask so the forced-on steps are never blocked. Fed into the same parameter, a lockout could be silently overridden by that pin, so it'd need an explicit decision whether the lockout or the min-on carryover takes priority. Within the horizon it goes the other way, a semi-continuous load just can't schedule a run that spans a masked-off hole at all. Both tie into the boundary validation you flagged.
• The mask cap also applies to sequence loads (the constraint isn't gated by load type), so a lockout hole means a power sequence has to fit entirely on one side of it. Probably the right behaviour, but worth stating.
• Would also want to double check how this interacts with MPC's rolling horizon vs day-ahead's full horizon, since the timestep indices mean different things in each, haven't traced that fully myself.

None of that is a reason not to do it, just scope to be aware of. Whether this gets picked up is David's call obviously, I'm just a contributor here too. Happy to help turn this into a proper issue/spec (maybe consolidating with #391) if there's interest in taking it forward.