feat: add optional heating device model (leaky thermal store)

[andig]

Fix #48

Motivation

The MILP treats loadpoints as vehicles with batteries — they can only be filled with energy. Heating devices (hot water tanks, buffer storage) don't fit that pattern: they are leaky and lose energy proportionally to their temperature. This PR adds an optional model for them.

Model

Per 15-minute slot, a heating device is a leaky thermal store:

temp[t] = temp[t-1] + alpha*temp[t-1] + beta*h[t] + gamma

• alpha < 0 — leak rate (losses grow with temperature)
• beta — temperature gain per consumed Wh
• gamma — constant drift, absorbs ambient conditions

All three coefficients are fitted by least squares (fit_heating_model) from the device's history of temperatures and consumed energy in 15-minute slots — exactly the data evcc has available. Coefficients scale by dt/900 for other slot lengths.

MILP integration

Pure LP addition, no new binaries:

• heat input h[t] (bounded by c_max) enters the energy balance as consumption
• temperature must stay in a soft comfort band [temp_min, temp_max], penalized like battery SOC violations (°C converted to Wh-equivalent via beta)

The price signal alone then produces the right behavior: bank heat while electricity is cheap, coast through expensive slots on stored heat.

API

• request: optional heating list with temp_min, temp_max, temp_initial, c_max, history_temp, history_energy (fit happens server-side; unusable history → 400)
• response: per-device heating_energy and temperature series
• documented in openapi.yaml

Tests

• fit recovers known synthetic parameters (1e-8)
• short / non-heating history rejected
• cheap-first price profile: all heating lands in the cheap half, temperature never leaves the band, heating energy shows up as grid import
• full API roundtrip

All 13 existing golden cases unchanged; 17/17 tests pass, ruff clean.

Deliberately out of scope

• terminal heat value (comfort band already prevents horizon-end freeloading)
• min-modulation binary for heat pumps (add c_min + binary like batteries when hardware needs it)
• ambient-temperature forecast input (gamma carries historic ambient)
• Go harness (solver/) mirror — batteries only for now

🤖 Generated with Claude Code

[andig]

/cc @daniel309 just for sake of experiment. This would replace part of the solution you've put into Go code. I'm undecided where the better place is?

[andig]

Another idea: we could split the learning algorithm for the historic data to determine the parameters from actually running the optimizer. Should we just make this a different endpoint?

[andig]

Added in 493fe81: POST /optimize/heating-parameters exposes the thermal-model fit separately — takes history_temp/history_energy (15-min slots), returns fitted alpha/beta/gamma for inspection and validation. Also fixes the BadRequest errorhandler so message-only 400s return their JSON body.

[andig]

Extracted the BadRequest errorhandler fix into #86 — it affects existing endpoints on main independent of this PR. The short-history 400 test here asserts only the status code until #86 lands.

[daniel309]

interesting approach @andig. I tried to understand what this is doing, let me know if this is correct

1. this PR adds a model for a thermal store, i.e. a battery/warm water tank that leaks stored energy due to heat loss of the tank
2. the formula for the heat loss of the warm water tank is essentially: current energy stored + new energy added in the slot - energy loss per slot (a constant)
3. the three parameters above are obtained by doing least-square fitting based on earlier observations (from history) of those values

The optimizers job is to decide when to store energy given prices etc (as usual, just like charging home battery or car) and to stay within the temp_min and temp_max target parameters.

If this is correct, then I think you have a nice model for treating a warmwater tank as energy storage and optimize "loading" this storage just like a battery.

I am not sure if this is very useful though, because

1. warmwater is consumed quickly, not steadily (shower, bath, ...). The model has no chance to predict when this happens. So you need to optimize frequently to account for sudden tank drains (shower used).
2. because of this, heater controllers allow users to define schedules when to heat, what min/max temps to use and when to ignore temp being under minimum. there is schedules for the circulation pump etc. I dont think evcc should replace a heating controller. its missing major information for that and it would be totally redundant. the heating controller should decide when to heat the tank, not evcc.
3. for external "tips", virtually all heating controllers have sgready controls for "boosting" warmwater tank temperature on pv purplus. This is by sending a simple sgready signal (boost on), and then let the controller decide on all the details about min/max temps etc.
4. I think the proper approach would be to let the optimizer decide when to send the sgready "boost" signal to the water heater.

Now, I know that there also is a SGReady "boost" for room heating water. The idea is to use the building itself as energy storage (concrete floors), and to heat floors a bit higher (1, max 2 degrees more. cant do more as it will become uncomfortable otherwise).

I can tell you from experience that neither boost option makes a lot of sense and most people that have experimented with it eventually turned this off again (including myself). Reasons are that higher temperatures in the water heater cause increased wear on a heatpump compressor, and that using concrete as storage just causes your heatpump to turn off (after boost flag is removed). And then on again some time later. This again is bad for the heatpump, as you are forcing on/off mode instead of nicely modulating through the entire day.

