Planner: per-slot power cap in planCapped (Phase 2 core)

Generalise optimalPlan into planCapped: with no cap it is the old full-power
duration accounting (optimalPlan delegates, behaviour unchanged); with a
per-slot availability a slot delivers min(maxPower, avail) and is skipped
below minPower (semi-continuous), so a power-limited slot counts less and the
plan spills into more slots. Not yet wired into Plan - needs the ledger.

Author: andig

core/planner/capped_test.go

@@ -0,0 +1,49 @@
+package planner
+
+import (
+	"testing"
+	"time"
+
+	"github.com/evcc-io/evcc/api"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPlanCapped(t *testing.T) {
+	start := time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC)
+	target := start.Add(4 * time.Hour)
+
+	mk := func(n int) api.Rates {
+		var r api.Rates
+		for i := 0; i < n; i++ {
+			s := start.Add(time.Duration(i) * time.Hour)
+			r = append(r, api.Rate{Start: s, End: s.Add(time.Hour), Value: 0.1})
+		}
+		return r
+	}
+
+	const maxPower, minPower = 11000.0, 1380.0
+	full := func(time.Time) float64 { return maxPower }
+	half := func(time.Time) float64 { return maxPower / 2 }
+
+	// full availability == unconstrained duration accounting
+	p := planCapped(mk(4), time.Hour, target, full, maxPower, minPower)
+	assert.Equal(t, time.Hour, Duration(p))
+
+	// half power -> plan spills into twice the wall-clock time for the same energy
+	p = planCapped(mk(4), time.Hour, target, half, maxPower, minPower)
+	assert.Equal(t, 2*time.Hour, Duration(p))
+	assert.Len(t, p, 2)
+
+	// a slot below min power is skipped (semi-continuous)
+	skipFirst := func(ts time.Time) float64 {
+		if ts.Equal(start) {
+			return minPower - 1
+		}
+		return maxPower
+	}
+	p = planCapped(mk(4), time.Hour, target, skipFirst, maxPower, minPower)
+	assert.Equal(t, time.Hour, Duration(p))
+	for _, r := range p {
+		assert.False(t, r.Start.Equal(start), "sub-min slot must be skipped")
+	}
+}

core/planner/planner.go

@@ -39,19 +39,37 @@ func New(log *util.Logger, tariff api.Tariff, opt ...func(t *Planner)) *Planner
 // - rates are sorted in ascending order by cost and descending order by start time (prefer late slots)
 // - rates are filtered to [now, targetTime] window by caller
 func optimalPlan(rates api.Rates, requiredDuration time.Duration, targetTime time.Time) api.Rates {
+	return planCapped(rates, requiredDuration, targetTime, nil, 0, 0)
+}
+
+// planCapped builds a lowest-cost plan; with avail==nil each slot is full power
+// (duration accounting), else min(maxPower, avail) and skipped below minPower.
+func planCapped(rates api.Rates, requiredDuration time.Duration, targetTime time.Time, avail func(time.Time) float64, maxPower, minPower float64) api.Rates {
 	plan := make(api.Rates, 0, int64(requiredDuration)/int64(tariff.SlotDuration)+3)
 
 	for _, slot := range rates {
 		slotDuration := slot.End.Sub(slot.Start)
-		requiredDuration -= slotDuration
+
+		// per-slot power factor: full unless a capacity cap applies
+		factor := 1.0
+		if avail != nil && maxPower > 0 {
+			p := avail(slot.Start)
+			if p < minPower {
+				continue // semi-continuous: charge >= min or not at all
+			}
+			factor = min(maxPower, p) / maxPower
+		}
+
+		requiredDuration -= time.Duration(float64(slotDuration) * factor)
 
 		// slot covers more than we need, so shorten it
 		if requiredDuration < 0 {
+			trim := time.Duration(float64(-requiredDuration) / factor)
 			// the first (if not single) slot should start as late as possible
 			if IsFirst(slot, plan) && len(plan) > 0 {
-				slot.Start = slot.Start.Add(-requiredDuration)
+				slot.Start = slot.Start.Add(trim)
 			} else {
-				slot.End = slot.End.Add(requiredDuration)
+				slot.End = slot.End.Add(-trim)
 			}
 			requiredDuration = 0
 		}

docs/agents/loadmanagement-aware-planning.md

@@ -106,10 +106,11 @@ sequence stays untouched.
 - [x] Per-slot residual-capacity ledger (`planner.CapacityLedger`): `Available`,
       `Reserve`, and `CanHost` (semi-continuous min-power gate). Single circuit,
       static budget for now; parent/child tree still TODO.
-- [ ] Extend `planner.Plan` / `optimalPlan` to accept a per-slot power cap.
-      Today a slot equals full Pmax; a capped slot delivers
-      `min(Pmax, residual) × slotLen`, so a partially-available slot must spill
-      the plan into more slots. This is the core rework.
+- [x] `planner.planCapped` (per-slot power cap): with `avail==nil` it is the old
+      full-power duration accounting (`optimalPlan` delegates, behaviour
+      unchanged); with a cap a slot delivers `min(maxPower, avail)` and is skipped
+      below `minPower`, so a power-limited slot counts proportionally less and the
+      plan spills into more slots. Not yet wired into `Plan` (needs the ledger).
 - [ ] Site orchestration: reserve forced load → plan loadpoints in priority
       order against the ledger, subtracting each reservation.
 - [ ] Allocate the shared budget in whole `EffectiveMinPower()` chunks