warmcast 0.1.0__py3-none-any.whl

warmcast/core/__init__.py

@@ -0,0 +1,156 @@
+"""Warmcast core engine. Callers import from here, never from the submodules."""
+
+from .backtest import GATE2_DAYS, GATE2_MAE_C, NightlyFit, Scorecard, ZoneSummary, walk_forward
+from .engine import Engine
+from .house import (
+    EMITTER_PRIORS,
+    INTERNAL_GAIN_KW,
+    THERMOSTAT_SUN_C_PER_KW_PV,
+    ComfortBand,
+    Emitter,
+    EmitterPriors,
+    House,
+    HouseConfigError,
+    OffPeriod,
+    Prior,
+    SolarGain,
+    Zone,
+    ZoneId,
+    ZoneSensor,
+    parse_house,
+)
+from .learning import (
+    Accepted,
+    FitOutcome,
+    KeptPrevious,
+    NotEnoughData,
+    Scores,
+    ShapeChoice,
+    estimate_dhw_baseline,
+    learn,
+)
+from .model import (
+    CODE_VERSION,
+    AirAndFabric,
+    AirOnly,
+    DiscreteZone,
+    Drivers,
+    Estimate,
+    FitWindow,
+    HeatShare,
+    ThermalModel,
+    Trajectory,
+    ZoneShape,
+    ZoneState,
+    describe_thermostats,
+    discretise,
+    drivers_from_segment,
+    estimate_state,
+    prior_model,
+    prior_shape,
+    share_heat,
+    simulate,
+    solar_gain_kw,
+    thermostat_offset_c,
+)
+from .ports import HistorySource, ModelStore
+from .scoring import PvForecast, ZoneDayScore, nightly_cutoff, scorable_days, score_day
+from .settings import LearnSettings
+from .signals import (
+    Aggregation,
+    DataReport,
+    Feed,
+    FeedCoverage,
+    HeatSource,
+    History,
+    HourlyStats,
+    RawSeries,
+    RawValue,
+    Samples,
+    Segment,
+    Signal,
+    ZoneSeries,
+    build_history,
+    house_feeds,
+)
+from .sun import morning_weight, sun_position
+
+__all__ = [
+    "CODE_VERSION",
+    "EMITTER_PRIORS",
+    "GATE2_DAYS",
+    "GATE2_MAE_C",
+    "INTERNAL_GAIN_KW",
+    "THERMOSTAT_SUN_C_PER_KW_PV",
+    "Accepted",
+    "Aggregation",
+    "AirAndFabric",
+    "AirOnly",
+    "ComfortBand",
+    "DataReport",
+    "DiscreteZone",
+    "Drivers",
+    "Emitter",
+    "EmitterPriors",
+    "Engine",
+    "Estimate",
+    "Feed",
+    "FeedCoverage",
+    "FitOutcome",
+    "FitWindow",
+    "HeatShare",
+    "HeatSource",
+    "History",
+    "HistorySource",
+    "HourlyStats",
+    "House",
+    "HouseConfigError",
+    "KeptPrevious",
+    "LearnSettings",
+    "ModelStore",
+    "NightlyFit",
+    "NotEnoughData",
+    "OffPeriod",
+    "Prior",
+    "PvForecast",
+    "RawSeries",
+    "RawValue",
+    "Samples",
+    "Scorecard",
+    "Scores",
+    "Segment",
+    "ShapeChoice",
+    "Signal",
+    "SolarGain",
+    "ThermalModel",
+    "Trajectory",
+    "Zone",
+    "ZoneDayScore",
+    "ZoneId",
+    "ZoneSensor",
+    "ZoneSeries",
+    "ZoneShape",
+    "ZoneState",
+    "ZoneSummary",
+    "build_history",
+    "describe_thermostats",
+    "discretise",
+    "drivers_from_segment",
+    "estimate_dhw_baseline",
+    "estimate_state",
+    "house_feeds",
+    "learn",
+    "morning_weight",
+    "nightly_cutoff",
+    "parse_house",
+    "prior_model",
+    "prior_shape",
+    "scorable_days",
+    "score_day",
+    "share_heat",
+    "simulate",
+    "solar_gain_kw",
+    "sun_position",
+    "thermostat_offset_c",
+    "walk_forward",
+]

