Commitments can be scoped to specific sensors, binding their aggregate flow

[Flix6x]

Description

A flex-context commitment gains an optional sensors field: instead of binding each device of the matching commodity separately, the commitment binds the aggregate flow of the devices whose power sensors are listed, as one grouped commitment (using the existing device_group machinery of FlowCommitment).

Example — reserve an upward-regulation band on a site's e-heaters (their combined consumption must stay at/above the band, with downward deviation penalized):

{
  "commitments": [
    {
      "name": "reserved band",
      "sensors": [123, 124],
      "baseline": "10 MW",
      "down-price": "-10000 EUR/MWh"
    }
  ]
}

If none of the listed sensors appear in the flex-model, a warning is logged and the commitment binds nothing (rather than failing the whole schedule).

Look & Feel

New unit test test_sensor_scoped_commitment_binds_aggregate_of_selected_devices: two 8 MW heaters that would otherwise stay off (they only cost money) are held at a combined 10 MW — a level neither device could carry alone — while the rest of the planning problem is unaffected.

How to test

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

🤖 Generated with Claude Code

https://claude.ai/code/session_016MLCUiSdXDqDBmg8GbYp1B

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33860891 | 📁 Comparing c35820a against latest (60cfda8)

  🔍 Preview build  

87 files changed · + 10 added · ± 77 modified

+ Added

• _autodoc/GROUP.html
• _autodoc/INFLEXIBLE_CONSUMPTION.html
• _autodoc/INFLEXIBLE_PRODUCTION.html
• _autodoc/OPERATION_MODES.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.soc_projection.html
• _autosummary/flexmeasures.data.schemas.scheduling.groups.html
• _autosummary/flexmeasures.data.schemas.scheduling.utils.html
• host/multi-tenancy.html
• tut/toy-example-group-constraints.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/COMMITMENTS.html
• _autodoc/INFLEXIBLE_DEVICE_SENSORS.html
• _autodoc/SOC_MAXIMA.html
• and 67 more...

[Flix6x]

I only wish to clear up some documentation. And one clarification request.

The test is correct, but would be slightly stronger if the statement about 0 consumption being preferred without the extra commitment would be proven.

[Flix6x]

Is the regular commitment not aggregating over all devices (of one grid-connected commodity), rather than applied to each device individually?

[Flix6x]

Explain the term "band" in the docstring.

[Flix6x]

I think this would also close #2179, as this essentially adds support for an activation price per device, if you model the commitment with a zero baseline, a positive upwards deviation price and a negative downward deviation price. But if that is the case, then I suggest an additional test (making sure that the problem remains convex) and extending the documentation accordingly.

[Flix6x]

