[Flix6x]

Stacked on #279 (base dev/s2-frbc-complete), as asked in the review of #271. Merge #279 first.

Why

S2 lets a resource manager expect any usage, negative included, and says nothing about what happens when the storage cannot take it. FlexMeasures plans a forecast usage as forced. So a gain at a full storage, or a draw at an empty one that the actuator cannot keep up with, leaves no feasible plan, and the storage gets no instruction. Until now the handler clipped negative usage to zero, which hid the first case and not the second.

What

With a usage_correction_sensor_id and FlexMeasures v1.1.0 or newer, FRBCSimple asks for a schedule with a correction of the usage forecast:

• A second device on the storage's stock (same state-of-charge sensor), on a commodity of its own, so it never touches the site's electricity. No instruction is ever sent for it.

• Per step, it may only move the expected usage towards zero: give back up to the expected usage, or take away up to the expected gain. It works the same on both sides, since S2's fill levels do not say which bound is an overflow.

• It is priced as a last resort: at twice an upper bound on what one MWh of stock can be worth to the scheduler. The request carries a coherent set of prices to make that bound finite and numerically sound:

  • band breach prices at 10× the highest absolute market price over the window (soc_breach_price_factor);
  • the asset's own stored per-MW prices (peaks, commitments) added to the bound;
  • a breach of the site's capacity left out of the bound (see below), with the site's breach price kept from the asset, or else stated at FlexMeasures' default of 10000 per kW.

  Device capacities are kept hard, so the correction cannot move a usage past zero.

• A negative expected usage is then planned as stated. It is also recorded as stated without a correction (since 905254e, from a review comment on docs(changelog): say each S2 change plainly #283): there, the schedule request carries the forecast without its negative values. Only a FlexMeasures server before v0.23.0, which takes a usage only as a sensor, still gets it recorded as zero. The usage is sent inline, from the same forecast as the correction's limits and the translation back into instructions.

• Where a correction cannot be planned (prices unreadable, a state-of-charge sensor with a resolution, a stored price that cannot be bounded, a stored flex context with commodities), the forecast is planned without its negative values, as before, with a warning saying why.

It is opt-in: FRBCSiteConfigurator(correct_usage=True), or S2_CORRECT_USAGE=1 for the example server. That is because it replaces FlexMeasures' default band breach price (1000 EUR/kWh) with a market-relative one, which is the deployment's call. Handlers without the new sensor behave exactly as before.

How the price was chosen

Probes against FlexMeasures v1.1.0 measured, per scenario, the correction price above which the scheduler stops using a correction it does not need. That threshold is what a MWh of stock is worth to the scheduler. Each matched one term of the bound:

What makes stock worth something	Worth per MWh of stock
Buying or disposing of energy	|price| / charging efficiency, divided again by the storage efficiency per step held
Flow commitment, peak, or any-breach price per MW	price / step length
Site capacity breach	P / step length + P (measured, but left out of the bound)
Fill-level band breach	P / step length + P per step breached

With FlexMeasures' default breach prices, a dominant price was about 1e8 EUR/MWh, where HiGHS already returned over-corrected plans. With the coherent set, over a 24-hour window with prices from −120 to 450 EUR/MWh, the correction price is about 1.8e6 EUR/MWh:

• It was used only where physics forced it.
• It was never used instead of a band breach, or to profit from negative prices.
• Solves took about 0.7 s and were identical on repeat.

Priced at the band's breach price instead, the correction replaced band breaches (9.24 vs 3.12 kWh) and corrected where nothing needed correcting.

Why the site's capacity breach is left out. Pricing the correction above a site breach needs the request to set a site breach price the solver can live with. In the co-simulation (below), a site breach price of 100× the market price kept the correction solvable but let the houses ignore their steering capacity, and 1000× pushed the correction price to 1.3e7 EUR/MWh, where HiGHS declared every house schedule infeasible (replays put the cliff between 0.7e7 and 1.3e7 for this house). So a correction can now be cheaper than a site breach, while it stays dearer than a band breach, which the plan still uses first.

The asset's stored inflexible devices are carried into the electricity entry, and named empty at the top level, because FlexMeasures merges the stored context in there too and would count them twice (FlexMeasures/flexmeasures#2848).

FlexMeasures fills in its default site breach price only for a flex context without commodities; in a commodity entry, a site capacity without one stays hard. The request therefore states that default itself (FlexMeasures/flexmeasures#2846).

Evidence

• Tests: 809 pass.
• Mutation gate: 42 of 42 mutants killed.
• FlexMeasures v1.1.0 end to end: the exact request this handler builds, for a storage at 118 kWh under a 120 kWh hard top with a forced 14.4 kWh gain, is accepted and solved. The correction removes exactly 12.4 kWh, and the stock never exceeds 120. Without the correction device, the same request has no feasible plan.
• Adversarial review: found that the stock read every forecast on the sensor while the limits used only the latest; that the asset's stored electricity flex context was dropped under a commodity list; that a stored relax-capacity-constraints would soften the limits; and that efficiencies above one lowered the bound. All are fixed in the second commit, which also makes the correction opt-in.

Co-simulation

One steered day, two houses, the community capacity policy, deterministic solver settings. Every run below had 0 degree-hours outside the comfort band.

Run	Client	Breach (kWh)	Peak (kW)	Notes
C1	#279, no correction	0.058	2.21	reference
D3	site breach 100× market	0.348	2.267	correction engaged, steering ineffective
D4	site breach 1000× market			every house schedule infeasible (correction price 1.3e7), run aborted
D5	site breach left out, none stated			site capacity hard in the commodity entry, schedules infeasible, stopped
D6	4b7b023	0.052	2.21	inflexible devices counted twice: the houses planned against a doubled base load
C2	a31f1cf, correction off	0.052	2.21	matches C1
D7	a31f1cf (this head)	0.745	2.55	inflexible devices counted once, 3.5 h over the limit
D7b	a31f1cf, repeat of D7	0.778	2.55	reproduces D7

• With the correction off, this PR behaves like fix(S2): the remaining findings (2 of 2) #279 (C2 vs C1).
• D6's match with C1 was an artefact. Its planned residual of 2.419 kW came from double-counted inflexible devices: at its peak, a house's planned aggregate power was exactly twice its inflexible load, with the heat pump planned at 0 kW. a31f1cf counts each device once, and D7's planned residual is back at C1's 0.21 kW.
• With the correction on, the community limit holds worse, and this is not noise (D7 and D7b agree). The correction device is never used. A single evening request plans much the same with or without the correction form, so the difference arises in the steering the community converges to. Details are in this comment; the cause is still being looked into.

The correction is opt-in. Until the cause is found, it should not be switched on for steered communities.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CcpawsJs74cSwFLXkz7ZwW

[coveralls]

Coverage Report for CI Build 42648128287

Warning

No base build found for commit 2e62cf2 on dev/s2-frbc-complete.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 96.188%

Details

• Patch coverage: 215 of 215 lines across 3 files are fully covered (100%).

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	3384
Covered Lines:	3255
Line Coverage:	96.19%
Coverage Strength:	4.42 hits per line

---

💛 - Coveralls

[Flix6x]

Co-simulation results for this PR: two simulated homes with heat pumps, one day, steered as a community under a 2 kW limit. Each run uses deterministic solver settings.

Run	Client	Usage correction	Breach (kWh)	Peak (kW)	Hours over the limit	Fallbacks
C1	#279	off	0.058	2.21	0.5	0
C2	a31f1cf	off	0.052	2.21	0.25	0
D7	a31f1cf	on	0.745	2.55	3.5	0
D7b	a31f1cf	on (repeat of D7)	0.778	2.55	3.75	0

Comfort was kept in every run, and no run fell back to its last plan.

What this shows:

• With the correction off, this PR behaves like fix(S2): the remaining findings (2 of 2) #279 (C2 vs C1). Its other changes, such as sending the usage with the request, do not change the outcome.
• The correction makes the community limit hold worse, and this is not noise (D7 and D7b agree). The correction device itself is never used: all its planned values are zero. In the evening, the homes' own plans run both heat pumps at once, while the community steering reports a planned residual of 0.21 kW, as in C1.
• Replaying one evening request in FlexMeasures gives about the same plan in every form tried. It was sent in the correction form, then without the correction device, then flattened as with the correction off. It was also replayed with FlexMeasures' default band breach price, and with usage clipped at zero. So a single home solves the same steering signals the same way either way. The difference arises over the community's iterations, in the steering the homes get back.
• Each home's stored inflexible devices are now counted once (a31f1cf; replay of D7's last request). The planned residual went from 2.419 kW (D6) back to 0.21 kW.

Next: find why the community steering converges to signals that leave the homes' plans over the limit when the correction is on. Until then, the correction (opt-in) should not be switched on for steered communities.