warmcast/core/backtest.py

@@ -0,0 +1,112 @@
+"""Replaying the nightly loop over past days, to see how well it would have predicted them."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+import numpy as np
+
+from .house import House, ZoneId
+from .learning import Accepted, FitOutcome, learn
+from .model import ThermalModel, prior_model
+from .scoring import ZoneDayScore, nightly_cutoff, scorable_days, score_day
+from .settings import LearnSettings
+from .signals import History
+
+GATE2_DAYS = 7
+GATE2_MAE_C = 0.5
+
+
+@dataclass(frozen=True)
+class NightlyFit:
+    """The refit that ran at 22:00 on the evening before `day`."""
+
+    day: date
+    outcome: FitOutcome
+
+
+@dataclass(frozen=True)
+class ZoneSummary:
+    zone: ZoneId
+    days: tuple[date, ...]
+    mae_c: float
+    max_error_c: float
+
+
+@dataclass(frozen=True)
+class Scorecard:
+    """Per zone and day, what the nightly loop predicted and what happened.
+
+    `unscored` lists the days whose readings did not cover the replay.
+    """
+
+    rows: tuple[ZoneDayScore, ...]
+    fits: tuple[NightlyFit, ...]
+    unscored: tuple[date, ...]
+    run_seconds: float
+
+    def summary(self, last_days: int = GATE2_DAYS) -> Mapping[ZoneId, ZoneSummary]:
+        """Each zone's mean and largest absolute peak error over its last scored days."""
+        by_zone: dict[ZoneId, list[ZoneDayScore]] = {}
+        for row in self.rows:
+            by_zone.setdefault(row.zone, []).append(row)
+        out = {}
+        for zone, rows in by_zone.items():
+            recent = sorted(rows, key=lambda r: r.day)[-last_days:]
+            errors = np.abs([r.error_c for r in recent])
+            out[zone] = ZoneSummary(
+                zone, tuple(r.day for r in recent), float(np.mean(errors)), float(np.max(errors))
+            )
+        return out
+
+    def gate2_met(self) -> bool:
+        """Every zone has seven scored days and a mean peak error within 0.5 °C over them."""
+        summaries = self.summary(GATE2_DAYS).values()
+        return bool(summaries) and all(
+            len(s.days) == GATE2_DAYS and s.mae_c <= GATE2_MAE_C for s in summaries
+        )
+
+
+def walk_forward(
+    history: History,
+    house: House,
+    first_day: date,
+    last_day: date,
+    settings: LearnSettings = LearnSettings(),  # noqa: B008
+    refit_every_days: int = 1,
+) -> Scorecard:
+    """Replay the nightly loop from `first_day` to `last_day`, both included.
+
+    Before each day, `learn` runs on the readings up to 22:00 the evening before, with the
+    model the loop would have carried from earlier nights (none at the start), and its
+    accept rule decides which model predicts the day. With `refit_every_days` above 1 the
+    model is refitted only on every so many days, to save time. Nothing is saved.
+    """
+    if last_day < first_day:
+        raise ValueError(f"The last day {last_day} is before the first day {first_day}.")
+    if refit_every_days < 1:
+        raise ValueError("refit_every_days must be at least 1.")
+    started = time.perf_counter()
+    scorable = set(scorable_days(history, settings))
+    current: ThermalModel | None = None
+    in_use = prior_model(house)
+    rows: list[ZoneDayScore] = []
+    fits: list[NightlyFit] = []
+    unscored: list[date] = []
+    for i in range((last_day - first_day).days + 1):
+        day = first_day + timedelta(days=i)
+        if i % refit_every_days == 0:
+            cutoff = nightly_cutoff(day, settings)
+            outcome = learn(history.before(cutoff), house, current, cutoff, settings)
+            fits.append(NightlyFit(day, outcome))
+            if isinstance(outcome, Accepted):
+                current = outcome.model
+            in_use = outcome.model
+        if day in scorable:
+            rows.extend(score_day(in_use, history, house, day, settings).values())
+        else:
+            unscored.append(day)
+    return Scorecard(tuple(rows), tuple(fits), tuple(unscored), time.perf_counter() - started)

