Combined Heat and Power (CHP)

[Flix6x]

Description

Adds hard flow coupling between devices, so a single physical unit whose ports move in fixed proportion — a CHP, a heat pump, any converter — can be scheduled as one thing.

• Support coupling constraints in the device_scheduler to model devices such as CHP
• Model the coupling in the direct HiGHS backend too, so it holds under the default solver
• Express converters in the flex-model (coupling / coupling-coefficient), with schema support
• Added changelog item in documentation/changelog.rst

The constraint

device_scheduler gains a coupling_groups argument. Each entry maps a group name to a list of (device_index, coefficient) tuples. One free decision variable alpha is introduced per group per time step, and every member device is pinned to it:

P[d, j] == coeff_d * alpha[group, j]

so the ports cannot move independently — only the unit's overall level can. Sign convention: positive coefficient for input ports (consuming, positive ems_power), negative for output ports (producing, negative ems_power).

A CHP burning gas to make heat and power:

coupling_groups={"chp": [(0, 1.0), (1, -0.5), (2, -0.3)]}

Each unit of gas in yields 0.5 heat and 0.3 power out. In the flex-model that is one entry per commodity port, tied by a shared coupling name and a coupling-coefficient.

Coupling is a hard constraint on the feasible region, not a preference: it is the converter's physics, and it travels with the device wherever it is scheduled.

Both scheduler backends

#2364 landed a second, Pyomo-free backend that builds the HiGHS model directly, and made it the default (FLEXMEASURES_LP_SOLVER = "highspy"). Coupling is modelled in both:

• Pyomo path — coupling_alpha variable plus flow_coupling_rule.
• Direct HiGHS path — one free column per group per time step, and one equality row per coupled device.

This is not optional. device_scheduler forwards its arguments to the direct backend by name, so an unimplemented parameter raises NotImplementedError there rather than being silently dropped — and a silently dropped coupling_groups means uncoupled devices, a schedule that looks plausible and is wrong. A signature-coverage test fails the moment the two drift apart.

