Keep explicit zero directional capacity hard under relax-constraints

[sankalpsthakur]

Description

• Treat an explicit all-zero production-capacity / consumption-capacity as a physical impossibility, not an economic limit
• Under relax-constraints (or when breach prices are set), keep the hard derivative bound and do not create soft device capacity FlowCommitments for that direction
• Non-zero directional capacities may still be softened via breach prices (unchanged; explicit regression)
• Regression tests: hard bounds + no soft breach commitments for both directions; schedule never produces/consumes when that directional capacity is 0 with a directional breach price set
• Changelog entry

Context

Fixes #2323

Impact

Severity: physically impossible schedules under default relax-constraints.

Observed (community co-sim, #2323): heat pump with explicit production-capacity: 0 kW scheduled −1.764 kW production when site capacity was tight and site breach prices (10 000 EUR/kW) dwarfed device breach prices (100 EUR/kW). The LP rationally breached a soft zero-capacity commitment.

Root cause: explicit zero was turned into a soft FlowCommitment; hard bound stayed at symmetric -power-capacity. Breach prices soften limits, not impossibilities (#2272 spirit).

Workaround before this fix: set is_strictly_non_positive on consumption-only sensors.

How to test

pytest \
  flexmeasures/data/models/planning/tests/test_solver.py::test_explicit_zero_directional_capacity_stays_hard_under_relax_constraints \
  flexmeasures/data/models/planning/tests/test_solver.py::test_non_zero_directional_capacity_still_softens_under_breach_price \
  flexmeasures/data/models/planning/tests/test_solver.py::test_explicit_zero_directional_capacity_not_breached_in_schedule \
  flexmeasures/data/models/planning/tests/test_solver.py::test_device_power_capacity_uses_directional_capacity_before_site_fallback \
  flexmeasures/data/models/planning/tests/test_solver.py::test_capacity \
  -v

Related Items

• Fixes Explicit zero directional capacity should stay a hard constraint under relax-constraints #2323
• Smart-defaults context: Smarter commodity-context defaults and Commitment commodity field #2272
• Multi-asset schedule produces unexpected results #2329 reports EVSE discharge despite production-capacity: 0 W — same zero-capacity softening class; this PR fixes that constraint path (multi-asset interaction there may still need separate follow-up)

---

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

---

AI/LLM disclosure

• AI coding tools (including Grok and/or Codex agent-assisted editing) were used to help draft or modify code and this PR description.
• I reviewed the complete change, understand the reasoning, and ran the reported local tests before submitting.
• This submission is original work of authorship under the project CLA / contributor terms; AI output was not pasted unreviewed.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33959968 | 📁 Comparing fb91ee3 against latest (9acc4eb)

  🔍 Preview build  

77 files changed · + 10 added · ± 67 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html
• _autodoc/INFLEXIBLE_CONSUMPTION.html
• _autodoc/INFLEXIBLE_PRODUCTION.html
• _autodoc/OPERATION_MODES.html
• _autosummary/flexmeasures.api.common.rate_limiting.html
• _autosummary/flexmeasures.data.models.planning.highspy_optimization.html
• _autosummary/flexmeasures.data.models.planning.scheduling_problem.html
• _autosummary/flexmeasures.data.schemas.scheduling.groups.html
• host/plans.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• index.html
• py-modindex.html
• _autodoc/COMMITMENTS.html
• _autodoc/CONSUMPTION_CAPACITY.html
• _autodoc/GROUP.html
• _autodoc/INFLEXIBLE_DEVICE_SENSORS.html
• _autodoc/PRODUCTION_CAPACITY.html
• and 57 more...

[Flix6x]

Context for this PR from #2395, which works out the semantics behind it: this PR should land as written — the horizon-global guard is not a rough edge, it is doing the classification the design needs.

A fixed zero directional capacity carries two incompatible meanings in the wild:

• physics — the S2 CEM in Explicit zero directional capacity should stay a hard constraint under relax-constraints #2323 derives production-capacity: 0 kW from a heat pump's operation modes; it cannot produce at any price;
• preference — V2G-Liberty sets a windowed production-capacity: 0 kW during a calendar car reservation, so the charger stands idle once the soc-minima is reached and the user can unplug immediately (DC charging risks an arc if uncoupled while power is flowing). This is in our shipped docs, in documentation/tut/flex-model-v2g.rst.

The two separate on exactly the signal production_capacity_d.max() > 0 tests: physics zeros span the whole scheduling window; preference zeros are windowed. So making the guard elementwise — which an earlier draft of #2395 argued for — would harden V2G-Liberty's reservation windows and break the documented tutorial. Please keep it as it is.

Two small requests before merge:

1. Drop the soft_breach_names == [] assertion. The FlowCommitments can harmlessly remain: on the hardened slots their quantity is 0 and the hard bound pins flow to 0, so they are unbreachable and cost nothing. Asserting their absence over-specifies an incidental detail.
2. Add a test asserting that a windowed zero (zero over part of the horizon, non-zero elsewhere) stays soft. That is the V2G-Liberty contract and nothing currently pins it, so the next person to "simplify" this guard would break it silently. Happy to contribute that test as a follow-up if you would rather not expand the PR.

Also worth a line in the changelog and the flex-model docs stating the rule explicitly, since it is currently emergent rather than written down:

A directional capacity that is zero throughout the scheduling window is read as a physical property of the device and is enforced strictly. A zero covering only part of the window is read as a preference and may be breached at the applicable breach price.

On the PR description's note that this also fixes #2329: it fixes the reported EVSE discharge (that request's production-capacity segment covers the whole PT27H window at 0 W), and it correctly leaves that device's consumption zeros at 17:00–18:00 soft, since those coincide with its soc-minima and are the reservation pattern.

[Flix6x]

I have pushed the two changes I asked for above, plus a merge of main, so this does not sit waiting on you — thanks for bearing with the back-and-forth on the semantics.

1. Merged main. It now contains #2398, which stops relax-constraints from softening device capacities at all. That narrows this PR's audience — the default path no longer creates the situation — but it does not replace it: #2329 opts in with 'relax-capacity-constraints': true explicitly, so its EVSE's production-capacity: 0 W is still soft without this PR.

2. Dropped the soft_breach_names == [] assertion. It over-specifies. Next to the hard bound those commitments carry quantity 0, so the pinned flow cannot deviate from them: they are unbreachable and free. What the device obeys is the bound, which the same test already asserts. I left a comment in place of the assertion saying so.

3. Added test_windowed_zero_directional_capacity_stays_soft. This is the important one, and it pins the half of the rule that had no coverage.

The rule this PR implements is: a directional capacity of zero states a physical property of the device when it holds for the whole scheduling window, and a preference when it covers only part of it. Your horizon-wide production_capacity_d.max() > 0 is what distinguishes them, and that is correct — a heat pump never produces, whereas a reservation is a window.

That matters because a real client depends on the preference half. V2G-Liberty punches value: 0 windows into an otherwise non-zero capacity for each calendar car reservation, so the charger stands idle once the SoC target is met and the driver can unplug without waiting for the socket to unlock (DC charging risks an arc if uncoupled under flow). Hardening those windows would turn that preference into an infeasibility whenever a soc-minimum needs the device to act during one. The V2G tutorial documents the same shape.

I checked the new test has teeth: mutating the guard to a per-timestep variant (not (production_capacity_d == 0).any()) makes it fail with derivative min of [-2, -0], i.e. the zero hour hardened. With the guard as you wrote it, it passes.

4. Wrote the rule down, on both consumption-capacity and production-capacity in metadata.py, and rewrote the changelog entry to state both halves. It was emergent behaviour before — nothing said it, and nothing stopped a later reader from "simplifying" the horizon-wide check into a per-timestep one.

For context on where this fits: #2395 covers the wider question of why one field carries two meanings, and what it would take to stop guessing.