Keep device capacities hard unless relaxation is asked for

[Flix6x]

Description

• Fill in default device breach prices only when relaxation is asked for — through relax-capacity-constraints, or through a relax-constraints that was passed explicitly rather than defaulted
• Leave the SoC and site capacity constraints following the default, where softening was the point
• Stop overwriting explicitly given device breach prices with the defaults
• Docs (relax-constraints field description, API introduction note) + changelog

Context

Fixes the default-path half of #2323, and is step 1 of the plan in #2395.

Since relax-constraints began defaulting to True (#2172, unreleased), every scheduling request gets default device breach prices, which turns a directional device capacity into a soft constraint for everybody. That is wrong wherever the capacity states a physical impossibility rather than an economic preference — in #2323 a heat pump with production-capacity: 0 kW was scheduled to produce −1.764 kW, because breaching the device (100 EUR/kW) was cheaper than breaching the site (10 000 EUR/kW). The LP was right, given what we told it.

Before the default flip, softening only ever happened when the user explicitly set consumption-breach-price / production-breach-price (shipped in v0.26.0, PR #1405). "You asked for a breach price, so we softened your capacity" is a defensible reading of an opt-in. This PR restores that opt-in without taking anything away: an explicit relax-constraints: true still relaxes everything, exactly as it did before.

Impact

Behaviour change, on top of an unreleased behaviour change, so most users never saw the intermediate state.

flex-context	device capacities	SoC	site capacities
(nothing given)	hard (was soft)	soft	soft
relax-constraints: true	soft	soft	soft
relax-capacity-constraints: true	soft	soft	soft
relax-constraints: false	hard	hard	hard

Anyone who wants the current behaviour adds one field. Anyone who was relying on the pre-#2172 opt-in is unaffected.

Second change: explicit device breach prices are no longer overwritten

The guard's own comment says "unless already set explicitly", but A or B and C and D parses as A or (B and C and D), so the "already set" conditions only ever guarded the relax_constraints branch — and set_default_breach_prices assigns unconditionally. Setting relax-capacity-constraints: true together with consumption-breach-price: 7 EUR/kW therefore silently replaced the 7 with the 100 EUR/kW default. It now keeps the caller's price.

The same precedence shape remains in the SoC and site-capacity blocks. Fixing those changes behaviour for soc-minima/soc-maxima and the site capacities too, and the SoC one needs the relax flags to become tri-state (relax_soc_constraints has load_default=False, so "unset" and "explicitly False" are indistinguishable). Left for its own PR; tracked in #2395.

What this does not fix

#2329, which passes 'relax-capacity-constraints': true explicitly. That is an opt-in, so the device breach prices are still filled and its EVSE's production-capacity: 0 W is still soft. Closing that needs a way to tell a physical zero from a preferential one — see #2395, and PR #2345 for the interim rule.

How to test

pytest \
  flexmeasures/data/schemas/tests/test_scheduling.py::test_device_capacity_relaxation_is_opt_in \
  flexmeasures/data/schemas/tests/test_scheduling.py::test_explicit_device_breach_price_is_not_overwritten \
  flexmeasures/data/schemas/tests/ \
  flexmeasures/data/models/planning/tests/ \
  -v

Related Items

• Fixes the default-path half of Explicit zero directional capacity should stay a hard constraint under relax-constraints #2323
• Step 1 of production-capacity: 0 means two different things, and the rule that separates them is unwritten #2395
• Follows feat: Split flex-context settings by commodity for dynamic capacity scheduling #2172

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures
• Added changelog item in documentation/changelog.rst

🤖 Generated with Claude Code

https://claude.ai/code/session_014qPe5bv41RDTuBVtpdxjWH

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33925921 | 📁 Comparing 0cdd62f against latest (65d2a70)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

• changelog.html
• _autodoc/RELAX_CONSTRAINTS.html
• api/introduction.html
• api/v3_0.html
• features/scheduling.html

[Copilot]

Pull request overview

This PR adjusts flex-context price-defaulting so that device directional capacities (consumption-capacity / production-capacity) remain hard constraints unless the caller explicitly opts into relaxing them, preventing physically impossible schedules caused by default breach pricing.

Changes:

• Update FlexContextSchema.check_prices to only auto-fill default device breach prices when relax-capacity-constraints is set, or when relax-constraints was explicitly provided (not merely defaulted).
• Add regression tests covering opt-in device relaxation and ensuring explicitly provided device breach prices aren’t overwritten.
• Update API/OpenAPI/docs/changelog text to document the revised relaxation semantics.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
flexmeasures/data/schemas/scheduling/init.py	Changes defaulting logic so default relax-constraints no longer softens device directional capacities
flexmeasures/data/schemas/tests/test_scheduling.py	Adds tests for opt-in device capacity relaxation and non-overwriting of explicit breach prices
flexmeasures/data/schemas/scheduling/metadata.py	Updates relax-constraints field description to reflect new semantics
flexmeasures/ui/static/openapi-specs.json	Updates OpenAPI description for relax-constraints accordingly
documentation/api/introduction.rst	Notes that device directional capacities stay hard unless explicitly relaxed
documentation/changelog.rst	Adds changelog entry describing the behavior change and explicit-price preservation

Suppressed comments (4)

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

• This comment wraps mid-phrase (“as it did” → next line), which violates the repo’s rule that comments only break lines after punctuation. Please reflow the comment.

        # An explicitly passed relax-constraints still softens everything, as it did
        # before relax-constraints defaulted to True.

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

• This docstring wraps mid-phrase (“…that cannot” → next line), which violates the repo’s rule that docstrings only break lines after punctuation. Please reflow without mid-phrase breaks.

    A directional capacity can state a physical impossibility (a heat pump that cannot
    produce), so making it breachable at a price has to be asked for, either through
    relax-capacity-constraints or through an explicitly passed relax-constraints.

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

• This docstring wraps mid-phrase (“…keep it” → next line), which violates the repo’s rule that docstrings only break lines after punctuation. Please reflow without mid-phrase breaks.

    ``set_default_breach_prices`` assigns unconditionally, so the guard has to keep it
    from running at all when the caller already priced a breach themselves.

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

• This comment wraps mid-phrase between lines (“…puts” → next line), which violates the repo’s rule that comments only break lines after punctuation. Please reflow it.

    # The opposite direction is left alone too: pricing one direction explicitly puts
    # the caller in charge of both, rather than mixing their price with our default.

[Flix6x]

Consider merging with the previous changelog entry, referencing the two PRs.