Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/heat-planner-package.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"ftw": patch
---

Internal: a heat planner package (`heatplan`) that proposes control values
for one zone from prices, weather and the site's energy plan. Nothing calls
it yet. No behaviour change.
75 changes: 69 additions & 6 deletions docs/adr/0012-heat-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,18 @@

- Status: accepted.
- Implementation: the declaration
([#1995](https://github.com/srcfl/ftw/pull/1995)) and the twin in shadow
([#1996](https://github.com/srcfl/ftw/pull/1996)) are proposed as PRs.
Planned control has not shipped.
([#1995](https://github.com/srcfl/ftw/pull/1995)), the twin in shadow
([#1996](https://github.com/srcfl/ftw/pull/1996)) and the planner package
(`go/internal/heatplan`, from
[#2013](https://github.com/srcfl/ftw/pull/2013) in
[#2022](https://github.com/srcfl/ftw/pull/2022)) are merged. Nothing
calls the planner yet, and planned control has not shipped.
- Date: 2026-11-10
- Decided by: Fredrik on 10 November 2026, in his
[answers on #1994](https://github.com/srcfl/ftw/pull/1994#issuecomment-6763083595),
and on the hot-water floor on 12 November 2026
([answer](https://github.com/srcfl/ftw/pull/1994#issuecomment-6832196178)).
([answer](https://github.com/srcfl/ftw/pull/1994#issuecomment-6832196178)),
and on comfort that follows the day's price on 15 November 2026.
See [Decisions](#decisions).
- Builds on: [#520](https://github.com/srcfl/ftw/issues/520), the
[`thermal`](../../go/internal/thermal/model.go) contract, driver
Expand Down Expand Up @@ -140,6 +144,52 @@ thermal:
- Without a comfort sensor, a zone cannot be planned. The roadmap does not
let Core assume indoor temperature.

#### Comfort follows the day's price

Decided on 15 November 2026; see [Decisions](#decisions), point 9. What a
degree is worth to the owner depends on
what the day costs. A warm bathroom floor is cheap comfort on a cheap day,
and a slightly cooler room is an easy saving on a dear one. That is a choice
about comfort, not about timing, and it needs no model of the house. The
rule is in `heatplan.PriceComfort`; the configuration below is the shape it
will take, and comes with the change that acts on it:

```yaml
thermal:
cheap_day_ore_kwh: 150 # at or below: all of cheap_day_raise_k
normal_day_ore_kwh: 260 # the owner's own target
dear_day_ore_kwh: 400 # at or above: all of dear_day_lower_k
zones:
- comfort_sensor: { driver: wiser, metric: bathroom_floor_c }
cheap_day_raise_k: 2.5
- comfort_sensor: { driver: wiser, metric: bathroom_air_c }
dear_day_lower_k: 1.0
step_k: 0.5
```

- The price is the mean total consumer price of the day the comfort is for,
once at least 22 hours of it are known. Between the levels the target
moves linearly, so a day one öre over a level is not a different day.
- Each direction is per zone and off at zero. A floor may follow cheap days
up while the room air only follows dear days down.
- The moved target stays inside the zone's hard band.
- **Nothing has a default.** These numbers depend on the contract, the
price area and the household. A site that sets none is unchanged.
- A shift rounded to the control's step never passes the owner's limit: a
raise of 2.5 K in steps of 1 K is 2 K.
- **The comfort rule comes first.** It moves the target, and the plan and
the baseline it is measured against both stand on that target, so the
plan is never credited with what the comfort rule saved.
- **It is the owner's target, not planned control.** It needs no trusted
twin. It still sends a value to the device, so decision 2 holds: a
device-side timed hold, or a small step from the device's own value.
- **There is no least saving.** A limit on what the plans must save before
they act was proposed and is not taken. In the one house that ran it,
with 5 kr a day, the plans saved 0.1–4.9 kr and the limit was never
reached, so it only turned the planner off. Instead the planner runs in
shadow first and the owner sees what it would have saved per day, then
turns planned control on with that number in view.

### 2. Declaration by the driver

Two optional fields on an existing control, an optional `sensors` list and
Expand Down Expand Up @@ -360,8 +410,20 @@ Fredrik answered on the hot-water floor on 12 November 2026:
wins and Core does not reject it. Core holds the owner's floor and timer,
with these three numbers as defaults when nothing is set.

Fredrik answered on comfort that follows the day's price on 15 November 2026:

9. **Comfort that follows the day's price** is taken, as section 1
describes, as the owner's own rule. It needs no trusted twin, and
decision 2 applies to what it sends. **There is no least daily saving.**
The planner runs in shadow first, and the box shows the owner what it
would have saved before planned control is turned on.

## Open

- **What makes a day cheap or dear.** Comfort that follows the price uses
the day's mean against the owner's fixed levels. Whether a longer
reference, such as the month, serves better is open until it has run in
more than one house.
- **Holding off a reheat needs a control.** Many heat pumps start a
hot-water charge by themselves at their own start temperature. The planner
can only delay a reheat on a device whose driver declares a control that
Expand Down Expand Up @@ -407,8 +469,9 @@ Fredrik answered on the hot-water floor on 12 November 2026:
learns, as the car's is. This touches the load model and the plan's
inputs, so it needs the owner's decision.
- **Zones share the site in the order they are planned.** A zone gets
the surplus and headroom the zones before it left. This is less than
section 4 asks: zones on a shared source are not yet planned together.
the surplus, headroom and battery energy the zones before it left. This
is less than section 4 asks: zones on a shared source are not yet
planned together.

The battery rule comes from a simulation with synthetic houses and
prices, not from hardware. A planner that took battery energy for cheap
Expand Down
148 changes: 148 additions & 0 deletions go/internal/heatplan/archetypes_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
package heatplan

import (
"math"

"github.com/srcfl/ftw/go/internal/thermal"
)

// Seven heated things with round, plausible numbers. They are fixtures for
// the tests, not defaults: a real zone's numbers come from its twin.

const (
slotH = 0.25
day = 96
)

func flat(n int, v float64) []float64 {
out := make([]float64, n)
for i := range out {
out[i] = v
}
return out
}

// hours builds a per-slot series from a value per hour of day.
func hours(n int, f func(hour float64) float64) []float64 {
out := make([]float64, n)
for i := range out {
out[i] = f(math.Mod(float64(i)*slotH, 24))
}
return out
}

func between(h, from, to float64) bool { return h >= from && h < to }

// eveningPeak is a flat price with one expensive evening.
func eveningPeak(n int, base, peak float64) []float64 {
return hours(n, func(h float64) float64 {
if between(h, 17, 20) {
return peak
}
return base
})
}

func room(n int, tauH, capacity, outdoorC float64) Zone {
return Zone{
TauH: tauH, CapacityKWhPerK: capacity, StartC: 21,
BoundaryC: flat(n, outdoorC), TargetC: flat(n, 21), MinC: flat(n, 20), MaxC: flat(n, 22),
ComfortWeight: 2,
}
}

// A timber house on panel radiators.
func radiatorHouse(n int, price []float64) Request {
return Request{SlotH: slotH, Price: price, OutdoorC: flat(n, 0),
Zone: room(n, 40, 8, 0),
Actuator: Actuator{Strategy: thermal.InfluenceSetpoint, Values: Values(20, 22, 0.5, 21, 8),
MaxHeatKW: 8, Source: Source{Kind: SourceDirectElectric}}}
}

// The same house behind one air-to-air unit. The unit heats the air, and the
// air is what its sensor sees, so the zone is light and quick.
func airToAirHouse(n int, price, outdoor []float64) Request {
z := room(n, 20, 3, 0)
z.BoundaryC = outdoor
return Request{SlotH: slotH, Price: price, OutdoorC: outdoor, Zone: z,
Actuator: Actuator{Strategy: thermal.InfluenceSetpoint, Values: Values(20, 22, 0.5, 21, 8),
MaxHeatKW: 5, Source: Source{Kind: SourceHeatPump, SinkApproachK: 18, FrostLoss: 0.1}}}
}

// A concrete slab fed by an air-to-water pump on a heating curve.
func slabHouse(n int, price, outdoor []float64) Request {
z := room(n, 100, 20, 0)
z.BoundaryC = outdoor
return Request{SlotH: slotH, Price: price, OutdoorC: outdoor, Zone: z,
Actuator: Actuator{Strategy: thermal.InfluenceCurveOffset, Values: Values(-3, 3, 1, 0, 8),
ZoneKPerUnit: 0.4, SupplyKPerUnit: 2, MaxHeatKW: 8,
Source: Source{Kind: SourceHeatPump, Supply: &SupplyCurve{ColdOutdoorC: -15, ColdSupplyC: 45, MildOutdoorC: 15, MildSupplyC: 25}}}}
}

// A tiled bathroom floor on a heating cable. hpCOP above zero puts it inside
// a house a heat pump keeps at 21 °C.
func bathroomFloor(n int, price []float64, hpCOP float64) Request {
z := Zone{TauH: 12, CapacityKWhPerK: 0.6, StartC: 23,
BoundaryC: flat(n, 21), TargetC: flat(n, 23), MinC: flat(n, 21.5), MaxC: flat(n, 26),
ComfortWeight: 2}
if hpCOP > 0 {
z.LossCreditCOP = flat(n, hpCOP)
}
return Request{SlotH: slotH, Price: price, OutdoorC: flat(n, 0), Zone: z,
Actuator: Actuator{Strategy: thermal.InfluenceSetpoint, Values: Values(21.5, 26, 0.5, 23, 12),
MaxHeatKW: 0.8, Source: Source{Kind: SourceDirectElectric}}}
}

// A 300 l hot-water tank in a 20 °C utility room, drawn from morning and
// evening.
func hotWaterTank(n int, price []float64, src Source) Request {
draws := hours(n, func(h float64) float64 {
switch {
case between(h, 7, 7.5):
return -4
case between(h, 19, 19.5):
return -5
}
return 0
})
return Request{SlotH: slotH, Price: price, OutdoorC: flat(n, 0),
Zone: Zone{TauH: 200, CapacityKWhPerK: 0.35, StartC: 55,
BoundaryC: flat(n, 20), TargetC: flat(n, 55), MinC: flat(n, 50), MaxC: flat(n, 65),
DisturbanceK: draws},
Actuator: Actuator{Strategy: thermal.InfluenceSetpoint, Values: Values(50, 65, 2.5, 55, 8),
MaxHeatKW: 3, Source: src}}
}

// A 1500 l covered spa outdoors, used 19–22 and let down in between.
func spa(n int, price []float64) Request {
use := func(h float64) bool { return between(h, 19, 22) }
return Request{SlotH: slotH, Price: price, OutdoorC: flat(n, 0),
Zone: Zone{TauH: 200, CapacityKWhPerK: 1.74, StartC: 34,
BoundaryC: flat(n, 0),
TargetC: hours(n, func(h float64) float64 { return map[bool]float64{true: 38, false: 34}[use(h)] }),
MinC: hours(n, func(h float64) float64 { return map[bool]float64{true: 37.5, false: 30}[use(h)] }),
MaxC: flat(n, 40)},
Actuator: Actuator{Strategy: thermal.InfluenceSetpoint, Values: Values(30, 40, 1, 34, 12),
MaxHeatKW: 3, Source: Source{Kind: SourceDirectElectric}}}
}

// A 40 m³ covered pool on its own air-source pump, which only starts and
// stops.
func pool(n int, price, outdoor []float64) Request {
return Request{SlotH: slotH, Price: price, OutdoorC: outdoor,
Zone: Zone{TauH: 300, CapacityKWhPerK: 46, StartC: 27,
BoundaryC: outdoor, TargetC: flat(n, 27), MinC: flat(n, 26), MaxC: flat(n, 29)},
Actuator: Actuator{Strategy: thermal.InfluenceOnOff, MaxHeatKW: 10,
MinOnSlots: 2, MinOffSlots: 2,
Source: Source{Kind: SourceHeatPump, CarnotFraction: 0.3, MaxCOP: 7}}}
}

// A summer day: 12 °C at dawn, 24 °C mid-afternoon.
func summerDay(n int) []float64 {
return hours(n, func(h float64) float64 { return 18 - 6*math.Cos((h-3)*math.Pi/12) })
}

// A winter day: −6 °C at dawn, 2 °C mid-afternoon.
func winterDay(n int) []float64 {
return hours(n, func(h float64) float64 { return -2 - 4*math.Cos((h-3)*math.Pi/12) })
}
Loading
Loading