The solver-agnostic half of the argument handling lives in scheduling_problem.py (also from #2364): the coupling_device_specs collection is built once there, as a field on SchedulingProblem, and both backends read it from the same place.

Testing

pytest -k test_chp_coupling
pytest -k test_factory_chp_dispatch

Plus a chp_coupling_groups scenario in test_highspy_equivalence.py, running a three-port CHP through both backends and comparing schedules and costs. It was verified to fail with the coupling rows disabled, so it cannot pass vacuously — worth stating because test_commitments.py and test_storage.py do not use the app_with_each_solver fixture and therefore only ever run under the configured default solver.

CI: 12/13 checks pass, tests on Python 3.10/3.11/3.12.

The red check is DCO, and it is not a sign-off problem — the app reports it could not evaluate: this PR has 257 commits, GitHub's REST API caps at 250, and the app's GraphQL fallback did not complete. Re-running it is not exposed over the API. It needs a UI re-run or a maintainer override.

Further improvements

• coupling_groups is the fourth device-grouping parameter on device_scheduler, after stock_groups, ems_constraint_groups and the commitment device_group — and Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 adds a fifth, balance_groups. Each has its own shape, its own spec-collection block and its own constraint family, while all of them are ultimately a set of devices plus a kind of constraint over it. Now that scheduling_problem.py owns every one of those collection steps, it is the natural place to converge them on a single membership concept with a menu of constraint kinds. This is the engine-side counterpart of the open question "should we converge site capacity and group capacity?" in the flex-config placement draft.
• Coupling vs balance are adjacent but distinct and should stay so: coupling fixes members in fixed proportion to a common level; a balance group (Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289) constrains their sum to zero. Worth documenting the difference explicitly, since both read as "a group of devices that move together".
• A converter shorthand in the flex-model, expanding to the per-port + coupling form — sketched in Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289's description.

Related items

• Add a Pyomo-free scheduling backend (direct highspy model construction) #2364 — direct HiGHS backend and the shared scheduling_problem module.
• Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 — stacked on this; internal commodity nodes (balance_groups), which complete the factory case end-to-end.

[Flix6x]

Addressed the review comment on coupled converter port directions: a coupled device no longer needs the opposite direction set to a fixed 0. The flow direction is now smart-defaulted the same way site capacities are — an input port gives only a consumption-capacity (production defaults to 0), an output port gives only a production-capacity (consumption defaults to 0). Setting the opposite direction to a fixed 0 explicitly still works (back-compat), and only genuinely ambiguous flex-models are rejected: both directions flowing (both non-zero) or neither given.

Changes:

• _resolve_coupling_coefficient (devices.py) infers the sign from which directional capacity flows, treating an explicit zero on the opposite side as a legacy marker.
• The validate_coupling_direction_is_unambiguous validator (storage.py) now requires exactly one active direction rather than exactly one fixed zero.
• Updated the COUPLING_COEFFICIENT metadata docs (regenerated OpenAPI specs) to drop the "must set … to a fixed 0" requirement and explain the defaulting, mirroring the site-capacity defaulting.
• Added/adjusted tests (schema validation + a direct _resolve_coupling_coefficient direction test); the existing CHP factory/coupling tests that use explicit zeros still pass.

[Flix6x]

Direct HiGHS backend support — done in this branch

(Updated: this note originally described what #2364 would require of this branch. That work has since landed here, so it now records what is in rather than what is needed.)

#2364 is merged. It added a second scheduler backend building the HiGHS model directly, made it the default (FLEXMEASURES_LP_SOLVER = "highspy"), and moved the solver-agnostic half of device_scheduler into flexmeasures/data/models/planning/scheduling_problem.py.

b6257e7d3 merges main into this branch and settles all three consequences.

1. The conflict was mechanical. The device_to_group / group_to_devices construction this branch rewrote for multi-group membership had moved, unchanged, into prepare_scheduling_problem(). Both of this branch's additions to that block now live there: the overlapping group_to_devices membership (a commodity converter participates in every node it touches), and the coupling_device_specs collection, which became a field on the SchedulingProblem dataclass so both backends read it from one place.

2. coupling_groups is modelled in the direct backend. Arguments reach it by name, so the parameter would have raised NotImplementedError there rather than being silently dropped — coupled devices quietly not coupled would have been much harder to notice, since the CHP tests predate the default flip. The mirror is one free variable per group per time step (the group's common normalised flow) and one equality per coupled device:

ems_power[d, j] - coeff * alpha[g, j] == 0

The Pyomo coupling_alpha variable and flow_coupling_rule are unchanged.

3. Equivalence coverage. A chp_coupling_groups scenario in test_highspy_equivalence.py runs a three-port CHP (gas in 1.0, heat out −0.5, power out −0.3) through both backends. It was checked to fail with the new rows disabled, so it cannot pass vacuously — worth stating, because tests/test_commitments.py and tests/test_storage.py do not use the app_with_each_solver fixture and so only ever run under the configured default solver.

CI is green: 12/13 checks pass, tests on Python 3.10/3.11/3.12.

The one red check is DCO, and it is not a sign-off problem — the app reports it could not evaluate, because this PR has 257 commits and GitHub's REST API caps at 250, after which its GraphQL fallback did not complete. Re-running it via the API is not exposed to a user token.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (10)

flexmeasures/data/schemas/tests/test_scheduling.py:1595

• Docstring wraps mid-phrase across lines. Reflow to avoid breaking in the middle of a sentence.

    """test_uncoupled_device_needs_no_directional_capacities: the coupling-direction check
    only applies to devices that define a `coupling` field."""

flexmeasures/data/schemas/tests/test_scheduling.py:1604

• Docstring wraps mid-phrase across multiple lines. Please reflow so line breaks occur only after punctuation.

    """test_blank_coupling_name_is_rejected: a provided coupling name must contain at least
    one non-whitespace character, so unrelated devices cannot be silently coupled under an
    empty group key. This holds for both the scheduling and the db-stored schema."""

flexmeasures/data/schemas/tests/test_scheduling.py:1624

• Docstring wraps mid-phrase across lines. Reflow to avoid mid-sentence line breaks.

    """test_db_flex_model_coupling_round_trips: a db-stored flex-model (validated via
    DBStorageFlexModelSchema, e.g. by patch_asset) accepts `coupling`/`coupling-coefficient`
    and round-trips them."""

flexmeasures/data/schemas/tests/test_scheduling.py:1577

• Docstring wraps mid-phrase across multiple lines. This repo’s docstring convention is to break lines only after punctuation, so this should be reflowed (or shortened) to avoid mid-sentence line breaks.

This issue also appears in the following locations of the same file:

• line 1594
• line 1602
• line 1622

    """test_coupling_direction_must_be_unambiguous: a device with a `coupling` field must
    have an unambiguous flow direction, inferred from which directional capacity is given
    (the opposite direction defaults to zero), so the sign of its coupling coefficient can
    be inferred."""

flexmeasures/data/schemas/scheduling/storage.py:664

• This docstring contains several mid-phrase line breaks (e.g. lines ending with “a” / “be”). The project’s docstring convention is to wrap only after punctuation; please reflow the docstring accordingly.

        """A coupled device must have an inferable flow direction.

        The flow direction is inferred from which directional capacity is given:
        a device with (only) a consumption-capacity is an input (consuming) device,
        and a device with (only) a production-capacity is an output (producing)

flexmeasures/data/models/planning/devices.py:232

• This docstring’s bullet list uses line endings like “->” and breaks lines mid-phrase, which violates the repo’s docstring line-break convention (wrap only after punctuation). Reflowing the bullets into full sentences makes it consistent and easier to grep/review.

    """Resolve a coupled device's internal signed coupling coefficient.

    Coupling coefficients in flex-models are user-facing positive magnitudes.
    The internal sign is inferred from which directional capacity allows flow
    (mirroring how a missing directional site/device capacity defaults to zero):

    - only a (non-zero) ``consumption_capacity`` flows -> input device ->
      internally positive coefficient
    - only a (non-zero) ``production_capacity`` flows -> output device ->
      internally negative coefficient

    The unspecified direction is assumed to be zero, so the user no longer needs
    to set the opposite direction to a fixed 0 (though doing so still works).
    """

flexmeasures/data/models/planning/scheduling_problem.py:319

• These comments include mid-phrase line breaks and an em-dash line ending, which conflicts with the repo’s comment wrapping convention (break only after punctuation). Reflow into fewer, sentence-complete lines to keep search/review stable.

    # Group keys are namespaced strings: a declared stock group's key (a state-of-charge sensor id)
    # could otherwise collide with the device index of an ungrouped device,
    # silently merging that device into the stock group.
    #
    # A device may belong to more than one stock group —
    # a commodity converter (e.g. a steamer bridging a heat node and a steam node) participates in every node it touches,
    # so ``group_to_devices`` keeps the full (possibly overlapping) membership.
    # ``device_to_group`` records only the primary group (first assignment wins),
    # used where a single owning group is needed (per-device stock bounds).

flexmeasures/data/models/planning/scheduling_problem.py:371

• coupling_groups is converted into (group_index, device_index, coefficient) triples without validating device indices or coefficients. In particular, an out-of-range device index can corrupt the direct HiGHS model (column indices are computed arithmetically), potentially producing incorrect schedules or hard-to-diagnose solver errors. Please validate indices and require finite, non-zero coefficients during problem preparation.

    # Collect (group_index, device_index, coefficient) triples for coupling constraints.
    # Each device in each group will be constrained: P[d, j] == coeff * alpha[group, j],
    # where alpha is a free variable representing the common normalised flow.
    coupling_device_specs: list[tuple[int, int, float]] = []
    if coupling_groups:
        for g_idx, (_group_name, members) in enumerate(coupling_groups.items()):
            for d_idx, coeff in members:
                coupling_device_specs.append((g_idx, d_idx, coeff))

flexmeasures/data/schemas/scheduling/storage.py:914

• DBStorageFlexModelSchema validates that coupling is non-blank, but it does not enforce the same “unambiguous flow direction” rule as StorageFlexModelSchema. This allows persisting flex-model entries with coupling but ambiguous/missing directional capacities, which can later lead to incorrect sign inference (or a late scheduling-time validation failure). Consider applying the same schema-level validation here, so invalid converter-port definitions are rejected at persist time.

    @validates("coupling")
    def validate_coupling(self, coupling: str | None, **kwargs):
        _validate_coupling_name(coupling)

    @validates_schema
    def forbid_time_series_specs(self, data: dict, **kwargs):
        """Do not allow time series specs for the flex-model fields saved in the db."""

flexmeasures/ui/static/openapi-specs.json:7164

• The OpenAPI schema documents coupling-coefficient with minimum: 0.0, but the actual Marshmallow validation is strictly positive (min_inclusive=False) and tests assert that 0 is rejected. This makes the generated API docs inaccurate; consider reflecting the exclusive lower bound in the schema output.

            "type": "number",
            "default": 1.0,
            "minimum": 0.0,
            "description": "Positive coupling magnitude for this device within its coupling group.\nThe scheduler couples the power flows of all devices in the group: each device's power is its coupling coefficient times the group's common flow level.\nThe flow direction of each device is inferred from which directional capacity is set: a device given only a <code>production-capacity</code> is an output (producing) device, and a device given only a <code>consumption-capacity</code> is an input (consuming) device.\nThe unspecified direction is assumed to be zero (mirroring how a missing directional site capacity defaults to zero), so there is no need to set the opposite direction to a fixed 0 (though setting it explicitly still works).\nFor example, a CHP unit with 50% thermal and 30% electrical efficiency uses a gas input device (coefficient 1), a heat output device (coefficient 0.5) and an electricity output device (coefficient 0.3).\nDefaults to 1.\n",
            "example": 0.5

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (8)

flexmeasures/data/schemas/tests/test_scheduling.py:1596

• This test constructs a datetime without tzinfo. Use a timezone-aware datetime (e.g. pytz.UTC) for consistency and to avoid accidentally relying on naive datetime behavior.

    schema = StorageFlexModelSchema(start=datetime(2026, 6, 1), sensor=None)

flexmeasures/data/schemas/tests/test_scheduling.py:1613

• This test uses a naive datetime for start. Use a timezone-aware datetime (this file already imports pytz).

        StorageFlexModelSchema(start=datetime(2026, 6, 1), sensor=None).load(

flexmeasures/data/schemas/scheduling/storage.py:68

• Docstring wraps mid-phrase (lines don’t end with punctuation), which violates the project’s docstring/comment line-break convention and makes text search/review comments unstable.

    """Reject blank/whitespace-only coupling names.

    A blank coupling name would become a coupling-group key, silently coupling
    unrelated devices under an empty group. When provided, the name must contain
    at least one non-whitespace character.

flexmeasures/data/schemas/scheduling/storage.py:663

• This docstring wraps mid-sentence and has lines not ending with punctuation (e.g. lines ending with "active"/"works)"), which violates the repo’s line-break-after-punctuation rule for docstrings/comments.

        The unspecified direction is assumed to be zero, mirroring how a missing directional site capacity defaults to zero,
        so the user does not need to set the opposite direction to a fixed 0 (though doing so still works).

        The direction is ambiguous only when both directions are active
        (each side either flows itself, or is marked active by a fixed zero on the opposite side),

flexmeasures/data/models/planning/scheduling_problem.py:319

• Comment block wraps mid-phrase and includes a line ending with an em dash ("—"), which violates the repo’s line-break-after-punctuation rule for comments/docstrings.

    # Group keys are namespaced strings: a declared stock group's key (a state-of-charge sensor id)
    # could otherwise collide with the device index of an ungrouped device,
    # silently merging that device into the stock group.
    #
    # A device may belong to more than one stock group —

flexmeasures/data/models/planning/devices.py:230

• Docstring wraps mid-sentence (line ends with "flow"), violating the repo’s rule that docstring/comment lines only break after punctuation.

    Coupling coefficients in flex-models are user-facing positive magnitudes.
    The internal sign is inferred from which directional capacity allows flow
    (mirroring how a missing directional site/device capacity defaults to zero):

flexmeasures/data/schemas/tests/test_scheduling.py:1579

• This test constructs a datetime without tzinfo. Project convention is to use timezone-aware datetimes throughout (and this file already uses pytz.UTC elsewhere).

This issue also appears in the following locations of the same file:

• line 1596
• line 1613

    schema = StorageFlexModelSchema(start=datetime(2026, 6, 1), sensor=None)

flexmeasures/data/schemas/scheduling/storage.py:913

• DBStorageFlexModelSchema allows persisting coupling/coupling-coefficient without enforcing an unambiguous flow direction (directional capacities). That means an invalid coupled device can be stored in the DB and later be interpreted with an arbitrary sign in _resolve_coupling_coefficient, potentially producing wrong schedules or unexpected infeasibility at scheduling time.

    @validates("coupling")
    def validate_coupling(self, coupling: str | None, **kwargs):
        _validate_coupling_name(coupling)

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (4)

flexmeasures/data/models/planning/scheduling_problem.py:315

• This inline comment breaks mid-phrase using an em dash at end-of-line. Repo docstring/comment conventions require each physical line to end with a comma/semicolon/colon/period to keep search/review stable.

    # A device may belong to more than one stock group —
    # a commodity converter (e.g. a steamer bridging a heat node and a steam node) participates in every node it touches,

flexmeasures/ui/static/openapi-specs.json:7163

• The OpenAPI schema for coupling-coefficient declares minimum: 0.0, but the Marshmallow validation in StorageFlexModelSchema/DBStorageFlexModelSchema requires the value to be strictly positive (min_inclusive=False). This mismatch can mislead API clients into sending 0 (which the server will reject).

          "coupling-coefficient": {
            "type": "number",
            "default": 1.0,
            "minimum": 0.0,
            "description": "Positive coupling magnitude for this device within its coupling group.\nThe scheduler couples the power flows of all devices in the group: each device's power is its coupling coefficient times the group's common flow level.\nThe flow direction of each device is inferred from which directional capacity is set: a device given only a <code>production-capacity</code> is an output (producing) device, and a device given only a <code>consumption-capacity</code> is an input (consuming) device.\nThe unspecified direction is assumed to be zero (mirroring how a missing directional site capacity defaults to zero), so there is no need to set the opposite direction to a fixed 0 (though setting it explicitly still works).\nFor example, a CHP unit with 50% thermal and 30% electrical efficiency uses a gas input device (coefficient 1), a heat output device (coefficient 0.5) and an electricity output device (coefficient 0.3).\nDefaults to 1.\n",

flexmeasures/data/schemas/scheduling/storage.py:662

• Docstring line breaks here violate the repo convention to break lines only after punctuation. Line 659 ends mid-sentence and the next lines continue the clause, which makes docstrings harder to search and quote reliably.

        The direction is ambiguous only when both directions are active
        (each side either flows itself, or is marked active by a fixed zero on the opposite side),
        or when neither is (both missing).
        Such flex-models are rejected.

flexmeasures/data/models/planning/devices.py:223

• This docstring wraps a sentence mid-phrase (line 222), which violates the repo convention to break lines only after punctuation.

    Coupling coefficients in flex-models are user-facing positive magnitudes.
    The internal sign is inferred from which directional capacity allows flow
    (mirroring how a missing directional site/device capacity defaults to zero):