diff --git a/.changeset/heat-shadow-plan.md b/.changeset/heat-shadow-plan.md new file mode 100644 index 000000000..df9d819b0 --- /dev/null +++ b/.changeset/heat-shadow-plan.md @@ -0,0 +1,24 @@ +--- +"ftw": minor +--- + +Heat zones can now be planned. A new `heat` section names each zone's +sensor, control, boundary, heat output, target and hard band, and the owner's +own rules: price comfort, peak relief and a least saving per day for all +zones together. No number has a default. Core plans every quarter from the +thermal twins, the stored prices and the weather forecast, and shows the plan +and what it would save at `GET /api/heat/plan`. Nothing is written unless +`heat.write` is on; then a zone's setpoint is held through the same control +holds as an operator's request, only while its twin is trusted, the least +saving is reached and the site meter is fresh, and the device is handed back +to its own default otherwise. A device that drops a written value by itself is +written again before it does. + +A zone can name its heat input (`heat_input: "/"`), so a room +sensor on one device, such as an underfloor gateway, learns against the heat +of another, such as a heat pump's estimated space heat. A sensor named in +`heat.zones` is learned even when its driver does not declare it. + +A zone can be heated by a heat pump (`source: heat_pump`) with the owner's +efficiency and heat curve, and planned through a declared curve offset with +the owner's figures for what one unit does. diff --git a/.changeset/heatplan-owner-rules.md b/.changeset/heatplan-owner-rules.md new file mode 100644 index 000000000..c6739e1db --- /dev/null +++ b/.changeset/heatplan-owner-rules.md @@ -0,0 +1,12 @@ +--- +"ftw": patch +--- + +The heat planner no longer stops and starts for a sliver of price: a change +of value must earn a share of what one slot at full output costs, so a price +that wobbles by a couple of percent gives 11 changes a day instead of 74 at +about 0.4 % higher planned cost. Two rules the owner sets are added to the +planner, both off at zero and with no default: a least saving a day's plans +must reach together before they are acted on, and a short price peak a zone +may sit through at the bottom of its band. Nothing calls them yet; the +planner still only proposes. diff --git a/config.example.yaml b/config.example.yaml index c9073eea6..b5dcd14dd 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -280,6 +280,43 @@ fleet_ping: # soc_min: 0.10 # soc_max: 0.95 +# Heat control (docs/adr/0012). Every number is the owner's and none has a +# default. Without write: true the plan is shadow: GET /api/heat/plan shows +# it and what it would save, and nothing is written. Prices are the stored +# total price (öre/kWh); min_per_day is in öre for all zones together. +# heat: +# write: false +# savings: { min_per_day: 500, keep_share: 0.8 } +# zones: +# - name: bathroom_floor +# sensor: wiser_7/floor_temp_c # the twin that judges this zone +# control: wiser_7/set_setpoint # a declared setpoint control +# # heat_input: ctc/space_heat_w # when the heat comes from another device +# boundary: wiser_7/room_temp_c # or "outdoor" +# source: direct_electric +# heat_kw: 0.6 +# target_c: 24.5 +# min_c: 20 +# max_c: 27 +# comfort_weight: 2 +# price_comfort: { cheap_price: 150, normal_price: 260, dear_price: 400, raise_k: 1, lower_k: 0 } +# peak_relief: { min_price: 200, factor: 3, window_h: 12, max_hours: 3 } +# # A house heated by a hydronic heat pump, its rooms read elsewhere. +# - name: house +# sensor: LK/zone_2_temp_c +# heat_input: CTC/space_heat_w # the pump's estimated space heat +# boundary: outdoor +# source: heat_pump +# heat_kw: 6 +# target_c: 21 +# min_c: 20 +# max_c: 22.5 +# heat_pump: # zero or absent: the planner's start point +# carnot_fraction: 0.5 +# supply: { cold_outdoor_c: -20, cold_supply_c: 45, mild_outdoor_c: 15, mild_supply_c: 24 } +# # control: CTC/set_heat_curve_offset # once the driver declares one +# # curve_effect: { zone_k_per_unit: 0.5, supply_k_per_unit: 1 } + # Peak-power tariff (weekday 06–20 local time). Same minor units as # grid_tariff_ore_kwh, per kW, excluding VAT. 0 disables it. # price: diff --git a/docs/adr/0012-heat-control.md b/docs/adr/0012-heat-control.md index f98704f94..9bcc667d8 100644 --- a/docs/adr/0012-heat-control.md +++ b/docs/adr/0012-heat-control.md @@ -424,6 +424,29 @@ Fredrik answered on comfort that follows the day's price on 15 November 2026: 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. +- **A least saving, as the owner's own number.** Decision 9 did not take + one, on the evidence that in the one house that ran it the plans saved + 0.1–4.9 kr a day against a limit of 5 kr and the limit never opened. That + figure was one room's saving read against a limit that is the household's. + Summed over the three rooms, as the limit is, the same house's log reached + 5 kr on 15 and 16 November and held it open for 84 % and 41 % of the + time. Part of that was a room model that overstated what a preheat saves; + with the model corrected the sum is 2–4 kr a day and the limit is mostly + closed, which is the effect decision 9 describes. The question left is what + the limit is for. Proposed: not a switch that turns the planner off, but the + owner's own answer to "what must a day's saving be worth to me before I + accept a change of comfort or a write to my devices". It is off at zero, + has no default, and the shadow run's saving per day is what the owner sets + it against. `heatplan.SavingsGate` carries the rule so the owner's number + has somewhere to go if the decision is revisited; nothing calls it yet. +- **Sitting out a short price peak.** The same house keeps a second rule of + its own: a slot is a peak when it costs at least 200 öre and three times + the lowest price of the next 12 hours, and a zone may sit at the bottom of + its band for at most 3 hours of one. On a dear but flat day nothing is a + peak and the rule does nothing, which is why it cannot replace the + planner. `heatplan.PeakRelief` carries it as the owner's numbers, with no + default, applied to a zone's target after `PriceComfort`; the band is not + moved. - **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 diff --git a/go/cmd/ftw/heat_control.go b/go/cmd/ftw/heat_control.go new file mode 100644 index 000000000..dbf33b367 --- /dev/null +++ b/go/cmd/ftw/heat_control.go @@ -0,0 +1,111 @@ +package main + +import ( + "sync" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatrun" + "github.com/srcfl/ftw/go/internal/state" +) + +// heatCatalog is the driver catalog as the heat control reads it. The +// reload path replaces it; the heat tick reads it from another goroutine. +type heatCatalog struct { + mu sync.Mutex + drivers []config.Driver + catalog []drivers.CatalogEntry +} + +func (h *heatCatalog) set(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry) { + h.mu.Lock() + defer h.mu.Unlock() + h.drivers = append([]config.Driver(nil), cfgDrivers...) + h.catalog = catalog +} + +// control is the declared control behind a driver instance's name. A driver +// that is disabled, observe-only or unknown has none. +func (h *heatCatalog) control(driver, control string) (drivers.CatalogControl, bool) { + h.mu.Lock() + defer h.mu.Unlock() + for _, d := range h.drivers { + if d.Name != driver || d.Disabled || d.ObserveOnly { + continue + } + entry := drivers.EntryForDriver(h.catalog, d.Lua) + if entry == nil { + return drivers.CatalogControl{}, false + } + for _, c := range entry.Controls { + if c.ID == control { + return c, true + } + } + } + return drivers.CatalogControl{}, false +} + +// heatPrices reads the stored total price, the one the owner's limits are +// written in. +func heatPrices(st *state.Store, zone func() string) func(from, to time.Time) []heatrun.Price { + return func(from, to time.Time) []heatrun.Price { + z := zone() + if st == nil || z == "" { + return nil + } + rows, err := st.LoadPrices(z, from.Add(-time.Hour).UnixMilli(), to.UnixMilli()) + if err != nil { + return nil + } + out := make([]heatrun.Price, 0, len(rows)) + for _, r := range rows { + if r.SlotLenMin <= 0 { + continue + } + out = append(out, heatrun.Price{ + Start: time.UnixMilli(r.SlotTsMs), + Len: time.Duration(r.SlotLenMin) * time.Minute, + Value: r.TotalOreKwh, + }) + } + return out + } +} + +// heatOutdoor is the outdoor forecast for n quarters from start, from rows +// fetched within the last 12 hours, or false when any quarter is missing. +func heatOutdoor(st *state.Store, since func() int64) func(start time.Time, n int) ([]float64, bool) { + return func(start time.Time, n int) ([]float64, bool) { + if st == nil || n <= 0 { + return nil, false + } + end := start.Add(time.Duration(n) * 15 * time.Minute) + rows, err := st.LoadForecasts(start.Add(-2*time.Hour).UnixMilli(), end.UnixMilli()) + if err != nil { + return nil, false + } + now := time.Now() + out := make([]float64, n) + for k := 0; k < n; k++ { + t := start.Add(time.Duration(k)*15*time.Minute + 7*time.Minute).UnixMilli() + found := false + for _, r := range rows { + slotLen := r.SlotLenMin + if slotLen <= 0 { + slotLen = 60 + } + if t >= r.SlotTsMs && t < r.SlotTsMs+int64(slotLen)*60*1000 && r.TempC != nil && + usableTrainingWeather(r, now) && r.FetchedAtMs >= since() { + out[k], found = *r.TempC, true + break + } + } + if !found { + return nil, false + } + } + return out, true + } +} diff --git a/go/cmd/ftw/heat_holds_wiring_test.go b/go/cmd/ftw/heat_holds_wiring_test.go new file mode 100644 index 000000000..22f19c724 --- /dev/null +++ b/go/cmd/ftw/heat_holds_wiring_test.go @@ -0,0 +1,82 @@ +package main + +import ( + "go/ast" + "go/parser" + "go/token" + "testing" +) + +// The heat control and the API must hold devices through one +// drivercontrol.Holds. If main handed the API none, the API would build its +// own, and an operator's hold and a planned value would sit on two locks: +// each would think the driver free and could expire into a default that +// undoes the other. main.go is read rather than run because building the +// whole process here would test everything but this. +func TestMainHandsTheHeatControlAndTheAPIOneSetOfHolds(t *testing.T) { + fset := token.NewFileSet() + file, err := parser.ParseFile(fset, "main.go", nil, 0) + if err != nil { + t.Fatal(err) + } + + var made []string // identifiers assigned from drivercontrol.New + heatHolds, apiHolds := "", "" + ast.Inspect(file, func(n ast.Node) bool { + switch n := n.(type) { + case *ast.AssignStmt: + for i, rhs := range n.Rhs { + call, ok := rhs.(*ast.CallExpr) + if !ok || !isSelector(call.Fun, "drivercontrol", "New") || i >= len(n.Lhs) { + continue + } + if id, ok := n.Lhs[i].(*ast.Ident); ok { + made = append(made, id.Name) + } + } + case *ast.CompositeLit: + switch { + case isSelector(n.Type, "heatrun", "HoldsWriter"): + heatHolds = fieldIdent(n, "Holds") + case isSelector(n.Type, "api", "Deps"): + apiHolds = fieldIdent(n, "ControlHolds") + } + } + return true + }) + + if len(made) != 1 { + t.Fatalf("main.go makes %d sets of control holds (%v), want 1", len(made), made) + } + if heatHolds != made[0] { + t.Errorf("heatrun.HoldsWriter{Holds: %q}, want %q", heatHolds, made[0]) + } + if apiHolds != made[0] { + t.Errorf("api.Deps{ControlHolds: %q}, want %q; without it the API builds its own", apiHolds, made[0]) + } +} + +func isSelector(e ast.Expr, pkg, name string) bool { + sel, ok := e.(*ast.SelectorExpr) + if !ok || sel.Sel.Name != name { + return false + } + id, ok := sel.X.(*ast.Ident) + return ok && id.Name == pkg +} + +// fieldIdent is the identifier a keyed composite literal sets field to, or "". +func fieldIdent(lit *ast.CompositeLit, field string) string { + for _, elt := range lit.Elts { + kv, ok := elt.(*ast.KeyValueExpr) + if !ok { + continue + } + if key, ok := kv.Key.(*ast.Ident); ok && key.Name == field { + if v, ok := kv.Value.(*ast.Ident); ok { + return v.Name + } + } + } + return "" +} diff --git a/go/cmd/ftw/main.go b/go/cmd/ftw/main.go index eb6c4c2d4..19afa87f9 100644 --- a/go/cmd/ftw/main.go +++ b/go/cmd/ftw/main.go @@ -49,6 +49,7 @@ import ( "github.com/srcfl/ftw/go/internal/control" "github.com/srcfl/ftw/go/internal/currency" "github.com/srcfl/ftw/go/internal/devtools" + "github.com/srcfl/ftw/go/internal/drivercontrol" "github.com/srcfl/ftw/go/internal/driverinventory" "github.com/srcfl/ftw/go/internal/driverrepo" "github.com/srcfl/ftw/go/internal/drivers" @@ -58,6 +59,7 @@ import ( "github.com/srcfl/ftw/go/internal/ftwcli" "github.com/srcfl/ftw/go/internal/gatewayidentity" "github.com/srcfl/ftw/go/internal/ha" + "github.com/srcfl/ftw/go/internal/heatrun" "github.com/srcfl/ftw/go/internal/journal" "github.com/srcfl/ftw/go/internal/loadmodel" "github.com/srcfl/ftw/go/internal/loadpoint" @@ -1068,6 +1070,11 @@ func main() { // Likewise constructed further down; the applier hands it the zones a // changed configuration or driver catalog declares. var thermalTwins *thermaltwin.Service + heatCat := &heatCatalog{} + var heatSvc *heatrun.Service + // One set of control holds for the API and the heat control, so a + // planned value and an operator's hold share a lock and an expiry. + controlHolds := drivercontrol.New(func() drivercontrol.Registry { return reg }) // Caller holds forecastConfigMu for a live transition. Keep persisted state // intact during a short unconfirmed startup; only confirmed live bindings @@ -1198,8 +1205,9 @@ func main() { observeOnly = config.ObserveOnlyDriverSet(newCfg) capMu.Unlock() if thermalTwins != nil { - thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog)) + thermalTwins.SetZones(thermalTwinZones(newCfg.Drivers, reloadCatalog, newCfg.Heat)) } + heatCat.set(newCfg.Drivers, reloadCatalog) warnIfEVHasBatteryCapacity(newCfg.Drivers, newCfg.Loadpoints, reloadCatalog) // Swap inverter-group tags (#143) and per-driver power @@ -1490,11 +1498,48 @@ func main() { } thermalTwins = thermaltwin.NewService(st, tel) thermalTwins.Temp = loadSvc.Temp - thermalTwins.SetZones(thermalTwinZones(twinDrivers(), driverCatalog)) + thermalTwins.SetZones(thermalTwinZones(twinDrivers(), driverCatalog, func() *config.Heat { cfgMu.RLock(); defer cfgMu.RUnlock(); return cfg.Heat }())) thermalTwins.PowerDrivers = func() []string { return thermalTwinPowerDrivers(twinDrivers()) } thermalTwins.Start(ctx) defer thermalTwins.Stop() + // ---- Heat control (docs/adr/0012) ---- + // Plans the owner's heat.zones every quarter. It writes nothing unless + // heat.write is on, and then only through the shared control holds. + heatCat.set(twinDrivers(), driverCatalog) + heatSvc = heatrun.New(heatrun.Inputs{ + Config: func() *config.Heat { + cfgMu.RLock() + defer cfgMu.RUnlock() + return cfg.Heat + }, + Twins: thermalTwins.Snapshot, + Latest: tel.LatestMetric, + Prices: heatPrices(st, func() string { + cfgMu.RLock() + defer cfgMu.RUnlock() + if cfg.Price == nil { + return "" + } + return cfg.Price.Zone + }), + Outdoor: heatOutdoor(st, func() int64 { return forecastSettings.Snapshot().WeatherSinceMS }), + Control: heatCat.control, + Writer: heatrun.HoldsWriter{Holds: controlHolds}, + SiteFresh: func() bool { + cfgMu.RLock() + meter := cfg.SiteMeterDriver() + watchdog := time.Duration(cfg.Site.WatchdogTimeoutS) * time.Second + cfgMu.RUnlock() + if watchdog <= 0 { + watchdog = 60 * time.Second + } + return meter != "" && !tel.IsStale(meter, telemetry.DerMeter, watchdog) + }, + }) + heatSvc.Start(ctx) + defer heatSvc.Stop() + // ---- Start OCPP 1.6J Central System (optional) ---- // Chargers dial us, so there is nothing to add to cfg.Drivers and no Lua // driver involved. A charge point whose identity (the last segment of the @@ -2636,6 +2681,8 @@ func main() { PVModel: pvSvc, LoadModel: loadSvc, ThermalTwin: thermalTwins, + HeatPlan: heatSvc, + ControlHolds: controlHolds, ForecastLearning: forecastTrackerSvc, Loadpoints: lpMgr, Cars: carsRT, diff --git a/go/cmd/ftw/thermal_twin.go b/go/cmd/ftw/thermal_twin.go index d0c964dda..b6845e255 100644 --- a/go/cmd/ftw/thermal_twin.go +++ b/go/cmd/ftw/thermal_twin.go @@ -2,6 +2,7 @@ package main import ( "sort" + "strings" "github.com/srcfl/ftw/go/internal/config" "github.com/srcfl/ftw/go/internal/drivers" @@ -16,7 +17,11 @@ import ( // // complete is false when an enabled driver has no catalog entry, so its // sensors are unknown rather than absent. The service then forgets no twin. -func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry) (zones []thermaltwin.Zone, complete bool) { +// +// A sensor the owner names in heat.zones is learned even when its driver +// does not declare it, as a room sensor on an underfloor gateway, and takes +// the heat input the owner named for it. +func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry, heat *config.Heat) (zones []thermaltwin.Zone, complete bool) { var out []thermaltwin.Zone complete = true for _, d := range cfgDrivers { @@ -39,6 +44,30 @@ func thermalTwinZones(cfgDrivers []config.Driver, catalog []drivers.CatalogEntry }) } } + if heat != nil { + enabled := map[string]bool{} + for _, d := range cfgDrivers { + if !d.Disabled && d.Lua != "" { + enabled[d.Name] = true + } + } + index := map[string]int{} + for i, z := range out { + index[z.Key] = i + } + for _, hz := range heat.Zones { + driver, metric, ok := strings.Cut(hz.Sensor, "/") + if !ok || !enabled[driver] { + continue + } + if i, ok := index[hz.Sensor]; ok { + out[i].HeatInput = hz.HeatInput + continue + } + index[hz.Sensor] = len(out) + out = append(out, thermaltwin.Zone{Key: hz.Sensor, SensorDriver: driver, SensorMetric: metric, HeatInput: hz.HeatInput}) + } + } sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key }) return out, complete } diff --git a/go/cmd/ftw/thermal_twin_test.go b/go/cmd/ftw/thermal_twin_test.go index 79a4e440b..0f75fac0f 100644 --- a/go/cmd/ftw/thermal_twin_test.go +++ b/go/cmd/ftw/thermal_twin_test.go @@ -39,7 +39,7 @@ func TestThermalTwinZonesFromDeclaredSensors(t *testing.T) { {Name: "grid", Lua: filepath.Join(dir, "meter.lua")}, } - got, complete := thermalTwinZones(cfg, catalog) + got, complete := thermalTwinZones(cfg, catalog, nil) if !complete { t.Error("complete = false with every enabled driver in the catalog") } @@ -53,10 +53,27 @@ func TestThermalTwinZonesFromDeclaredSensors(t *testing.T) { // A driver the catalog cannot describe has unknown sensors, not none: // the list is incomplete and no twin may be forgotten on its strength. missing := append(cfg, config.Driver{Name: "gone", Lua: filepath.Join(dir, "gone.lua")}) - if got, complete := thermalTwinZones(missing, catalog); complete || !reflect.DeepEqual(got, want) { + if got, complete := thermalTwinZones(missing, catalog, nil); complete || !reflect.DeepEqual(got, want) { t.Errorf("with an unreadable driver: zones = %+v, complete = %v; want the same zones, incomplete", got, complete) } - if got, complete := thermalTwinZones(cfg, nil); complete || len(got) != 0 { + // A sensor the owner names in heat.zones is learned though its driver + // declares nothing, with the heat input the owner named; a declared one + // takes the named input too. A disabled driver's sensor is not. + heat := &config.Heat{Zones: []config.HeatZone{ + {Sensor: "grid/zone_1_temp_c", HeatInput: "ctc/space_heat_w"}, + {Sensor: "wiser/room_bed_temp_c", HeatInput: "wiser/floor_heat_w"}, + {Sensor: "spare/room_bed_temp_c"}, + }} + withHeat, _ := thermalTwinZones(cfg, catalog, heat) + wantHeat := []thermaltwin.Zone{ + {Key: "grid/zone_1_temp_c", SensorDriver: "grid", SensorMetric: "zone_1_temp_c", HeatInput: "ctc/space_heat_w"}, + {Key: "wiser/room_bed_temp_c", SensorDriver: "wiser", SensorMetric: "room_bed_temp_c", HeatInput: "wiser/floor_heat_w"}, + {Key: "wiser/room_living_temp_c", SensorDriver: "wiser", SensorMetric: "room_living_temp_c"}, + } + if !reflect.DeepEqual(withHeat, wantHeat) { + t.Errorf("with heat zones = %+v, want %+v", withHeat, wantHeat) + } + if got, complete := thermalTwinZones(cfg, nil, nil); complete || len(got) != 0 { t.Errorf("without a catalog: zones = %+v, complete = %v; want none, incomplete", got, complete) } if p := thermalTwinPowerDrivers(cfg); !reflect.DeepEqual(p, []string{"wiser", "grid"}) { diff --git a/go/internal/api/api.go b/go/internal/api/api.go index 1f3b3a227..b74d42c83 100644 --- a/go/internal/api/api.go +++ b/go/internal/api/api.go @@ -48,6 +48,7 @@ import ( "github.com/srcfl/ftw/go/internal/fleetping" "github.com/srcfl/ftw/go/internal/forecast" "github.com/srcfl/ftw/go/internal/ha" + "github.com/srcfl/ftw/go/internal/heatrun" "github.com/srcfl/ftw/go/internal/loadmodel" "github.com/srcfl/ftw/go/internal/loadpoint" "github.com/srcfl/ftw/go/internal/localzone" @@ -178,7 +179,13 @@ type Deps struct { // Optional: load digital-twin self-learner. LoadModel *loadmodel.Service // Optional: shadow thermal twins of declared room sensors. - ThermalTwin *thermaltwin.Service + ThermalTwin *thermaltwin.Service + // HeatPlan is the heat zones' plan; nil when Core runs none. + HeatPlan *heatrun.Service + // ControlHolds, when set, is shared with Core's heat control so planned + // values and an operator's hold go through one lock. Nil gives the API + // holds of its own. + ControlHolds *drivercontrol.Holds ForecastLearning ForecastLearning // Optional: EV loadpoint state consumed by the API and MPC. @@ -341,7 +348,11 @@ func New(deps *Deps) *Server { drafts: newDriverDrafts(), marks: make(map[string]routeMark), } - s.controlHolds = drivercontrol.New(s.controlRegistry) + if deps.ControlHolds != nil { + s.controlHolds = deps.ControlHolds + } else { + s.controlHolds = drivercontrol.New(s.controlRegistry) + } s.setup = onboarding.NewWithSecrets(deps.State, s.preserveSetupSecrets, filepath.Dir(deps.ConfigPath)) if deps.SaveConfigWithValues == nil && deps.State != nil { deps.SaveConfigWithValues = func(path string, cfg *config.Config, values map[string]string, reviewedJSON []byte, beforeSave func() error) error { @@ -540,6 +551,7 @@ func (s *Server) routes() { s.handle("POST /api/pvmodel/reset", Configure, s.handlePVModelReset) s.handle("GET /api/loadmodel", Read, s.handleLoadModel) s.handle("GET /api/thermal/twins", Read, s.handleThermalTwins) + s.handle("GET /api/heat/plan", Read, s.handleHeatPlan) s.handle("POST /api/loadmodel/profile", Configure, s.handleLoadModelProfile) s.handle("POST /api/loadmodel/reset", Configure, s.handleLoadModelReset) s.handle("GET /api/research/load/dump", Read, s.handleLoadResearchDump) diff --git a/go/internal/api/api_agent_catalog.go b/go/internal/api/api_agent_catalog.go index 42a75d3ed..f951e1799 100644 --- a/go/internal/api/api_agent_catalog.go +++ b/go/internal/api/api_agent_catalog.go @@ -25,7 +25,8 @@ var agentAPIHints = []protocol.AgentAPIRoute{ {Path: "/api/data-sources", Description: "Available data sources and freshness"}, {Path: "/api/battery_models", Description: "Learned battery model and efficiency"}, {Path: "/api/loadmodel", Description: "Load forecast model and learning"}, - {Path: "/api/thermal/twins", Description: "Learned thermal twins of room sensors; shadow only, nothing controls from them"}, + {Path: "/api/thermal/twins", Description: "Learned thermal twins of room sensors; heat control writes from them only when heat.write is on"}, + {Path: "/api/heat/plan", Description: "Heat zones' plan per quarter, the day's saving against the owner's least saving, and what was written; shadow unless heat.write is on"}, {Path: "/api/pvmodel", Description: "Solar forecast model and learning"}, {Path: "/api/forecast", Description: "Load and solar forecasts", Query: map[string]string{"range": "Time ahead, such as 24h"}}, {Path: "/api/prices", Description: "Stored import and export prices", Query: map[string]string{"range": "Time ahead, such as 24h", "since_ms": "Unix milliseconds", "until_ms": "Unix milliseconds"}}, diff --git a/go/internal/api/api_heat_holds_test.go b/go/internal/api/api_heat_holds_test.go new file mode 100644 index 000000000..529bb1bd6 --- /dev/null +++ b/go/internal/api/api_heat_holds_test.go @@ -0,0 +1,102 @@ +package api + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "sync" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivercontrol" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatrun" + "github.com/srcfl/ftw/go/internal/telemetry" +) + +// sharedHoldsServer is controlServer with the holds handed in, the way main +// hands the same holds to the API and to the heat control. +func sharedHoldsServer(t *testing.T) (*Server, *drivercontrol.Holds, *telemetry.Store) { + t.Helper() + dir := t.TempDir() + lua := filepath.Join(dir, "probe.lua") + if err := os.WriteFile(lua, []byte(controlProbeLua), 0o600); err != nil { + t.Fatal(err) + } + tel := telemetry.NewStore() + reg := drivers.NewRegistry(tel) + cfg := config.Driver{Name: "heat", Lua: lua} + if err := reg.Add(context.Background(), cfg); err != nil { + t.Fatalf("add driver: %v", err) + } + t.Cleanup(reg.ShutdownAll) + holds := drivercontrol.New(func() drivercontrol.Registry { return reg }) + srv := New(&Deps{ + Tel: tel, + Registry: reg, + Cfg: &config.Config{Drivers: []config.Driver{cfg}}, + CfgMu: &sync.RWMutex{}, + DriverDir: dir, + ConfigPath: filepath.Join(dir, "config.yaml"), + ControlHolds: holds, + }) + return srv, holds, tel +} + +// With one set of holds, an operator's hold is the heat control's to see and +// leave alone, and a planned value is the operator's to see and release. Two +// sets would each think the driver free and expire into a default that +// undoes the other. +func TestTheAPIAndTheHeatControlShareOneHold(t *testing.T) { + srv, holds, tel := sharedHoldsServer(t) + if srv.controlHolds != holds { + t.Fatal("the API built its own holds instead of using the ones it was given") + } + heat := heatrun.HoldsWriter{Holds: holds} + + if rec := post(t, srv, "/api/drivers/heat/control", + `{"control":"set_offset","value":2,"duration_s":600}`); rec.Code != http.StatusOK { + t.Fatalf("operator POST = %d, body %s", rec.Code, rec.Body.String()) + } + if control, _, ok := heat.Active("heat"); !ok || control != "set_offset" { + t.Fatalf("heat control sees hold %q %v, want the operator's set_offset", control, ok) + } + if rec := del(t, srv, "/api/drivers/heat/control"); rec.Code != http.StatusOK { + t.Fatalf("operator DELETE = %d", rec.Code) + } + waitMetric(t, tel, "heat", "defaulted", 1) + if _, _, ok := heat.Active("heat"); ok { + t.Fatal("the operator released, the heat control still sees a hold") + } + + if _, err := heat.Hold(context.Background(), "heat", "set_offset", 1, 10*time.Minute); err != nil { + t.Fatalf("planned hold: %v", err) + } + rec := httptest.NewRecorder() + srv.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/drivers/heat", nil)) + var detail driverDetailResp + if err := json.Unmarshal(rec.Body.Bytes(), &detail); err != nil { + t.Fatal(err) + } + if detail.Hold == nil || detail.Hold.Control != "set_offset" { + t.Fatalf("the API shows hold %+v, want the planned set_offset", detail.Hold) + } + if rec := del(t, srv, "/api/drivers/heat/control"); rec.Code != http.StatusOK { + t.Fatalf("operator DELETE of a planned hold = %d", rec.Code) + } + waitMetric(t, tel, "heat", "defaulted", 2) + if _, _, ok := heat.Active("heat"); ok { + t.Fatal("the operator released a planned hold, it is still armed") + } +} + +func del(t *testing.T, srv *Server, path string) *httptest.ResponseRecorder { + t.Helper() + rec := httptest.NewRecorder() + srv.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodDelete, path, nil)) + return rec +} diff --git a/go/internal/api/api_heat_plan.go b/go/internal/api/api_heat_plan.go new file mode 100644 index 000000000..7ff73d5b3 --- /dev/null +++ b/go/internal/api/api_heat_plan.go @@ -0,0 +1,14 @@ +package api + +import "net/http" + +// GET /api/heat/plan — each heat zone's plan from the last slot, what the +// zones together would save a day against the owner's least saving, and what +// was written. `write: false` means the plan is shadow and nothing was sent. +func (s *Server) handleHeatPlan(w http.ResponseWriter, r *http.Request) { + if s.deps.HeatPlan == nil { + writeJSON(w, http.StatusOK, map[string]any{"enabled": false, "write": false}) + return + } + writeJSON(w, http.StatusOK, s.deps.HeatPlan.Snapshot()) +} diff --git a/go/internal/config/config.go b/go/internal/config/config.go index 0b8e473f0..d3c7375bc 100644 --- a/go/internal/config/config.go +++ b/go/internal/config/config.go @@ -33,6 +33,7 @@ type Config struct { Price *Price `yaml:"price,omitempty" json:"price,omitempty"` Weather *Weather `yaml:"weather,omitempty" json:"weather,omitempty"` Planner *Planner `yaml:"planner,omitempty" json:"planner,omitempty"` + Heat *Heat `yaml:"heat,omitempty" json:"heat,omitempty"` Batteries map[string]Battery `yaml:"batteries,omitempty" json:"batteries,omitempty"` EVCharger *EVCharger `yaml:"ev_charger,omitempty" json:"ev_charger,omitempty"` Loadpoints []Loadpoint `yaml:"loadpoints,omitempty" json:"loadpoints,omitempty"` @@ -1972,6 +1973,9 @@ func (c *Config) Validate() error { if err := c.FleetPing.Validate(); err != nil { return err } + if err := c.Heat.Validate(); err != nil { + return err + } if err := c.validateModbusProxy(); err != nil { return err } diff --git a/go/internal/config/heat.go b/go/internal/config/heat.go new file mode 100644 index 000000000..12c1db6d1 --- /dev/null +++ b/go/internal/config/heat.go @@ -0,0 +1,209 @@ +package config + +import ( + "fmt" + "math" + "regexp" + + "github.com/srcfl/ftw/go/internal/heatplan" +) + +// Heat is the owner's heat control (docs/adr/0012). Everything in it is the +// owner's own number: the band a zone may move in, what a cheap or dear day +// is worth, the least saving worth acting on, the peak worth sitting out. +// There is no default for any of them, and a section that is left out +// changes nothing. Plans are proposals; they are only written to a device +// when Write is true. +type Heat struct { + // Write lets Core send a plan's values to the zones' controls. False, the + // default, runs the planner in shadow: the plan and what it would save + // are shown and nothing is written. + Write bool `yaml:"write,omitempty" json:"write,omitempty"` + // Savings is the least saving a day's plans must reach together, over + // every zone, before they are acted on. Nil means no limit. + Savings *heatplan.SavingsGate `yaml:"savings,omitempty" json:"savings,omitempty"` + Zones []HeatZone `yaml:"zones,omitempty" json:"zones,omitempty"` +} + +// HeatZone is one heated thing: a room's air, a floor. +type HeatZone struct { + // Name is the zone's own name, used in plans and logs. + Name string `yaml:"name" json:"name"` + // Sensor is the thermal twin's key for this zone, "/". + Sensor string `yaml:"sensor" json:"sensor"` + // Control is the declared control the plan moves, "/". + // Empty means the zone is planned in shadow only. + Control string `yaml:"control,omitempty" json:"control,omitempty"` + // HeatInput is the "/" that measures or estimates the + // heat warming this zone, for the thermal twin to learn against. Needed + // when the sensor is on one device and the heat comes from another, as + // room sensors on an underfloor gateway heated by a heat pump. Empty + // lets the twin find a heat pump's power by itself. + HeatInput string `yaml:"heat_input,omitempty" json:"heat_input,omitempty"` + // Boundary is what the zone loses heat to: "outdoor" for the weather + // forecast, or "/" for a measured temperature, such as + // the room air around a floor. Required: a floor that loses heat to + // outdoors is planned as a different thing. + Boundary string `yaml:"boundary" json:"boundary"` + // Source is what makes the heat: "direct_electric" or "heat_pump". + Source string `yaml:"source" json:"source"` + // HeatPump is the pump's efficiency, for source heat_pump. Nil, or a + // field left at zero, takes the planner's starting point (half the + // ideal COP, capped at 6), which is no claim about any pump. + HeatPump *HeatPump `yaml:"heat_pump,omitempty" json:"heat_pump,omitempty"` + // CurveEffect is what one unit of a curve_offset control does, the + // owner's figures until a twin learns them. Required for a zone whose + // control is a curve offset. + CurveEffect *CurveEffect `yaml:"curve_effect,omitempty" json:"curve_effect,omitempty"` + // HeatKW is the heat at full output, the owner's figure: a floor's area + // times its rating, a radiator's plate. + HeatKW float64 `yaml:"heat_kw" json:"heat_kw"` + // TargetC is what the owner asks for; MinC and MaxC the hard band + // around it. The band is never widened. + TargetC float64 `yaml:"target_c" json:"target_c"` + MinC float64 `yaml:"min_c" json:"min_c"` + MaxC float64 `yaml:"max_c" json:"max_c"` + // ComfortWeight prices distance from the target; see heatplan.Zone. + ComfortWeight float64 `yaml:"comfort_weight,omitempty" json:"comfort_weight,omitempty"` + // PriceComfort moves the target with the day's mean price. + PriceComfort *heatplan.PriceComfort `yaml:"price_comfort,omitempty" json:"price_comfort,omitempty"` + // PeakRelief lets the zone sit at the bottom of its band through a peak. + PeakRelief *heatplan.PeakRelief `yaml:"peak_relief,omitempty" json:"peak_relief,omitempty"` +} + +// The words a heat zone's boundary and source may take besides a sensor key. +const ( + HeatBoundaryOutdoor = "outdoor" + HeatSourceDirectElectric = "direct_electric" + HeatSourceHeatPump = "heat_pump" +) + +// HeatPump is a heat pump's efficiency as the owner knows it. +type HeatPump struct { + // CarnotFraction is the share of the ideal COP the pump reaches. + CarnotFraction float64 `yaml:"carnot_fraction,omitempty" json:"carnot_fraction,omitempty"` + // MaxCOP caps the COP. + MaxCOP float64 `yaml:"max_cop,omitempty" json:"max_cop,omitempty"` + // FrostLoss is the share of output an air-source pump loses to + // defrosting at its worst, around +1 °C. + FrostLoss float64 `yaml:"frost_loss,omitempty" json:"frost_loss,omitempty"` + // Supply is the heat curve of a hydronic pump: the flow temperature at + // a cold and a mild outdoor temperature. Nil for a pump that heats the + // zone itself. + Supply *HeatSupplyCurve `yaml:"supply,omitempty" json:"supply,omitempty"` +} + +// HeatSupplyCurve is a heat curve by two points, flat outside them. +type HeatSupplyCurve struct { + ColdOutdoorC float64 `yaml:"cold_outdoor_c" json:"cold_outdoor_c"` + ColdSupplyC float64 `yaml:"cold_supply_c" json:"cold_supply_c"` + MildOutdoorC float64 `yaml:"mild_outdoor_c" json:"mild_outdoor_c"` + MildSupplyC float64 `yaml:"mild_supply_c" json:"mild_supply_c"` +} + +// CurveEffect is one unit of a curve offset: how far it moves the zone and +// the flow. +type CurveEffect struct { + ZoneKPerUnit float64 `yaml:"zone_k_per_unit" json:"zone_k_per_unit"` + SupplyKPerUnit float64 `yaml:"supply_k_per_unit" json:"supply_k_per_unit"` +} + +// PlanSource is the zone's source as the planner reads it. +func (z HeatZone) PlanSource() heatplan.Source { + if z.Source != HeatSourceHeatPump { + return heatplan.Source{Kind: heatplan.SourceDirectElectric} + } + src := heatplan.Source{Kind: heatplan.SourceHeatPump} + if hp := z.HeatPump; hp != nil { + src.CarnotFraction, src.MaxCOP, src.FrostLoss = hp.CarnotFraction, hp.MaxCOP, hp.FrostLoss + if c := hp.Supply; c != nil { + src.Supply = &heatplan.SupplyCurve{ColdOutdoorC: c.ColdOutdoorC, ColdSupplyC: c.ColdSupplyC, MildOutdoorC: c.MildOutdoorC, MildSupplyC: c.MildSupplyC} + } + } + return src +} + +var heatKey = regexp.MustCompile(`^[^/\s]+/[^/\s]+$`) + +// Validate refuses a heat section that cannot be read one way. +func (h *Heat) Validate() error { + if h == nil { + return nil + } + if h.Savings != nil { + if err := h.Savings.Validate(); err != nil { + return fmt.Errorf("heat.savings: %w", err) + } + } + seen := map[string]bool{} + for i, z := range h.Zones { + at := fmt.Sprintf("heat.zones[%d]", i) + if z.Name == "" { + return fmt.Errorf("%s: name is required", at) + } + if seen[z.Name] { + return fmt.Errorf("%s: zone %q is listed twice", at, z.Name) + } + seen[z.Name] = true + if !heatKey.MatchString(z.Sensor) { + return fmt.Errorf("%s (%s): sensor must be \"/\"", at, z.Name) + } + if z.Control != "" && !heatKey.MatchString(z.Control) { + return fmt.Errorf("%s (%s): control must be \"/\"", at, z.Name) + } + if z.HeatInput != "" && !heatKey.MatchString(z.HeatInput) { + return fmt.Errorf("%s (%s): heat_input must be \"/\"", at, z.Name) + } + if z.Boundary != HeatBoundaryOutdoor && !heatKey.MatchString(z.Boundary) { + return fmt.Errorf("%s (%s): boundary must be \"outdoor\" or \"/\"", at, z.Name) + } + if z.Source != HeatSourceDirectElectric && z.Source != HeatSourceHeatPump { + return fmt.Errorf("%s (%s): source must be %q or %q", at, z.Name, HeatSourceDirectElectric, HeatSourceHeatPump) + } + if z.HeatPump != nil && z.Source != HeatSourceHeatPump { + return fmt.Errorf("%s (%s): heat_pump is set but source is %q", at, z.Name, z.Source) + } + if err := z.PlanSource().Validate(); err != nil { + return fmt.Errorf("%s (%s): heat_pump: %w", at, z.Name, err) + } + if e := z.CurveEffect; e != nil { + if math.IsNaN(e.ZoneKPerUnit+e.SupplyKPerUnit) || math.IsInf(e.ZoneKPerUnit+e.SupplyKPerUnit, 0) || + e.ZoneKPerUnit <= 0 || e.ZoneKPerUnit > 5 || e.SupplyKPerUnit < 0 || e.SupplyKPerUnit > 10 { + return fmt.Errorf("%s (%s): curve_effect needs zone_k_per_unit above 0 and at most 5, supply_k_per_unit 0 to 10", at, z.Name) + } + } + if !(z.HeatKW > 0) || z.HeatKW > 500 { + return fmt.Errorf("%s (%s): heat_kw must be above 0 and at most 500", at, z.Name) + } + for _, v := range []float64{z.TargetC, z.MinC, z.MaxC, z.ComfortWeight} { + if math.IsNaN(v) || math.IsInf(v, 0) { + return fmt.Errorf("%s (%s): temperatures must be finite", at, z.Name) + } + } + if !(z.MinC <= z.TargetC && z.TargetC <= z.MaxC) || z.MinC == z.MaxC { + return fmt.Errorf("%s (%s): need min_c <= target_c <= max_c with a band wider than zero", at, z.Name) + } + if z.ComfortWeight < 0 { + return fmt.Errorf("%s (%s): comfort_weight must not be negative", at, z.Name) + } + if z.PriceComfort != nil { + if err := z.PriceComfort.Validate(); err != nil { + return fmt.Errorf("%s (%s): price_comfort: %w", at, z.Name, err) + } + } + if z.PeakRelief != nil { + if err := z.PeakRelief.Validate(); err != nil { + return fmt.Errorf("%s (%s): peak_relief: %w", at, z.Name, err) + } + } + } + if h.Write { + for _, z := range h.Zones { + if z.Control != "" { + return nil + } + } + return fmt.Errorf("heat.write is on but no zone has a control to write to") + } + return nil +} diff --git a/go/internal/config/heat_test.go b/go/internal/config/heat_test.go new file mode 100644 index 000000000..22cffe307 --- /dev/null +++ b/go/internal/config/heat_test.go @@ -0,0 +1,127 @@ +package config + +import ( + "strings" + "testing" + + "gopkg.in/yaml.v3" + + "github.com/srcfl/ftw/go/internal/heatplan" +) + +// The numbers the house that built the planner runs, as its owner would write +// them. Every one of them is the owner's, and none has a default. +const houseHeatYAML = ` +write: false +savings: { min_per_day: 500, keep_share: 0.8 } +zones: + - name: badrum + sensor: wiser_7/floor_temp_c + control: wiser_7/set_setpoint + boundary: wiser_7/room_temp_c + source: direct_electric + heat_kw: 0.6 + target_c: 24.5 + min_c: 20 + max_c: 27 + price_comfort: { cheap_price: 150, normal_price: 260, dear_price: 400, raise_k: 1, lower_k: 1, step_k: 0.5 } + peak_relief: { min_price: 200, factor: 3, window_h: 12, max_hours: 3 } +` + +func TestHeatSectionReadsTheOwnersNumbers(t *testing.T) { + var h Heat + if err := yaml.Unmarshal([]byte(houseHeatYAML), &h); err != nil { + t.Fatal(err) + } + if err := h.Validate(); err != nil { + t.Fatal(err) + } + z := h.Zones[0] + if h.Write || h.Savings.MinPerDay != 500 || h.Savings.KeepShare != 0.8 || + z.MaxC != 27 || z.PriceComfort.DearPrice != 400 || z.PeakRelief.MaxHours != 3 { + t.Fatalf("numbers were not read: %+v %+v", h, z) + } + var _ heatplan.PeakRelief = *z.PeakRelief +} + +func TestHeatSectionLeftOutOrEmptyChangesNothing(t *testing.T) { + if (*Heat)(nil).Validate() != nil || (&Heat{}).Validate() != nil { + t.Fatal("an absent or empty heat section was refused") + } +} + +func TestHeatSectionRefusesWhatCannotBeReadOneWay(t *testing.T) { + ok := HeatZone{Name: "a", Sensor: "d/m", Boundary: "outdoor", Source: "direct_electric", HeatKW: 1, TargetC: 22, MinC: 20, MaxC: 24} + for name, tc := range map[string]struct { + h Heat + want string + }{ + "no name": {Heat{Zones: []HeatZone{{Sensor: "d/m", TargetC: 22, MinC: 20, MaxC: 24}}}, "name"}, + "twice": {Heat{Zones: []HeatZone{ok, ok}}, "twice"}, + "bad sensor": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "dm", TargetC: 22, MinC: 20, MaxC: 24}}}, "sensor"}, + "bad control": {Heat{Zones: []HeatZone{{Name: "a", Sensor: "d/m", Control: "x", TargetC: 22, MinC: 20, MaxC: 24}}}, "control"}, + "target outside": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.TargetC = 25 })}}, "min_c"}, + "no band": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.MinC, z.TargetC, z.MaxC = 22, 22, 22 })}}, "band"}, + "bad gate": {Heat{Savings: &heatplan.SavingsGate{MinPerDay: 5, KeepShare: 2}, Zones: []HeatZone{ok}}, "savings"}, + "bad relief": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.PeakRelief = &heatplan.PeakRelief{MaxHours: 3, Factor: 1, WindowH: 12} })}}, "peak_relief"}, + "write no control": {Heat{Write: true, Zones: []HeatZone{ok}}, "control"}, + "bad boundary": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.Boundary = "" })}}, "boundary"}, + "no heat": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatKW = 0 })}}, "heat_kw"}, + "bad heat input": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatInput = "ctc" })}}, "heat_input"}, + "unknown source": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.Source = "gas" })}}, "source"}, + "pump on electric": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.HeatPump = &HeatPump{} })}}, "heat_pump"}, + "bad curve": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { + z.Source = "heat_pump" + z.HeatPump = &HeatPump{Supply: &HeatSupplyCurve{ColdOutdoorC: 15, ColdSupplyC: 45, MildOutdoorC: -15, MildSupplyC: 25}} + })}}, "heat_pump"}, + "bad effect": {Heat{Zones: []HeatZone{with(ok, func(z *HeatZone) { z.CurveEffect = &CurveEffect{ZoneKPerUnit: 0} })}}, "curve_effect"}, + } { + err := tc.h.Validate() + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Errorf("%s: error %v, want one mentioning %q", name, err, tc.want) + } + } + w := ok + w.Control = "d/set_setpoint" + if err := (&Heat{Write: true, Zones: []HeatZone{w}}).Validate(); err != nil { + t.Errorf("a zone with a control and write on was refused: %v", err) + } +} + +func with(z HeatZone, f func(*HeatZone)) HeatZone { f(&z); return z } + +// The house the planner was built for: a CTC with an air-to-water pump on +// a heat curve, the rooms read by an underfloor gateway. +const houseHeatPumpYAML = ` +zones: + - name: house + sensor: LK/zone_2_temp_c + heat_input: CTC/space_heat_w + boundary: outdoor + source: heat_pump + heat_kw: 6 + target_c: 21 + min_c: 20 + max_c: 22.5 + heat_pump: + carnot_fraction: 0.45 + supply: { cold_outdoor_c: -20, cold_supply_c: 45, mild_outdoor_c: 15, mild_supply_c: 24 } + curve_effect: { zone_k_per_unit: 0.5, supply_k_per_unit: 1 } +` + +func TestHeatSectionReadsAHeatPump(t *testing.T) { + var h Heat + if err := yaml.Unmarshal([]byte(houseHeatPumpYAML), &h); err != nil { + t.Fatal(err) + } + if err := h.Validate(); err != nil { + t.Fatal(err) + } + src := h.Zones[0].PlanSource() + if src.Kind != heatplan.SourceHeatPump || src.CarnotFraction != 0.45 || src.Supply == nil || src.Supply.At(-20) != 45 { + t.Fatalf("source = %+v", src) + } + if h.Zones[0].CurveEffect.ZoneKPerUnit != 0.5 || h.Zones[0].HeatInput != "CTC/space_heat_w" { + t.Fatalf("zone = %+v", h.Zones[0]) + } +} diff --git a/go/internal/heatplan/comfort.go b/go/internal/heatplan/comfort.go index 035087c5a..365fa6147 100644 --- a/go/internal/heatplan/comfort.go +++ b/go/internal/heatplan/comfort.go @@ -3,6 +3,7 @@ package heatplan import ( "errors" "math" + "sort" ) // This file holds the owner's rule for what heat is worth, beside the plan @@ -16,9 +17,15 @@ import ( // on the comfort that day is worth. It needs no model of the zone and holds // from the first day. // -// There is no least saving before a plan may act. What a plan saves is shown -// to the owner from the shadow run, and the owner decides with that number -// in view (ADR 0012, decision 9). +// Two more rules are the owner's own number for when a saving is worth a +// change of comfort or a write to a device. Both are off at zero. +// +// - SavingsGate: the least a day's plans must save together before they are +// acted on. Below it every zone stays on its target. What a plan saves is +// also shown to the owner from the shadow run; the gate is the owner's way +// to say what a saving has to be worth to them. +// - PeakRelief: a short, sharp price peak the owner will sit through at the +// bottom of the band, with how sharp and how long as the owner's numbers. // PriceComfort moves a zone's target with the day's mean price. All prices // are in the unit of Request.Price. @@ -27,17 +34,17 @@ type PriceComfort struct { // raised by all of RaiseK. NormalPrice is where the target is the // owner's own, and DearPrice the mean at or above which it is lowered by // all of LowerK. Between them the shift is linear, never a step. - CheapPrice float64 `json:"cheap_price"` - NormalPrice float64 `json:"normal_price"` - DearPrice float64 `json:"dear_price"` + CheapPrice float64 `yaml:"cheap_price" json:"cheap_price"` + NormalPrice float64 `yaml:"normal_price" json:"normal_price"` + DearPrice float64 `yaml:"dear_price" json:"dear_price"` // RaiseK and LowerK are how far the target moves, in kelvin. Zero turns // that direction off: a floor may follow cheap days up while the room // air only follows dear days down. - RaiseK float64 `json:"raise_k"` - LowerK float64 `json:"lower_k"` + RaiseK float64 `yaml:"raise_k" json:"raise_k"` + LowerK float64 `yaml:"lower_k" json:"lower_k"` // StepK rounds the shift to the control's step, halves away from zero. // Zero leaves it unrounded. - StepK float64 `json:"step_k,omitempty"` + StepK float64 `yaml:"step_k,omitempty" json:"step_k,omitempty"` } // Enabled reports whether the rule moves anything. @@ -148,3 +155,173 @@ func (p Plan) Saving() float64 { } return math.Max(0, p.BaselineCost-p.Cost) } + +// SavingsGate is the owner's least saving for planned heat to be acted on. +// It is a choice about what a saving is worth to this household, so it has +// no default: zero opens the gate always. +type SavingsGate struct { + // MinPerDay is what the plans must save together in a day, in the unit + // of Request.Price times kWh. Zero or less opens the gate always. + MinPerDay float64 `yaml:"min_per_day" json:"min_per_day"` + // KeepShare is the share of MinPerDay below which an open gate closes + // again, so that a saving near the limit does not open and close it + // every slot. From above 0 to 1; zero means 1, no hysteresis. + KeepShare float64 `yaml:"keep_share,omitempty" json:"keep_share,omitempty"` +} + +// Validate refuses a gate that cannot be read one way. +func (g SavingsGate) Validate() error { + if !finite(g.MinPerDay, g.KeepShare) || g.KeepShare < 0 || g.KeepShare > 1 { + return errors.New("heatplan: the savings gate keeps a share of 0 to 1 of a finite limit") + } + return nil +} + +// Open reports whether the plans together save enough to act on, and what +// they save scaled to a day. horizonH is the horizon the plans cover; a +// horizon longer than a day is scaled down and a shorter one up, since a +// morning with half a day of prices would otherwise never reach a daily +// limit. wasOpen is the gate's last answer. +// +// The plans passed in are the plans of every zone the gate covers, each +// counted once: a limit is the household's, and a limit compared with one +// room's saving would read as never reached. +// +// A closed gate means every zone is left on its target, which with +// PriceComfort is the target that day is worth. An invalid gate, or a +// horizon that is not a length of time, is closed: the devices then run +// themselves, which is always safe. +func (g SavingsGate) Open(plans []Plan, horizonH float64, wasOpen bool) (open bool, perDay float64) { + if g.Validate() != nil || !(horizonH > 0) || !finite(horizonH) { + return false, 0 + } + var saved float64 + for _, p := range plans { + saved += p.Saving() + } + perDay = saved * 24 / horizonH + if g.MinPerDay <= 0 { + return true, perDay + } + limit := g.MinPerDay + if wasOpen && g.KeepShare > 0 { + limit *= g.KeepShare + } + return perDay >= limit, perDay +} + +// PeakRelief lets a zone sit at the bottom of its band through a short price +// peak. A slot is in a peak when its price is at least MinPrice and at least +// Factor times the lowest price in the WindowH hours from it, itself +// included. Of every unbroken stretch of such slots only the dearest +// MaxHours are relieved, so a long dear period is not one peak: its +// beginning is left to the plan. With a price that is zero or negative +// somewhere in the window, the ratio holds for any slot at or above MinPrice. +// +// It is the owner's rule and has no default: MaxHours zero turns it off. +type PeakRelief struct { + // MinPrice is the price below which no slot is a peak, in the unit of + // Request.Price. + MinPrice float64 `yaml:"min_price" json:"min_price"` + // Factor is how many times the window's lowest price a peak costs. Above 1. + Factor float64 `yaml:"factor" json:"factor"` + // WindowH is how far ahead the lowest price is looked for, in hours. + WindowH float64 `yaml:"window_h" json:"window_h"` + // MaxHours is the longest relief in one peak. + MaxHours float64 `yaml:"max_hours" json:"max_hours"` +} + +// Enabled reports whether the rule relieves anything. +func (r PeakRelief) Enabled() bool { return r.MaxHours > 0 } + +// Validate refuses a rule that cannot be read one way. A rule that is off +// needs no other number. +func (r PeakRelief) Validate() error { + if !finite(r.MinPrice, r.Factor, r.WindowH, r.MaxHours) || r.MaxHours < 0 { + return errors.New("heatplan: peak relief must be finite, and its longest relief not negative") + } + if r.MaxHours == 0 { + return nil + } + if r.MaxHours > 24 || !(r.Factor > 1) || !(r.WindowH > 0) || r.WindowH > 48 { + return errors.New("heatplan: peak relief needs a factor above 1, a window of up to 48 hours and a longest relief of up to 24 hours") + } + return nil +} + +// Slots marks the slots of price that the rule relieves. An invalid or +// disabled rule, or a price that is not finite, marks none. +func (r PeakRelief) Slots(price []float64, slotH float64) []bool { + out := make([]bool, len(price)) + if !r.Enabled() || r.Validate() != nil || !(slotH > 0) || !finite(slotH) { + return out + } + for _, p := range price { + if !finite(p) { + return out + } + } + window := int(math.Ceil(r.WindowH/slotH - 1e-9)) + keep := int(math.Floor(r.MaxHours/slotH + 1e-9)) + if window < 1 || keep < 1 { + return out + } + n := len(price) + peak := make([]bool, n) + for k, p := range price { + if p < r.MinPrice { + continue + } + end := min(n, k+window) + low := price[k] + for _, q := range price[k:end] { + low = math.Min(low, q) + } + peak[k] = low <= 0 || p >= r.Factor*low + } + for k := 0; k < n; { + if !peak[k] { + k++ + continue + } + j := k + for j < n && peak[j] { + j++ + } + // The dearest slots of the stretch; the earlier one wins a tie. + idx := make([]int, 0, j-k) + for i := k; i < j; i++ { + idx = append(idx, i) + } + sort.SliceStable(idx, func(a, b int) bool { return price[idx[a]] > price[idx[b]] }) + for rank, i := range idx { + if rank < keep { + out[i] = true + } + } + k = j + } + return out +} + +// Apply returns the zone with its target let down to the bottom of its band +// in the relieved slots. The band is the owner's hard limit and stays where +// it is. Apply it after PriceComfort, which moves the target for the day. +// The zone passed in is not changed. +func (r PeakRelief) Apply(z Zone, price []float64, slotH float64) Zone { + relieved := r.Slots(price, slotH) + changed := false + target := make([]float64, len(z.TargetC)) + copy(target, z.TargetC) + for i := range target { + if i < len(relieved) && relieved[i] && i < len(z.MinC) && z.MinC[i] < target[i] { + target[i] = z.MinC[i] + changed = true + } + } + if !changed { + return z + } + z.TargetC = target + return z +} diff --git a/go/internal/heatplan/comfort_test.go b/go/internal/heatplan/comfort_test.go index 11b40e991..020618725 100644 --- a/go/internal/heatplan/comfort_test.go +++ b/go/internal/heatplan/comfort_test.go @@ -171,3 +171,257 @@ func TestPriceComfortStepNeverPassesTheOwnersLimit(t *testing.T) { } } } + +// Five kronor a day, in öre, as a household set it. +func TestSavingsGateWeighsEveryPlanTogether(t *testing.T) { + gate := SavingsGate{MinPerDay: 500, KeepShare: 0.8} + if open, perDay := gate.Open([]Plan{saves(200), saves(250)}, 24, false); open || perDay != 450 { + t.Errorf("450 a day: open %v, per day %v", open, perDay) + } + if open, perDay := gate.Open([]Plan{saves(200), saves(250), saves(60)}, 24, false); !open || perDay != 510 { + t.Errorf("510 a day: open %v, per day %v", open, perDay) + } + // No room reaches the limit alone, and together they do. A limit read + // against one room at a time would look as if it were never reached. + for _, one := range []float64{200, 190, 180} { + if open, _ := gate.Open([]Plan{saves(one)}, 24, false); open { + t.Errorf("%v from one room opened the gate", one) + } + } + if open, perDay := gate.Open([]Plan{saves(200), saves(190), saves(180)}, 24, false); !open || perDay != 570 { + t.Errorf("three rooms: open %v, per day %v", open, perDay) + } + // Half a day of prices: the same plans are worth twice as much a day. + if open, perDay := gate.Open([]Plan{saves(260)}, 12, false); !open || perDay != 520 { + t.Errorf("260 in 12 hours: open %v, per day %v", open, perDay) + } + // Two days of horizon are not two days of saving in one. + if open, perDay := gate.Open([]Plan{saves(900)}, 48, false); open || perDay != 450 { + t.Errorf("900 in 48 hours: open %v, per day %v", open, perDay) + } +} + +func TestSavingsGateDoesNotFlapAtTheLimit(t *testing.T) { + gate := SavingsGate{MinPerDay: 500, KeepShare: 0.8} + open := false + var got []bool + for _, v := range []float64{480, 510, 480, 410, 390, 480, 500} { + open, _ = gate.Open([]Plan{saves(v)}, 24, open) + got = append(got, open) + } + want := []bool{false, true, true, true, false, false, true} + for i := range want { + if got[i] != want[i] { + t.Fatalf("gate over time = %v, want %v", got, want) + } + } + if open, _ := (SavingsGate{MinPerDay: 500}).Open([]Plan{saves(480)}, 24, true); open { + t.Error("without a keep share an open gate stayed open below the limit") + } +} + +// A plan that leaves its band, or costs more than leaving the device alone, +// adds nothing to what the gate weighs. +func TestSavingsGateCountsOnlyFeasiblePlans(t *testing.T) { + out := saves(900) + out.BandExcursionKh = 0.5 + worse := Plan{Cost: 1100, BaselineCost: 1000} + gate := SavingsGate{MinPerDay: 500} + if open, perDay := gate.Open([]Plan{out, worse, saves(300)}, 24, false); open || perDay != 300 { + t.Errorf("open %v, per day %v; want closed at 300", open, perDay) + } +} + +// No limit set is no gate. A gate that cannot be read is closed, because +// leaving the devices to themselves is the safe answer. +func TestSavingsGateWithoutALimitIsOpenAndABrokenOneIsClosed(t *testing.T) { + if open, _ := (SavingsGate{}).Open(nil, 24, false); !open { + t.Error("the zero value closed the gate") + } + for name, g := range map[string]SavingsGate{ + "keep share above 1": {MinPerDay: 500, KeepShare: 1.5}, + "negative keep": {MinPerDay: 500, KeepShare: -0.1}, + "not a number": {MinPerDay: math.NaN()}, + } { + if g.Validate() == nil { + t.Errorf("%s: Validate accepted it", name) + } + if open, _ := g.Open([]Plan{saves(9000)}, 24, true); open { + t.Errorf("%s: gate open", name) + } + } + for _, h := range []float64{0, -3, math.NaN(), math.Inf(1)} { + if open, _ := (SavingsGate{MinPerDay: 500}).Open([]Plan{saves(9000)}, h, true); open { + t.Errorf("horizon %v: gate open", h) + } + } +} + +// The owner's rule from the house that built it: a peak is at least 200 and +// three times the lowest price of the next 12 hours, and the zone may sit at +// the bottom of its band for at most 3 hours of one. +var houseRule = PeakRelief{MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 3} + +func relievedHours(r PeakRelief, price []float64) float64 { + var n float64 + for _, v := range r.Slots(price, slotH) { + if v { + n += slotH + } + } + return n +} + +func TestPeakReliefNeedsASharpPeakNotAHighDay(t *testing.T) { + // A flat price, even a dear one, has nothing to wait for. + if got := relievedHours(houseRule, flat(day, 450)); got != 0 { + t.Errorf("a flat dear day relieved %v h", got) + } + // A dear plateau: the dearest hour is 1.4 times the cheapest, not 3. + plateau := hours(day, func(h float64) float64 { return 300 + 100*math.Sin(h/24*2*math.Pi) }) + if got := relievedHours(houseRule, plateau); got != 0 { + t.Errorf("a plateau relieved %v h", got) + } + // A real peak: 100 at night, 450 for five evening hours. + peak := eveningPeak(day, 100, 450) + got := relievedHours(houseRule, peak) + if got != 3 { + t.Errorf("a 3-hour limit relieved %v h of a 3-hour peak", got) + } +} + +func TestPeakReliefLimitsALongPeakToItsDearestHours(t *testing.T) { + price := hours(day, func(h float64) float64 { + switch { + case between(h, 17, 22): + return 400 + 10*(h-17) // five hours, rising + default: + return 100 + } + }) + rule := PeakRelief{MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 2} + got := rule.Slots(price, slotH) + var n float64 + for i, v := range got { + if v { + n += slotH + if h := math.Mod(float64(i)*slotH, 24); h < 20 { + t.Errorf("relieved slot at %v h, before the dearest two hours of a rising peak", h) + } + } + } + if n != 2 { + t.Errorf("relieved %v h, want 2", n) + } +} + +func TestPeakReliefBelowItsMinimumPriceIsNoPeak(t *testing.T) { + // A tenfold step, but at prices an owner calls small. + price := hours(day, func(h float64) float64 { + if between(h, 17, 20) { + return 50 + } + return 5 + }) + if got := relievedHours(houseRule, price); got != 0 { + t.Errorf("relieved %v h below the minimum price", got) + } +} + +func TestPeakReliefLetsTheTargetDownToTheBandOnly(t *testing.T) { + price := eveningPeak(day, 100, 450) + z := radiatorHouse(day, price).Zone + before := append([]float64(nil), z.TargetC...) + out := houseRule.Apply(z, price, slotH) + if len(out.TargetC) != len(before) { + t.Fatalf("target length %d, want %d", len(out.TargetC), len(before)) + } + var lowered int + for i := range before { + switch { + case out.TargetC[i] == before[i]: + case out.TargetC[i] == z.MinC[i]: + lowered++ + default: + t.Fatalf("slot %d target %v: neither untouched nor the bottom of the band %v", i, out.TargetC[i], z.MinC[i]) + } + if out.MinC[i] != z.MinC[i] || out.MaxC[i] != z.MaxC[i] { + t.Fatalf("slot %d: the band moved", i) + } + } + if lowered == 0 { + t.Fatal("no slot was let down") + } + for i, v := range before { + if z.TargetC[i] != v { + t.Fatal("Apply changed the zone it was given") + } + } +} + +func TestPeakReliefOffOrBrokenChangesNothing(t *testing.T) { + price := eveningPeak(day, 100, 450) + z := radiatorHouse(day, price).Zone + for name, r := range map[string]PeakRelief{ + "zero value": {}, + "no longest relief": {MinPrice: 200, Factor: 3, WindowH: 12}, + "factor not above 1": {MinPrice: 200, Factor: 1, WindowH: 12, MaxHours: 3}, + "no window": {MinPrice: 200, Factor: 3, MaxHours: 3}, + "not a number": {MinPrice: math.NaN(), Factor: 3, WindowH: 12, MaxHours: 3}, + "longer than a day": {MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: 30}, + "negative longest": {MinPrice: 200, Factor: 3, WindowH: 12, MaxHours: -1}, + } { + if relievedHours(r, price) != 0 { + t.Errorf("%s relieved something", name) + } + out := r.Apply(z, price, slotH) + for i := range z.TargetC { + if out.TargetC[i] != z.TargetC[i] { + t.Errorf("%s moved the target in slot %d", name, i) + break + } + } + } + if (PeakRelief{}).Validate() != nil { + t.Error("the zero value is not a valid, switched-off rule") + } + if houseRule.Validate() != nil { + t.Errorf("the house rule was refused: %v", houseRule.Validate()) + } + if (PeakRelief{MinPrice: 200, Factor: 1, WindowH: 12, MaxHours: 3}).Validate() == nil { + t.Error("a factor of 1 was accepted") + } + // A price that is not a number relieves nothing. + bad := append([]float64(nil), price...) + bad[10] = math.NaN() + if relievedHours(houseRule, bad) != 0 { + t.Error("a price series with a NaN relieved something") + } +} + +// Through the plan: the zone is let down further inside a relieved peak, and +// what it stored is worth more than the heat it would have held for comfort, +// so the heat bought comes out cheaper. The plan already buys nothing inside +// a peak this sharp, so the difference is where the zone sits, not how much +// is bought. +func TestPeakReliefLetsThePlanSitLowerThroughAPeak(t *testing.T) { + price := eveningPeak(day, 100, 450) + r := radiatorHouse(day, price) + plain := propose(t, r) + r.Zone = houseRule.Apply(r.Zone, price, slotH) + relieved := propose(t, r) + if got := heat(relieved, 17, 20); got > heat(plain, 17, 20)+1e-9 { + t.Errorf("bought %.2f kWh in the relieved peak, more than %.2f without the rule", got, heat(plain, 17, 20)) + } + loPlain, _ := tempRange(plain, 17, 20) + loRelieved, _ := tempRange(relieved, 17, 20) + if !(loRelieved < loPlain-0.05) { + t.Errorf("coldest in the peak %.2f with the rule, %.2f without: it did not sit lower", loRelieved, loPlain) + } + if loRelieved < r.Zone.MinC[0]-1e-6 { + t.Errorf("the zone left its band: %.2f below %.2f", loRelieved, r.Zone.MinC[0]) + } + if !(relieved.Cost < plain.Cost) { + t.Errorf("heat cost %.0f with the rule, %.0f without: nothing was saved", relieved.Cost, plain.Cost) + } +} diff --git a/go/internal/heatplan/plan.go b/go/internal/heatplan/plan.go index c7abb0d3c..e3fdb5da7 100644 --- a/go/internal/heatplan/plan.go +++ b/go/internal/heatplan/plan.go @@ -67,6 +67,11 @@ const ( // offers few values: a sliver over the limit can buy a whole slot of // heat, and must still lose. limitWeightFactor = 1e3 + // A change of value must gain at least this share of what one slot at + // full output costs. Without it the plan stops for a single slot to + // win a sliver on a small price step, and every such stop is a write + // to the device and a relay cycle. + switchShare = 0.1 ) // Zone is one heated thing as its twin describes it, in thermal terms. @@ -343,6 +348,7 @@ type solver struct { bandPerKh float64 limitPerKWh float64 chatter float64 + switchCost float64 lo, step float64 points int @@ -409,6 +415,7 @@ func newSolver(r Request) *solver { s.comfortPerKh = z.ComfortWeight * holdPerKh s.bandPerKh = bandWeightFactor * (heatPrice*z.CapacityKWhPerK + holdPerKh + 1e-9) s.chatter = chatterShare * holdPerKh * r.SlotH + s.switchCost = switchShare * heatPrice * a.MaxHeatKW * r.SlotH // The site's import limit outranks the band. A kWh held back costs the // zone at most 1/C kelvin outside its band for the rest of the horizon; // a kWh over the limit must cost more than that. @@ -675,7 +682,7 @@ func (s *solver) run(baseline bool) Plan { } } - plan := Plan{Slots: make([]Slot, 0, s.n)} + idx := make([]int, s.n) temp, rs := s.r.Zone.StartC, s.startState() for k := 0; k < s.n; k++ { var next [][]float64 @@ -683,11 +690,34 @@ func (s *solver) run(baseline bool) Plan { next = values[k+1] } j, st, nrs := pick(k, rs, temp, next) + idx[k], temp, rs = j, st.next, nrs + } + if !baseline { + s.smooth(idx) + } + return s.follow(idx) +} + +// act is the action for an index; below zero is a device with only start +// and stop left on its own thermostat, which holds the target. +func (s *solver) act(i int) action { + if i < 0 { + return action{setpoint: func(k int) float64 { return s.r.Zone.TargetC[k] }} + } + return s.acts[i] +} + +// follow predicts the zone under a sequence of actions. +func (s *solver) follow(idx []int) Plan { + plan := Plan{Slots: make([]Slot, 0, s.n)} + temp := s.r.Zone.StartC + for k, j := range idx { + st := s.advance(k, temp, s.act(j)) value := s.r.Zone.TargetC[k] if j >= 0 { value = s.acts[j].value } - temp, rs = st.next, nrs + temp = st.next plan.Slots = append(plan.Slots, Slot{Value: value, TempC: temp, HeatKWh: st.heatKWh, ElecKWh: st.elecKWh, Cost: st.cost}) plan.Cost += st.cost plan.BandExcursionKh += s.excursion(k, temp) * s.r.SlotH @@ -696,3 +726,75 @@ func (s *solver) run(baseline bool) Plan { plan.Cost += s.terminal(temp) return plan } + +// objective is what the plan minimises for a sequence of actions, or +Inf +// when the sequence breaks a minimum run. +func (s *solver) objective(idx []int) float64 { + temp, rs, total := s.r.Zone.StartC, s.startState(), 0.0 + for k, j := range idx { + next, ok := s.allowed(rs, s.acts[j]) + if !ok { + return math.Inf(1) + } + st := s.advance(k, temp, s.acts[j]) + total += st.cost + st.penalty + if j != s.neutral(k) { + total += s.chatter + } + temp, rs = st.next, next + } + return total + s.terminal(temp) +} + +// smooth removes the changes of value that do not pay for themselves. The +// optimum is found first and without a cost on changing, so that a long +// preheat is weighed as a whole; then each run of one value is folded into +// a neighbour when that costs less than switchCost for every change it +// removes. What is left is the plan's shape without the single slots it +// stopped or started for a sliver. +func (s *solver) smooth(idx []int) { + total := s.objective(idx) + run := make([]int, 0, s.n) + for a := 0; a < s.n; { + b := a + for b < s.n && idx[b] == idx[a] { + b++ + } + if a == 0 && b == s.n { + return + } + run = append(run[:0], idx[a:b]...) + removed := 1 + if a > 0 && b < s.n && idx[a-1] == idx[b] { + removed = 2 + } + best, bestTotal := -1, total+s.switchCost*float64(removed) + try := func(v int) { + for k := a; k < b; k++ { + idx[k] = v + } + if t := s.objective(idx); t < bestTotal { + best, bestTotal = v, t + } + copy(idx[a:b], run) + } + if a > 0 { + try(idx[a-1]) + } + if b < s.n && (a == 0 || idx[b] != idx[a-1]) { + try(idx[b]) + } + if best < 0 { + a = b + continue + } + for k := a; k < b; k++ { + idx[k] = best + } + total = bestTotal + // The run has joined a neighbour: weigh the joined run again. + for a > 0 && idx[a-1] == idx[a] { + a-- + } + } +} diff --git a/go/internal/heatplan/plan_test.go b/go/internal/heatplan/plan_test.go index 126229bad..f5959e15b 100644 --- a/go/internal/heatplan/plan_test.go +++ b/go/internal/heatplan/plan_test.go @@ -831,3 +831,38 @@ func TestBatteryMakesAPeakCheaperToHeatThrough(t *testing.T) { } } } + +func valueChanges(p Plan) int { + n := 0 + for i := 1; i < len(p.Slots); i++ { + if p.Slots[i].Value != p.Slots[i-1].Value { + n++ + } + } + return n +} + +// A price that wobbles by a couple of percent from slot to slot is worth +// nothing to chase: every change of value is a write to the device. The plan +// keeps the shape the real peak gives it and ignores the wobble. +func TestAWobbleInThePriceIsNotChased(t *testing.T) { + price := eveningPeak(day, 100, 200) + for i := range price { + price[i] += 2 * float64(i%2) + } + for name, c := range map[string]struct { + r Request + max int + }{ + "slab": {slabHouse(day, price, flat(day, 0)), 6}, + "radiators": {radiatorHouse(day, price), 16}, + } { + p := propose(t, c.r) + if got := valueChanges(p); got > c.max { + t.Errorf("%s: %d changes of value for a wobble, want at most %d", name, got, c.max) + } + if p.Cost >= p.BaselineCost { + t.Errorf("%s: cost %.0f, no better than %.0f left alone", name, p.Cost, p.BaselineCost) + } + } +} diff --git a/go/internal/heatplan/source.go b/go/internal/heatplan/source.go index 138bd4368..327911485 100644 --- a/go/internal/heatplan/source.go +++ b/go/internal/heatplan/source.go @@ -95,6 +95,9 @@ type Source struct { MaxCOP float64 } +// Validate refuses a source the planner cannot read one way. +func (s Source) Validate() error { return s.validate() } + func (s Source) validate() error { switch s.Kind { case SourceDirectElectric: diff --git a/go/internal/heatrun/holds.go b/go/internal/heatrun/holds.go new file mode 100644 index 000000000..309846c5b --- /dev/null +++ b/go/internal/heatrun/holds.go @@ -0,0 +1,48 @@ +package heatrun + +import ( + "context" + "encoding/json" + "errors" + "time" + + "github.com/srcfl/ftw/go/internal/drivercontrol" +) + +// HoldsWriter writes through the same holds an operator's control request +// uses, so the two share one lock and one expiry and neither can expire into +// a default that undoes the other. +type HoldsWriter struct{ Holds *drivercontrol.Holds } + +// Hold sends the value the way POST /api/drivers/{name}/control does. +func (w HoldsWriter) Hold(ctx context.Context, driver, control string, value float64, d time.Duration) (int64, error) { + body, err := json.Marshal(map[string]any{"action": control, "value": value, "offset": value}) + if err != nil { + return 0, err + } + var ( + exp int64 + sent error + ) + w.Holds.Send(ctx, driver, control, value, body, d, func(h drivercontrol.Hold, err error) { + exp, sent = h.ExpiresAt, err + }) + if sent == nil && exp == 0 { + return 0, errors.New("the hold was not armed") + } + return exp, sent +} + +// Active is the driver's hold now, if any. +func (w HoldsWriter) Active(driver string) (string, int64, bool) { + h := w.Holds.Active(driver) + if h == nil { + return "", 0, false + } + return h.Control, h.ExpiresAt, true +} + +// Release ends the hold and sends the driver's own default. +func (w HoldsWriter) Release(ctx context.Context, driver string) error { + return w.Holds.SendDefault(ctx, driver) +} diff --git a/go/internal/heatrun/service.go b/go/internal/heatrun/service.go new file mode 100644 index 000000000..190edf6e9 --- /dev/null +++ b/go/internal/heatrun/service.go @@ -0,0 +1,685 @@ +// Package heatrun plans the owner's heat zones with heatplan and, when the +// owner has turned writing on, holds each zone's control at the plan's value +// through drivercontrol (docs/adr/0012). +// +// It is shadow first. With heat.write off, the default, it plans every slot, +// shows the plan and what it would save, and writes nothing. With it on, a +// zone is written only when all of these hold: its twin is trusted, its +// control is declared as a setpoint, the plans of every zone together pass +// the owner's least saving, and no one else holds the driver. Anything else +// hands the device back to its own default, so a fault ends in the device +// running itself. +package heatrun + +import ( + "context" + "errors" + "fmt" + "log/slog" + "math" + "sync" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatplan" + "github.com/srcfl/ftw/go/internal/thermal" + "github.com/srcfl/ftw/go/internal/thermaltwin" +) + +const ( + // SlotH is the planning slot. Prices come in quarters. + SlotH = 0.25 + slot = 15 * time.Minute + // A horizon shorter than this is not worth planning; one longer is cut. + minSlots = 8 + maxSlots = 36 * 4 + // A reading older than this is not the zone now. + maxReadingAge = 15 * time.Minute + // A day's mean price needs this much of the day known. + dayMinHours = 22 + // From this local hour the comfort is for tomorrow when its prices are + // known, as the evening already heats for it. + tomorrowFromHour = 20 + // How long a written value is held when the driver declares no limit. + // Each tick writes again, so a value outlives a dead Core by at most + // this long. + defaultHold = 30 * time.Minute +) + +// Price is one price slot, in the unit the owner's limits are written in +// (öre/kWh including grid fee and tax, as the price service stores it). +type Price struct { + Start time.Time + Len time.Duration + Value float64 +} + +// Writer is the part of drivercontrol.Holds the service writes through, so +// planned values and an operator's hold share one lock and one expiry. +type Writer interface { + // Hold sends value to the control and holds it for d. It returns when + // the hold expires. + Hold(ctx context.Context, driver, control string, value float64, d time.Duration) (expiresAtMs int64, err error) + // Active is the hold on the driver now: its control and expiry, and + // whether there is one. + Active(driver string) (control string, expiresAtMs int64, ok bool) + // Release clears the hold and sends the driver's own default. + Release(ctx context.Context, driver string) error +} + +// Inputs is everything the service reads. Each is read at each tick. +type Inputs struct { + Config func() *config.Heat + Twins func() []thermaltwin.ZoneStatus + Latest func(driver, metric string) (float64, time.Time, bool) + Prices func(from, to time.Time) []Price + Outdoor func(from time.Time, n int) ([]float64, bool) + // Control is the declared control behind "/". + Control func(driver, control string) (drivers.CatalogControl, bool) + // Writer is nil when nothing may be written, whatever the config says. + Writer Writer + // SiteFresh reports whether the site meter is current. Stale site-meter + // data stops dispatch (AGENTS.md); nil means no meter is known, which + // also stops it. + SiteFresh func() bool + // Now is time.Now unless a test sets it. + Now func() time.Time +} + +// Gate is the owner's least saving as the last tick weighed it. +type Gate struct { + Set bool `json:"set"` + Limit float64 `json:"min_per_day,omitempty"` + PerDay float64 `json:"per_day"` + Open bool `json:"open"` + HorizonH float64 `json:"horizon_h"` +} + +// ZonePlan is one zone's plan and what was done with it. +type ZonePlan struct { + Name string `json:"name"` + Sensor string `json:"sensor"` + Control string `json:"control,omitempty"` + // Planned is false when the zone could not be planned; Reason says why. + Planned bool `json:"planned"` + Reason string `json:"reason,omitempty"` + Twin string `json:"twin_status,omitempty"` + // StartC is the zone now; TargetC the owner's target and DayTargetC the + // target the day's price moved it to. + StartC float64 `json:"start_c,omitempty"` + TargetC float64 `json:"target_c"` + DayTargetC float64 `json:"day_target_c"` + DayMean float64 `json:"day_mean_price,omitempty"` + PeakSlots int `json:"peak_relief_slots,omitempty"` + Value *float64 `json:"value,omitempty"` + Neutral *float64 `json:"neutral_value,omitempty"` + Saving float64 `json:"saving"` + Cost float64 `json:"cost"` + Baseline float64 `json:"baseline_cost"` + ExcursionKh float64 `json:"band_excursion_kh"` + // Write is what was done with the control this tick. + Write string `json:"write"` + Slots []heatplan.Slot `json:"slots,omitempty"` +} + +// Snapshot is the last tick. +type Snapshot struct { + At time.Time `json:"at"` + Enabled bool `json:"enabled"` + Write bool `json:"write"` + Gate Gate `json:"gate"` + Zones []ZonePlan `json:"zones"` + // Prices is the horizon's price per slot, from At. + Prices []float64 `json:"prices,omitempty"` +} + +type held struct { + control string + value float64 + expiresMs int64 + changedAt time.Time + hold time.Duration +} + +// refreshEvery is how often held values are checked between plans. A device +// that drops a written value by itself (CTC resets its control registers +// five minutes after the last write) is written again before its hold ends. +const refreshEvery = 30 * time.Second + +// Service runs the plan every slot. +type Service struct { + in Inputs + + mu sync.Mutex + last Snapshot + gateOpen bool + held map[string]held // by driver: what this service holds + + cancel context.CancelFunc + done chan struct{} +} + +// New returns a service that has not started. +func New(in Inputs) *Service { + if in.Now == nil { + in.Now = time.Now + } + return &Service{in: in, held: map[string]held{}} +} + +// Start ticks at every slot boundary until Stop. +func (s *Service) Start(ctx context.Context) { + ctx, s.cancel = context.WithCancel(ctx) + s.done = make(chan struct{}) + go func() { + defer close(s.done) + // Let telemetry and the twins fill before the first plan. + next := s.in.Now().Add(time.Minute) + ticker := time.NewTicker(refreshEvery) + defer ticker.Stop() + for { + select { + case <-ctx.Done(): + return + case <-ticker.C: + } + if now := s.in.Now(); !now.Before(next) { + s.Tick(ctx) + next = now.Truncate(slot).Add(slot) + } else { + s.Refresh(ctx) + } + } + }() +} + +// Refresh writes a held value again when its hold would end before the next +// check, and hands the device back if the site meter went stale since the +// plan. It decides nothing new: values change only at Tick. +func (s *Service) Refresh(ctx context.Context) { + s.mu.Lock() + defer s.mu.Unlock() + if s.in.Writer == nil { + return + } + now := s.in.Now() + for driver, h := range s.held { + if s.in.SiteFresh == nil || !s.in.SiteFresh() { + s.releaseLocked(ctx, driver) + continue + } + if time.UnixMilli(h.expiresMs).Sub(now) > 3*refreshEvery { + continue + } + if c, exp, ok := s.in.Writer.Active(driver); !ok || c != h.control || exp != h.expiresMs { + // Expired, or someone else holds it now: not ours to renew. + delete(s.held, driver) + continue + } + exp, err := s.in.Writer.Hold(ctx, driver, h.control, h.value, h.hold) + if err != nil { + delete(s.held, driver) + slog.Warn("heat: renewing a hold failed", "driver", driver, "err", err) + continue + } + h.expiresMs = exp + s.held[driver] = h + } +} + +// Stop ends the ticks and hands back every driver this service holds. +func (s *Service) Stop() { + if s.cancel == nil { + return + } + s.cancel() + <-s.done + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + s.mu.Lock() + defer s.mu.Unlock() + for driver := range s.held { + s.releaseLocked(ctx, driver) + } +} + +// Snapshot returns the last tick. +func (s *Service) Snapshot() Snapshot { + s.mu.Lock() + defer s.mu.Unlock() + out := s.last + out.Zones = append([]ZonePlan(nil), s.last.Zones...) + return out +} + +// Tick plans every zone once and writes what may be written. +func (s *Service) Tick(ctx context.Context) { + s.mu.Lock() + defer s.mu.Unlock() + now := s.in.Now() + var cfg *config.Heat + if s.in.Config != nil { + cfg = s.in.Config() + } + snap := Snapshot{At: now} + if cfg == nil || len(cfg.Zones) == 0 || cfg.Validate() != nil { + s.last = snap + s.releaseAllLocked(ctx) + return + } + snap.Enabled = true + snap.Write = cfg.Write && s.in.Writer != nil + + start := now.Truncate(slot) + price := s.horizon(start) + snap.Prices = price + twins := map[string]thermaltwin.ZoneStatus{} + if s.in.Twins != nil { + for _, t := range s.in.Twins() { + twins[t.Key] = t + } + } + + zones := make([]ZonePlan, len(cfg.Zones)) + plans := make([]heatplan.Plan, 0, len(cfg.Zones)) + reqs := make([]*heatplan.Request, len(cfg.Zones)) + for i, zc := range cfg.Zones { + zp := ZonePlan{Name: zc.Name, Sensor: zc.Sensor, Control: zc.Control, TargetC: zc.TargetC, DayTargetC: zc.TargetC} + req, err := s.request(zc, twins, price, start, now, &zp) + if err != nil { + zp.Reason = err.Error() + zones[i] = zp + continue + } + plan, err := heatplan.Propose(*req) + if err != nil { + zp.Reason = err.Error() + zones[i] = zp + continue + } + reqs[i] = req + zp.Planned = true + zp.Saving, zp.Cost, zp.Baseline, zp.ExcursionKh = plan.Saving(), plan.Cost, plan.BaselineCost, plan.BandExcursionKh + zp.Slots = plan.Slots + if len(plan.Slots) > 0 { + v := plan.Slots[0].Value + zp.Value = &v + } + plans = append(plans, plan) + zones[i] = zp + } + + gate := heatplan.SavingsGate{} + if cfg.Savings != nil { + gate = *cfg.Savings + } + horizonH := float64(len(price)) * SlotH + open, perDay := gate.Open(plans, horizonH, s.gateOpen) + if len(plans) == 0 { + open, perDay = false, 0 + } + s.gateOpen = open + snap.Gate = Gate{Set: gate.MinPerDay > 0, Limit: gate.MinPerDay, PerDay: perDay, Open: open, HorizonH: horizonH} + + wanted := map[string]bool{} + for i, zc := range cfg.Zones { + zones[i].Write = s.write(ctx, cfg, zc, &zones[i], reqs[i], twins, open, snap.Write, now, wanted) + } + // A driver this service holds that no zone wants any more goes back. + for driver := range s.held { + if !wanted[driver] { + s.releaseLocked(ctx, driver) + } + } + snap.Zones = zones + s.last = snap +} + +// horizon is the price per slot from start, as far as prices run unbroken. +func (s *Service) horizon(start time.Time) []float64 { + if s.in.Prices == nil { + return nil + } + rows := s.in.Prices(start, start.Add(maxSlots*slot)) + var out []float64 + for k := 0; k < maxSlots; k++ { + t := start.Add(time.Duration(k) * slot) + v, ok := priceAt(rows, t) + if !ok { + break + } + out = append(out, v) + } + return out +} + +func priceAt(rows []Price, t time.Time) (float64, bool) { + for _, r := range rows { + if !t.Before(r.Start) && t.Before(r.Start.Add(r.Len)) && !math.IsNaN(r.Value) && !math.IsInf(r.Value, 0) { + return r.Value, true + } + } + return 0, false +} + +// dayMean is the mean price of the day the comfort is for: today, or from +// the evening tomorrow when tomorrow is known. +func (s *Service) dayMean(now time.Time) (float64, bool) { + if s.in.Prices == nil { + return 0, false + } + day := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()) + mean := func(d time.Time) (float64, bool) { + end := d.AddDate(0, 0, 1) + rows := s.in.Prices(d, end) + var series []float64 + for t := d; t.Before(end); t = t.Add(slot) { + if v, ok := priceAt(rows, t); ok { + series = append(series, v) + } + } + return heatplan.DayMean(series, SlotH, dayMinHours) + } + if now.Hour() >= tomorrowFromHour { + if m, ok := mean(day.AddDate(0, 0, 1)); ok { + return m, true + } + } + return mean(day) +} + +func splitKey(key string) (string, string) { + for i := 0; i < len(key); i++ { + if key[i] == '/' { + return key[:i], key[i+1:] + } + } + return key, "" +} + +func (s *Service) reading(key string, now time.Time) (float64, error) { + if s.in.Latest == nil { + return 0, errors.New("no telemetry") + } + driver, metric := splitKey(key) + v, at, ok := s.in.Latest(driver, metric) + if !ok { + return 0, fmt.Errorf("%s has no reading", key) + } + if now.Sub(at) > maxReadingAge { + return 0, fmt.Errorf("%s was last read %s ago", key, now.Sub(at).Round(time.Minute)) + } + return v, nil +} + +func constant(n int, v float64) []float64 { + out := make([]float64, n) + for i := range out { + out[i] = v + } + return out +} + +// request builds one zone's request, or says why it cannot. +func (s *Service) request(zc config.HeatZone, twins map[string]thermaltwin.ZoneStatus, price []float64, start, now time.Time, zp *ZonePlan) (*heatplan.Request, error) { + n := len(price) + if n < minSlots { + return nil, fmt.Errorf("only %d quarters of prices are known", n) + } + twin, ok := twins[zc.Sensor] + if !ok { + return nil, errors.New("no thermal twin learns this sensor") + } + zp.Twin = string(twin.Status) + p := twin.Params + if p.TauH == nil || p.CapacityKWhPerK == nil { + return nil, errors.New("the twin has no physical model yet") + } + startC, err := s.reading(zc.Sensor, now) + if err != nil { + return nil, err + } + zp.StartC = startC + + var outdoor []float64 + if s.in.Outdoor != nil { + if o, ok := s.in.Outdoor(start, n); ok && len(o) == n { + outdoor = o + } + } + var boundary []float64 + if zc.Boundary == config.HeatBoundaryOutdoor { + if outdoor == nil { + return nil, errors.New("no outdoor forecast for the horizon") + } + boundary = outdoor + } else { + b, err := s.reading(zc.Boundary, now) + if err != nil { + return nil, fmt.Errorf("boundary: %w", err) + } + boundary = constant(n, b) + } + if outdoor == nil { + if zc.Source == config.HeatSourceHeatPump { + return nil, errors.New("a heat pump needs the outdoor forecast for the horizon") + } + // Direct electric heat does not depend on the weather; the + // planner still wants a series. + outdoor = boundary + } + + z := heatplan.Zone{ + TauH: *p.TauH, + CapacityKWhPerK: *p.CapacityKWhPerK, + OtherGainKPerH: p.OtherGainKPerH, + StartC: startC, + BoundaryC: boundary, + TargetC: constant(n, zc.TargetC), + MinC: constant(n, zc.MinC), + MaxC: constant(n, zc.MaxC), + ComfortWeight: zc.ComfortWeight, + } + if zc.PriceComfort != nil && zc.PriceComfort.Enabled() { + if mean, ok := s.dayMean(now); ok { + zp.DayMean = mean + z = zc.PriceComfort.Apply(z, mean) + zp.DayTargetC = z.TargetC[0] + } + } + if zc.PeakRelief != nil && zc.PeakRelief.Enabled() { + for _, v := range zc.PeakRelief.Slots(price, SlotH) { + if v { + zp.PeakSlots++ + } + } + z = zc.PeakRelief.Apply(z, price, SlotH) + } + + act, neutral, err := s.actuator(zc) + if err != nil { + return nil, err + } + if neutral != nil { + zp.Neutral = neutral + } + return &heatplan.Request{SlotH: SlotH, Price: price, OutdoorC: outdoor, Zone: z, Actuator: act}, nil +} + +// actuator is the zone's control as the plan sees it. A zone with no +// control is planned as if a thermostat could be set anywhere in its band +// in half-degree steps, so the owner sees what a control would do. +func (s *Service) actuator(zc config.HeatZone) (heatplan.Actuator, *float64, error) { + act := heatplan.Actuator{Strategy: thermal.InfluenceSetpoint, MaxHeatKW: zc.HeatKW, Source: zc.PlanSource()} + lo, hi, step := zc.MinC, zc.MaxC, 0.5 + var declaredDefault *float64 + if zc.Control != "" { + if s.in.Control == nil { + return heatplan.Actuator{}, nil, errors.New("the control's declaration is not known") + } + c, ok := s.in.Control(splitKey(zc.Control)) + if !ok { + return heatplan.Actuator{}, nil, fmt.Errorf("%s is not a declared control", zc.Control) + } + if c.Thermal == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s does not say what it does to heat", zc.Control) + } + in := c.Input + if in.Min == nil || in.Max == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s declares no range", zc.Control) + } + if in.Step != nil && *in.Step > 0 { + step = *in.Step + } + declaredDefault = in.Default + switch c.Thermal.Strategy { + case thermal.InfluenceSetpoint: + lo, hi = math.Max(lo, *in.Min), math.Min(hi, *in.Max) + case thermal.InfluenceCurveOffset: + if zc.CurveEffect == nil { + return heatplan.Actuator{}, nil, fmt.Errorf("%s is a curve offset; the zone needs curve_effect", zc.Control) + } + act.Strategy = thermal.InfluenceCurveOffset + act.ZoneKPerUnit, act.SupplyKPerUnit = zc.CurveEffect.ZoneKPerUnit, zc.CurveEffect.SupplyKPerUnit + lo, hi = *in.Min, *in.Max + default: + return heatplan.Actuator{}, nil, fmt.Errorf("%s is %s; only setpoints and curve offsets are planned yet", zc.Control, c.Thermal.Strategy) + } + } + act.Values = candidates(lo, hi, step) + if len(act.Values) == 0 { + return heatplan.Actuator{}, nil, errors.New("the control can reach nothing inside the band") + } + // The device's own value: its declared default, or for a setpoint the + // step nearest the target, for an offset the step nearest zero. + aim := zc.TargetC + if act.Strategy == thermal.InfluenceCurveOffset { + aim = 0 + } + if declaredDefault != nil { + aim = *declaredDefault + } + neutral := act.Values[0] + for _, v := range act.Values { + if math.Abs(v-aim) < math.Abs(neutral-aim) { + neutral = v + } + } + return act, &neutral, nil +} + +// candidates are the control's steps from lo to hi, at most 16; a fine step +// over a wide band is coarsened by whole multiples so lo and hi stay in. +func candidates(lo, hi, step float64) []float64 { + if !(step > 0) || hi < lo { + return nil + } + first := math.Ceil(lo/step-1e-9) * step + count := int(math.Floor((hi-first)/step+1e-9)) + 1 + if count < 1 { + return nil + } + mult := 1 + for (count-1)/mult+1 > 16 { + mult++ + } + var out []float64 + for i := 0; i < count; i += mult { + out = append(out, math.Round((first+float64(i)*step)*1000)/1000) + } + return out +} + +// write does what may be done with one zone's control and says what it did. +func (s *Service) write(ctx context.Context, cfg *config.Heat, zc config.HeatZone, zp *ZonePlan, req *heatplan.Request, twins map[string]thermaltwin.ZoneStatus, gateOpen, writeOn bool, now time.Time, wanted map[string]bool) string { + if zc.Control == "" { + return "shadow: no control" + } + if !writeOn { + return "shadow: writing is off" + } + driver, control := splitKey(zc.Control) + // The zone may claim the driver only while it would write to it. + switch { + case !zp.Planned || zp.Value == nil: + return s.giveBack(ctx, driver, "not planned") + case twins[zc.Sensor].Status != thermaltwin.StatusTrusted: + return s.giveBack(ctx, driver, "twin not trusted") + case !gateOpen: + return s.giveBack(ctx, driver, "below the least saving") + case s.in.SiteFresh == nil || !s.in.SiteFresh(): + return s.giveBack(ctx, driver, "site meter is stale") + } + if wanted[driver] { + return "skipped: another zone writes to this driver" + } + value := *zp.Value + if zp.Neutral != nil && value == *zp.Neutral { + return s.giveBack(ctx, driver, "plan asks for the device's own") + } + ours, mine := s.held[driver] + if c, exp, ok := s.in.Writer.Active(driver); ok && (!mine || c != ours.control || exp != ours.expiresMs) { + return "skipped: held by someone else" + } + wanted[driver] = true + + hold := defaultHold + minInterval := time.Duration(0) + if c, ok := s.in.Control(driver, control); ok && c.Thermal != nil { + if c.Thermal.DeviceHoldMaxS != nil && *c.Thermal.DeviceHoldMaxS > 0 { + hold = min(hold, time.Duration(*c.Thermal.DeviceHoldMaxS)*time.Second) + } + if c.Thermal.MinIntervalS != nil { + minInterval = time.Duration(*c.Thermal.MinIntervalS) * time.Second + } + } + if mine && ours.value != value && now.Sub(ours.changedAt) < minInterval { + return fmt.Sprintf("held %.1f: the control may change again in %s", ours.value, (minInterval - now.Sub(ours.changedAt)).Round(time.Minute)) + } + if mine && ours.value == value && time.UnixMilli(ours.expiresMs).Sub(now) > 3*refreshEvery { + return fmt.Sprintf("holding %.1f", value) + } + exp, err := s.in.Writer.Hold(ctx, driver, control, value, hold) + if err != nil { + delete(s.held, driver) + slog.Warn("heat: write failed", "zone", zc.Name, "control", zc.Control, "err", err) + return "write failed: " + err.Error() + } + changed := now + if mine && ours.value == value { + changed = ours.changedAt + } + s.held[driver] = held{control: control, value: value, expiresMs: exp, changedAt: changed, hold: hold} + return fmt.Sprintf("wrote %.1f", value) +} + +func (s *Service) giveBack(ctx context.Context, driver, why string) string { + if _, mine := s.held[driver]; !mine { + return "device runs itself: " + why + } + s.releaseLocked(ctx, driver) + return "released: " + why +} + +func (s *Service) releaseAllLocked(ctx context.Context) { + for driver := range s.held { + s.releaseLocked(ctx, driver) + } +} + +// releaseLocked hands the driver back only while the hold is still this +// service's: an operator's newer hold is not undone. +func (s *Service) releaseLocked(ctx context.Context, driver string) { + ours := s.held[driver] + delete(s.held, driver) + if s.in.Writer == nil { + return + } + if c, exp, ok := s.in.Writer.Active(driver); ok && (c != ours.control || exp != ours.expiresMs) { + return + } + if err := s.in.Writer.Release(ctx, driver); err != nil { + slog.Warn("heat: release failed", "driver", driver, "err", err) + } +} diff --git a/go/internal/heatrun/service_test.go b/go/internal/heatrun/service_test.go new file mode 100644 index 000000000..460cdb81b --- /dev/null +++ b/go/internal/heatrun/service_test.go @@ -0,0 +1,405 @@ +package heatrun + +import ( + "context" + "strings" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/config" + "github.com/srcfl/ftw/go/internal/drivers" + "github.com/srcfl/ftw/go/internal/heatplan" + "github.com/srcfl/ftw/go/internal/thermal" + "github.com/srcfl/ftw/go/internal/thermaltwin" +) + +func fp(v float64) *float64 { return &v } +func ip(v int) *int { return &v } + +type fakeWriter struct { + holds map[string]struct { + control string + exp int64 + } + sent []float64 + released []string + now func() time.Time +} + +func newWriter(now func() time.Time) *fakeWriter { + return &fakeWriter{holds: map[string]struct { + control string + exp int64 + }{}, now: now} +} + +func (w *fakeWriter) Hold(_ context.Context, driver, control string, v float64, d time.Duration) (int64, error) { + exp := w.now().Add(d).UnixMilli() + w.holds[driver] = struct { + control string + exp int64 + }{control, exp} + w.sent = append(w.sent, v) + return exp, nil +} + +func (w *fakeWriter) Active(driver string) (string, int64, bool) { + h, ok := w.holds[driver] + if !ok || h.exp <= w.now().UnixMilli() { + return "", 0, false + } + return h.control, h.exp, true +} + +func (w *fakeWriter) Release(_ context.Context, driver string) error { + delete(w.holds, driver) + w.released = append(w.released, driver) + return nil +} + +type house struct { + now time.Time + cfg *config.Heat + status thermaltwin.Status + price func(h float64) float64 + floor float64 + w *fakeWriter + + meterStale bool +} + +// A bathroom floor the size of the one that built this: 0.6 kW, coasting +// some ten hours, regulated on its floor sensor by an air thermostat. +func newHouse() *house { + h := &house{ + now: time.Date(2026, 11, 17, 12, 0, 0, 0, time.Local), + status: thermaltwin.StatusTrusted, + floor: 23, + price: func(hr float64) float64 { + if hr >= 17 && hr < 20 { + return 450 + } + return 100 + }, + } + h.cfg = &config.Heat{Write: true, Zones: []config.HeatZone{{ + Name: "badrum", Sensor: "wiser_7/floor_temp_c", Control: "wiser_7/set_setpoint", + Boundary: "wiser_7/room_temp_c", Source: "direct_electric", HeatKW: 0.6, + TargetC: 24.5, MinC: 20, MaxC: 27, ComfortWeight: 2, + }}} + h.w = newWriter(func() time.Time { return h.now }) + return h +} + +func (h *house) service() *Service { + return New(Inputs{ + Config: func() *config.Heat { return h.cfg }, + Twins: func() []thermaltwin.ZoneStatus { + return []thermaltwin.ZoneStatus{{ + Zone: thermaltwin.Zone{Key: "wiser_7/floor_temp_c"}, + Status: h.status, + Params: thermaltwin.Params{TauH: fp(10), CapacityKWhPerK: fp(0.4)}, + }} + }, + Latest: func(driver, metric string) (float64, time.Time, bool) { + switch metric { + case "floor_temp_c": + return h.floor, h.now, true + case "room_temp_c": + return 21, h.now, true + } + return 0, time.Time{}, false + }, + Prices: func(from, to time.Time) []Price { + var out []Price + for t := from.Truncate(time.Hour); t.Before(to); t = t.Add(time.Hour) { + out = append(out, Price{Start: t, Len: time.Hour, Value: h.price(float64(t.Hour()))}) + } + // Prices known until midnight tomorrow. + end := time.Date(2026, 11, 19, 0, 0, 0, 0, time.Local) + var cut []Price + for _, p := range out { + if p.Start.Before(end) { + cut = append(cut, p) + } + } + return cut + }, + Control: func(driver, control string) (drivers.CatalogControl, bool) { + if driver != "wiser_7" || control != "set_setpoint" { + return drivers.CatalogControl{}, false + } + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(5), Max: fp(30), Step: fp(0.5)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceSetpoint, MinIntervalS: ip(300), DeviceHoldMaxS: ip(1800)}, + }, true + }, + Writer: h.w, + SiteFresh: func() bool { return !h.meterStale }, + Now: func() time.Time { return h.now }, + }) +} + +func TestShadowPlansAndWritesNothing(t *testing.T) { + h := newHouse() + h.cfg.Write = false + s := h.service() + s.Tick(context.Background()) + snap := s.Snapshot() + if !snap.Enabled || snap.Write { + t.Fatalf("enabled %v write %v", snap.Enabled, snap.Write) + } + z := snap.Zones[0] + if !z.Planned || z.Value == nil || len(z.Slots) == 0 { + t.Fatalf("zone not planned: %+v", z) + } + if !strings.HasPrefix(z.Write, "shadow") || len(h.w.sent) != 0 { + t.Fatalf("write %q, sent %v", z.Write, h.w.sent) + } +} + +// Before a peak the plan stores heat in the floor: it asks for more than the +// device's own setpoint, and with writing on and the twin trusted it is held. +func TestTrustedZoneIsWrittenAndHeldOnce(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if len(h.w.sent) != 1 || !strings.HasPrefix(z.Write, "wrote") { + t.Fatalf("write %q, sent %v, value %v neutral %v", z.Write, h.w.sent, deref(z.Value), deref(z.Neutral)) + } + // The next quarter with the same value does not write again while the + // hold has time left. + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; len(h.w.sent) != 1 && !strings.HasPrefix(z.Write, "wrote") { + t.Fatalf("second tick: %q, sent %v", z.Write, h.w.sent) + } + s.Stop() +} + +func deref(p *float64) any { + if p == nil { + return nil + } + return *p +} + +func TestUntrustedTwinOrClosedGateWritesNothingAndHandsBack(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v (%q)", h.w.sent, s.Snapshot().Zones[0].Write) + } + + h.status = thermaltwin.StatusLearning + h.now = h.now.Add(slot) + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !strings.HasPrefix(z.Write, "released") || len(h.w.released) != 1 { + t.Fatalf("untrusted: %q, released %v", z.Write, h.w.released) + } + + h.status = thermaltwin.StatusTrusted + h.cfg.Savings = &heatplan.SavingsGate{MinPerDay: 1e6} + h.now = h.now.Add(slot) + s.Tick(context.Background()) + snap := s.Snapshot() + if snap.Gate.Open || !strings.Contains(snap.Zones[0].Write, "least saving") || len(h.w.sent) != 1 { + t.Fatalf("closed gate: %+v, %q, sent %v", snap.Gate, snap.Zones[0].Write, h.w.sent) + } +} + +// An operator's hold on the driver is not overwritten and not released. +func TestAnOperatorsHoldIsLeftAlone(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + h.w.holds["wiser_7"] = struct { + control string + exp int64 + }{"set_setpoint", h.now.Add(time.Hour).UnixMilli()} + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !strings.Contains(z.Write, "someone else") || len(h.w.sent) != 0 { + t.Fatalf("%q, sent %v", z.Write, h.w.sent) + } + h.cfg.Write = false + s.Tick(context.Background()) + if len(h.w.released) != 0 { + t.Fatalf("released an operator's hold: %v", h.w.released) + } +} + +// Writing off after writing hands the device back at once. +func TestTurningWritingOffHandsTheDeviceBack(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + h.cfg.Write = false + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if len(h.w.released) != 1 { + t.Fatalf("released %v after writing was turned off", h.w.released) + } +} + +func TestZoneThatCannotBePlannedSaysWhy(t *testing.T) { + for name, tc := range map[string]struct { + mod func(h *house) + want string + }{ + "stale sensor": {func(h *house) { h.floor = 22; h.now = h.now.Add(0) }, ""}, + "no model": {func(h *house) { h.cfg.Zones[0].Sensor = "wiser_8/floor_temp_c" }, "no thermal twin"}, + "undeclared control": {func(h *house) { h.cfg.Zones[0].Control = "wiser_7/other" }, "not a declared control"}, + } { + if tc.want == "" { + continue + } + h := newHouse() + tc.mod(h) + s := h.service() + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if z.Planned || !strings.Contains(z.Reason, tc.want) { + t.Errorf("%s: planned %v reason %q", name, z.Planned, z.Reason) + } + } +} + +func TestCandidatesStayWithinSixteenAndKeepTheEnds(t *testing.T) { + got := candidates(20, 27, 0.5) + if len(got) > 16 || got[0] != 20 || got[len(got)-1] > 27 { + t.Fatalf("candidates %v", got) + } + if got := candidates(20, 22, 0.5); len(got) != 5 { + t.Fatalf("candidates %v", got) + } + if candidates(22, 20, 0.5) != nil { + t.Fatal("an empty range gave candidates") + } +} + +// Stale site-meter data stops dispatch: the device goes back to itself. +func TestStaleSiteMeterStopsWriting(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v", h.w.sent) + } + h.meterStale = true + h.now = h.now.Add(slot) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; !strings.Contains(z.Write, "site meter") || len(h.w.released) != 1 { + t.Fatalf("%q, released %v", z.Write, h.w.released) + } +} + +// A device that drops a written value after five minutes is written again +// between plans, and stops being written when the meter goes stale. +func TestShortDeviceHoldIsRenewedBetweenPlans(t *testing.T) { + h := newHouse() + h.now = time.Date(2026, 11, 17, 15, 0, 0, 0, time.Local) + h.floor = 22 + s := h.service() + s.in.Control = func(driver, control string) (drivers.CatalogControl, bool) { + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(5), Max: fp(30), Step: fp(0.5)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceSetpoint, DeviceHoldMaxS: ip(300)}, + }, true + } + s.Tick(context.Background()) + if len(h.w.sent) != 1 { + t.Fatalf("setup: sent %v (%q)", h.w.sent, s.Snapshot().Zones[0].Write) + } + for i := 0; i < 28; i++ { // 14 minutes in 30 s steps + h.now = h.now.Add(refreshEvery) + s.Refresh(context.Background()) + if _, _, ok := h.w.Active("wiser_7"); !ok { + t.Fatalf("the hold lapsed after %v", time.Duration(i+1)*refreshEvery) + } + } + if len(h.w.sent) < 3 || len(h.w.sent) > 6 { + t.Fatalf("renewed %d times in 14 minutes of a 5-minute hold", len(h.w.sent)-1) + } + h.meterStale = true + s.Refresh(context.Background()) + if len(h.w.released) != 1 { + t.Fatalf("a stale meter did not hand the device back: %v", h.w.released) + } +} + +// The house heated by a CTC on a heat curve, its rooms read by an +// underfloor gateway: a heat pump zone planned on the outdoor forecast, in +// shadow, and through a curve offset once the pump declares one. +func heatPumpHouse(h *house, outdoor bool) *Service { + h.cfg = &config.Heat{Zones: []config.HeatZone{{ + Name: "house", Sensor: "wiser_7/floor_temp_c", HeatInput: "CTC/space_heat_w", + Boundary: "outdoor", Source: "heat_pump", HeatKW: 6, + TargetC: 21, MinC: 20, MaxC: 22.5, ComfortWeight: 2, + HeatPump: &config.HeatPump{Supply: &config.HeatSupplyCurve{ColdOutdoorC: -20, ColdSupplyC: 45, MildOutdoorC: 15, MildSupplyC: 24}}, + }}} + h.floor = 21 + s := h.service() + s.in.Twins = func() []thermaltwin.ZoneStatus { + return []thermaltwin.ZoneStatus{{Zone: thermaltwin.Zone{Key: "wiser_7/floor_temp_c"}, Status: h.status, + Params: thermaltwin.Params{TauH: fp(60), CapacityKWhPerK: fp(5)}}} + } + if outdoor { + s.in.Outdoor = func(_ time.Time, n int) ([]float64, bool) { return constant(n, 0), true } + } + return s +} + +func TestHeatPumpZoneNeedsTheForecastAndPlansWithIt(t *testing.T) { + h := newHouse() + s := heatPumpHouse(h, false) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; z.Planned || !strings.Contains(z.Reason, "outdoor forecast") { + t.Fatalf("without a forecast: planned %v, %q", z.Planned, z.Reason) + } + h = newHouse() + s = heatPumpHouse(h, true) + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; !z.Planned || z.Value == nil { + t.Fatalf("with a forecast: %+v", z) + } +} + +func TestCurveOffsetIsPlannedOnlyWithItsEffect(t *testing.T) { + h := newHouse() + s := heatPumpHouse(h, true) + h.cfg.Zones[0].Control = "CTC/set_heat_curve_offset" + s.in.Control = func(driver, control string) (drivers.CatalogControl, bool) { + return drivers.CatalogControl{ID: control, + Input: drivers.CatalogControlInput{Type: "number", Min: fp(-5), Max: fp(5), Step: fp(1), Default: fp(0)}, + Thermal: &drivers.CatalogThermalControl{Asset: thermal.AssetSpaceHeat, Strategy: thermal.InfluenceCurveOffset}, + }, true + } + s.Tick(context.Background()) + if z := s.Snapshot().Zones[0]; z.Planned || !strings.Contains(z.Reason, "curve_effect") { + t.Fatalf("without an effect: planned %v, %q", z.Planned, z.Reason) + } + h.cfg.Zones[0].CurveEffect = &config.CurveEffect{ZoneKPerUnit: 0.5, SupplyKPerUnit: 1} + s.Tick(context.Background()) + z := s.Snapshot().Zones[0] + if !z.Planned || z.Neutral == nil || *z.Neutral != 0 { + t.Fatalf("with an effect: %+v", z) + } + for _, sl := range z.Slots { + if sl.Value < -5 || sl.Value > 5 { + t.Fatalf("offset %v outside the declared range", sl.Value) + } + } +} diff --git a/go/internal/thermaltwin/service.go b/go/internal/thermaltwin/service.go index 7dda8fdea..983c43ebf 100644 --- a/go/internal/thermaltwin/service.go +++ b/go/internal/thermaltwin/service.go @@ -40,6 +40,11 @@ type Zone struct { Key string `json:"key"` SensorDriver string `json:"sensor_driver"` SensorMetric string `json:"sensor_metric"` + // HeatInput is the owner's "/" for the heat that warms + // this zone, such as a heat pump's estimated space heat for a room + // sensor on another device. Empty means the sensor's own driver's, or + // the single other driver's, HeatPowerMetric. + HeatInput string `json:"heat_input,omitempty"` } // MetricReader is the part of the telemetry store the service reads. @@ -222,7 +227,8 @@ func (s *Service) sampleLocked(zs *zoneState, now time.Time) { } zs.src = src if src != "" { - p, _, ok := s.read(src, HeatPowerMetric, now) + driver, metric := powerRef(src) + p, _, ok := s.read(driver, metric, now) if !ok { zs.gap = true return @@ -236,6 +242,14 @@ func (s *Service) sampleLocked(zs *zoneState, now time.Time) { // driver reporting heat power. Two candidates is no answer: the twin cannot // tell which one heats this zone. func (s *Service) powerSourceLocked(z Zone, now time.Time) string { + if z.HeatInput != "" { + // The owner named it: that one or none, never a guess. + driver, metric := powerRef(z.HeatInput) + if _, _, ok := s.read(driver, metric, now); ok { + return z.HeatInput + } + return "" + } if _, _, ok := s.read(z.SensorDriver, HeatPowerMetric, now); ok { return z.SensorDriver } @@ -254,6 +268,15 @@ func (s *Service) powerSourceLocked(z Zone, now time.Time) string { return "" } +// powerRef splits a heat input source: "/" as the owner +// named it, or a bare driver name for its HeatPowerMetric. +func powerRef(src string) (driver, metric string) { + if i := strings.Index(src, "/"); i >= 0 { + return src[:i], src[i+1:] + } + return src, HeatPowerMetric +} + func (s *Service) read(driver, metric string, now time.Time) (float64, time.Time, bool) { if s.Tele == nil || driver == "" { return 0, time.Time{}, false diff --git a/go/internal/thermaltwin/service_test.go b/go/internal/thermaltwin/service_test.go index 1fdb4f234..86c76c6d6 100644 --- a/go/internal/thermaltwin/service_test.go +++ b/go/internal/thermaltwin/service_test.go @@ -221,3 +221,34 @@ func TestServiceNeedsOutdoorTemperature(t *testing.T) { t.Errorf("samples = %d without outdoor temperature, want 0", got.Samples) } } + +// A room sensor on an underfloor gateway is heated by a heat pump on another +// device. The owner names the pump's space heat as its heat input, and that +// wins over every power the twin could otherwise find, even with several. +func TestServiceUsesTheHeatInputTheOwnerNamed(t *testing.T) { + tele := fakeTele{} + room := Zone{Key: "lk/zone_1_temp_c", SensorDriver: "lk", SensorMetric: "zone_1_temp_c", HeatInput: "ctc/space_heat_w"} + s := newTestService(tele, fakeStore{}, room) + run(s, t0, 31, func(now time.Time) { + tele["lk/zone_1_temp_c"] = metric{21, now} + tele["ctc/space_heat_w"] = metric{4000, now} + tele["heishamon/hp_power_w"] = metric{1500, now} + tele["nibe/hp_power_w"] = metric{900, now} + }) + if z := zoneStatus(t, s, room.Key); z.PowerSource != "ctc/space_heat_w" { + t.Errorf("power source = %q, want ctc/space_heat_w", z.PowerSource) + } + + // Without a reading from the named source there is no heat input: the + // twin does not fall back to a pump the owner did not name. + quiet := Zone{Key: "lk/zone_2_temp_c", SensorDriver: "lk", SensorMetric: "zone_2_temp_c", HeatInput: "ctc/space_heat_w"} + tele2 := fakeTele{} + s2 := newTestService(tele2, fakeStore{}, quiet) + run(s2, t0, 31, func(now time.Time) { + tele2["lk/zone_2_temp_c"] = metric{21, now} + tele2["heishamon/hp_power_w"] = metric{1500, now} + }) + if z := zoneStatus(t, s2, quiet.Key); z.PowerSource != "" { + t.Errorf("power source = %q, want none when the named input is silent", z.PowerSource) + } +} diff --git a/go/test/site/runner/runner.go b/go/test/site/runner/runner.go index 821a8f3fc..3650fdb06 100644 --- a/go/test/site/runner/runner.go +++ b/go/test/site/runner/runner.go @@ -28,7 +28,8 @@ var watchedPaths = []string{ "go/internal/units/", // charge steps "go/internal/localzone/", // household clock: goal deadlines, import hour "go/internal/cars/", "go/internal/sitepower/", - "go/internal/thermal/", // control heat effects, imported by drivers + "go/internal/thermal/", // control heat effects, imported by drivers + "go/internal/heatplan/", // the owner's heat rules, imported by config "go/internal/events/", "go/internal/state/", "drivers/", "optimizer/native/bundle/", // bundled drivers and solver "go/test/site/",