Share storage-efficiency per stock group and index solver stock by group

[Flix6x]

Description

Closes #2324. Originally stacked on #2282; now that #2282 has merged, this PR targets main directly.

Since #2321, a shared stock's SoC parameters live on a single flex-model entry and all group members receive the group's initial stock — but storage-efficiency remained a per-device field, silently allowing members of one stock group to declare different loss rates for the same physical stock. This PR:

• Treats storage-efficiency as a property of the stock: it may be defined on the entry holding the stock's SoC parameters (including stock-only entries, where it was previously ignored) or on exactly one member device, and applies to all members. Conflicting definitions fail fast, mirroring Track devices via a typed device inventory in the StorageScheduler #2321's handling of the other SoC parameters. This resolves the long-standing # todo: move storage-efficiency into a shared parameter… in storage.py.
• Indexes the solver's stock variable and balance recursion by stock group instead of by device (follow-up to Speed up device_scheduler with a recursive stock balance #2282, as suggested in its review): one recursion per shared stock instead of one per member, dropping the redundant secondary stock variables/constraints. device_scheduler validates that grouped devices share their storage efficiency and initial stock, so direct callers get a clear error instead of silently ambiguous semantics.

Bugfix

While wiring this up, a latent key collision surfaced in device_to_group: declared stock groups are keyed by state-of-charge sensor id, while ungrouped devices used their own device index as group key. An ungrouped device whose index equalled a SoC sensor id was silently merged into that stock group, feeding its flows into the wrong stock — test_simulation_with_dynamic_consumption_capacity actually exercised this (the building's raw electricity load was counted as heat inflow into the buffer). Group keys are now namespaced.

How to test

pytest flexmeasures/data/models/planning/tests/test_commitments.py -k storage_efficiency
pytest flexmeasures/data/models/planning/tests/

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33635401 | 📁 Comparing 24756f4 against latest (db31a27)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• changelog.html
• genindex.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.html
• _autosummary/flexmeasures.data.schemas.scheduling.html
• api/v3_0.html
• features/scheduling.html

[Flix6x]

Requirement from the off-tick SoC projection work (#2194): when off-tick SoC constraints auto-enable relax-soc-constraints, we want the softening scoped to the device(s) actually using off-tick constraints — other devices in a multi-device flex-model should keep their hard SoC constraints.

The tricky case is a shared stock: since #2321, its SoC parameters (incl. soc-targets/soc-minima/soc-maxima) live on a single flex-model entry — possibly a stock-only entry without a power sensor — while the constraints are applied (and softened into StockCommitments) on the first device of the stock group. So scoping cannot key on the entry's own power sensor; it needs the mapping entry → stock key → the device that applies the stock's constraints.

Since this PR already treats the stock group as the canonical unit in the solver (group-indexed stock recursion, shared storage-efficiency), it would be good to tackle that mapping here:

1. Expose a canonical stock_key → member devices / stock_key → applying device lookup (e.g. on DeviceInventory), so deserialization-time logic can resolve which device a stock entry's SoC constraints land on.
2. Ideally, go one step further and attach the soft SoC StockCommitments to the stock group rather than to a device index — matching the new group-indexed stock variable — so per-stock scoping (and result mapping) becomes structural instead of positional.

With that in place, #2194's relaxation scoping can track stock keys instead of power sensor ids, which also fixes the case where a member device entry carries the SoC parameters of a stock whose first device is a different entry.

[Flix6x]

Done in 239c6da — both parts:

1. Lookups: DeviceInventory.stock_groups was already the canonical stock_key → member devices map; added DeviceInventory.stock_constraint_device(stock_key) for the device that applies a stock's SoC constraints (the group's first member). Together these give Feat/offtick soc projection #2194 the entry → stock key → applying device resolution at deserialization time.

2. Structural attachment: StockCommitment gains a scalar stock attribute (the stock key), stamped by the StorageScheduler on all soft SoC commitments (soc-minima, soc-maxima, prefer-full-sooner). In the solver, a stock-scoped commitment resolves its device group from the stock key — coupling to the group's stock via the group's first device — so the device index it names no longer matters. A new parametrized test proves the commitment binds the group stock identically whether it names the group's first or second device (the previously broken case you mentioned). With this, Feat/offtick soc projection #2194's relaxation scoping can track stock keys throughout.

Two observations from the trenches, both out of scope here:

• device_stock_commitment_equalities in linear_optimization.py is dead code — it's never registered as a model constraint; all device-level commitments route through grouped_commitment_equalities. Could be removed.
• ems_flow_commitment_equalities returns (None, center, None) bounds, i.e. EMS-level FlowCommitments (no device, no commodity filter) generate no coupling constraint at all, leaving their deviation variables free. The StorageScheduler always sets device/commodity so production paths are unaffected, but direct device_scheduler callers passing an EMS-level FlowCommitment get an unbounded model (I hit this writing the new test). Worth a follow-up issue?

[Flix6x]

Follow-up to my earlier comment, from the #2194 work just pushed: besides the relaxation scoping, #2194 now also records at which time the starting state of charge is actually known (when soc-at-start is resolved from the state-of-charge field), keyed by the device's power sensor id (soc_at_start_datetimes), to project an off-tick starting SoC onto the next scheduling tick.

For a shared stock, that timing is a property of the stock (the measurement pertains to the stock's SoC, resolved on the entry holding the SoC parameters), not of any particular member device. So when this PR introduces the canonical stock_key → devices mapping, both trackers from #2194 should move to stock keys in the same sweep:

• off_tick_soc_sensor_ids (scoping of auto-enabled SoC relaxation), and
• soc_at_start_datetimes (off-tick starting-SoC projection).

Both currently key on the power sensor id and rely on "the first device of the stock group applies the stock's constraints", which is exactly the positional convention this PR is in a good place to replace.

[Flix6x]

All three follow-ups handled:

• Dead code removed in 2655c84 (device_stock_commitment_equalities).
• ems_flow_commitment_equalities: not addressed by any open scheduler PR (perf: precompute constraint arrays for device_scheduler callbacks #2291, Add FLEXMEASURES_LP_SOLVER_OPTIONS to configure solver options #2283 checked), so opened EMS-level FlowCommitments generate no coupling constraint in device_scheduler #2326.
• Tracker rekey: implemented on Feat/offtick soc projection #2194's branch (1a0b144), since both trackers live there — see my comment on Feat/offtick soc projection #2194 for details. Nothing further was needed on this PR's side: the canonical mapping (stock_groups + stock_constraint_device) and _resolve_stock_key (from Track devices via a typed device inventory in the StorageScheduler #2321) cover the resolution, so the rekey has no dependency on this PR and the two merge in either order (only a trivial textual overlap: both branches introduce the same device_stock_key lookup in _prepare).