Pushed the recommended follow-ups (on top of a merge with current main, which includes #2374):

• Optional group scope on a commitment, alongside the existing sensors list — at most one of the two (schema-validated). A group reference reuses the group's resolved membership (group_to_devices), so you don't restate the member sensors; a sensors list stays the general cherry-pick form that can span electrical groups. No multi-group membership is introduced — the two are different relationships (topology vs. market selection).
• Inflexible-inclusion semantics documented: a sensors scope binds the listed flexible devices only (by_sensor_id), while a group scope includes the group's inflexible members (the node's total flow). Spelled out on the schema field and _resolve_commitment_scope.
• Commodity-share validation: a scoped set spanning more than one commodity is rejected (a commitment binds the aggregate flow of a single commodity).
• Robustness: scoped commitments now carry provenance='custom' (was missing, so they weren't tagged for cost reporting), and each gets a unique device_group label so two same-named scoped commitments can't merge.

Tests: group-scope binding (end-to-end), the sensors/group mutual-exclusion, plus the existing 22 commitment tests still green. Changelog updated.

[Copilot]

Pull request overview

Adds optional scoping for flex-context commitments so they can bind the aggregate flow of a selected subset of devices (via a sensors list or a group reference), reusing existing FlowCommitment.device_group aggregation behavior in the planning solver.

Changes:

• Extend the scheduling Commitment schema and OpenAPI to accept sensors and group as optional, mutually exclusive commitment scope selectors.
• Update StorageScheduler.convert_to_commitments to build a single aggregate-flow FlowCommitment when a scope is provided, with warning-and-skip behavior when the scope matches no devices.
• Add tests covering sensor-scoped and group-scoped aggregate-flow commitments, plus schema validation for mutual exclusivity.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
flexmeasures/ui/static/openapi-specs.json	Documents new sensors / group commitment fields and (re)positions GroupReference schema.
flexmeasures/data/schemas/scheduling/init.py	Adds sensors and group fields to CommitmentSchema and validates mutual exclusivity.
flexmeasures/data/models/planning/tests/test_commitments.py	Adds unit tests asserting aggregate binding behavior for sensor- and group-scoped commitments.
flexmeasures/data/models/planning/storage.py	Implements scoped commitment resolution and construction of aggregate-flow FlowCommitments.
documentation/changelog.rst	Adds a main changelog entry describing the new scoped-commitment capability.

[Flix6x]

Fixed in c35820a: _build_scoped_commitment now pins the commitment's commodity to the (single) commodity of its scoped devices, overriding the schema's electricity default, so cost attribution matches the scope. Added test_scoped_commitment_pins_commodity_to_scoped_devices.

[Flix6x]

Fixed: removed the stray "unscoped battery" clause — that test only models the two heaters.

[Flix6x]

Added test_scoped_commitment_with_no_matching_devices_warns_and_binds_nothing, which asserts the warning is logged and the scheduler binds nothing (returns no commitment) rather than failing.

[Flix6x]

Reflowed the comment to break only after punctuation, per the repo convention.

[Copilot]

Pull request overview

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

Suppressed comments (6)

flexmeasures/data/models/planning/tests/test_commitments.py:2201

• This new test docstring breaks lines mid-sentence (e.g. after "that"), which goes against the repo convention to only break lines after punctuation (see .github/instructions/docstrings.instructions.md:38). Please rewrap so each line ends at punctuation.

    """A commitment scoped to a ``group`` reference binds the aggregate flow of that
    group's members, reusing the group's resolved membership -- the same band effect as
    listing the members' sensors, but pointing at the group instead."""

flexmeasures/data/models/planning/tests/test_commitments.py:2276

• This new test docstring introduces mid-sentence line breaks, which conflicts with the repo's docstring/comment wrapping convention (line breaks only after punctuation; see .github/instructions/docstrings.instructions.md:38). Rewrap the docstring so each line ends with punctuation.

    """A scoped commitment's commodity follows its scoped devices, overriding the
    schema's electricity default -- so its cost is attributed to the right commodity."""

flexmeasures/data/models/planning/tests/test_commitments.py:2323

• This new test docstring breaks a sentence across lines without punctuation at the line break, which conflicts with the repo convention (see .github/instructions/docstrings.instructions.md:38). Rewrap so each line break happens after punctuation.

    """A scope that matches no device in the flex-model logs a warning and binds
    nothing, rather than failing the whole schedule."""

flexmeasures/data/models/planning/storage.py:1698

• The new scoped-commitment comment block introduces mid-sentence line breaks, which conflicts with the repo convention to only break lines after punctuation (see .github/instructions/docstrings.instructions.md:38). Rewrapping improves searchability and keeps diffs stable.

            # A commitment scoped to a subset of devices binds the *aggregate* flow of
            # those devices as one commitment, rather than each device separately. The
            # scope is given either as a raw list of power `sensors` (a cherry-pick that
            # may span electrical groups, e.g. an aFRR band on a site's e-heaters) or as
            # a `group` reference (the members of an electrical group, reusing its

flexmeasures/data/models/planning/storage.py:1559

• This docstring paragraph has several mid-sentence line breaks (e.g. after "the"), which goes against the repo's docstring/comment wrapping convention (line breaks only after punctuation; see .github/instructions/docstrings.instructions.md:38). Rewrap these sentences so each line ends with punctuation.

This issue also appears on line 1694 of the same file.

        A ``group`` scope yields the group's (leaf) members, which -- unlike the
        by-sensor scope -- include any inflexible members, so the aggregate covers the
        node's total flow (fixed load included). A ``sensors`` scope yields the listed
        *flexible* devices (``by_sensor_id`` returns schedulable devices only, so
        inflexible devices are not bound by a sensor scope). Canonical indices always

flexmeasures/data/models/planning/tests/test_commitments.py:2093

• This new test docstring uses mid-sentence line breaks, which conflicts with the repo convention to only break lines after punctuation (see .github/instructions/docstrings.instructions.md:38). Rewrapping into full sentences per line will make future diffs and text search cleaner.

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

• line 2199
• line 2275
• line 2322

    """A commitment scoped to specific sensors (here: two e-heaters) binds their
    aggregate flow as one commitment: a baseline of 10 MW with a steep penalty on
    downward deviation keeps their combined consumption at 10 MW even though a
    cheaper allocation (0 MW) exists.
    """