Balance internal commodity nodes (heat/steam networks) via first-class balance groups

[Flix6x]

Description

Stacked on #2218. Completes the missing piece of the CHP/factory work: scheduling a multi-commodity factory end-to-end through StorageScheduler.compute().

• device_scheduler gains a balance_groups argument: each group lists the devices of an internal commodity node (a heat or steam network without a grid connection) whose stock-side flows must sum to zero at every time step. This replaces the earlier workaround of overlapping stock groups with a min=max=0 "reference device" (which never worked automatically from a flex-model — see the investigation notes on dev/simulate-factory).
• The StorageScheduler derives balance groups from the flex-config: a non-electricity commodity without energy prices in the flex-context is treated as an internal node (previously this raised Missing consumption price). Electricity still requires a price.
• Converters are described in the flex-model as one entry per commodity port, tied together by a coupling group — so per-commodity balance groups are disjoint and no overlapping group tricks are needed.
• Added changelog item in documentation/changelog.rst

How to test

pytest flexmeasures/data/models/planning/tests/test_commitments.py -k factory_chp_dispatch
pytest flexmeasures/data/models/planning/tests/test_storage.py -k factory_chp_dispatch_through_storage_scheduler

The engine-level factory test is parametrized to run in both modes (reference-device stock groups and balance groups) and must produce identical dispatch. The new StorageScheduler test drives the full factory (CHP + gas boiler + e-heater + steamer meeting a fixed 15 kW steam demand from an inflexible sensor) purely from a flex-model and flex-context.

Further Improvements

• An explicit named-node concept in the flex-context (e.g. multiple heat networks per site) is a possible future extension; for now one internal node per commodity suffices.
• A first-class 'converter' flex-model shorthand that expands into port devices + a coupling group could reduce verbosity.

Related Items

Stacked on #2218; continues the work explored on dev/simulate-factory (#2113-era factory simulation).

🤖 Generated with Claude Code

https://claude.ai/code/session_016MLCUiSdXDqDBmg8GbYp1B

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33538451 | 📁 Comparing f3f2b3b against latest (922ecf6)

  🔍 Preview build  

9 files changed · + 2 added · ± 7 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html

± Modified

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

[Flix6x]

Pushed a fix from real-world testing (a paper-mill factory scenario): the node balance now sums plain ems_power instead of stock-side terms. A device can sit in both a stock group (via state-of-charge, e.g. a steamer discharging a heat buffer) and a commodity balance group (via its commodity) — its derivative efficiencies and the buffer's soc-usage/stock-delta assigned to it describe the stock-side conversion and must not leak into the commodity balance. That leak made a realistic scenario (buffer with standing losses) infeasible.

Heads-up for the #2272 interaction: #2272's smart defaults fill a zero consumption-price into price-free commodity contexts, which defeats this PR's priceless-commodity internal-node detection when both are merged. The fix (tested on a local merge of both branches) is to record durably on the context whether any price field was user-given (a prices_are_defaulted flag set in fill_grid_connection_defaults) and let _prepare treat all-defaulted prices as 'no prices'. It needs code from both PRs, so I'll open it as a small follow-up once the second of the two lands — the commit is ready.

🤖 Generated with Claude Code

[Flix6x]

Superseded by #2289 after a commit-message cleanup (force-pushes to this branch are blocked by repository rules).