Confine device power to operation-mode power bands

[Flix6x]

Description

Adds support for devices whose power is not free to modulate within [0, P_max], but is confined to a set of power bands — e.g. a device that is either off or running at (or above) some minimum power. Fixes #2113.

Following the S2 standard's FRBC OperationMode terminology, the storage flex-model gains an operation-modes field: a list of power ranges, each declared with an explicit sign convention (consumption-range and/or production-range, both non-negative). The device must operate within one of the declared ranges at every time step:

"operation-modes": [
    {"consumption-range": ["0 W", "0 W"]},
    {"consumption-range": ["883.7 W", "883.7 W"]}
]

In the device_scheduler, this adds one binary variable per device per band per time step (exactly one band active; device power bounded by the active band's range), turning the LP into a MILP when the field is used. Without the field, the model is unchanged.

Motivation / validation

When a control layer (e.g. an S2 CEM/RM pair) receives a fractional schedule for an on/off device, it has to round it — typically up — which can overshoot site capacity limits. In a two-house community co-simulation with on/off heaters, a community-level capacity breach could not be resolved because the scheduler kept planning fractional heater power that was implemented as full-on blocks. With this field, the schedule only contains implementable power values; in that same co-simulation the breach was fully resolved (community peak landed exactly on the inflexible-load floor), with no observed solver slowdown (~10s solves, HiGHS, 96 time steps).

Runtime impact (LP vs MILP)

Benchmarked device_scheduler directly (HiGHS via appsi_highs, wall time incl. model build): a synthetic battery-like device doing price arbitrage at 15-min resolution (±1 MW, ±2 MWh, sinusoidal day/night prices, one price commitment per device).

Scenario	T=96 (1 day)	T=192 (2 days)	T=672 (1 week)
LP baseline (no bands)	0.45 s	0.71 s	2.15 s
MILP, 2 bands (off / [0.4, 1] MW)	0.41 s	1.02 s	2.74 s
MILP, 3 bands (± bands and off)	0.56 s	1.08 s	3.08 s
MILP, 5 bands	1.77 s	1.11 s	3.38 s

Multiple banded devices scale roughly linearly here (T=96, 3 bands: 3 devices 1.14 s, 5 devices 1.56 s).

So on these instances the binaries cost ~1.3–2× the LP solve time (worst observed: ~4×), not orders of magnitude. Two structural reasons:

• The formulation (sum(b) = 1, with power bounded by Σ b·min ≤ p ≤ Σ b·max) is the tight disjunctive formulation: its LP relaxation equals the convex hull of the band union per time step, so the root relaxation is strong. A big-M formulation would be strictly weaker.
• The binaries don't couple across time steps except indirectly through the stock recursion.

Adversarial instances (near-flat prices creating many equally good band choices, tight SoC targets interacting with band gaps, several banded devices competing for site capacity) can branch harder than this. Practical levers, should that occur:

• Convexity preprocessing (possible follow-up): binaries are only necessary when the band union has gaps; bands that merge into one contiguous interval could be collapsed into plain derivative min/max bounds, skipping the MILP entirely.
• Solver options: FLEXMEASURES_LP_SOLVER_OPTIONS can pass mip_rel_gap (0.1–1% is usually invisible in schedule quality) and time_limit to HiGHS.

Scope

• New OperationModeSchema + operation-modes field in the storage flex-model schema (documented via the metadata module, so it shows up in the docs table and OpenAPI specs).
• device_power_bands argument on device_scheduler, wired through StorageScheduler._prepare/compute.
• Docs: field documented in the storage flex-model table (with S2 reference) + changelog entry.
• Tests: flexmeasures/data/models/planning/tests/test_operation_modes.py (on/off band, min-power band, and a no-bands sanity check).

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33766970 | 📁 Comparing ec684ff against latest (922ecf6)

  🔍 Preview build  

75 files changed · + 7 added · ± 68 modified

+ Added

• _autodoc/GROUP.html
• _autodoc/OPERATION_MODES.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.soc_projection.html
• _autosummary/flexmeasures.data.schemas.scheduling.utils.html
• host/multi-tenancy.html
• tut/toy-example-group-constraints.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/COMMITMENTS.html
• _autodoc/SOC_MAXIMA.html
• _autodoc/SOC_MINIMA.html
• and 58 more...

[Flix6x]

Addressed:

• Sign-explicit ranges: replaced the single signed power-range with consumption-range (positive = consumption) and/or production-range (positive = production). A mode may use either or both; combining both (each starting at 0) forms one band through zero [-production_max, +consumption_max]. Documented that the S2 signed power-range maps to the FM consumption-range. Added schema tests for the mapping + validation; OpenAPI regenerated.
• Changelog: applied your suggested wording (now references PR Confine device power to operation-mode power bands #2278).

The unit-commitment work stays out of this PR (separate branches). I will reconcile the branches stacked on this one — #2327 (running-cost) and the operation-modes UC route — to the new key names.

[Copilot]

Pull request overview

This PR adds support for constraining device power to discrete “operation modes” (power bands) in the storage flex-model, wiring the new field through scheduling so the device scheduler can enforce banded operation (MILP when used), along with documentation, OpenAPI updates, and regression tests.

Changes:

• Add operation-modes to the storage flex-model schema (with validation and metadata/docs exposure).
• Wire operation-modes through StorageScheduler into device_scheduler via a new device_power_bands argument and corresponding MILP constraints.
• Add tests covering LP-level band behavior and end-to-end wiring through StorageScheduler, plus docs/changelog/OpenAPI updates.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
flexmeasures/ui/static/openapi-specs.json	Adds OpenAPI schemas/field docs for OperationMode and operation-modes.
flexmeasures/data/schemas/scheduling/storage.py	Introduces OperationModeSchema and adds operation-modes to StorageFlexModelSchema.
flexmeasures/data/schemas/scheduling/metadata.py	Adds OPERATION_MODES metadata used for generated docs/OpenAPI descriptions.
flexmeasures/data/models/planning/storage.py	Converts operation-modes to signed MW bands and forwards them into device_scheduler.
flexmeasures/data/models/planning/linear_optimization.py	Extends device_scheduler with optional per-device power band constraints (MILP).
flexmeasures/data/models/planning/tests/test_operation_modes.py	New targeted tests for band constraints and schema-to-band mapping.
flexmeasures/data/models/planning/tests/test_solver.py	Integration/regression tests ensuring StorageScheduler wiring enforces/forwards bands.
documentation/features/scheduling.rst	Documents the new operation-modes flex-model field.
documentation/changelog.rst	Adds changelog entry announcing the new operation-modes capability.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

flexmeasures/data/schemas/scheduling/metadata.py:400

• PR description example for operation-modes uses {"power-range": [...]} (signed range), but the implemented/public schema and docs use consumption-range / production-range (and no power-range field). To avoid confusing reviewers/API users, please update the PR description example to match the actual payload shape.

    description="""Confine the device's power to one of several power ranges at every time step.
Each operation mode declares a ``consumption-range`` (non-negative, positive is consumption) and/or a ``production-range`` (non-negative, positive is production); a mode may use either or both, and combining both (each starting at 0) forms a single band through zero.
This is useful for devices that cannot modulate their power freely, such as a device that is either off or running at some minimum power (or at one fixed power).
Terminology and semantics follow the `operation modes of the S2 standard <https://docs.s2standard.org/model-reference/FRBC/FRBC.OperationMode/>`_.
S2 fixes one sign convention for power (positive is consumption), whereas FM leaves it to the user; an S2 signed power-range therefore maps onto these fields by sign: its non-negative part corresponds to the FM ``consumption-range``, negative S2 power values (production) correspond to the FM ``production-range`` (with their sign flipped to non-negative), and an S2 range spanning zero maps to a combination of both.