[Flix6x]

Stacked on #286 (base feat/s2-usage-correction). Merge #286 first.

Follows up on a review comment on #283: "If S2 states a rate, shouldn't this then be better modelled as an extra component in the soc-usage list?"

Why

S2 states leakage as a rate per fill-level range, in fill-level units per second. FRBCSimple planned it as a storage-efficiency, which FlexMeasures takes as a share of the stock. So the plan had the storage leak in proportion to how full it was, which was exact at one fill level only, and S2 does not say leakage is proportional.

What

• Leakage as usage. The leakage rate of the fill-level range the storage starts in is added to soc-usage, constant over the schedule window, and sent with the request. No storage-efficiency is sent any more.
• With a usage correction (feat(FRBC): correct a usage forecast no plan can absorb, instead of clipping it #286), the correction's limits and the stock's usage cover the forecast and the leakage together. An empty storage cannot give its leakage either, so the correction can take that away like any other forced usage.
• Without a correction, the forecast and the leakage are added up first and then clipped at zero, as the forecast alone was.
• Recorded as a rate. The leakage sensor now records the rate itself, in the fill-rate unit, over the window, so what the resource manager declares can still be seen next to the schedule. A failed recording no longer blocks the plan, since the leakage goes with the request. The site sensor is now called leakage (kWh/s) instead of storage efficiency (%), in FRBC_SITE_SENSORS and the example server.
• Older servers. Only a usage given with the request can carry the leakage, which FlexMeasures supports from v0.23.0. An older server is planned without leakage, and this is logged.
• Correction price. Leakage planned as a usage drains the same whatever the stock, so the storage term of the correction price's bound is now 1.

Caveats

• A flat rate keeps draining an empty storage, where physical leakage stops. That is the same situation as a usage forecast the storage cannot absorb, which the usage correction handles.
• The rate depends on the fill-level range, and the plan moves the fill level. With one series, the range the storage starts in is used, as before.

Evidence

• Tests: 815 pass. New or rewritten tests cover the rate per starting range, scaling by fill_level_scale, recording the rate (and not again for the same window), planning despite a failed recording, an older server, leakage without a usage forecast or its sensor, the correction covering both, clipping both together without a correction, and the correction price's storage term. Each fails when its behaviour is broken.
• Mutation gate: 14 of 14 mutants killed, including three ported from feat(FRBC): correct a usage forecast no plan can absorb, instead of clipping it #286's set whose code this changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CcpawsJs74cSwFLXkz7ZwW

[coveralls]

Coverage Report for CI Build 42683851519

Warning

No base build found for commit 905254e on feat/s2-usage-correction.
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.203%

Details

• Patch coverage: 44 of 44 lines across 2 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:	3397
Covered Lines:	3268
Line Coverage:	96.2%
Coverage Strength:	4.41 hits per line

---

💛 - Coveralls

[Flix6x]

kWh/s would be a terrible unit to read typical residential values in (in FM UI and logs). I would pick a better FM sensor unit.

[Flix6x]

Agreed. Rates of fill level (the fill rate, the usage forecast and the leakage) are now recorded in a power unit instead of per second. There is a new fill_rate_unit setting, like energy_unit and power_unit: W (the default), kW or MW. The site creates these three sensors in W, so the example's leakage reads 62.5 W instead of 1.7e-5 kWh/s (ca1bfb7, 83fbf23; changelog updated). An existing site keeps the fill rate and usage forecast sensors it already has in kWh/s; FlexMeasures converts the posted values into them.

[Flix6x]

Applied to every sensor the CEM sets up, in 3b18345: power, measured-power and usage correction are now in W as well, so every power and rate of fill level a new site gets is in W, the handler's default. Energy and fill levels stay in kWh, and prices per kWh. A larger site, such as one with charge points, can pass its own sensors and set power_unit and fill_rate_unit. A site created before this keeps its sensors, and the CEM now logs a warning for each one in a different unit than a new site would get.

[Flix6x]

Dropped the warning about a kept sensor in another unit again (f2d9cca): FlexMeasures converts what is posted into the sensor's own unit, so there is nothing to warn about.