warmcast/core/engine.py

@@ -0,0 +1,102 @@
+"""The engine the app runs: a house bound to its history source and its model store."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, date, datetime, time, timedelta
+from zoneinfo import ZoneInfo
+
+from .backtest import Scorecard, walk_forward
+from .house import House, ZoneId
+from .learning import Accepted, FitOutcome, KeptPrevious, estimate_dhw_baseline, learn
+from .model import Drivers, ThermalModel, Trajectory, ZoneState, estimate_state, prior_model
+from .model import simulate as simulate_model
+from .ports import HistorySource, ModelStore
+from .scoring import nightly_cutoff
+from .settings import LearnSettings
+from .signals import History, build_history, house_feeds
+
+
+class Engine:
+    """Learns, saves and runs one house's thermal model.
+
+    `dhw_baseline_kwh_per_day` is the hot water heat per day used to estimate space heat
+    without valve data; left out, it is worked out from the days with the heating off.
+    """
+
+    def __init__(
+        self,
+        house: House,
+        history_source: HistorySource,
+        store: ModelStore[ThermalModel],
+        *,
+        step: timedelta = timedelta(minutes=30),
+        settings: LearnSettings = LearnSettings(),  # noqa: B008
+        lookback: timedelta = timedelta(days=365),
+        dhw_baseline_kwh_per_day: float | None = None,
+    ) -> None:
+        self._house = house
+        self._source = history_source
+        self._store = store
+        self._step = step
+        self._settings = settings
+        self._lookback = lookback
+        self._dhw_baseline = dhw_baseline_kwh_per_day
+
+    def history(self, start: datetime, end: datetime) -> History:
+        raw = self._source.read(frozenset(house_feeds(self._house)), start, end)
+        baseline = self._dhw_baseline
+        if baseline is None:
+            baseline = estimate_dhw_baseline(build_history(raw, self._house, self._step, None)[0])
+        return build_history(raw, self._house, self._step, baseline)[0]
+
+    def model(self) -> ThermalModel:
+        """The current model, or the starting guesses before the first accepted fit."""
+        return self._store.current() or prior_model(self._house)
+
+    def refit(self, now: datetime) -> FitOutcome:
+        """Learn from the readings up to `now`.
+
+        An accepted model is saved and made current. A rejected candidate is saved but the
+        current model stays. Not enough data saves nothing.
+        """
+        history = self.history(now - self._lookback, now)
+        outcome = learn(history, self._house, self._store.current(), now, self._settings)
+        if isinstance(outcome, Accepted):
+            self._store.save(outcome.model, make_current=True)
+        elif isinstance(outcome, KeptPrevious):
+            self._store.save(outcome.candidate, make_current=False)
+        return outcome
+
+    def state(self, at: datetime) -> Mapping[ZoneId, ZoneState]:
+        """Each zone's state at `at`, from the readings in the slots just before it."""
+        window = timedelta(hours=self._settings.window_hours)
+        history = self.history(at - window, at)
+        if not history.segments or history.segments[-1].end < at - self._step:
+            raise ValueError(f"There are no usable readings in the slot before {at}.")
+        return estimate_state(self.model(), self._house, history.segments[-1])
+
+    def simulate(
+        self, drivers: Drivers, state: Mapping[ZoneId, ZoneState] | None = None
+    ) -> Trajectory:
+        """Run the current model forward over `drivers`.
+
+        Without a `state`, it starts from the readings just before `drivers.start`. A caller
+        that simulates many plans from the same moment can pass `state(...)` once instead.
+        """
+        start = self.state(drivers.start) if state is None else state
+        return simulate_model(self.model(), start, drivers)
+
+    def backtest(self, first_day: date, last_day: date, refit_every_days: int = 1) -> Scorecard:
+        """Replay the nightly loop over past days. Nothing is saved to the store."""
+        tz = ZoneInfo(self._settings.timezone)
+        start = nightly_cutoff(first_day, self._settings) - self._lookback
+        end = datetime.combine(last_day + timedelta(days=1), time(), tzinfo=tz).astimezone(UTC)
+        return walk_forward(
+            self.history(start, end),
+            self._house,
+            first_day,
+            last_day,
+            self._settings,
+            refit_every_days,
+        )