[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 recorded and planned as stated. 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.

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.

Evidence

• Tests: 802 pass, 40 of them new; diff coverage 193 of 193 added statements.
• Mutation gate: 35 of 35 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 (this head)	0.052	2.21	no fallbacks, no infeasible jobs

D6 matches C1 on breach and peak. Cost differences between these runs are within what repeats of the same code showed on #279, so I draw no conclusion from them. One difference remains open: the community planner reports a planned residual breach of 2.419 kW at each step in D3 and D6, against at most 0.21 kW in C1, while the realized breach is the same.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CcpawsJs74cSwFLXkz7ZwW

[coveralls]

Coverage Report for CI Build 42532459987

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.168%

Details

• Patch coverage: 197 of 197 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:	3366
Covered Lines:	3237
Line Coverage:	96.17%
Coverage Strength:	4.43 hits per line

---

💛 - Coveralls