heating-mpc-ha/docs/MODEL.md

Heating MPC thermal model

This document describes the model used from version 0.4.0: what it computes, the units and meaning of every coefficient, when each part learns, what the forecasts assume, and how the model is validated. It is observational: nothing here controls the boiler.

Time step and inputs

The model works in 5-minute steps, the polling interval. For each zone i, each poll provides:

Symbol	Meaning	Unit	Source
T_i	Zone temperature: sensor-weighted mean of its usable sensors	°C	zone sensors
T_out	Outdoor temperature (first fresh, valid source)	°C	weather sources
lag	Radiator-lag proxy, 0 (cold) to 1 (fully warm); 20-minute first-order response to the relay, integrated at the relay's actual switch times	–	relay state + read-only listener
q_i	Electrical heat above baseline after its thermal response	kW	heat sources
O_i	Sum of open windows' opening factors, weighted by the share of the interval they were open	–	window sensors
F_i	Same, each window also weighted by cos(angle between wind direction and the window's facing)	–	windows + wind direction
v, g	Wind speed and gust speed	m/s	weather sources
R_i	Recovery weight after the zone's last window closed: exp(−t / τ_rec), 0 below 0.05	–	window sensors
T_ref,i	Zone temperature at the poll before the window opened	°C	zone sensors

Equations

Per 5-minute step, the predicted change of zone i is the sum of layers:

ΔT_i = loss    × (T_out − T_i)        envelope heat loss
     + heat    × lag                  boiler, through the radiators
     + bias                           constant gains and losses
     + internal × q_i                 electrical heat above baseline     (extended layer)
     + Σ_j couple:j × (T_j − T_i)     exchange with adjacent zones       (extended layer)
     + vent_natural  × O_i (T_out − T_i)                                 (ventilation layer)
     + vent_wind     × O_i v (T_out − T_i)
     + vent_wind_dir × F_i v (T_out − T_i)
     + vent_gust     × O_i max(0, g − v) (T_out − T_i)                   (optional)
     + vent_cross    × O_i O_other (T_out − T_i)                         (optional)
     + recovery      × R_i (T_ref,i − T_i)

All coefficients are in °C per 5 minutes per unit of their term. They are statistical estimates, not measured physical properties: heat is not boiler efficiency, and a relay that is on does not prove the burner is firing.

In conceptual continuous-time form this corresponds to

C_i dT_i/dt = UA_i (T_out − T_i) + Q_boiler + Q_internal + Q_ventilation + Σ_j K_ij (T_j − T_i) + Q_other

divided through by the zone's effective heat capacity C_i and discretized to 5 minutes. The model is first-order (one temperature per zone). Thermal inertia enters through the radiator lag, the electrical response filter and the recovery term; a separate wall-mass state is not modeled (see Limitations).

Base layer

The base layer is the 3-parameter model of earlier versions (loss, heat, bias), learned per zone. It is always kept: it is the fallback whenever another layer's inputs are unknown, and the comparison that shows whether the other layers help.

Extended layer

Present when a zone has an enabled heat source or an adjacent zone. It learns all base terms plus internal and couple:<zone> and replaces the base layer in forecasts once it is as trained as the base layer needs to be (200 samples, 30 with the relay on, 30 off). If any of its inputs is unknown, the base layer is used.

Electrical heat

For each enabled source:

effective power  = measured W − measured W of enabled sources included in it   (≥ 0)
baseline         = 20th percentile of the last 24 h of effective power, or the manual value
variable heat    = heat fraction × (effective power − baseline) / 1000          (kW)
thermal response : r ← r + (1 − exp(−5 min / τ)) × (variable heat held during the interval − r)

q_i is the sum of the responses of the zone's sources. Centring on the baseline matters: the persistent load (for example a UPS drawing 200 W all day) is already part of the bias term, so feeding it again would count it twice. The baseline needs one hour of data; after startup or an outage a source's response must run for two time constants before it is used for learning.

Only active power counts (W, kW, mW). VA (apparent power) and % (UPS load) are rejected. A UPS output sensor does not include the UPS's own losses; if they matter, measure the input side or lower the heat fraction accordingly.

Ventilation layer

Present when a zone has an enabled window. Learned separately, from the part of the measured change the closed-window layers cannot explain, only while a window is open, its state is unknown, or the zone is recovering. During those periods the base and extended layers do not learn, so window events cannot inflate loss or shift bias.

vent_wind_dir is bounded by vent_wind (|vent_wind_dir| ≤ vent_wind), so the combined wind term never goes negative: a leeward window still ventilates.

Wind direction is meteorological: the direction the wind comes from, degrees clockwise from north. A window's azimuth is the direction its outside faces. Wind from the azimuth blows straight at the window (cos = 1); wind from behind the building gives −1. Angle differences wrap around north correctly.

Priors, bounds and confidence

Coefficient	Prior	Bounds	Prior worth
loss	0.002	0 … 0.04	as in earlier versions
heat	0.045	0 … 0.25	as in earlier versions
bias	0	−0.06 … 0.06	as in earlier versions
internal	0	0 … 0.5	20 samples at 0.4 kW
couple:j	0	0 … 0.05	200 samples at 1 °C difference
vent_natural	0	0 … 0.2	20 samples at opening 1, 15 °C difference
vent_wind, vent_wind_dir	0	0 … 0.03 / ±vent_wind	20 samples at 4 m/s
vent_gust	0	0 … 0.03	20 samples
vent_cross	0	0 … 0.1	100 samples
recovery	0	0 … 0.5	20 samples at 0.5 °C deficit

New effects start at 0: no effect is assumed until the data shows one. Learning is recursive least squares with exponential forgetting (about 3.5 days of samples), a covariance bound that stops windup during long periods without excitation, and outlier rejection above 0.8 °C per 5 minutes.

Each coefficient reports:

• confidence: the share of its information that comes from data rather than the prior (0 = prior only);
• std: its standard error, using a running estimate of the unexplained noise;
• samples: how many accepted samples actually exercised it;
• identified: at least 30 exercising samples and confidence ≥ 0.8.

A coefficient can move without being identified. Example from the tests: two rooms whose temperature difference stays fairly steady cannot separate exchange between them from each room's bias; the learner finds a positive coupling but correctly reports it as not identified.

Learning conditions

A zone learns from the interval between two polls only when:

• the polls are 4.5–5.5 minutes apart, the relay held one state throughout and the radiator-lag estimate is known within 0.1 (for example ~32 minutes after an HA restart);
• the outdoor source did not change and the zone used the same sensors at both polls;
• for the extended layer, every source in the zone is settled and every adjacent zone was usable;
• for the ventilation layer, every window state in the zone is known.

No experiments are run and the boiler is never switched to gather data: everything is learned passively.

Forecasts

Forecasts simulate all zones together, step by step, over the MPC horizon (60–180 minutes):

• Weather: held at current values.
• Electrical heat: the variable part fades towards baseline with a configurable half-life (default 30 minutes; 0 = stops now), and the room keeps following it with its response time. A gaming PC drawing 600 W now is not assumed to run on for two hours.
• Windows: an open window is assumed to stay open for a configurable time (default 15 minutes), then close; the zone then recovers.
• Relay: the candidate plan being evaluated.

For the plan search the step is compiled into exact per-zone coefficients (every term is linear in the temperatures and the lag), which keeps the 180-minute search fast on a Raspberry Pi.

Plan forecasts are counterfactual while Generic Thermostat controls the relay: they describe what would happen under the MPC's proposed plan.

Validation

The Forecast Error sensors score forecasts that are valid for comparison with measured temperatures. At every poll the model parameters are frozen; 15, 30, 60 and 120 minutes later all zones are replayed from that poll using the relay, electrical heat and window history that actually followed (outdoor temperature held at its start value), and compared with the readings. The base layer and a no-change forecast are scored on exactly the same spans:

• mae, bias: the full model's error;
• persistence_mae, skill: against assuming no change;
• base_model_mae, improvement_vs_base: against the base layer alone. A feature that does not improve this should be switched off (for example the gust term).

Results on synthetic apartments (the tests; these check the method, not real-world accuracy):

Scenario	60-min error, full	base	no change
Office, UPS 200 W + 400 W gaming sessions, thermostat cycling	0.031 °C	0.182 °C	0.40 °C
Bedroom, 15–20 min ventilation every 4 h, wind and recovery	0.026 °C	0.218 °C	0.52 °C
Two adjacent rooms, true exchange 0.01	0.024 °C	0.037 °C	0.29 °C

In the ventilation scenario, the same data without the window configured produced a −0.013 °C/5 min cooling bias and an 11 % inflated boiler coefficient, which is the contamination the separate ventilation layer prevents.

Limitations

• One temperature per zone: walls and air are not separate states. The recovery term approximates the air warming back after ventilation.
• Response times (electrical heat, recovery) are configured, not learned. Compare settings with improvement_vs_base.
• Coupling between zones heated by one boiler is weakly identifiable; it is shrunk towards 0 and usually reported as not identified.
• Natural and wind ventilation terms both scale with the opening; with little wind variation their split is uncertain even when their combined effect is accurate.
• Forecasts hold weather constant and use one scenario for electrical heat and windows; no forecast uncertainty band is computed yet.
• Window sensors with a permanently unknown state keep their zone out of learning; disable such a window.