For room heating especially, I dont think this PR makes sense. Room heating energy consumption cant be controlled or "planned" by an optimizer. You cant "shift" energy consumption around (i.e. turn on heater a few hours a day only) as this usually comes with comfort loss (humans detect very small changes in room temperature: 20C feels "cold", 22C feels "hot". Plus, room heaters (especially heatpumps, but even oil or gas heaters) need to run in long intervals for longevity/durability reasons. You cant cycle them on and off a lot, this will cause damage to their compressors.

A room heating's energy demand is in direct relationship with outdoor temperature. Future outdoor temp by far is the best predictor for future room heating energy consumption. The optimizer relies on future household consumption to create good schedules for charging (home and car) batteries.

my verdict: I see big value in predicting future loads of a heater to enable the optimizer to make better decisions for charging. I dont see value in trying to use a warmwater tank or concrete floors as "battery" and plan their charging via optimizer.

Sorry for the wall of text, I hope this all makes sense.

[daniel309]

edit: this PR may make sense for "heating rods", i.e. electric warm water heaters. these dont suffer from on/off cycling or increased wear if target water temperatures are higher.

not sure how much value though, as these are modelled as "chargers" today. Their primary purpose is to use pv surplus, and often their priority is such that they should only be used when all other batteries are full already and there is still pv surplus available.

[andig]

@daniel309 thanks for the feedback! I've cooked up this PR as a small experiment, not necessarily as "the final solution" for what ever ;). I have specifically done that with evcc-io/evcc#28232 in mind.

That said, the model isn't supposed to target any specific device type in terms of controlling it. The only goal (and maybe the model doesn't do that yet) is identifying the temperature-adjusted energy demand and adjusting the baseline demand profile accordingly (493fe81). We'll still need to decide, which parts should be part of the model and what should be part of the calling Go side.

[daniel309]

That said, the model isn't supposed to target any specific device type in terms of controlling it. The only goal (and maybe the model doesn't do that yet) is identifying the temperature-adjusted energy demand and adjusting the baseline demand profile accordingly (493fe81). We'll still need to decide, which parts should be part of the model and what should be part of the calling Go side.

I see. If the intention is purely forecast, I think its required to treat these 2 cases: warmwater and room heating separately and with different forecast models.

Your approach above could be a solution for warmwater. but maybe looking into timeseries models (to predict when people shower) would be worth looking into (google timeseriesfm or tranditional methods). As the problem here is less to predict the steady loss of temperature (your gamma) but rather when excessive energy is used for shower/bathtub, etc. This often is periodic behavior (e.g. period of a day). Also, most heatings have configuration set by users to account for that periodic behavior (schedules for "zirkulationspumpe", block time (night) for when to not re-heat despite minimum reached, etc) which amplifies and solidifies the repeating power consumption. So the job would be to discover this periodic behavior by observing consumption and creating a predictor from that.

However, I dont think it will work for house heating at all. Energy demand here is largely dependent on outdoor temperature (plus dampening to account for heating loss through insulation, but thats a minor factor). The best predictor for outdoor temparature is a weather forecast.

[andig]

Your approach above could be a solution for warmwater.

Why? With lower outside temp, the HP will require more power for room heating, too?

The best predictor for outdoor temparature is a weather forecast.

Exactly!

[andig]

Ahh, now I see what you mean: https://github.com/evcc-io/optimizer/pull/85/changes#diff-d910ba2ef878f7db0223a966b81c8b3f3b65027bb39e4431bb05140171eece39R523. The model takes the wrong temperature. This should be the forecasted outside temp, not the target thermal store temp.

[andig]

Updated the approach based on further discussion: the heating model no longer correlates history against the device's own storage/room temperature, and it's no longer schedulable by the optimizer.

New design:

• fit_heating_model(outside_temp, energy) fits a simple heating curve energy = slope*outside_temp + intercept (2 params, least squares) instead of the 3-param leaky-store model.
• No more temp state, comfort band, or h[t] decision variable in the MILP — heating is a forecasted load, folded directly into required consumption (gt) before optimization, the same way household consumption is.
• /heating-parameters now returns slope/intercept. New /heating-forecast endpoint takes a temperature forecast and returns predicted energy directly.
• This trades away the "bank heat when cheap" flexibility of the old model for a much simpler, more directly verifiable curve fit against actual outside temperature (which is what's physically driving heating demand, not the store's own temperature).

All tests updated and passing (20/20), ruff clean.

[daniel309]

yes, this is what I meant.

I dont fully understand the approach though. can you explain a bit?

1. what is the purpose of fitting a linear heating curve? how is it used?

2. If a heat curve is needed, shouldnt this be the usual logarhytmic function instead?, see this for example: https://mnemotron.de/lux/heatcurve.html. Viessmann, Wolf and others are similar.

3. I still believe room and water heating should be completely separated, using separate prediction models (time series vs. wweather forecast). its a special case that one heater does both. many people have separate devices for each use-case.