Feat: scheduler support for device groups

[Ahmad-Wahid]

This PR extends the Commitment model and device scheduler to support grouped devices within a single commitment. This work is the basis for quite the list of follow-up features:

• grouping devices by commodity: Add multi‑commodity support to device scheduler #1946
• grouping devices by a shared storage: Feat: Support shared storage (multi‑feed stock) #2001
• grouping devices by a shared power group:
  • Intermediate Power Constraint #1418
  • [FlexMeasures/Scheduler] Investigate Missing Parent-Child Physical Constraint Propagation #2092
  • [StorageScheduler] Support aggregate-power schedule output at multiple topology levels #2038

Why

Until now, a commitment could apply to:

• a single device, or
• the entire EMS.

This was insufficient for real‑world setups such as:

• multiple producers feeding a shared thermal buffer,
• several devices jointly constrained by a single stock target,
• aggregated soft limits that should be penalized once per group, not per device.

What changed

• Commitments now support custom device groups, allowing a single

• FlowCommitment or StockCommitment to aggregate over multiple devices.

• The scheduler aggregates flows or stocks per device group and applies deviation penalties once per group per timestep.

• Commitments may reference:

  • a single device,
  • multiple devices (via list‑valued device entries),
  • or multiple disjoint groups within the same commitment.

• New Pyomo sets (cg, cjg) and constraints enforce grouped commitment
  equalities consistently for both flow and stock commitments.

• Cost reporting correctly aggregates costs per logical commitment instead of
  duplicating them per device.

Result

This enables correct modelling of shared buffers and feeder‑level soft
constraints without artificial cost inflation or duplicated baselines.

How to test

1️⃣ Run the new unit tests

pytest -k test_multi_feed_device_scheduler_shared_buffer
pytest -k test_device_group_shared_buffer

These tests verify:

• two devices jointly satisfy a single stock target,
• deviation costs are applied once per group, not per device,
• gas and electricity commitments are costed separately and consistently.

2️⃣ Sanity‑check behaviour (what to look for)

• Only one commitment group exists for the shared thermal buffer
• Battery remains in its own independent group
• Total commitment costs do not scale with number of devices
• Electricity and gas costs match expected values

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #32423445 | 📁 Comparing a9174a5 against latest (5d0d44f)

  🔍 Preview build  

4 files changed

± changelog.html
± genindex.html
± _autosummary/flexmeasures.data.models.planning.html
± api/v3_0.html

[Flix6x]

Great draft! Let's start collecting todos in the PR description. We can decide what is in scope and what is out. One idea would be to split it up by feature:

Feature: multi-commodity

• spec how we would encode the commodity per device in the flex-model
• extend flex-model schema, limiting the commodity field to electricity and gas
• exclude gas-fired devices from all current EMS commitments
• add gas-price field to flex-context
• set up gas commitment using gas-powered devices and gas-price
• extend scheduling.rst
• extend tutorial

Feature: beyond electricity and gas

• add commodity field to commitment schema
• document how to set up other commodities

Feature: multi-feed stocks

• spec how we would encode the shared storage per device in the flex-model
• extend flex-model schema
• extend scheduling.rst
• extend tutorial

Feature: multi-feed flows

• spec how we would encode the shared capacity per device in the flex-model
• extend flex-model schema
• extend scheduling.rst
• extend tutorial

---

Alternatively, we do one PR first to create support for all 3 features in the device_scheduler only, and touch the StorageScheduler just enough so we can safely experiment with the first two features in simulation. Then, once we're experienced we tackle the flex-model schema, and split up the documentation work for the 3 features.

NB for the schema speccing, we already have some results from a previous session regarding feature 3, in terms of defining a grid topology. I believe the design that came out of that should also fit the other two features, so we end up with a similar UX for what would at first glance appear to be three very different features.

[Flix6x]

This is the one thing I'm still unsure about. The total costs stayed the same, which is good, but the distribution between EV and battery shifted in the battery's favour. I don't have an explanation for it. I do know that there is currently no tie-breaking rule that would favour one over the other, which makes me willing to accept this.

[Flix6x]

This will likely become problematic once we need to model a device that belongs to both a shared power constraint and a shared storage, but let's deal with it once the problem actually presents itself.