Skip to content

feat(battery): learn charge and discharge rate grids (SoC x battery temperature) - #6212

Merged
springfall2008 merged 18 commits into
mainfrom
feat/battery-rate-grids
Nov 15, 2026
Merged

springfall2008 merged 18 commits into
mainfrom
feat/battery-rate-grids

Conversation

@springfall2008

@springfall2008 springfall2008 commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Why

The plan models the rate a battery achieves as min(rated x SoC curve, temperature cap). Fleet data says the two interact: a cold battery starts tapering at a lower SoC. On one install the taper begins around 80% SoC at 28 C, around 60% at 20 C, and almost straight away at 12 C. No SoC curve plus temperature cap can represent that.

A per-install rate grid (rate as a fraction of rated, by SoC and battery temperature), fitted by weighted least squares under a monotone rule, was tested against 26 fleet installs. Each model was fitted on 80% of the measured cells and scored on the rest, in 5 folds:

Holdout test Grid Today's model
Random cells held out (mean error, fraction of rated) 0.050 0.083
Whole temperature degrees held out 0.058 0.117
Installs where the grid was better (degrees held out) 23 of 25

What changes

  • One grid per direction (charge, discharge): 101 SoC columns x whole degrees. It is learned from runs of 15 minutes or more at the full written rate; the first and last 5 minutes are dropped and the rest is cut into 5-minute segments.
  • Evidence is ignored when it shows a failure, not a limit: the battery not charging or discharging, a forced export that did not reach the grid (from grid_power), an export-limited minute, or a temperature reading of exactly 0 (treated as missing).
  • The fit: weighted isotonic regression (Dykstra's projections over PAVA). The rate never rises with SoC (charge) or as SoC falls (discharge), or as the temperature falls. Weights halve every 90 days, evidence is kept for a year, and values are capped at 1.2.
  • Fallback: a learned grid is used from 20 cells over 3 days. The apps.yaml curves (battery_*_power_curve, its _default, battery_temperature_*_curve) are converted into a grid and act as the fallback and prior. Below the evidence a manual cold curve still applies; Predbat never extrapolates a slower rate.
  • Learning is on by default: battery_rate_grid_auto: False plans with the manual curves only. Setting a manual curve no longer turns learning off.
  • History windows: battery_rate_grid_history_days (default 28) is what the first scan reads, and any scan until one succeeds. battery_rate_grid_scan_days (default 2) is what each daily scan reads, widened after a gap. A failed history read is retried after an hour. Reads longer than days_previous pass tracked=False, so the history cache doesn't keep 28 days of each sensor afterwards.
  • Engine: each plan step reads one SoC curve, picked from the grid by that step's forecast temperature. The C++ kernel takes a table of curve rows and a row index per step (ABI 12, parity revision 22, all six binaries rebuilt).
  • Ceiling: on a path at or below the rated rate (AC charge, export) the ceiling is absolute, so a cold 1 kW limit is 1 kW on both. On a path above the rated rate (a hybrid's DC charge from PV) a learned grid scales with the path, as the SoC curve did, because the history only measures the battery up to its rated rate. A manual temperature cap stays absolute there too; each curve row carries it as an extra entry, so kernel rows are 103 wide. A request below the ceiling is never scaled.
  • Removed: the separate SoC curve learner, the temperature curve learner and battery_temperature_charge_curve_auto (added in feat(battery): learn the temperature charge curve, keep auto SoC curves in storage and out of the cold #6189), the discharge temperature evidence, and their four sensors.
  • New sensors: binary_sensor.predbat_battery_charge_rate_grid and binary_sensor.predbat_battery_discharge_rate_grid.
  • Curves page: both grids in 3D (plotly gl3d, loaded on that page only) with the last 90 days of evidence as dots, a short 10% x 5 C table of each, and a status table.

Behaviour changes to note

  • Plans from manual curves are unchanged on the golden debug cases.
  • The random-scenario baseline is regenerated: 8 of 20 plans move. The template's DC charge maximum (1 kW) is below the rated AC rate, so the DC path now uses the battery's absolute taper rather than 1 kW x the curve. Reproduced on scenario 15 against the pre-change engine.
  • With no curves set at all, the old 1C cap from find_battery_temperature_cap is kept, so the default grid plans exactly as before.

Speed (predbat_debug_agile1.yaml, 3 runs each)

Before After
C++ kernel 0.443-0.478 s 0.446-0.477 s (no difference beyond noise)
Python only 16.0 s 15.6-15.9 s

The Python path was 27% slower at first, because a shared lru cache hashed the 101-entry curve on every lookup. Each curve now gets its own small-keyed cache (utils.rate_curve_function).

Review fixes (independent whole-branch review: 0 critical, 6 important)

  • Storage outages: a store that does not read back is only treated as empty after failed reads on 3 cycles spanning 10 minutes, so an outage cannot let one scan replace the stored year.
  • Ignored commands: discharge evidence needs grid_power history, and a charge minute needs grid import when that history exists. An ignored command (the battery covering the house, or charging from PV only) is no longer learned as a slow battery.
  • Gaps: with no manual curves, gaps are interpolated from the measured neighbours instead of being filled to the highest rate the rule allows.
  • Cache size: the per-curve lookup caches are bounded at 64 curves x 2048 lookups; unbounded, they could reach about 2 GB over weeks.
  • Manual temperature caps: a grid learned without temperature is capped by a manual temperature curve at every degree. Below the evidence only the manual temperature cap applies, not the manual SoC curve. A manual cap stays absolute on a hybrid's DC path. An exact 0 with a learned grid takes the manual exact-0 cap.
  • Debug dumps: the year of evidence and the derived grids are kept out of debug dumps (and so out of debug_history snapshots); replay rebuilds them from the learned grids.

Deferred minors:

  • Rate scaling is divided out at scan time, so it is applied twice to stored evidence if battery_rate_max_scaling changes later.
  • A 0-1 C reading looks up a manual curve at the whole degree (1).
  • A fluctuating soc_max refits every cycle.
  • A temperature sensor added or removed later discards or freezes the evidence gathered without it.

Tests

New tests cover the grid maths, the scan (including failure filters, exact 0 and export limits), storage/fallback/sensors, the absolute ceiling, kernel parity with a cooling forecast crossing grid rows, and the Curves page. The quick suite and pre-commit pass, as do kernel parity and the debug and random goldens.

🤖 Generated with Claude Code

CI and others added 17 commits November 15, 2026 18:53
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Runs of 15+ minutes at the full written rate, 5 minutes dropped at each end, the rest cut into 5-minute segments
(SoC, temperature, rate / rated / battery_loss / rate scaling). A minute where the battery did not move, a forced
export that did not reach the grid, or an exact 0 temperature reading breaks the run. grid_power loading is factored
out of find_export_limited_minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… grids

battery_rate_grid_update() builds the manual grid from the apps.yaml curves (fallback and prior), scans the history
daily for grid evidence, keeps it in storage for a year and fits the learned grid; battery_rate_grid_auto (default on)
lays it over the manual one. Two binary sensors (battery_charge/discharge_rate_grid) carry the source, evidence and a
coarse grid. battery_temperature_charge_curve_auto is removed, and setting a manual curve no longer turns learning off.
The old learners are unwired; their tests go (the temperature-cap rule tests move to test_battery_rate_grid).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The plan reads one 101-entry battery ceiling curve per step, picked from the charge/discharge rate grids by that
step's forecast temperature (Prediction.rate_curves). The grids are derived on demand (PredBat.rate_grids), keyed on
the curves, battery size and learned grids, so a tariff comparison or debug replay never plans with a stale one.

The ceiling is absolute on a path at or below the rated rate (AC charge, export): a cold limit is the same kW on
each. On a path above it (a hybrid's DC charge) the curve scales with the path, as the SoC curve did, because the
history only measures the battery up to its rated rate. A request below the ceiling is never scaled.

find_charge_rate and get_*_rate_curve take the curve in place of the SoC curve and temperature curve. The hot path
uses per-curve cached lookups (rate_curve_function): keying one shared cache on the 101-entry curve cost 27%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The kernel context's temperature cap arrays and single SoC curves become a small table of rate grid curve rows
(102 wide: 101 SoC percents then the rated rate) and a row index per step; rate_curve_pct mirrors
utils.rate_curve_ceiling. ABI 11 -> 12, parity revision 20 -> 22, all six binaries rebuilt with zig.

Parity edge cases cover a forecast cooling through learned grid rows. The random scenario baseline is regenerated:
8 of 20 plans move because the template's 1 kW DC charge maximum is below the rated AC rate, so the DC path now
uses the battery's absolute taper rather than 1 kW x the curve.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…D with a short table

A status table for the two grids (source, cells, evidence days, temperature range, when learned, last scan), then
each grid as a plotly 3D surface (SoC x temperature x rate / rated, gl3d bundle loaded on this page only) with the
last 90 days' evidence segments as dots, and the grid at 10% SoC x 5 C as a table. The old ApexCharts curve charts go.

Also: warmer than the evidence a learned grid is no longer capped by the manual grid - that made a warmer row slower
than the warmest learned one (seen on fleet data: 1.00 at 35 C under 1.11 at 30 C).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…limmer colour bar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ners

The SoC curve finder and learner (and the path that logged a curve for apps.yaml), the temperature curve learner
and overlay, the discharge temperature evidence, their sensors, attributes and constants are replaced by the rate
grids. find_charge_curve's tests go with it; its export-limit cases move to the rate grid scan tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
apps-yaml.md gains a Battery rate grids section (learning, battery_rate_grid_auto, what is ignored, the exact-0
rule, fallback to the apps.yaml curves, the absolute ceiling and the hybrid DC exception, the sensors and the Curves
page); the old auto-curve and temperature-learning text goes, the manual curve reference stays. FAQ, setup,
customisation and web interface pages follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nds, gaps, cache size, debug dumps

- A store that does not read back is only treated as empty once its reads have failed on 3 cycles over 10 minutes;
  until then a save waits, so a storage outage cannot let one scan replace a year of evidence.
- Discharge evidence needs grid_power history (an ignored forced export looks like a slow battery otherwise), and a
  charge minute needs grid import when there is history (a charge command ignored while PV charges the battery).
- With no curve set in apps.yaml, gaps in the evidence are interpolated from the measured neighbours instead of
  leaning on the default grid, which filled them to the highest rate the rule allowed.
- The per-curve lookup caches are bounded (64 curves x 2048 lookups); unbounded they could reach ~2 GB over weeks.
- The year of evidence and the derived grids are kept out of debug dumps; replay rebuilds them from the learned grids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…arned without temperature

Review fixes:
- A grid learned with no temperature (battery_temperature but no battery_temperature_history) was used at every
  temperature, dropping a manual temperature curve; it is now capped by it at each degree.
- Below the evidence only the manual temperature cap applies, not the manual SoC curve (the learned rows carry the taper).
- On a hybrid's DC path above the rated rate a learned grid scales with the path, but a manual temperature cap now
  stays absolute in kW, as it did before the grids: each curve row carries it as entry 102 (kernel rows 103 wide,
  parity revision 23, binaries rebuilt).
- An exact 0 reading with a learned grid takes the manual exact-0 cap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…try hourly, and keep long reads out of the history cache

- battery_rate_grid_history_days (default 28): the first scan, and any until one has succeeded, reads this much history
  (as much as there is). battery_rate_grid_scan_days (default 2): later scans read this much - a day since the last
  plus a day's overlap - widened to cover a longer gap since the last successful scan, capped at the history setting.
- A scan whose history read failed is retried after 60 minutes instead of a day, without losing the full first window.
- A read longer than days_previous passes tracked=False, so the history cache does not keep (and refresh every cycle)
  28 days of each sensor from then on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@springfall2008
springfall2008 marked this pull request as ready for review November 15, 2026 19:37
@github-actions github-actions Bot added the BOT_REVIEW Trigger an autotriage label Nov 15, 2026
…ta pad option

minute_data() and minute_data_state() fill every minute of the window they are asked for, padding the time before
the oldest record. With the 28-day first scan and Home Assistant's default 10 days of history, the padded days
counted as coverage, so the per-day merge removed stored evidence the scan never saw (and padding could form fake
full-rate runs). Both functions gain pad (default True, unchanged for every other caller); the rate grid scan passes
pad=False for every history it reads and stops at the shortest real history, temperature and grid_power included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@springfall2008

Copy link
Copy Markdown
Owner Author

Automated review failed to complete for this PR. Reason: Claude ran out of turns before finishing (--max-turns) (exit status 1). Failed at: triage_daemon.py:2133 in review_pr() (daemon 9573cbed). Log: pr-6212-review.log in the bot's logs directory. Not retrying automatically; remove BOT_FAILED and re-add BOT_REVIEW to try again.

@springfall2008 springfall2008 added BOT_FAILED An automated triage/PR attempt failed; see the comment for details and removed BOT_REVIEW Trigger an autotriage labels Nov 15, 2026
@springfall2008
springfall2008 enabled auto-merge (squash) November 15, 2026 19:56
@springfall2008
springfall2008 merged commit 5319072 into main Nov 15, 2026
8 checks passed
@springfall2008
springfall2008 deleted the feat/battery-rate-grids branch November 15, 2026 19:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

BIG_ROCK BOT_FAILED An automated triage/PR attempt failed; see the comment for details

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant