Skip to content

feat(forecast): Phase 4 – PR 4-E Lastprognose und Risikomodell für Puffer und Ziele - #30

Open
PXLJAKE wants to merge 11 commits into
phase-4/d-pv-forecastfrom
phase-4/e-load-risk
Open

PXLJAKE wants to merge 11 commits into
phase-4/d-pv-forecastfrom
phase-4/e-load-risk

Conversation

@PXLJAKE

@PXLJAKE PXLJAKE commented Oct 23, 2026

Copy link
Copy Markdown
Owner

Gestapelt auf #29 (PR 4-D). Die Basis wird nach dem Merge der Vorgänger umgestellt.

Was

WP6 und WP7 aus docs/plans/phase-4.md.

WP6 – Lastprognose (suncore/forecast/load.py, load_service.py, stats.py, days.py):

  • Grundlast = Haus − alle konfigurierten Geräte, jedes genau einmal. Viertelstunden mit nicht gemessenem Gerät fallen aus dem Profil, sobald es genug voll gemessene Tage gibt.
  • Neuaufbau aus HA holt jetzt auch die Leistungssensoren der Geräte nach. So stecken die Geräte in den ersten Wochen nicht doppelt in der Grundlast.
  • Profile je Tagtyp (Werktag, Wochenende, Feiertag) × 96 Viertelstunden:
    • exponentiell geglättet (Halbwertszeit 21 Tage), robust gegen Ausreißer;
    • fehlen Daten für einen Tagtyp, wird auf den ähnlichsten ausgewichen: Feiertag → Wochenende → alle Tage ohne Feiertage.
  • Feiertage optional über einen workday-Sensor: Zustand für heute, workday.check_date für andere Tage. days_offset wird ausgeglichen. Der Cache trägt einen Fingerabdruck der Sensor-Konfiguration.
  • Temperatur optional: Heiz- und Kühlterm begrenzt, aus selbst aufgezeichneter Temperatur der Wetter-Entität. temperature_unit ist am HA-Quelltext geprüft, °C/°F/K. Wirkt nur für fast volle Prognosetage.
  • Bänder und Kaltstart: P10/P90 aus den Residuen. Ab Tag 1 nutzbar durch die 28 aus HA nachgeladenen Tage, sonst Kaltstart mit breitem Band.
  • Gütemessung im Nachtjob, Speicherung stündlich. API GET /api/v1/forecast/load?hours=48.

WP7 – Risikomodell (suncore/forecast/risk.py, risk_learning.py):

  • Fenster: rest_of_night, rest_of_today, night, next_day, bridge (Nacht und nächster Tag als ein Quantil) und day_and_night.
  • Gelernte Verteilung des Netto-Energiefehlers (PV − Last) je Fenster × Wetterklasse:
    • aktiv ab 30 Tagen mit Stichproben;
    • Lernzeitpunkte an Sonnenaufgang + 1 h und Sonnenuntergang − 1 h;
    • Fenster mit abgeregelten Slots und Fenster ohne vollständige Prognose werden nicht gelernt.
  • Vorher: Quantile der Quellen. PV und Last gelten als unabhängig, gerechnet mit einer zweiteiligen Normalverteilung; die Formel steht im Modul. Ohne P10/P90 der PV-Quelle gilt ein Standardband je Wetterklasse (default_band, UNVERIFIED).
  • Funktionen für den Planer, jede mit Reason:
    • net_energy_quantile
    • morning_buffer_pct: ein Quantil über Tag und Nacht, ohne doppelte Vorsicht
    • evening_target_pct: Reserve + Nacht, mit bridge_next_day zusätzlich der Fehlbetrag des nächsten Tages
  • Untergrenzen und Strategie:
    • Die Untergrenze ist effective_reserve_pct = max(Min-SoC der Anlage, Reserve + Drift) (ADR-0013 §3, neu in core/battery.py).
    • Nie über Max-SoC.
    • goals.battery_target gilt als Untergrenze des Abendziels (vom Maintainer bestätigt); die zeitgebundene Bedingung kommt in 4-F.
    • prefer_full setzt den Morgenpuffer auf Max-SoC.
  • API GET /api/v1/forecast/risk.

Warum

Plan §0, aus dem zusammengeführten Konzept: Der Akku soll die Nacht und möglichst auch einen schlechten nächsten Tag abdecken. Der Puffer wird aus dem gelernten Prognoserisiko berechnet, mit „vorsichtig“ als Standard. Der Planer (4-F) liest diese Werte direkt.

Wie getestet

  • ./scripts/check.sh grün: 3807 Python-Tests, 219 Frontend-Tests, Abdeckung 96 %. markdownlint ohne Fehler.

  • Hypothesis-Tests:

    • Puffer und Abendziel steigen monoton mit Risikostufe, PV-Unsicherheit und Lastband, auch auf dem gelernten Pfad.
    • Sie liegen nie unter den manuellen Grenzen, nie unter dem Min-SoC der Anlage und nie über Max-SoC.
  • Szenarien:

    Szenario Ergebnis
    Sonniger Tag niedriger Puffer
    Wechselnd bewölkt höherer Puffer
    Zwei schwache Tage Abendziel auf Max-SoC
    Prognose wochenlang zu optimistisch höheres Abendziel nach 30 Tagen
  • Weitere Tests:

    • Workday-Versatz zusammen mit check_date.
    • Lernen ohne PV-Prognose.
    • Gemeinsame Heiz- und Kühlregression.
    • Lastprognose über den Sommerzeit-Wechsel.
    • Sonnen-Anker im Winter und im Sommer.
    • Fenster vor Sonnenaufgang.
  • Laufzeit: Ein Refit dauert im amd64-Container 118–163 ms, die Prognose etwa 1 ms. aarch64 ist noch nicht gemessen.

Risiken

  • Konstanten nicht kalibriert: Alle Konstanten von Last- und Risikomodell sind begründet, aber nicht an echten Daten eingestellt (UNVERIFIED). Das betrifft auch die Standard-PV-Bänder.
  • Neuaufbau nur einmal: Ein Neuaufbau, der schon gelaufen ist, wird nicht wiederholt. Bestehende Test-Installationen bekommen die Geräte-Historie nicht nachträglich; beim Maintainer läuft der Neuaufbau zum ersten Mal mit 4-B.
  • Gerätewechsel: Nach Änderungen an der Geräteliste werden Historie und Risiko-Stichproben nicht neu abgeleitet (in STATUS dokumentiert).
  • Allowlist: workday.check_date ist neu auf der Read-only-Allowlist, am HA-Quelltext als SupportsResponse.ONLY ohne Zustandsänderung geprüft. Die Aufrufe laufen über den Ratenbegrenzer, höchstens 12 je Lauf.
  • Commit-Historie: Mehrere ähnliche feat-Commits wegen der Nutzungslimits. Squash-Merge empfohlen.

Safety-Review

n/a laut Reviewer: Kein Geräte-Schreibpfad. Allowlist, Grenzregeln und Ratenbegrenzer halten. Der Last-Task wird beim Stoppen erst nach der Gerätefreigabe abgewartet. Die Reserve-Untergrenze folgt ADR-0013; 4-G nutzt dieselbe Funktion im Gate.

Checkliste

  • Tests für neues Verhalten, Lint/Typen/Tests grün
  • Keine hardcodierten UI-Strings; neue Keys in en und de (Reason-Texte nennen die eingestellte Risikostufe)
  • Doku aktualisiert (Plan-Abweichungen, Recherche: temperature_unit, workday days_offset)
  • docs/STATUS.md aktualisiert
  • Nichts erfunden: Quellen geprüft, Offenes als UNVERIFIED

Offene Fragen an den Maintainer

Beantwortet am 2026-10-23: goals.battery_target bleibt Untergrenze des Abendziels, und ein Feiertag unter der Woche zählt anfangs wie ein Wochenende.

Für die beiden neuen Fragen gilt ohne Antwort der Standard:

  1. Morgenpuffer: Verbraucher haben Vorrang, sobald nach heute und der kommenden Nacht beim gewählten Risiko noch mindestens eine weitere durchschnittliche Nacht übrig ist. Standard: so lassen.

  2. Standard-PV-Bänder, solange eine Quelle kein P10/P90 liefert:

    Wetterklasse unteres Band oberes Band
    klar 0,85 1,10
    gemischt 0,55 1,35
    bedeckt 0,35 1,70

    Dich betrifft das nicht, Solcast liefert P10/P90. Standard: so lassen.

  3. UNVERIFIED:

    • ob deine Wetter-Integration stündliche Vorhersagen liefert;
    • workday.check_date über den Supervisor-Proxy.

Generated by Claude Code

claude added 11 commits October 21, 2026 22:36
…ce (WP6)

Base load = house minus the configured devices; profiles per day type and
quarter hour with exponential smoothing (half-life 21 days), clipped z-score,
shrinkage for thin day types, optional temperature term, residual quantiles,
cold start. forecast.load gains optional workday/weather entity refs
(additive in v2, carried through by the wizard form); workday.check_date
joins the read-only actions; accuracy bookkeeping can score the load forecast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
… (WP6)

GET /api/v1/forecast/load; load_profile accuracy in the nightly job and in
/forecast/accuracy; HaLoadReader (workday state, workday.check_date,
weather temperature and weather.get_forecasts hourly); the service is
rebuilt on forecast/devices changes and refits after the history rebuild.
Demo: deterministic workday sensor and weather entity, battery model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…arget functions (WP7)

Windows rest_of_today/night/next_day/bridge anchored on the next sunset;
net energy quantile from the learnt relative errors per window and
weather class after min_history_days, else from the source quantiles
(two-piece normal, PV and load independent); morning_buffer_pct and
evening_target_pct with structured reasons, manual limits and max SoC
always winning, prefer_full = max SoC. Hypothesis and scenario tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…k view (WP7)

Samples per anchor day from the forecasts at 06:00 (rest_of_today) and
18:00 (night, next_day, bridge) against measured PV and base load, kept
365 days in learned_param net_error; GET /api/v1/forecast/risk with the
windows, morning buffer, evening target, reasons and distribution source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…and targets (WP6, WP7)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…rning and one quantile for the morning buffer (WP7 review)

- M4: core.battery.effective_reserve_pct (ADR-0013 decision 3) is the floor
  of evening target and morning buffer; never below the site min SoC.
- M5: a PV forecast without a band uses a default relative band per
  weather class (default_band, UNVERIFIED constants) until learnt.
- M3: a window is learnt only if the PV and load forecasts cover it;
  without a PV forecast only the night. Coverage now counts the window's
  slots (a series that ends early no longer looks complete).
- m2: rest_of_night (now to sunrise) instead of mixing it into
  rest_of_today; m3: anchors sunrise + 1 h and sunset - 1 h; m4: clipped
  daytime windows are dropped (flags from the PV nightly job).
- m7: the morning buffer uses one quantile over the new day_and_night
  window against the median night need (no comfort factor).
- n1: reasons name the configured risk level; n3: evening_at documented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…and use only full temperature days (WP6 review)

- M1: Home Assistant evaluates the workday sensor and workday.check_date
  for the date plus days_offset; the sensor's state is placed on
  today + offset and check_date is asked for d - offset.
- m6: the cached answers carry a fingerprint (entity id, workdays,
  excludes, days_offset); a change drops them.
- m5: the temperature term shifts a forecast day only with >= 20 hours of
  recorded or forecast temperatures.
- n4: the demo workday sensor uses the scenario's local date.
- m8: tests for the offset, the joint heating/cooling regression and a
  forecast over the DST day.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
… devices out of the base load profile (WP6 review M2)

The statistics rebuild also fetches every device's power sensor (mean, W)
into device.<id>.power_w. Quarter hours where a device has no measurement
are left out of a day type's profile once it has 7 fully measured days;
before that they are kept and the day type is flagged
(unmeasured_in_profile in GET /forecast/load).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…elvin (review n2)

Home Assistant always sets temperature_unit on a weather entity and converts
the forecasts to it (weather/entity.py state_attributes, _convert_forecast,
core 5cfe9aad); UnitOfTemperature includes K, which is now converted instead
of dropped. Research note records it and the verified workday offset.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants