Fix Wh/W unit mismatch in peak shaving, add scenario charts to the docs

[MaStr]

Summary

Fixes a unit bug in the time and price peak shaving rules that made them too weak (or entirely inactive) at 15-minute resolution, and adds documentation showing how each rule behaves over an example day.

Four commits, reviewable in order:

Commit	Content
3f9a8c0	The fix + 3 regression tests
9b5c93f	scripts/verify_pv_surplus_charge_limit.py
0af8b3c	Scenario charts for the docs (CSV + Chart.js)
406df34	Document the min-charge-rate / solar-floor interaction

The bug

_calculate_peak_shaving_charge_limit and _calculate_peak_shaving_charge_limit_price_based summed the PV surplus per slot and then multiplied by interval_hours to "convert it to Wh":

total_cheap_surplus_wh += surplus * interval_hours

But production / consumption already hold Wh energy per slot, not average power. The extra multiplication shrank the computed surplus by a factor of interval_hours.

At 60-minute resolution interval_hours == 1.0, so the bug was invisible — which is why it survived. At 15-minute resolution (0.25) the surplus came out 4x too small, so the reservation and ramp caps were too loose or skipped entirely.

The unit convention is confirmed independently in three places:

• forecastsolar/baseclass.py — "values in Wh per 15 minutes"
• core.py — production[0] *= (1 - elapsed_in_current), a scaling that only makes sense for energy
• forecast_metrics.py — battery - net accumulated slot by slot with no interval_hours anywhere

solar_limit.py was never affected: it correctly converts the power limit into a per-slot Wh budget via feed_in_limit_w * slot_h.

Behaviour change

This is not cosmetic. At 15-minute resolution the rules were completely inactive across the whole range free_capacity < surplus <= 4 x free_capacity. They now engage there, often clamped straight to the 500 W minimum charge rate. Users running 15-minute resolution with peak shaving enabled will see noticeably more restrictive PV charging. Worth a mention in the release notes.

60-minute behaviour is bit-identical (multiplication by 1.0 was a no-op).

Verification

• The three new regression tests were checked against the pre-fix source: all three fail there with the predicted values (-1 != 2000, -1 != 400, 2400 != 600), and pass after.
• Full suite: 853 passed.
• scripts/verify_pv_surplus_charge_limit.py walks the Wh/W conversion step by step against the real compute_solar_limit(). Its cross-checks are asserts, so it fails if the production code stops matching the expected arithmetic.
• mkdocs build --strict: no warnings.
• The rendered docs page was loaded in Chromium: 8 charts painted, summary table populated, no error placeholders.

Documentation

New page Peak Shaving Scenarios walks one example day through all eight rule combinations (baseline, three solo rules, four combinations).

Data and presentation are separated: scripts/generate_peak_shaving_csv.py writes one CSV per configuration into docs/assets/data/peak_shaving/, and docs/assets/js/peak-shaving-charts.js renders them as interactive charts. The markdown only carries <div class="ps-chart" data-scenario="time"></div>.

The simulation drives the shipped implementation — it calls _apply_peak_shaving and _apply_solar_limit, the same two post-processing steps calculate_inverter_mode runs — so the published charts cannot drift from actual behaviour. The upstream discharge decision is stipulated so the charts isolate peak shaving; both the page and the script docstring state that scope.

Chart.js 4.4.1 (MIT) is vendored under docs/assets/js/vendor/ rather than loaded from a CDN, which keeps the build hermetic and the page working offline. The renderer fails visibly if the library is missing instead of leaving empty boxes.

The Deploy Documentation workflow regenerates the CSVs before mkdocs build; they are also committed so a local mkdocs serve works without running the script first.

Finding along the way

Building the charts surfaced a separate, pre-existing interaction: the solar cap rule sets cap == floor when free capacity is scarce so the battery absorbs only otherwise-curtailed energy, but enforce_min_pv_charge_rate raises anything below 500 W. At the edges of the clip window the floor is small, so the battery eats the capacity that was just reserved:

clip energy in the first three clip slots : 173 Wh
actually charged at the 500 W minimum     : 375 Wh
excess                                    : 202 Wh   -> curtailed later

solar_cap on its own therefore curtails slightly more than the time rule on the example day. This is a genuine trade-off rather than a clear defect (the 500 W minimum exists to avoid inefficient trickle charging), so no code was changed for it — it is documented on both pages and tracked in #409.

Notes

• No configuration parameters added or changed, so no HA add-on mirroring needed.
• pylint 10.00/10 on both new scripts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GLFFvTcH61V4pd21xjpd34

[Copilot]

Pull request overview

Fixes a unit mismatch in NextLogic peak shaving calculations where PV surplus (already provided as Wh per slot) was incorrectly multiplied by interval_hours again, understating surplus for sub-hourly resolutions (notably 15-minute slots) and weakening/skipping peak shaving caps. This aligns the time-based and price-based peak shaving logic with the forecast provider contract (energy-per-slot), and adds tests + documentation/simulation artifacts to prevent regressions.

Changes:

• Correct peak shaving surplus aggregation in NextLogic by removing the extra * interval_hours energy scaling while keeping the existing Wh↔W conversions where appropriate.
• Add 15-minute regression tests that would fail under the former double-scaling bug.
• Add documentation, charting JS/CSS, generated CSV scenario datasets, and CI docs-build steps to keep the published scenarios aligned with the shipped implementation.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/batcontrol/logic/next.py	Removes erroneous interval_hours multiplication when summing surplus energy in time/price peak shaving calculations.
tests/batcontrol/logic/test_peak_shaving.py	Adds/updates 15-minute interval tests to assert correct Wh-per-slot handling and prevent regression.
scripts/verify_pv_surplus_charge_limit.py	Adds a step-by-step verification script to desk-check Wh↔W conversions in the solar limit rule using production code.
scripts/generate_peak_shaving_csv.py	Adds a generator script producing scenario CSV datasets by exercising the real peak shaving + solar limit implementation.
scripts/README.md	Documents the new scripts and their intended usage.
docs/features/peak-shaving.md	Expands documentation around minimum charge-rate interaction and links to the scenarios page.
docs/features/peak-shaving-scenarios.md	New documentation page explaining and embedding scenario charts backed by generated CSVs.
docs/assets/js/peak-shaving-charts.js	Adds client-side rendering of scenario charts from generated CSVs (Chart.js).
docs/assets/css/peak-shaving-charts.css	Adds styling/layout for the scenario charts and summary table.
docs/assets/js/vendor/chart.umd.js	Vendors Chart.js for documentation rendering without external CDN dependency.
docs/assets/data/peak_shaving/*.csv	Adds generated scenario datasets consumed by the docs charts (baseline + rule combinations + summary).
mkdocs.yml	Registers the new scenarios page and includes the chart JS/CSS assets.
.github/workflows/docs.yml	Installs the package and generates scenario CSV data as part of the documentation build pipeline.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.