feat: unit-committed affine coupling groups (on/off + min-load + no-load base)

[Flix6x]

Extends the coupling primitive (#2218) with unit commitment: a coupling group can now have an on/off binary, a minimum level when on, and a per-port no-load base gated by that binary.

What it does

When a coupling group is unit-committed, the solver introduces a per-timestep binary u_g[j] ∈ {0,1} and a marginal level alpha_g[j] ≥ 0, with:

• min_g * u_g[j] <= alpha_g[j] <= max_g * u_g[j] — alpha is 0 when off, and at least the minimum level when on;
• for every port d in the group: P[d,j] == coeff_d * alpha_g[j] + base_d * u_g[j],

where coeff_d is the existing signed coupling coefficient and base_d is the new signed per-port no-load base. This makes the affine cogeneration/CHP model exact, including no-load fuel: in an unprofitable step the whole unit idles (all ports exactly 0, no no-load fuel burned), and when running it stays at or above the minimum level.

Purely proportional (non-UC) coupling is unchanged: the problem stays an LP unless some group is unit-committed (a group becomes unit-committed only when coupling-min is set or a non-zero coupling-base is given). Minimum up/down times are out of scope.

Schema

• coupling-base (per port): a signed power quantity whose direction follows the port's flow direction (like coupling-coefficient); default 0.
• coupling-min (on the group's reference port, the port with |coefficient| = 1): a power quantity that sets the group minimum and enables unit commitment. max_g comes from the reference port's power-capacity.

Both fields are documented in metadata.py, added to the storage flex-model schemas, and reflected in openapi-specs.json. They are carried through DeviceInventory (coupling_uc, coupling_bases) and storage.py to device_scheduler.

Tests

• A factory-style, hand-computed 1-step unit-committed cogeneration dispatch (driving electrical output, affine gas/heat with no-load bases): verifies full idle in an unprofitable step, running at max (≥ Pmin) in a profitable step, and the exact objective.
• Plumbing tests that a unit-committed flex-model resolves to the expected signed bases and (min, max) bounds in MW, and that a group without min/base stays purely proportional.
• The existing proportional coupling tests still pass unchanged.

Stacked on #2218.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33704588 | 📁 Comparing b09a437 against latest (7c17a5d)

  🔍 Preview build  

14 files changed · + 4 added · ± 10 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_BASE.html
• _autodoc/COUPLING_COEFFICIENT.html
• _autodoc/COUPLING_MIN.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.linear_optimization.html
• _autosummary/flexmeasures.data.schemas.scheduling.storage.html
• _autosummary/flexmeasures.utils.job_utils.html
• api/v3_0.html
• cli/change_log.html
• features/scheduling.html