diff --git a/.changeset/planner-hourly-import-limit.md b/.changeset/planner-hourly-import-limit.md new file mode 100644 index 000000000..c5575f9aa --- /dev/null +++ b/.changeset/planner-hourly-import-limit.md @@ -0,0 +1,5 @@ +--- +"ftw": patch +--- + +The plan now keeps each clock hour under the hourly import limit. The planner used to see only the fuse. With a 4.5 kW limit it could plan the car at 4.8 kW for four hours, import 5.5 kWh in an hour and show a charging goal as met that FTW could not deliver. Each plan now gets every clock hour in the box's local time and what the hour in progress has used, and FTW rejects a plan that imports more in an hour than it may. A planned hour keeps a little under the limit, because the car charges in whole amps and FTW raises it only with a step to spare; the plan then promises about what the car gets. When the limit puts a goal out of reach, the plan says how much is missing. The home battery covers the house so the car gets more of the hour. The bundled Energyplan worker does not take the hours yet: when its plan breaks them, FTW uses its own plan. Where FTW cannot plan the site itself, it keeps the worker's plan, says the plan may break the limit, and still holds each hour to it live. A new limit replans at once. diff --git a/docs/energyplan-contract.md b/docs/energyplan-contract.md index d15d238e7..3a2e158dc 100644 --- a/docs/energyplan-contract.md +++ b/docs/energyplan-contract.md @@ -36,10 +36,11 @@ whose I/O exceeds the call deadline; a later call may start a fresh process. The handshake identifies the worker, its version, protocol range and features. Protocol compatibility and supported features govern use, not matching Core and Energyplan release numbers. Current features are `champion`, -`forecast_reset`, `partial_slots`, `demand_charges`, `ev_duty` and -`charging_periods` and `published_prices`; the worker also reports -`forecast_protocol_version`. -Core negotiates `charging_periods` before sending its optional fields. +`forecast_reset`, `partial_slots`, `demand_charges`, `ev_duty`, +`charging_periods`, `published_prices` and `hourly_import_caps`; the worker +also reports `forecast_protocol_version`. +Core negotiates `charging_periods` before sending its optional fields, and +`hourly_import_caps` before sending `hourly_import_caps`. New optional request fields need capability negotiation or a paired update that preserves deployed clients. Unknown optimizer request fields are errors. @@ -92,6 +93,31 @@ charge/discharge direction in each slot. Demand-charge windows use explicit UTC intervals and elapsed import from Core; Core owns local calendar and daylight-saving conversion. +`hourly_import_caps` carries the owner's hourly import limit as a hard +limit. Each entry is `{start_ms, end_ms, max_mean_w, elapsed_import_wh}`: +one local clock hour as UTC milliseconds, the mean import the hour may hold +in W, and the import in Wh the hour has already used before the plan starts +(0 for later hours). Core sends one entry per clock hour that overlaps the +plan, from the first slot's execution start to the horizon end; a +daylight-saving day has 23 or 25. The hour in progress may start before the +first slot and the last may end after the horizon; an entry outside the plan +is ignored. Entries must not overlap, last 1 minute to 25 hours, and number +at most 512. Import is `max(0, grid)` per pulse state: a duty slot imports +`duty * max(0, grid on)` plus `(1 - duty) * max(0, grid off)`, at the cut +points between the cars' duties. In every scenario, the plan's import inside +an hour from execution start must not exceed +`max_mean_w * hours - elapsed_import_wh`. In an hour where every car is off +it may instead reach what the house alone imports there, +`max(0, load_w + pv_w)` per slot with the battery idle, if that is more: Core +cannot cut the house, but its live limit stops a car before the house. +`max_mean_w` may be 0: the hour then has room for the house alone. The worker +is stricter in one case: while a car pulses into solar surplus and the +battery charges, it counts the car's on-step import plus the whole charge. +The cap wins over EV goals, whose miss shows in +`flex_shortfall_wh`. The plan reports each hour in +`plan.hourly_import_caps` as `{start_ms, end_ms, import_wh, max_wh}` on the +published forecast, `import_wh` including the elapsed part. + Thermal, commercial and recourse inputs are unsupported. Protocol v1 has no per-phase electrical model, future connection windows or phase-switch schedule. Total watts cannot certify phase safety. Those extensions need an explicit @@ -169,11 +195,12 @@ objective. Unknown bounds and gaps remain null. When executed pulse cost and the optimized cost model differ, report `feasible` and omit the cost bound. Core validates physical execution; it does not independently prove optimality. -Current Core allows 500 ms for small plans and 5 s for larger plans or demand -charges, with a 7 s transport timeout. It reduces the budget near the first -slot's end and leaves 50 ms for validation/publication. These are compute and -call budgets, not a proven wall-time SLA. Measure queueing, startup, decoding, -solving, replay, encoding and Core validation separately when changing them. +Current Core allows 500 ms for small plans and 5 s for larger plans, demand +charges or hourly import caps, with a 7 s transport timeout. It reduces the +budget near the first slot's end and leaves 50 ms for validation/publication. +These are compute and call budgets, not a proven wall-time SLA. Measure +queueing, startup, decoding, solving, replay, encoding and Core validation +separately when changing them. A warm worker may keep one previous plan as a candidate. Before reuse it must match asset identities, advance time, rebuild energy from current measurements, diff --git a/go/cmd/ftw/main.go b/go/cmd/ftw/main.go index aafcb3aff..fe3ad6fc9 100644 --- a/go/cmd/ftw/main.go +++ b/go/cmd/ftw/main.go @@ -1670,6 +1670,13 @@ func main() { defer ctrlMu.Unlock() return control.PhaseImbalanceW(tel, ctrl, timeout, time.Now()) } + // The planner keeps each clock hour under the owner's import + // ceiling, from the budget Core's live limit counts. + mpcSvc.ImportCeiling = func() mpc.ImportCeiling { + ctrlMu.Lock() + defer ctrlMu.Unlock() + return control.PlanningImportCeiling(ctrl) + } // Cap planned export below the fuse when the operator set a site // export ceiling, so the DP never schedules a discharge that would // over-export and trip an inverter (the Ferroamp 0x8030 fault). diff --git a/go/internal/api/api.go b/go/internal/api/api.go index ecc4b96a1..3bd7d652a 100644 --- a/go/internal/api/api.go +++ b/go/internal/api/api.go @@ -1934,6 +1934,11 @@ func (s *Server) handleSetPeakImportCeiling(w http.ResponseWriter, r *http.Reque s.deps.CtrlMu.Lock() s.deps.Ctrl.PeakImportCeilingW = req.PeakImportCeilingW s.deps.CtrlMu.Unlock() + // The plan spreads each hour's import under the ceiling; a new ceiling + // changes what the plan may deliver. + if s.deps.MPC != nil && req.PeakImportCeilingW != prevW { + s.deps.MPC.RequestReplan("import_ceiling_changed") + } writeJSON(w, 200, map[string]any{"status": "ok", "peak_import_ceiling_w": req.PeakImportCeilingW}) } diff --git a/go/internal/api/api_peak_import_ceiling_test.go b/go/internal/api/api_peak_import_ceiling_test.go index a956628d3..540f4c580 100644 --- a/go/internal/api/api_peak_import_ceiling_test.go +++ b/go/internal/api/api_peak_import_ceiling_test.go @@ -131,3 +131,22 @@ func TestPeakImportCeilingNotAppliedWhenTheSaveFails(t *testing.T) { t.Fatalf("ceiling = %.0f W after a failed save, want 6,000", ctrl.PeakImportCeilingW) } } + +// A new ceiling changes what the plan may deliver, so the plan follows it at +// once instead of at the next quarter. +func TestPeakImportCeilingChangeReplans(t *testing.T) { + _, _, svc := newScheduleServer(t) + st, err := state.Open(filepath.Join(t.TempDir(), "state.db")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = st.Close() }) + srv := newCeilingServer(t, st, &control.State{}) + srv.deps.MPC = svc + + postCeiling(t, srv, "4500") + waitForSchedulePlan(t, svc) + if _, reason := svc.LastReplanInfo(); reason != "import_ceiling_changed" { + t.Fatalf("replan reason = %q, want import_ceiling_changed", reason) + } +} diff --git a/go/internal/control/import_hour.go b/go/internal/control/import_hour.go index bb69f7823..77b0b83af 100644 --- a/go/internal/control/import_hour.go +++ b/go/internal/control/import_hour.go @@ -5,6 +5,7 @@ import ( "math" "time" + "github.com/srcfl/ftw/go/internal/mpc" "github.com/srcfl/ftw/go/internal/telemetry" ) @@ -218,6 +219,32 @@ func (s *State) importRiseCeilingW(fuseMaxW float64) float64 { return eff } +// PlanningImportCeiling is the ceiling as the planner gets it, from the hour +// the live limit counts: the clock hour in progress and what it has used. +// Time with no record counts at the ceiling. Until a reading measures the +// hour against this ceiling, the rest of the hour may hold the ceiling, so +// the time before counts as used. A planned hour holds the ceiling less half +// a rise step: the car runs in whole steps and a rise keeps a step in hand, +// so a car under the ceiling ends each hour 0.4-0.6 kWh short of it. Planned +// at the ceiling the plan promised the car 8-15 % more than it got; at half +// a step less the car gets as much, within 1 % of the promise with the +// battery covering the house and 6 % without +// (TestSiteSimPlanUnderImportCeiling). Zero while the ceiling is off. +// Callers hold the control lock. +func PlanningImportCeiling(s *State) mpc.ImportCeiling { + if s == nil || !(s.PeakImportCeilingW > 0) { + return mpc.ImportCeiling{} + } + now, ceiling := s.now(), s.PeakImportCeilingW + start := s.importHourStart(now) + elapsedWh := ceiling * now.Sub(start).Hours() + if h := &s.importHour; s.importHourMeasured() { + elapsedWh = h.importedWh + ceiling*h.unknown.Hours() + } + step := evPhaseMarginA * s.SiteFuseVoltage * float64(s.SiteFusePhases) + return mpc.ImportCeiling{W: ceiling, MeanW: max(0, ceiling-step/2), HourStart: start, ElapsedWh: elapsedWh} +} + // ImportHourStatus is the clock hour's import budget left, negative once it // is overrun, and the import limit in force. ok is false while the ceiling is // off. Callers hold the control lock or a copy of State. diff --git a/go/internal/control/import_hour_planning_test.go b/go/internal/control/import_hour_planning_test.go new file mode 100644 index 000000000..ffbd77e69 --- /dev/null +++ b/go/internal/control/import_hour_planning_test.go @@ -0,0 +1,80 @@ +package control + +import ( + "math" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/mpc" +) + +// The planner gets the clock hour Core's live limit counts and what it has +// used. On 25 October 2026 02:00 comes twice in Stockholm, and each of the +// two hours counts its own import. +func TestPlanningImportCeilingOnTheLongDay(t *testing.T) { + zone, err := time.LoadLocation("Europe/Stockholm") + if err != nil { + t.Fatal(err) + } + var now time.Time + st, store := newImportHourState(&now) + st.PeakImportCeilingW, st.importHourZone = 4500, zone + first := time.Date(2026, 10, 25, 0, 0, 0, 0, time.UTC) // 02:00 CEST + for _, hour := range []time.Time{first, first.Add(time.Hour)} { + for at := hour; !at.After(hour.Add(20 * time.Minute)); at = at.Add(2 * time.Second) { + feedMeter(st, store, &now, at, 3000) + } + got := PlanningImportCeiling(st) + if !got.HourStart.Equal(hour) || got.HourStart.In(zone).Hour() != 2 || got.W != 4500 { + t.Fatalf("at %s: hour from %s, ceiling %.0f W", now.In(zone).Format("15:04 MST"), got.HourStart.In(zone).Format("15:04 MST"), got.W) + } + if want := 3000 * 20 / 60.; math.Abs(got.ElapsedWh-want) > 1 { + t.Fatalf("at %s: %.1f Wh used, want %.1f Wh", now.In(zone).Format("15:04 MST"), got.ElapsedWh, want) + } + } + st.PeakImportCeilingW = 0 + if got := PlanningImportCeiling(st); got != (mpc.ImportCeiling{}) { + t.Fatalf("ceiling off gave %+v", got) + } +} + +// A planned hour holds the ceiling less half a rise step, the margin +// TestSiteSimPlanUnderImportCeiling measures. +func TestPlanningImportCeilingKeepsHalfARiseStep(t *testing.T) { + now := time.Date(2026, 10, 26, 9, 0, 0, 0, hourTestZone) + st, _ := newImportHourState(&now) + st.PeakImportCeilingW = 4500 + // Half of 1 A on each of three 230 V phases. + if got := PlanningImportCeiling(st); got.MeanW != 4155 { + t.Fatalf("planned mean %.0f W, want 4155 W", got.MeanW) + } + st.PeakImportCeilingW = 300 + if got := PlanningImportCeiling(st); got.W != 300 || got.MeanW != 0 { + t.Fatalf("a ceiling under half a step: %+v, want it on with no room", got) + } +} + +// Before a reading measures the hour, as after a restart or a new ceiling, +// the live limit lets the rest of the hour hold the ceiling: the time before +// counts as used. A restart that seeds the hour from state.db counts what +// the record covers, and the time it misses at the ceiling. +func TestPlanningImportCeilingAfterARestart(t *testing.T) { + now := time.Date(2026, 10, 26, 9, 40, 0, 0, hourTestZone) + st, store := newImportHourState(&now) + st.PeakImportCeilingW = 4500 + if got := PlanningImportCeiling(st); math.Abs(got.ElapsedWh-3000) > 1e-6 || got.HourStart.Minute() != 0 { + t.Fatalf("at boot: %.1f Wh used in the hour from %s; want 3000 Wh from 09:00", got.ElapsedWh, got.HourStart.Format("15:04")) + } + // state.db covered 30 of the 40 minutes with 1.2 kWh. + st.SeedHourImport(now, 1200, 30*time.Minute) + feedMeter(st, store, &now, now.Add(time.Second), 2000) + if got := PlanningImportCeiling(st); math.Abs(got.ElapsedWh-(1200+4500/6.+2000/3600.)) > 1 { + t.Fatalf("seeded: %.1f Wh used, want 1200 Wh plus 10 unseen minutes at the ceiling", got.ElapsedWh) + } + now = now.Add(10 * time.Minute) + feedMeter(st, store, &now, now, 2000) + st.PeakImportCeilingW = 3000 // set during the hour, not yet seen by a reading + if got := PlanningImportCeiling(st); math.Abs(got.ElapsedWh-2500) > 1 { + t.Fatalf("new ceiling: %.1f Wh used, want 50 minutes at 3 kW", got.ElapsedWh) + } +} diff --git a/go/internal/control/sitesim_import_plan_test.go b/go/internal/control/sitesim_import_plan_test.go new file mode 100644 index 000000000..56620890e --- /dev/null +++ b/go/internal/control/sitesim_import_plan_test.go @@ -0,0 +1,182 @@ +package control + +import ( + "context" + "fmt" + "math" + "path/filepath" + "strings" + "testing" + "testing/synctest" + "time" + + "github.com/srcfl/ftw/go/internal/loadpoint" + "github.com/srcfl/ftw/go/internal/mpc" + "github.com/srcfl/ftw/go/internal/sitesim" + "github.com/srcfl/ftw/go/internal/state" +) + +// importPlanCase is the 25 October 2026 field case run closed-loop: an +// hourly import ceiling, 0.8 kW of house, a 9.6 kWh battery and a car that +// wants 19 kWh more by the deadline on a 3 × 20 A fuse. Core's planner +// replans every quarter from Core's own import hour and Core runs the plan. +type importPlanCase struct { + start, deadline time.Time + ceilingW, soc float64 + restartAt time.Duration // > 0: Core restarts then, with no record of the hour +} + +type importPlanHour struct { + start time.Time + plannedWh, metered float64 +} + +// runImportPlan returns each clock hour's import as the plan made at its +// start meant it and as the meter measured it, and the car's energy by the +// deadline as the first plan promised it and as delivered. It runs inside a +// synctest bubble. +func runImportPlan(t *testing.T, c importPlanCase) (hours []importPlanHour, promisedWh, deliveredWh float64) { + t.Helper() + zone := c.start.Location() + time.Sleep(c.start.Sub(time.Now())) // The bubble's clock becomes the plant's. + st, err := state.Open(filepath.Join(t.TempDir(), "state.db")) + if err != nil { + t.Fatal(err) + } + defer st.Close() + prices := make([]state.PricePoint, 32) + for i := range prices { + prices[i] = state.PricePoint{Zone: "SE3", SlotTsMs: c.start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), SlotLenMin: 15, + SpotOreKwh: 40 + float64(i%4), TotalOreKwh: 90 + float64(i%4), Source: "test", FetchedAtMs: c.start.UnixMilli()} + } + if err := st.SavePrices(prices); err != nil { + t.Fatal(err) + } + svc := mpc.New(st, nil, "SE3", mpc.Params{Mode: mpc.ModeArbitrage, SoCLevels: 21, ActionLevels: 21, + CapacityWh: 9600, InitialSoC: c.soc, SoCMin: .1, SoCMax: .95, MaxChargeW: 5000, MaxDischargeW: 5000, + ChargeEfficiency: .95, DischargeEfficiency: .95}) + svc.Horizon, svc.BaseLoad = 8*time.Hour, 800 + svc.UpdateBatteryFleet([]mpc.BatteryFleetMember{{Driver: "battery", CapacityWh: 9600, MaxChargeW: 5000, MaxDischargeW: 5000}}, 9600, 5000, 5000) + svc.UpdateSiteEconomics(mpc.SiteEconomics{FuseMaxW: 13800, Timezone: zone.String()}) + + p := sitesim.New(c.start, 20) + p.EVSE = &sitesim.EVSE{Phases: 3, MinA: 6, MaxA: 16, Delay: 5 * time.Second, ReadbackLag: 10 * time.Second} + p.Car = &sitesim.Car{Phases: 3, MaxW: 11040, Plugged: true} + p.Battery = &sitesim.Battery{Phases: 3, MaxChargeW: 5000, MaxDischargeW: 5000, CapacityWh: 9600, SoC: c.soc, Latency: 2 * time.Second} + p.HouseW = [3]float64{800. / 3, 800. / 3, 800. / 3} + if c.restartAt > 0 { + p.Events = []sitesim.Event{{At: c.restartAt, Kind: sitesim.CoreRestart, For: 20 * time.Second}} + } + + const carWh, needWh = 75000., 19000. + s := &simSite{p: p, lp: simLoadpoint()} + s.plan = func(now time.Time) (loadpoint.Directive, bool) { + d, ok := svc.SlotDirectiveAt(now) + if !ok { + return loadpoint.Directive{}, false + } + return d.LoadpointDirective(), true + } + s.setup = func(s *simSite) { + s.state.PeakImportCeilingW, s.state.importHourZone = c.ceilingW, zone + s.state.Mode, s.state.UseEnergyDispatch = ModePlannerArbitrage, true + s.state.SlotDirective = func(now time.Time) (SlotDirective, bool) { + d, ok := svc.SlotDirectiveAt(now) + if !ok { + return SlotDirective{}, false + } + return SlotDirectiveFromMPC(d), true + } + s.mgr.SetSchedule(s.lp.ID, loadpoint.Schedule{SoC: .8}) + } + s.boot() + // The planner reads the hour the live limit counts, as main.go wires it. + svc.ImportCeiling = func() mpc.ImportCeiling { return PlanningImportCeiling(s.state) } + svc.Loadpoint = func(int) *mpc.LoadpointSpec { + first := s.p.Now.Truncate(15 * time.Minute) + return &mpc.LoadpointSpec{ID: s.lp.ID, CapacityWh: carWh, InitialSoC: (.8*carWh - needWh + .9*s.p.EVSE.SessionWh) / carWh, SoCMax: 1, + Levels: 21, PluggedIn: true, TargetSoC: .8, TargetSlotIdx: int(c.deadline.Sub(first)/(15*time.Minute)) - 1, + MinChargeW: s.lp.MinChargeW, MaxChargeW: s.lp.MaxChargeW, AllowedStepsW: s.lp.AllowedStepsW, ChargeEfficiency: .9} + } + plannedWh := func(plan *mpc.Plan, from time.Time) float64 { + var wh float64 + for _, a := range plan.Actions { + begin, end := max(a.ExecutionStart(), from.UnixMilli()), min(a.SlotStartMs+int64(a.SlotLenMin)*60_000, from.Add(time.Hour).UnixMilli()) + if end > begin { + wh += math.Max(0, a.GridW) * float64(end-begin) / 3.6e6 + } + } + return wh + } + + nextReplan := c.start.Add(10 * time.Second) // Telemetry first. + for s.p.Now.Before(c.deadline) { + time.Sleep(sitesim.Step) + s.step() + now := s.p.Now + if s.downUntil.IsZero() && !now.Before(nextReplan) { + svc.Tele = s.store + plan := svc.ReplanWithReason(context.Background(), "slot_elapsed") + if plan == nil { + t.Fatalf("%s: no plan: %+v", now.Format("15:04:05"), svc.PlanSnapshot()) + } + if promisedWh == 0 { + promisedWh = needWh - plan.LoadpointShortfallWh[s.lp.ID] + } + if h := importHourStart(now, zone); len(hours) == 0 || !h.Equal(hours[len(hours)-1].start) { + hours = append(hours, importPlanHour{start: h, plannedWh: plannedWh(plan, h)}) + } + nextReplan = now.Truncate(15 * time.Minute).Add(15*time.Minute + time.Second) + } + if len(hours) > 0 { + hours[len(hours)-1].metered += math.Max(0, (p.A[0]+p.A[1]+p.A[2])*p.Voltage) * sitesim.Step.Hours() + } + // The site check's own idea of when a car should charge does not + // know the plan; every other invariant holds. + if s.failure != "" && !strings.Contains(s.failure, "idle") { + t.Fatal(s.failure) + } + } + return hours, promisedWh, .9 * s.p.EVSE.SessionWh +} + +// Plan and execution agree: no clock hour imports more than the ceiling, and +// the car gets about what the first plan promised. With the battery covering +// the house the car runs from the hour's start and the promise holds within +// 3 %. Without it the car needs the hour's slack to start and Core restarts +// it each time a quarter's energy is spent: 8 %. +func TestSiteSimPlanUnderImportCeiling(t *testing.T) { + zone, err := time.LoadLocation("Europe/Stockholm") + if err != nil { + t.Fatal(err) + } + nine := time.Date(2026, 10, 25, 9, 0, 0, 0, zone) + night := time.Date(2026, 10, 24, 23, 30, 0, 0, time.UTC).In(zone) // 01:30 CEST, before 02:00 comes twice + for _, c := range []struct { + name string + c importPlanCase + promise float64 + }{ + {"battery covers the house", importPlanCase{start: nine, deadline: nine.Add(4 * time.Hour), ceilingW: 4500, soc: .5}, .03}, + {"battery empty", importPlanCase{start: nine, deadline: nine.Add(4 * time.Hour), ceilingW: 4500, soc: .1}, .08}, + {"the 25-hour day", importPlanCase{start: night, deadline: night.Add(4 * time.Hour), ceilingW: 4500, soc: .5}, .03}, + {"restart in the hour", importPlanCase{start: nine, deadline: nine.Add(2 * time.Hour), ceilingW: 4500, soc: .5, restartAt: 40 * time.Minute}, .05}, + } { + t.Run(c.name, func(t *testing.T) { + synctest.Test(t, func(t *testing.T) { + hours, promised, delivered := runImportPlan(t, c.c) + var line string + for _, h := range hours { + line += fmt.Sprintf(" %s plan %.0f metered %.0f;", h.start.Format("15:04 MST"), h.plannedWh, h.metered) + if h.metered > c.c.ceilingW { + t.Errorf("%s: imported %.0f Wh, over the %.0f W ceiling", h.start.Format("15:04 MST"), h.metered, c.c.ceilingW) + } + } + t.Logf("car promised %.0f Wh, delivered %.0f Wh;%s", promised, delivered, line) + if math.Abs(delivered-promised) > c.promise*promised { + t.Errorf("delivered %.0f Wh against %.0f Wh promised, more than %.0f %% apart", delivered, promised, c.promise*100) + } + }) + }) + } +} diff --git a/go/internal/mpc/charging_periods.go b/go/internal/mpc/charging_periods.go index 92a840d75..93e8c7816 100644 --- a/go/internal/mpc/charging_periods.go +++ b/go/internal/mpc/charging_periods.go @@ -1,6 +1,9 @@ package mpc -import "context" +import ( + "context" + "math" +) // ChargingPeriods describes a preference, after deadline energy and physical // reserves. It never delays Core safety, manual stop, or charge completion. @@ -41,7 +44,7 @@ func (l *LoadpointSpec) departureMissWh() float64 { return 1 } -func (o *EnergyplanOptimizer) prepareEnergyplanRequest(ctx context.Context, request *externalRequest, p Params) error { +func (o *EnergyplanOptimizer) prepareEnergyplanRequest(ctx context.Context, request *externalRequest, slots []Slot, p Params) error { // Negotiate against the running worker on every request. Restart or a // binary rollback must not inherit a feature learned from another process. probeCtx, cancel := context.WithTimeout(ctx, o.cfg.Timeout) @@ -55,6 +58,20 @@ func (o *EnergyplanOptimizer) prepareEnergyplanRequest(ctx context.Context, requ request.Slots[i].Confidence = 0 } } + // A worker without the hours plans past them; Core's check rejects + // such a plan and uses its own. The worker plans the hours in its fleet + // model, with the demand charges' budget. + if optimizerHasFeature(info, "hourly_import_caps") && len(slots) > 0 { + for _, h := range p.ImportHours { + if importHourPlannedH(slots, h) > 0 { + request.HourlyImportCaps = append(request.HourlyImportCaps, externalImportCap{ + StartMs: h.StartMs, EndMs: h.EndMs, MaxMeanW: p.ImportMeanW, ElapsedImportWh: h.ElapsedImportWh}) + } + } + if len(request.HourlyImportCaps) > 0 { + request.Settings.TimeLimitS = math.Min(o.cfg.Timeout.Seconds()*0.8, energyplanBudget(slots, p, true).Seconds()) + } + } loads := p.activeLoadpoints() needed := false for _, lp := range loads { diff --git a/go/internal/mpc/charging_periods_test.go b/go/internal/mpc/charging_periods_test.go index 75f73cccd..a8614e193 100644 --- a/go/internal/mpc/charging_periods_test.go +++ b/go/internal/mpc/charging_periods_test.go @@ -34,7 +34,7 @@ func TestChargingPeriodsNegotiatesEachWorkerAndKeepsLegacyWire(t *testing.T) { if r.FlexLoads[0].Charging != nil { t.Fatal("generic sidecar received an unnegotiated field") } - if err := o.prepareEnergyplanRequest(context.Background(), &r, p); err != nil { + if err := o.prepareEnergyplanRequest(context.Background(), &r, slots, p); err != nil { t.Fatal(err) } c := r.FlexLoads[0].Charging diff --git a/go/internal/mpc/energyplan.go b/go/internal/mpc/energyplan.go index cefb6bf24..869c80f07 100644 --- a/go/internal/mpc/energyplan.go +++ b/go/internal/mpc/energyplan.go @@ -35,9 +35,18 @@ const ( energyplanFleetBudget = 5 * time.Second // Leave time for ValidatePlan and publication before firstSlotExpired. energyplanPublishMargin = 50 * time.Millisecond + // A worker that spends its whole budget must still answer before the + // call's deadline: 5 % of the time to it, at least this. + energyplanReplyMargin = 30 * time.Millisecond ) func energyplanTimeBudget(slots []Slot, p Params) time.Duration { + return energyplanBudget(slots, p, false) +} + +// energyplanBudget is the solve budget; hours says the request carries +// hourly import caps. +func energyplanBudget(slots []Slot, p Params, hours bool) time.Duration { batteries := len(p.Storages) if batteries == 0 && p.CapacityWh > 0 { batteries = 1 @@ -50,16 +59,17 @@ func energyplanTimeBudget(slots []Slot, p Params) time.Duration { budget = energyplanEVBudget } // 1 battery + 1 EV is 5 "assets". A 193-slot villa with demand charges - // routes to fleet MILP; 193*6 would leave it on the 500 ms budget. - if len(slots)*assets >= 193*5 || p.PVCurtailment.MinW > 0 || len(p.DemandCharges) > 0 { + // routes to fleet MILP; 193*6 would leave it on the 500 ms budget. The + // hourly import caps route there too. + if len(slots)*assets >= 193*5 || p.PVCurtailment.MinW > 0 || len(p.DemandCharges) > 0 || hours { budget = energyplanFleetBudget } remaining := remainingFirstSlot(slots) if remaining < energyplanSmallBudget { return 0 } - available := remaining - energyplanPublishMargin - if available < budget { + deadline := remaining - energyplanPublishMargin + if available := deadline - max(deadline/20, energyplanReplyMargin); available < budget { return available } return budget diff --git a/go/internal/mpc/energyplan_import_caps_test.go b/go/internal/mpc/energyplan_import_caps_test.go new file mode 100644 index 000000000..816f68749 --- /dev/null +++ b/go/internal/mpc/energyplan_import_caps_test.go @@ -0,0 +1,37 @@ +package mpc + +import ( + "context" + "os" + "testing" + "time" +) + +// A worker that takes hourly_import_caps plans the 25 October field case +// itself: Core sends the hours, and the worker's plan keeps every hour and +// shows the goal short. The bundled worker skips until its pin takes them. +func TestNativeEnergyplanTakesHourlyImportCaps(t *testing.T) { + binary := os.Getenv("FTW_NATIVE_SOLVER") + if binary == "" { + t.Skip("run make native-solver-test to include the Rust worker") + } + o, err := NewEnergyplanOptimizer(binary) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = o.Close() }) + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + info, err := o.Health(ctx) + if err != nil { + t.Fatal(err) + } + if !optimizerHasFeature(info, "hourly_import_caps") { + t.Skip("this worker does not take hourly_import_caps") + } + svc, start := importCeilingFieldService(t, o, true) + plan := checkImportCeilingFieldPlan(t, svc, start) + if plan.Solver == nil || plan.Solver.Fallback { + t.Fatalf("solver %+v; want the worker's own plan", plan.Solver) + } +} diff --git a/go/internal/mpc/energyplan_test.go b/go/internal/mpc/energyplan_test.go index b0df3e747..e5c6556ec 100644 --- a/go/internal/mpc/energyplan_test.go +++ b/go/internal/mpc/energyplan_test.go @@ -373,11 +373,16 @@ func TestEnergyplanTimeBudgetRespectsRemainingSlot(t *testing.T) { if got := energyplanTimeBudget(slots, p); got != 0 { t.Fatalf("200ms remaining fleet budget=%v, want fail-fast", got) } - trimFirstSlotRemaining(slots, 2*time.Second) - got := energyplanTimeBudget(slots, p) - remaining := remainingFirstSlot(slots) - if got <= 0 || got > remaining || remaining-got != energyplanPublishMargin { - t.Fatalf("2s remaining fleet budget=%v remaining=%v", got, remaining) + // Core's call ends energyplanPublishMargin before the slot does. A + // worker that spends its whole budget must still answer before that: + // 5 % of the time left, at least 30 ms. + for _, left := range []time.Duration{2 * time.Second, 500 * time.Millisecond, energyplanFleetBudget + 60*time.Millisecond} { + trimFirstSlotRemaining(slots, left) + got, remaining := energyplanTimeBudget(slots, p), remainingFirstSlot(slots) + deadline := remaining - energyplanPublishMargin + if want := deadline - max(deadline/20, 30*time.Millisecond); got <= 0 || got != want { + t.Fatalf("%v remaining: fleet budget=%v, want %v under the %v call deadline", left, got, want, deadline) + } } small, smallParams := topologyFixture(1, 0) trimFirstSlotRemaining(small, 2*time.Second) diff --git a/go/internal/mpc/ev_reserve.go b/go/internal/mpc/ev_reserve.go index d6cf98bc3..e9c66cd0e 100644 --- a/go/internal/mpc/ev_reserve.go +++ b/go/internal/mpc/ev_reserve.go @@ -50,6 +50,7 @@ func coreReservePlan(ctx context.Context, slots []Slot, p Params) (Plan, error) target = min(lp.TargetSoC, ceiling) * lp.CapacityWh steps = lp.normalizedSteps() } + _, importCaps := importHourCapsW(slots, p) for i, slot := range slots { if err := ctx.Err(); err != nil { return Plan{}, err @@ -62,7 +63,12 @@ func coreReservePlan(ctx context.Context, slots []Slot, p Params) (Plan, error) minBatteryW = max(minBatteryW, reservePowerForEnergy(bands[i+1].min-energy, hours, chargeEff, dischargeEff)) maxBatteryW = min(maxBatteryW, reservePowerForEnergy(bands[i+1].max-energy, hours, chargeEff, dischargeEff)) house := slot.LoadW + slot.PVW - chooseBattery := func(peak float64) (float64, bool) { + capW := math.Inf(1) + if importCaps != nil { + capW = importCaps[i] + } + // most bounds the battery from above, so it may cover the house. + chooseBattery := func(peak, most float64) (float64, bool) { low, high := reserveBatteryPowerRange(slot, p, peak) low, high = max(low, minBatteryW), min(high, maxBatteryW) if peak > 0 && lp != nil && lp.blocksBatteryToEV() { @@ -72,13 +78,16 @@ func coreReservePlan(ctx context.Context, slots []Slot, p Params) (Plan, error) return 0, false } b := min(max(0, low), high) + if b > most { + b = max(low, most) + } if !modeAllows(p.Mode, house, house+b, b) || !modeAllows(p.Mode, house+peak, house+peak+b, b) { return 0, false } return b, true } - peak, battery := 0.0, 0.0 - battery, ok := chooseBattery(0) + peak, battery, average := 0.0, 0.0, 0.0 + battery, ok := chooseBattery(0, math.Inf(1)) if !ok { return Plan{}, fmt.Errorf("slot %d: battery cannot keep the forecast within the site power limits", i) } @@ -89,13 +98,28 @@ func coreReservePlan(ctx context.Context, slots []Slot, p Params) (Plan, error) if lp.SurplusOnly && surplusOnlyExceedsHousePV(step, slot.LoadW, slot.PVW) { continue } - if b, ok := chooseBattery(step); ok { - peak, battery = step, b - break + b, ok := chooseBattery(step, math.Inf(1)) + if !ok { + continue + } + want := min(step, need/(eff*hours)) + if evAverageRoomW(capW, house+b, step) < want { + // The hour's import holds the car back: the battery + // covers the house to make room, never into export. + if covered, ok := chooseBattery(step, max(-max(0, house), capW-house-want)); ok { + b = covered + } } + avg := min(want, evAverageRoomW(capW, house+b, step)) + if !math.IsInf(capW, 1) && (avg <= 1e-6 || b < -solverZeroPowerToleranceW && house+b+avg < -50) { + // The hour leaves this step no room, or only part of the + // slot while the battery the step needs drives export. + continue + } + peak, battery, average = step, b, avg + break } } - average := min(peak, need/(eff*hours)) evEnergy += average * eff * hours energy += loadpoint.BatteryEnergyDeltaWh(battery, hours, chargeEff, dischargeEff) a := Action{ExecutionStartMs: slot.ExecutionStartMs, SlotStartMs: slot.StartMs, SlotLenMin: slot.LenMin, PriceOre: slot.PriceOre, SpotOre: slot.SpotOre, PVW: slot.PVW, LoadW: slot.LoadW, BatteryW: battery, GridW: house + battery + average, SoC: energy / p.CapacityWh, Reason: "Site power reserve"} @@ -200,6 +224,20 @@ func reserveSlotCost(slot Slot, p Params, a Action) float64 { if len(a.LoadpointMaxPowerW) == 0 { return SlotGridCostOre(slot, a.GridW*slot.DurationHours()/1000, p) } + cost := 0.0 + pulseGridW(a, func(share, gridW float64) { + cost += share * SlotGridCostOre(slot, gridW*slot.DurationHours()/1000, p) + }) + return cost +} + +// pulseGridW calls f with each pulse state's share of the slot and its grid +// flow. Without a pulse the slot is one state at its mean flow. +func pulseGridW(a Action, f func(share, gridW float64)) { + if len(a.LoadpointMaxPowerW) == 0 { + f(1, a.GridW) + return + } cuts := []float64{0, 1} totalAverage := 0.0 for id, peak := range a.LoadpointMaxPowerW { @@ -210,7 +248,6 @@ func reserveSlotCost(slot Slot, p Params, a Action) float64 { } } slices.Sort(cuts) - cost := 0.0 for i := 1; i < len(cuts); i++ { midpoint := (cuts[i-1] + cuts[i]) / 2 grid := a.GridW - totalAverage @@ -219,9 +256,8 @@ func reserveSlotCost(slot Slot, p Params, a Action) float64 { grid += peak } } - cost += (cuts[i] - cuts[i-1]) * SlotGridCostOre(slot, grid*slot.DurationHours()/1000, p) + f(cuts[i]-cuts[i-1], grid) } - return cost } // Check the minimum and maximum simultaneous EV draw. Full-interval charges diff --git a/go/internal/mpc/external_optimizer.go b/go/internal/mpc/external_optimizer.go index 3b4a4b83b..e256a957c 100644 --- a/go/internal/mpc/external_optimizer.go +++ b/go/internal/mpc/external_optimizer.go @@ -50,7 +50,7 @@ type ExternalOptimizer struct { cfg ExternalOptimizerConfig transport OptimizerTransport timeBudget func([]Slot, Params) time.Duration - prepareRequest func(context.Context, *externalRequest, Params) error + prepareRequest func(context.Context, *externalRequest, []Slot, Params) error } func NewExternalOptimizer(cfg ExternalOptimizerConfig) (*ExternalOptimizer, error) { @@ -75,6 +75,8 @@ type externalRequest struct { FlexLoads []externalFlexLoad `json:"flex_loads"` ThermalLoads []map[string]any `json:"thermal_loads"` DemandCharges []externalDemandCharge `json:"demand_charges,omitempty"` + // Sent only to a worker that announces hourly_import_caps. + HourlyImportCaps []externalImportCap `json:"hourly_import_caps,omitempty"` } type externalSettings struct { @@ -131,6 +133,16 @@ type externalDemandCharge struct { Hours []externalDemandHour `json:"hours,omitempty"` } +// externalImportCap is one clock hour of the owner's import ceiling: the +// plan's import in it may reach MaxMeanW over the hour less what the hour +// had used before the plan starts. +type externalImportCap struct { + StartMs int64 `json:"start_ms"` + EndMs int64 `json:"end_ms"` + MaxMeanW float64 `json:"max_mean_w"` + ElapsedImportWh float64 `json:"elapsed_import_wh"` +} + type externalDemandHour struct { StartMs int64 `json:"start_ms"` EndMs int64 `json:"end_ms"` @@ -213,7 +225,7 @@ func (o *ExternalOptimizer) Optimize(ctx context.Context, slots []Slot, p Params } request := o.buildRequest(slots, p) if o.prepareRequest != nil { - if err := o.prepareRequest(ctx, &request, p); err != nil { + if err := o.prepareRequest(ctx, &request, slots, p); err != nil { return Plan{}, fmt.Errorf("prepare optimizer request: %w", err) } } @@ -669,5 +681,9 @@ func validatePlan(slots []Slot, p Params, plan *Plan, vehicleRules bool) error { if math.Abs(plan.TotalCostOre-totalCost) > 0.1 { return fmt.Errorf("total cost %.4f, want %.4f", plan.TotalCostOre, totalCost) } + // Last, so an overrun hour is the only rule the plan breaks. + if err := validateImportHours(slots, p, plan.Actions); err != nil { + return &importHourOverrun{plan: *plan, err: err} + } return nil } diff --git a/go/internal/mpc/external_optimizer_test.go b/go/internal/mpc/external_optimizer_test.go index 87559cdb6..44a421243 100644 --- a/go/internal/mpc/external_optimizer_test.go +++ b/go/internal/mpc/external_optimizer_test.go @@ -19,7 +19,7 @@ func TestExternalRequestNegotiatesPublishedPricesAcrossWorkerRollback(t *testing for _, supported := range []bool{true, false, true} { transport.publishedPrices = supported request := external.buildRequest(slots, params) - if err := optimizer.prepareEnergyplanRequest(context.Background(), &request, params); err != nil { + if err := optimizer.prepareEnergyplanRequest(context.Background(), &request, slots, params); err != nil { t.Fatal(err) } raw, err := json.Marshal(request) diff --git a/go/internal/mpc/import_hours.go b/go/internal/mpc/import_hours.go new file mode 100644 index 000000000..dfc502db1 --- /dev/null +++ b/go/internal/mpc/import_hours.go @@ -0,0 +1,187 @@ +package mpc + +import ( + "fmt" + "math" + "time" +) + +// ImportCeiling is the owner's cap on each local clock hour's mean import as +// the planner gets it from Core's live import hour +// (control.PlanningImportCeiling). +type ImportCeiling struct { + W float64 // the owner's ceiling; 0 = off + MeanW float64 // the mean import a planned hour may hold + HourStart time.Time // the local clock hour in progress + ElapsedWh float64 // what that hour has used, as Core's live limit counts it +} + +// ImportHour is one local clock hour the plan spans and the import it had +// used before the plan starts. Core expands the hours from its own clock, so +// the planner needs no calendar: a local clock hour lasts an hour on the 23- +// and 25-hour days too. +type ImportHour struct { + StartMs, EndMs int64 + ElapsedImportWh float64 +} + +const hourMs = int64(time.Hour / time.Millisecond) + +// importHours lists the clock hours the slots overlap from their execution +// start: the hour in progress with what it has used, each later hour unused. +// The last may run past the horizon. +func importHours(slots []Slot, c ImportCeiling) []ImportHour { + if !(c.W > 0) || !finite(c.MeanW) || c.MeanW < 0 || !finite(c.ElapsedWh) || c.HourStart.IsZero() || len(slots) == 0 { + return nil + } + from := slots[0].ExecutionStart() + end, ok := slotEndMs(slots[len(slots)-1]) + if !ok { + return nil + } + var out []ImportHour + for start := c.HourStart.UnixMilli(); start < end; start += hourMs { + if start+hourMs <= from { + continue + } + h := ImportHour{StartMs: start, EndMs: start + hourMs} + if start == c.HourStart.UnixMilli() { + h.ElapsedImportWh = c.ElapsedWh + } + out = append(out, h) + } + return out +} + +// importLeftWh is what the plan may import in h: the hour's mean over its +// length, less what it had used. Negative once overrun. +func importLeftWh(h ImportHour, meanW float64) float64 { + return meanW*float64(h.EndMs-h.StartMs)/float64(hourMs) - h.ElapsedImportWh +} + +// importHourPlannedH is how much of h the slots plan. +func importHourPlannedH(slots []Slot, h ImportHour) float64 { + var spanH float64 + for _, s := range slots { + spanH += importHourOverlapH(s, h) + } + return spanH +} + +func importHourOverlapH(s Slot, h ImportHour) float64 { + end, ok := slotEndMs(s) + if !ok { + return 0 + } + return float64(max(0, min(end, h.EndMs)-max(s.ExecutionStart(), h.StartMs))) / float64(hourMs) +} + +// importHourCapsW spreads each hour's import left over its slots: the most a +// slot's mean import may be, without a car charging (caps) and with one +// (carCaps). Each slot keeps its own house import, so doing nothing stays +// feasible, and they share the room left evenly, never above the hour's +// mean: Core's live limit starts each hour at the mean, so it lets an even +// spread through. A car gets no house floor. In an hour the house alone +// overruns, the live limit holds the car, so no car charges there: its cap +// is negative. Nil when no hour applies. +func importHourCapsW(slots []Slot, p Params) (caps, carCaps []float64) { + if len(p.ImportHours) == 0 { + return nil, nil + } + caps, carCaps = make([]float64, len(slots)), make([]float64, len(slots)) + for i := range caps { + caps[i], carCaps[i] = math.Inf(1), math.Inf(1) + } + for _, h := range p.ImportHours { + var spanH, houseWh float64 + for _, s := range slots { + if ov := importHourOverlapH(s, h); ov > 0 { + spanH += ov + houseWh += max(0, s.LoadW+s.PVW) * ov + } + } + if spanH <= 0 { + continue + } + leftWh := max(0, importLeftWh(h, p.ImportMeanW)) + meanW, roomW := leftWh/spanH, (leftWh-houseWh)/spanH + for i, s := range slots { + if importHourOverlapH(s, h) > 0 { + house := max(0, s.LoadW+s.PVW) + caps[i] = min(caps[i], max(house, min(house+max(0, roomW), meanW))) + carCaps[i] = min(carCaps[i], min(house+roomW, meanW)) + if roomW < 0 { + carCaps[i] = math.Inf(-1) + } + } + } + } + return caps, carCaps +} + +// evAverageRoomW is the most mean EV power a slot holds under capW of mean +// import, with baseW the rest of its grid flow and the car pulsing at +// peakW. A pulse imports while it runs even when the slot exports between. +// A negative cap holds no car. +func evAverageRoomW(capW, baseW, peakW float64) float64 { + if capW < 0 { + return 0 + } + off, on := max(0, baseW), max(0, baseW+peakW) + if on <= off { + return peakW + } + return max(0, min(peakW, (capW-off)*peakW/(on-off))) +} + +// importHourOverrun is a plan that keeps every rule but a clock hour's +// import. Core plans the site itself instead; when it cannot, it publishes +// this plan, and the live limit still holds each hour. +type importHourOverrun struct { + plan Plan + err error +} + +func (e *importHourOverrun) Error() string { return e.err.Error() } + +func actionChargesCar(a Action) bool { + if a.LoadpointW > solverZeroPowerToleranceW { + return true + } + for _, w := range a.LoadpointPowerW { + if w > solverZeroPowerToleranceW { + return true + } + } + return false +} + +// validateImportHours checks the plan's import in each clock hour against +// what the hour has left. In an hour where every car is off, the house's own +// import never fails it: Core cannot cut the house. A car charges only in +// the room the hour has left, since the live limit cuts the car first. +func validateImportHours(slots []Slot, p Params, actions []Action) error { + for _, h := range p.ImportHours { + var spanH, importWh, houseWh float64 + car := false + for i, s := range slots { + ov := importHourOverlapH(s, h) + if ov <= 0 { + continue + } + spanH += ov + pulseGridW(actions[i], func(share, gridW float64) { importWh += share * max(0, gridW) * ov }) + houseWh += max(0, s.LoadW+s.PVW) * ov + car = car || actionChargesCar(actions[i]) + } + leftWh := importLeftWh(h, p.ImportMeanW) + if car { + houseWh = 0 + } + if importWh > max(leftWh, houseWh, 0)+solverGridLimitToleranceW*spanH { + return fmt.Errorf("clock hour from %s imports %.0f Wh, over the %.0f Wh it has left", + time.UnixMilli(h.StartMs).UTC().Format(time.RFC3339), importWh, leftWh) + } + } + return nil +} diff --git a/go/internal/mpc/import_hours_test.go b/go/internal/mpc/import_hours_test.go new file mode 100644 index 000000000..bd6f00f13 --- /dev/null +++ b/go/internal/mpc/import_hours_test.go @@ -0,0 +1,552 @@ +package mpc + +import ( + "context" + "encoding/json" + "fmt" + "math" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/srcfl/ftw/go/internal/state" + "github.com/srcfl/ftw/go/internal/telemetry" +) + +func stockholm(t testing.TB) *time.Location { + t.Helper() + zone, err := time.LoadLocation("Europe/Stockholm") + if err != nil { + t.Fatal(err) + } + return zone +} + +// planImportWh is the plan's import in [fromMs, toMs), counting a charging +// pulse's import while it runs. +func planImportWh(plan Plan, fromMs, toMs int64) float64 { + var wh float64 + for _, a := range plan.Actions { + start := max(a.ExecutionStart(), fromMs) + end := min(a.SlotStartMs+int64(a.SlotLenMin)*60_000, toMs) + if end <= start { + continue + } + pulseGridW(a, func(share, gridW float64) { wh += share * max(0, gridW) * float64(end-start) / 3.6e6 }) + } + return wh +} + +// importCeilingFieldService is the home box at 09:00 on 25 October 2026 +// (v0.155.1-beta.1): an hourly import ceiling of 4.5 kW, about 0.8 kW of +// house load, a 9.6 kWh battery that may feed the car, and a car that wants +// 19 kWh more by 13:00 on a 3 × 20 A fuse. The plan ran the car at 4.83 kW +// from 09:00, imported 4.5-5.7 kWh an hour and called the goal met. Core held +// each hour under 4.5 kWh. A planned hour holds the ceiling less half of +// Core's 690 W rise step (control.PlanningImportCeiling). +func importCeilingFieldService(t *testing.T, optimizer PlanOptimizer, ceiling bool) (*Service, time.Time) { + t.Helper() + start := time.Date(2026, 10, 25, 9, 0, 0, 0, stockholm(t)) + st, err := state.Open(filepath.Join(t.TempDir(), "state.db")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { st.Close() }) + prices := make([]state.PricePoint, 32) + for i := range prices { + prices[i] = state.PricePoint{ + Zone: "SE3", SlotTsMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), SlotLenMin: 15, + SpotOreKwh: 40 + float64(i%4), TotalOreKwh: 90 + float64(i%4), Source: "test", FetchedAtMs: start.UnixMilli(), + } + } + if err := st.SavePrices(prices); err != nil { + t.Fatal(err) + } + svc := New(st, nil, "SE3", Params{ + Mode: ModeArbitrage, SoCLevels: 21, ActionLevels: 21, + CapacityWh: 9600, InitialSoC: .5, SoCMin: .1, SoCMax: .95, + MaxChargeW: 5000, MaxDischargeW: 5000, ChargeEfficiency: .95, DischargeEfficiency: .95, + }) + svc.Optimizer = optimizer + svc.Horizon = 8 * time.Hour + svc.BaseLoad = 800 + svc.now = func() time.Time { return start.Add(30 * time.Second) } + tel := telemetry.NewStore() + soc := .5 + tel.Update("sungrow", telemetry.DerBattery, 0, &soc, nil) + tel.DriverHealthMut("sungrow").RecordSuccess() + svc.Tele = tel + svc.UpdateBatteryFleet([]BatteryFleetMember{{Driver: "sungrow", CapacityWh: 9600, MaxChargeW: 5000, MaxDischargeW: 5000}}, 9600, 5000, 5000) + svc.UpdateSiteEconomics(SiteEconomics{FuseMaxW: 13800, Timezone: "Europe/Stockholm"}) + svc.Loadpoint = func(int) *LoadpointSpec { + return &LoadpointSpec{ID: "carport", CapacityWh: 75000, InitialSoC: .8 - 19000./75000, SoCMax: 1, + Levels: 21, PluggedIn: true, TargetSoC: .8, TargetSlotIdx: 15, MinChargeW: 4140, MaxChargeW: 11040, + AllowedStepsW: []float64{0, 4140, 4830, 5520, 6210, 6900, 7590, 8280, 8970, 9660, 10350, 11040}, + ChargeEfficiency: .9} + } + if ceiling { + svc.ImportCeiling = func() ImportCeiling { + return ImportCeiling{W: 4500, MeanW: 4155, HourStart: start, ElapsedWh: 800 * 30 / 3600.} + } + } + return svc, start +} + +func checkImportCeilingFieldPlan(t *testing.T, svc *Service, start time.Time) Plan { + t.Helper() + if svc.Replan(context.Background()) == nil { + t.Fatalf("no plan published: %+v", svc.PlanSnapshot()) + } + plan := *svc.PlanSnapshot().Plan + for h := 0; h < 8; h++ { + from := start.Add(time.Duration(h) * time.Hour) + budget := 4155.0 + if h == 0 { + budget -= 800 * 30 / 3600. + } + if got := planImportWh(plan, from.UnixMilli(), from.Add(time.Hour).UnixMilli()); got > budget+1 { + t.Errorf("%s: plan imports %.0f Wh, over the hour's %.0f Wh", from.Format("15:04"), got, budget) + } + } + short := plan.LoadpointShortfallWh["carport"] + // The battery covers the house, so the car gets 4 h × 4.155 kW at 90 %: + // about 15 kWh of 19. + if delivered := 19000 - short; short < 1000 || delivered < 14500 { + t.Fatalf("goal by 13:00: %.0f Wh short, %.0f Wh delivered; want it flagged short with the hours' room used", short, delivered) + } + return plan +} + +func TestImportCeilingFieldCase(t *testing.T) { + t.Run("the hours stay under the ceiling and the goal is short", func(t *testing.T) { + svc, start := importCeilingFieldService(t, nil, true) + plan := checkImportCeilingFieldPlan(t, svc, start) + // The battery covers the house so the car gets the hour's room. + for _, a := range plan.Actions[:4] { + if a.LoadpointW > 0 && a.BatteryW > -700 { + t.Errorf("%s: battery %.0f W beside the car; want it covering the house", time.UnixMilli(a.SlotStartMs).In(start.Location()).Format("15:04"), a.BatteryW) + } + } + }) + t.Run("without the ceiling the plan overruns the hours", func(t *testing.T) { + // The scenario exercises the ceiling: master's plan for it. + svc, start := importCeilingFieldService(t, nil, false) + if svc.Replan(context.Background()) == nil { + t.Fatal("no plan published") + } + plan := *svc.PlanSnapshot().Plan + if got := planImportWh(plan, start.UnixMilli(), start.Add(time.Hour).UnixMilli()); got < 5000 { + t.Fatalf("09:00 imports %.0f Wh; the scenario needs a plan over the ceiling without it", got) + } + if short := plan.LoadpointShortfallWh["carport"]; short > 1 { + t.Fatalf("without the ceiling the goal is %.0f Wh short; the scenario needs a goal the fuse alone allows", short) + } + }) +} + +// The bundled worker does not announce hourly_import_caps: Core rejects its +// plan when it overruns an hour and publishes its own. +func TestNativeImportCeilingFieldCase(t *testing.T) { + worker := nativeWorker(t, 1500*time.Millisecond) + t.Cleanup(func() { _ = worker.Close() }) + svc, start := importCeilingFieldService(t, worker, true) + plan := checkImportCeilingFieldPlan(t, svc, start) + if plan.Solver == nil || !plan.Solver.Fallback || !strings.Contains(plan.Solver.FallbackReason, "clock hour") { + t.Fatalf("solver %+v; want Core's plan after the worker's overran an hour", plan.Solver) + } +} + +// A local clock hour lasts an hour on the 25-hour day: 02:00 comes twice. +func TestImportHoursOnTheLongDay(t *testing.T) { + zone := stockholm(t) + hourStart := time.Date(2026, 10, 25, 1, 0, 0, 0, zone) // CEST + now := hourStart.Add(40 * time.Minute) + slots := make([]Slot, 0, 14) + for at := now.Truncate(15 * time.Minute); at.Before(hourStart.Add(4 * time.Hour)); at = at.Add(15 * time.Minute) { + slots = append(slots, Slot{StartMs: at.UnixMilli(), LenMin: 15, LoadW: 500, PriceOre: 100}) + } + slots[0].ExecutionStartMs = now.UnixMilli() + hours := importHours(slots, ImportCeiling{W: 4500, MeanW: 4500, HourStart: hourStart, ElapsedWh: 3500}) + var got []string + for _, h := range hours { + got = append(got, time.UnixMilli(h.StartMs).In(zone).Format("15:04 MST")) + if h.EndMs-h.StartMs != hourMs { + t.Errorf("hour from %s lasts %d ms", got[len(got)-1], h.EndMs-h.StartMs) + } + } + if want := "01:00 CEST,02:00 CEST,02:00 CET,03:00 CET"; strings.Join(got, ",") != want { + t.Fatalf("hours %s, want %s", strings.Join(got, ","), want) + } + if hours[0].ElapsedImportWh != 3500 || hours[1].ElapsedImportWh != 0 || hours[2].ElapsedImportWh != 0 { + t.Fatalf("elapsed %+v", hours) + } + // Each of the two 02:00 hours holds its own 4.5 kWh. + caps, _ := importHourCapsW(slots, Params{ImportMeanW: 4500, ImportHours: hours}) + for i, s := range slots { + want := 4500.0 + if s.StartMs < hourStart.Add(time.Hour).UnixMilli() { + want = 1000 / (20. / 60) // what 01:00 has left over its last 20 minutes + } + if math.Abs(caps[i]-want) > 1e-6 { + t.Errorf("slot %s: cap %.1f W, want %.1f W", time.UnixMilli(s.StartMs).In(zone).Format("15:04 MST"), caps[i], want) + } + } +} + +// The hour in progress starts before the in-flight slot's execution and the +// last runs past the horizon: the plan's part of each may use what the hour +// has left, as Energyplan's hourly_import_caps count it. +func TestImportHoursAroundThePlan(t *testing.T) { + start := time.Date(2026, 10, 26, 9, 0, 0, 0, time.UTC) + slots := []Slot{ + {StartMs: start.Add(15 * time.Minute).UnixMilli(), ExecutionStartMs: start.Add(20 * time.Minute).UnixMilli(), LenMin: 15}, + {StartMs: start.Add(30 * time.Minute).UnixMilli(), LenMin: 15}, + } + c := ImportCeiling{W: 4690, MeanW: 4000, HourStart: start, ElapsedWh: 1000} + hours := importHours(slots, c) + if len(hours) != 1 || hours[0].StartMs != start.UnixMilli() || hours[0].EndMs != start.Add(time.Hour).UnixMilli() || hours[0].ElapsedImportWh != 1000 { + t.Fatalf("hours %+v", hours) + } + // 3 kWh left over the plan's 25 minutes of the hour. + if caps, _ := importHourCapsW(slots, Params{ImportMeanW: c.MeanW, ImportHours: hours}); math.Abs(caps[0]-3000/(25./60)) > 1e-6 { + t.Fatalf("caps %v", caps) + } + c.ElapsedWh = 5000 // overrun: only the house may import + slots[1].LoadW = 600 + if caps, carCaps := importHourCapsW(slots, Params{ImportMeanW: c.MeanW, ImportHours: importHours(slots, c)}); caps[0] != 0 || caps[1] != 600 || !math.IsInf(carCaps[0], -1) || !math.IsInf(carCaps[1], -1) { + t.Fatalf("overrun caps %v, with a car %v", caps, carCaps) + } + if importHours(slots, ImportCeiling{MeanW: 4000, HourStart: start}) != nil { + t.Fatal("no ceiling gave hours") + } + if got := importHours(slots, ImportCeiling{W: 500, HourStart: start}); len(got) != 1 { + t.Fatalf("a ceiling below the rise step gave %+v; want the hour with no room", got) + } +} + +// Each slot keeps its house import and shares the room left, never above +// the hour's mean, so the plan imports evenly as Core's live limit allows. +func TestImportHourCapsSpreadTheRoom(t *testing.T) { + start := time.Date(2026, 10, 26, 9, 0, 0, 0, time.UTC) + slots := make([]Slot, 4) + for i, w := range []float64{4000, 500, 500, -2000} { + slots[i] = Slot{StartMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: max(0, w), PVW: min(0, w)} + } + p := Params{ImportMeanW: 3000, ImportHours: []ImportHour{{StartMs: start.UnixMilli(), EndMs: start.Add(time.Hour).UnixMilli()}}} + caps, carCaps := importHourCapsW(slots, p) + // The house takes 1.25 kWh and leaves 1.75 kWh: 1.75 kW on top of each + // slot's house, never above the 3 kW mean. The 4 kW slot keeps its house, + // but a car there gets only the mean. + for i, want := range []float64{4000, 2250, 2250, 1750} { + if math.Abs(caps[i]-want) > 1e-9 || math.Abs(carCaps[i]-min(want, 3000)) > 1e-9 { + t.Errorf("slot %d: cap %.1f W, with a car %.1f W, want %.1f W", i, caps[i], carCaps[i], want) + } + } + p.ImportMeanW = 500 // less than the house: no room for a car + caps, carCaps = importHourCapsW(slots, p) + for i, want := range []float64{4000, 500, 500, 0} { + if math.Abs(caps[i]-want) > 1e-9 || !math.IsInf(carCaps[i], -1) { + t.Errorf("overrun hour, slot %d: cap %.1f W, with a car %.1f W, want %.1f W and none", i, caps[i], carCaps[i], want) + } + } +} + +func TestValidatePlanHoldsEachClockHourToItsBudget(t *testing.T) { + start := time.Date(2026, 10, 26, 9, 0, 0, 0, time.UTC) + slots := make([]Slot, 8) + for i := range slots { + slots[i] = Slot{StartMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: 800, PriceOre: 100, SpotOre: 50} + } + p := Params{Mode: ModeArbitrage, CapacityWh: 10000, InitialSoC: .5, SoCMin: .1, SoCMax: .9, MaxChargeW: 5000, MaxDischargeW: 5000, + ChargeEfficiency: 1, DischargeEfficiency: 1, ImportMeanW: 4500, + ImportHours: []ImportHour{ + {StartMs: start.UnixMilli(), EndMs: start.Add(time.Hour).UnixMilli()}, + {StartMs: start.Add(time.Hour).UnixMilli(), EndMs: start.Add(2 * time.Hour).UnixMilli()}, + }} + planWith := func(batteryW map[int]float64) Plan { + var plan Plan + soc := p.InitialSoC + for i, s := range slots { + b := batteryW[i] + soc += b * .25 / p.CapacityWh + a := Action{SlotStartMs: s.StartMs, SlotLenMin: 15, LoadW: s.LoadW, BatteryW: b, GridW: s.LoadW + b, SoC: soc} + a.CostOre = reserveSlotCost(s, p, a) + plan.TotalCostOre += a.CostOre + plan.Actions = append(plan.Actions, a) + } + return plan + } + // 0.8 kW + 4.9 kW in one quarter is 5.7 kW, under the fuse, but the + // hour's mean is 2.0 kW: inside the budget. + if plan := planWith(map[int]float64{2: 4900}); ValidatePlan(slots, p, &plan) != nil { + t.Fatal(ValidatePlan(slots, p, &plan)) + } + // 3.9 kW of battery charge all through 10:00 makes a 4.7 kW mean. + plan := planWith(map[int]float64{4: 3900, 5: 3900, 6: 3900, 7: 3900}) + if err := ValidatePlan(slots, p, &plan); err == nil || !strings.Contains(err.Error(), "clock hour") { + t.Fatalf("hour of 4.7 kW mean passed: %v", err) + } + // The house alone may overrun an hour that has used its budget. + p.ImportHours[0].ElapsedImportWh = 4400 + if plan := planWith(nil); ValidatePlan(slots, p, &plan) != nil { + t.Fatal(ValidatePlan(slots, p, &plan)) + } + if plan := planWith(map[int]float64{0: 1000}); ValidatePlan(slots, p, &plan) == nil { + t.Fatal("battery charge into an overrun hour passed") + } +} + +// A car pulse imports while it runs even when the slot exports between. +func TestValidatePlanCountsPulseImport(t *testing.T) { + start := time.Date(2026, 10, 26, 12, 0, 0, 0, time.UTC) + slots := make([]Slot, 4) + for i := range slots { + slots[i] = Slot{StartMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: 500, PVW: -4500, PriceOre: 100, SpotOre: 50} + } + lp := &LoadpointSpec{ID: "car", CapacityWh: 60000, Levels: 11, SoCMax: 1, InitialSoC: .5, PluggedIn: true, + MaxChargeW: 11000, AllowedStepsW: []float64{0, 11000}, ChargeEfficiency: 1} + p := Params{Mode: ModeArbitrage, ChargeEfficiency: 1, DischargeEfficiency: 1, Loadpoint: lp, ImportMeanW: 1000, + ImportHours: []ImportHour{{StartMs: start.UnixMilli(), EndMs: start.Add(time.Hour).UnixMilli()}}} + var plan Plan + soc := lp.InitialSoC + for _, s := range slots { + // 4 kW mean: 11 kW for 4/11 of the slot imports 7 kW, else 4 kW export. + soc += 4000 * .25 / lp.CapacityWh + a := Action{SlotStartMs: s.StartMs, SlotLenMin: 15, LoadW: s.LoadW, PVW: s.PVW, GridW: 0, LoadpointW: 4000, LoadpointSoC: soc, + LoadpointPowerW: map[string]float64{"car": 4000}, LoadpointSoCByID: map[string]float64{"car": soc}, LoadpointMaxPowerW: map[string]float64{"car": 11000}} + a.CostOre = reserveSlotCost(s, p, a) + plan.TotalCostOre += a.CostOre + plan.Actions = append(plan.Actions, a) + } + // Mean grid flow is 0 W, but the pulses import 7 kW × 4/11 ≈ 2.5 kWh. + if err := ValidatePlan(slots, p, &plan); err == nil || !strings.Contains(err.Error(), "clock hour") { + t.Fatalf("pulses importing 2.5 kWh passed a 1 kWh hour: %v", err) + } +} + +// The DP charges the battery in the cheap hour only as far as the hour's +// budget leaves room, and the plan passes the same check. +func TestOptimizeKeepsEachHourUnderItsBudget(t *testing.T) { + start := time.Date(2026, 10, 26, 1, 0, 0, 0, time.UTC) + slots := make([]Slot, 8) + for i := range slots { + price := 20.0 + if i >= 4 { + price = 300 + } + slots[i] = Slot{StartMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: 800, PriceOre: price, SpotOre: price / 2} + } + p := Params{Mode: ModeArbitrage, SoCLevels: 41, ActionLevels: 41, CapacityWh: 20000, InitialSoC: .2, SoCMin: .1, SoCMax: .95, + MaxChargeW: 8000, MaxDischargeW: 8000, ChargeEfficiency: .95, DischargeEfficiency: .95} + free := Optimize(slots, p) + if got := planImportWh(free, start.UnixMilli(), start.Add(time.Hour).UnixMilli()); got < 6000 { + t.Fatalf("without a budget the cheap hour imports %.0f Wh; the test needs it over 3 kWh", got) + } + p.ImportMeanW, p.ImportHours = 3000, []ImportHour{{StartMs: start.UnixMilli(), EndMs: start.Add(time.Hour).UnixMilli()}} + plan := Optimize(slots, p) + if err := ValidatePlan(slots, p, &plan); err != nil { + t.Fatal(err) + } + // The 400 W action grid reaches 2.8 of the 3 kWh. + if got := planImportWh(plan, start.UnixMilli(), start.Add(time.Hour).UnixMilli()); got > 3000+1e-6 || got < 2700 { + t.Fatalf("cheap hour imports %.0f Wh; want the room of its 3000 Wh used", got) + } +} + +type importCapTransport struct{ caps bool } + +func (c *importCapTransport) RoundTrip(context.Context, []byte) ([]byte, error) { + features := []string{"champion", "ev_duty", "published_prices"} + if c.caps { + features = append(features, "hourly_import_caps") + } + return json.Marshal(map[string]any{"name": "ftw-solver", "version": "test", "protocol_version": 1, "features": features}) +} +func (*importCapTransport) Close() error { return nil } + +// A worker that announces hourly_import_caps gets each hour, the mean and +// what the hour in progress had used. Any other worker, and every worker +// while the ceiling is off, gets the request it got before. +func TestEnergyplanRequestCarriesHourlyImportCaps(t *testing.T) { + slots, p := externalTestFixture() + transport := &importCapTransport{} + external := &ExternalOptimizer{cfg: ExternalOptimizerConfig{Timeout: 7 * time.Second}, transport: transport, timeBudget: energyplanTimeBudget} + o := &EnergyplanOptimizer{ExternalOptimizer: external} + request := func(p Params) string { + t.Helper() + r := external.buildRequest(slots, p) + r.RequestID = "fixed" + if err := o.prepareEnergyplanRequest(context.Background(), &r, slots, p); err != nil { + t.Fatal(err) + } + raw, err := json.Marshal(r) + if err != nil { + t.Fatal(err) + } + return string(raw) + } + off := p + on := p + on.ImportMeanW = 3810 + // The third hour lies past the slots: it is not sent. + on.ImportHours = []ImportHour{{StartMs: 0, EndMs: hourMs, ElapsedImportWh: 125}, {StartMs: hourMs, EndMs: 2 * hourMs}, {StartMs: 3 * hourMs, EndMs: 4 * hourMs}} + for _, caps := range []bool{true, false} { + transport.caps = caps + if request(on) == request(off) != !caps { + t.Fatalf("caps=%v: with the ceiling on the request changes %v", caps, request(on) != request(off)) + } + } + transport.caps = true + if got, want := request(on), `"hourly_import_caps":[{"start_ms":0,"end_ms":3600000,"max_mean_w":3810,"elapsed_import_wh":125},{"start_ms":3600000,"end_ms":7200000,"max_mean_w":3810,"elapsed_import_wh":0}]`; !strings.Contains(got, want) { + t.Fatalf("request %s\nwant %s", got, want) + } + // With the hours the worker gets the fleet budget; without them its own. + if got := request(on); !strings.Contains(got, `"time_limit_s":5,`) || !strings.Contains(request(off), `"time_limit_s":0.5,`) { + t.Fatalf("time limits: with hours %s; without %s", got, request(off)) + } + if strings.Contains(request(off), "hourly_import_caps") { + t.Fatal("the ceiling off sent caps") + } +} + +// ceilinglessOptimizer plans as a worker without the hours does: its plan +// keeps every rule but the hours, and Core's check names the hour. +type ceilinglessOptimizer struct{} + +func (ceilinglessOptimizer) Optimize(ctx context.Context, slots []Slot, p Params) (Plan, error) { + free := p + free.ImportHours, free.ImportMeanW = nil, 0 + plan, err := coreReservePlan(ctx, slots, free) + if err != nil { + return Plan{}, err + } + if err := ValidatePlan(slots, p, &plan); err != nil { + return Plan{}, fmt.Errorf("optimizer plan rejected: %w", err) + } + return plan, nil +} + +func (ceilinglessOptimizer) Close() error { return nil } + +// A worker plan that overruns an hour falls back to Core's own plan. When +// Core cannot plan the site itself, here a battery below its floor, the +// worker's plan is published as before the hours, with a warning, rather +// than no plan at all. +func TestImportCeilingWorkerPlanOverrunsAnHour(t *testing.T) { + for _, soc := range []float64{.5, .05} { + t.Run(fmt.Sprintf("battery %.0f %%", soc*100), func(t *testing.T) { + svc, start := importCeilingFieldService(t, ceilinglessOptimizer{}, true) + svc.Tele.Update("sungrow", telemetry.DerBattery, 0, &soc, nil) + if svc.Replan(context.Background()) == nil { + t.Fatalf("no plan published: %+v", svc.PlanSnapshot()) + } + snap := svc.PlanSnapshot() + got := planImportWh(*snap.Plan, start.UnixMilli(), start.Add(time.Hour).UnixMilli()) + warned := strings.Contains(strings.Join(snap.Warnings, " "), "Core cannot plan this site itself") + if soc == .5 { + if !snap.Plan.Solver.Fallback || got > 4155 || warned { + t.Fatalf("solver %+v, 09:00 imports %.0f Wh, warned %v; want Core's plan inside the hour", snap.Plan.Solver, got, warned) + } + return + } + if snap.Plan.Solver.Fallback || got <= 4155 || !warned { + t.Fatalf("solver %+v, 09:00 imports %.0f Wh, warnings %q; want the worker's plan with a warning", snap.Plan.Solver, got, snap.Warnings) + } + }) + } +} + +func TestNativeImportCeilingWhenCoreCannotPlan(t *testing.T) { + worker := nativeWorker(t, 1500*time.Millisecond) + t.Cleanup(func() { _ = worker.Close() }) + svc, _ := importCeilingFieldService(t, worker, true) + soc := .05 + svc.Tele.Update("sungrow", telemetry.DerBattery, 0, &soc, nil) + if svc.Replan(context.Background()) == nil { + t.Fatalf("no plan published: %+v", svc.PlanSnapshot()) + } + if w := strings.Join(svc.PlanSnapshot().Warnings, " "); !strings.Contains(w, "Core cannot plan this site itself") { + t.Fatalf("warnings %q", w) + } +} + +// A car step that needs the battery to discharge past the house fits the +// fuse only while it runs. When the hour makes it part-time, the battery +// would drive export beside the car: the reserve plan takes a smaller step. +func TestReservePlanUnderAnHourNeverChargesTheCarFromExport(t *testing.T) { + first := time.Date(2026, 10, 26, 10, 40, 0, 0, time.UTC) + for _, fuse := range []float64{6900, 8280} { + slots := make([]Slot, 12) + for i := range slots { + slots[i] = Slot{StartMs: first.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: 500, PriceOre: 100, SpotOre: 50, + Limits: PowerLimits{MaxImportW: fuse, MaxExportW: fuse}} + } + p := Params{Mode: ModeArbitrage, SoCLevels: 21, ActionLevels: 21, CapacityWh: 10000, InitialSoC: .8, SoCMin: .1, SoCMax: .95, + MaxChargeW: 5000, MaxDischargeW: 5000, ChargeEfficiency: .95, DischargeEfficiency: .95, + Loadpoint: &LoadpointSpec{ID: "car", CapacityWh: 60000, InitialSoC: .3, SoCMax: 1, Levels: 21, PluggedIn: true, MinChargeW: 4140, MaxChargeW: 11040, + AllowedStepsW: []float64{0, 4140, 6900, 11040}, ChargeEfficiency: .9, TargetSoC: .5, TargetSlotIdx: 10}} + c := ImportCeiling{W: 4500, MeanW: 4155, HourStart: first.Add(-40 * time.Minute), ElapsedWh: 3800} + p.ImportHours, p.ImportMeanW = importHours(slots, c), c.MeanW + if _, used, err := corePlanWithRecovery(context.Background(), slots, p); err != nil || len(used) != len(slots) { + t.Errorf("fuse %.0f W: %d of %d slots, err %v", fuse, len(used), len(slots), err) + } + } +} + +// The house may overrun an hour that has used its budget, but a car may not +// charge there on the import the battery frees by covering the house: Core's +// live limit stops the car. The plan holds the car to the next hour. +func TestNoCarOnTheHouseFloor(t *testing.T) { + start := time.Date(2026, 10, 26, 9, 0, 0, 0, time.UTC) + slots := make([]Slot, 8) + for i := range slots { + slots[i] = Slot{StartMs: start.Add(time.Duration(i) * 15 * time.Minute).UnixMilli(), LenMin: 15, LoadW: 800, PriceOre: 100, SpotOre: 50, + Limits: PowerLimits{MaxImportW: 13800, MaxExportW: 13800}} + } + lp := &LoadpointSpec{ID: "car", CapacityWh: 60000, InitialSoC: .3, SoCMax: 1, Levels: 21, PluggedIn: true, MinChargeW: 4140, MaxChargeW: 11040, + AllowedStepsW: []float64{0, 4140, 11040}, ChargeEfficiency: .9, TargetSoC: .5, TargetSlotIdx: 7} + p := Params{Mode: ModeArbitrage, SoCLevels: 21, ActionLevels: 21, CapacityWh: 10000, InitialSoC: .8, SoCMin: .1, SoCMax: .95, + MaxChargeW: 5000, MaxDischargeW: 5000, ChargeEfficiency: 1, DischargeEfficiency: 1, Loadpoint: lp, ImportMeanW: 4155, + ImportHours: []ImportHour{ + {StartMs: start.UnixMilli(), EndMs: start.Add(time.Hour).UnixMilli(), ElapsedImportWh: 4000}, + {StartMs: start.Add(time.Hour).UnixMilli(), EndMs: start.Add(2 * time.Hour).UnixMilli()}, + }} + plan, used, err := corePlanWithRecovery(context.Background(), slots, p) + if err != nil || len(used) != len(slots) { + t.Fatalf("%d of %d slots, err %v", len(used), len(slots), err) + } + for i, a := range plan.Actions { + if i < 4 && a.LoadpointW > 0 { + t.Errorf("slot %d: car at %.0f W in the hour that has 155 Wh left for 800 W of house", i, a.LoadpointW) + } + } + if plan.Actions[4].LoadpointW <= 0 { + t.Errorf("the car waits past 10:00: %+v", plan.Actions[4]) + } + // The same car beside a battery covering the house fails the check. + a := &plan.Actions[0] + a.BatteryW, a.LoadpointW = -800, 800 + a.LoadpointPowerW, a.LoadpointMaxPowerW = map[string]float64{"car": 800}, map[string]float64{"car": 4140} + err = validateImportHours(slots, p, plan.Actions) + if err == nil || !strings.Contains(err.Error(), "clock hour") { + t.Fatalf("car on the house floor passed: %v", err) + } +} + +// The DP plans on a SoC grid. Replayed from the real SoC, the battery can run +// short of the discharge that kept an hour under its budget, here at 12:45 +// in the field case: the car gives way rather than the hour overrunning. +func TestOptimizeCarGivesWayWhenTheBatteryRunsShort(t *testing.T) { + svc, _ := importCeilingFieldService(t, nil, true) + if svc.Replan(context.Background()) == nil { + t.Fatal("no plan published") + } + svc.mu.RLock() + slots, p := append([]Slot(nil), svc.lastSlots...), svc.lastParams + svc.mu.RUnlock() + plan := Optimize(slots, p) + if err := ValidatePlan(slots, p, &plan); err != nil { + t.Fatal(err) + } +} diff --git a/go/internal/mpc/mpc.go b/go/internal/mpc/mpc.go index 7030beda1..8118f6f0c 100644 --- a/go/internal/mpc/mpc.go +++ b/go/internal/mpc/mpc.go @@ -248,6 +248,14 @@ type Params struct { // DemandCharges are peak-power tariffs Core expanded to clock hours. // Empty leaves Energyplan on energy prices only. DemandCharges []DemandCharge + + // ImportHours carry the owner's hourly import ceiling: each clock hour + // the plan spans may import ImportMeanW over its length, less what it had + // used. ValidatePlan holds every plan to them, Core's own planners spread + // each hour over its slots, and a worker that announces + // hourly_import_caps gets them on its wire. + ImportMeanW float64 + ImportHours []ImportHour } // StorageAssetSpec is one independently constrained home battery in the @@ -660,6 +668,7 @@ func OptimizeContext(ctx context.Context, slots []Slot, p Params) (Plan, error) // The mean price scales the EV deadline penalty and labels reasons. meanPrice := horizonMeanPrice(slots) + importCaps, carImportCaps := importHourCapsW(slots, p) // Action grid spans −MaxDischargeW … +MaxChargeW and always contains // 0 W. With asymmetric charge/discharge limits, an odd number of evenly @@ -866,10 +875,14 @@ func OptimizeContext(ctx context.Context, slots []Slot, p Params) (Plan, error) continue } - // Per-slot power limits. + // Per-slot power limits, and the slot's share of + // its clock hour's import budget. if !slot.Limits.allowsImport(gridW) || !slot.Limits.allowsExport(gridW) { continue } + if importCaps != nil && (gridW > importCaps[t] || evW > 0 && gridW > carImportCaps[t]) { + continue + } gridKWh := gridW * dtH / 1000.0 var cost float64 @@ -1102,6 +1115,20 @@ func OptimizeContext(ctx context.Context, slots []Slot, p Params) (Plan, error) } } gridW := loadpoint.GridW(slot.LoadW, slot.PVW, actW, evW) + // The real SoC can leave the battery short of the policy's + // discharge. The car then gives way to the hour's import, as + // Core's live limit cuts the car first. + if evW > 0 && carImportCaps != nil && gridW > carImportCaps[t] { + evW = 0 + for k := len(evSteps) - 1; k > 0; k-- { + if loadpoint.GridW(slot.LoadW, slot.PVW, actW, evSteps[k]) <= carImportCaps[t] { + evW = evSteps[k] + break + } + } + evSoc2 = evSoc + evW*dtH*evChargeEff/lp.CapacityWh + gridW = loadpoint.GridW(slot.LoadW, slot.PVW, actW, evW) + } gridKWh := gridW * dtH / 1000.0 // Report the ACTUAL expected cost using the raw (un-blended) // prices so the UI summary reflects "what we'd actually pay diff --git a/go/internal/mpc/reserve_price.go b/go/internal/mpc/reserve_price.go index b1610a2a3..bc052bb0a 100644 --- a/go/internal/mpc/reserve_price.go +++ b/go/internal/mpc/reserve_price.go @@ -73,6 +73,7 @@ func priceReserveCharging(ctx context.Context, slots []Slot, p Params, reserve P a.LoadpointSoCByID = map[string]float64{lp.ID: lp.InitialSoC} } remaining := energyWh + _, importCaps := importHourCapsW(slots, p) for _, o := range offers { if err := ctx.Err(); err != nil { return Plan{}, err @@ -82,6 +83,13 @@ func priceReserveCharging(ctx context.Context, slots []Slot, p Params, reserve P } hours := slots[o.index].DurationHours() average := min(o.peakW, remaining/(eff*hours)) + if importCaps != nil { + slot := slots[o.index] + average = min(average, evAverageRoomW(importCaps[o.index], slot.LoadW+slot.PVW+reserve.Actions[o.index].BatteryW, o.peakW)) + if average <= 1e-6 { + continue + } + } a := &priced.Actions[o.index] a.LoadpointW = average a.LoadpointPowerW[lp.ID] = average diff --git a/go/internal/mpc/service.go b/go/internal/mpc/service.go index d8fec988b..70239123b 100644 --- a/go/internal/mpc/service.go +++ b/go/internal/mpc/service.go @@ -2,6 +2,7 @@ package mpc import ( "context" + "errors" "fmt" "log/slog" "maps" @@ -133,6 +134,10 @@ type Service struct { // watts. Nil or 0 plans against the aggregate fuse alone. Called // without s.mu; it may take the control lock. PhaseImbalanceW func() float64 + // ImportCeiling returns the owner's hourly import ceiling as Core + // enforces it. Nil or zero W plans without it. Called without s.mu; it + // may take the control lock. + ImportCeiling func() ImportCeiling // Set before Start. Called without s.mu; must not acquire the control lock. PVExecutionAllowed func(PVCurtailment) bool Load LoadPredictor // optional — overrides flat BaseLoad @@ -1694,6 +1699,10 @@ func (s *Service) runReplan(request replanRequest) *Plan { } limitNearImportForPhases(slots, now, fuseMaxW, phaseImbalanceW) limitNearImportForPhases(fallbackSlots, now, fuseMaxW, phaseImbalanceW) + var importCeiling ImportCeiling + if s.ImportCeiling != nil { + importCeiling = s.ImportCeiling() + } if s.PVCurtailmentProbe != nil { p.PVCurtailment = s.PVCurtailmentProbe() @@ -1741,6 +1750,10 @@ func (s *Service) runReplan(request replanRequest) *Plan { p.ExportFloorOreKwh = site.ExportFloorOreKwh p.PVForecastSafetyK = request.safetyK p.DemandCharges = s.demandChargesFor(site, slots, executionNow) + p.ImportHours = importHours(slots, importCeiling) + if p.ImportHours != nil { + p.ImportMeanW = importCeiling.MeanW + } if pvUncertainty != nil || s.ForecastSnapshot != nil { p.PVUncertaintyW = pvUncertaintyW } @@ -2059,6 +2072,17 @@ func (s *Service) runReplan(request replanRequest) *Plan { } plan = candidate + } else if overrun := (*importHourOverrun)(nil); errors.As(err, &overrun) && (recoveryRequired && !downsidePrimary || coreDPModelError(p) != nil) { + // Core cannot plan this site itself. The worker's plan keeps + // every rule but the hours, as before the hours existed; the + // live limit still holds each hour. + if request.wasCanceledByService() { + return s.canceledReplan(request, "primary-fallback") + } + s.recordPlanningFailure(request, "primary_optimizer", err.Error(), slots, p, optimizerErr) + plan = overrun.plan + p.ImportHours, p.ImportMeanW = nil, 0 + warnings = append(warnings, "Core cannot plan this site itself, so the plan may import more in an hour than the limit allows; Core still holds each hour to it: "+err.Error()) } else { if request.wasCanceledByService() { return s.canceledReplan(request, "primary-fallback")