fix: soc hysteresis band

Author: gmlexx

mpc/mpc.go

@@ -522,14 +522,14 @@ func (mpc *Controller) generateFeasibleDecisions(currentSOC float64, currentBatt
 		}
 		socGap := mpc.Config.BatteryMaxSOC - currentSOC
 		if socGap > 1e-9 {
-			// Use the same balancing-aware efficiency as calculateNewSOC so that
-			// the top-up charge correctly accounts for the extra energy required
-			// in the CV/balancing phase when the battery is nearly full.
-			efficiency := mpc.Config.BatteryEfficiency
+			// Use the same DC-side, balancing-aware efficiency as calculateNewSOC
+			// so that the top-up charge correctly accounts for the extra energy
+			// required in the CV/balancing phase when the battery is nearly full.
+			efficiency := 1.0
 			if mpc.Config.BatteryBalancingSOCThreshold > 0 &&
 				mpc.Config.BatteryBalancingEfficiencyFactor > 0 &&
 				currentSOC >= mpc.Config.BatteryBalancingSOCThreshold {
-				efficiency *= mpc.Config.BatteryBalancingEfficiencyFactor
+				efficiency = mpc.Config.BatteryBalancingEfficiencyFactor
 			}
 			// Invert calculateNewSOC: charge needed so that
 			//   currentSOC + charge * duration * efficiency / capacity == BatteryMaxSOC
@@ -689,14 +689,15 @@ func (mpc *Controller) canCharge(soc, charge float64) bool {
 		timeSlotDuration = 1.0
 	}
 
-	// Use the same balancing-aware efficiency as calculateNewSOC: in the CV/balancing
-	// phase near 100% SOC the same charge power produces less SOC increase, so more
-	// charge actions remain valid (they won't overshoot BatteryMaxSOC).
-	efficiency := mpc.Config.BatteryEfficiency
+	// Use the same DC-side convention and balancing-aware derate as
+	// calculateNewSOC so that both functions agree on how much the SOC actually
+	// rises.  BatteryEfficiency is deliberately NOT applied here: it is already
+	// accounted for on the AC side of the power balance.
+	efficiency := 1.0
 	if mpc.Config.BatteryBalancingSOCThreshold > 0 &&
 		mpc.Config.BatteryBalancingEfficiencyFactor > 0 &&
 		soc >= mpc.Config.BatteryBalancingSOCThreshold {
-		efficiency *= mpc.Config.BatteryBalancingEfficiencyFactor
+		efficiency = mpc.Config.BatteryBalancingEfficiencyFactor
 	}
 
 	// Convert power (kW) to energy (kWh) using the same formula as calculateNewSOC:
@@ -727,17 +728,27 @@ func (mpc *Controller) calculateNewSOC(currentSOC, charge, discharge float64) fl
 		timeSlotDuration = 1.0
 	}
 
-	// Apply reduced charging efficiency in the CV/balancing phase.
-	// When currentSOC is at or above BatteryBalancingSOCThreshold the battery is in
-	// constant-voltage mode: cells are being balanced and more input energy is needed
-	// per unit of SOC increase.  The efficiency factor captures this extra cost so
-	// that the optimizer correctly prices charging into the very top of the SOC range.
-	efficiency := mpc.Config.BatteryEfficiency
+	// Charge/discharge powers are DC-side (battery terminal) quantities, which
+	// is the convention the power balance in generateFeasibleDecisions uses:
+	// charging draws charge/BatteryEfficiency from the AC bus and discharging
+	// delivers discharge*BatteryEfficiency to it.  The conversion loss is
+	// therefore already accounted for on the AC side, and the DC-side energy
+	// that actually moves in or out of the cells is simply power * duration.
+	//
+	// Applying BatteryEfficiency again here would double-count the charging
+	// loss: bus->SOC would be modelled at efficiency^2 while SOC->bus stayed at
+	// efficiency, giving an asymmetric round trip (0.778 instead of 0.846 at
+	// efficiency=0.92) that made charging look worse than discharging.
+	//
+	// The CV/balancing derate is a separate physical effect and still applies:
+	// at or above BatteryBalancingSOCThreshold the cells are being balanced and
+	// far more input energy is needed per unit of SOC gain.
+	efficiency := 1.0
 	if charge > 0 &&
 		mpc.Config.BatteryBalancingSOCThreshold > 0 &&
 		mpc.Config.BatteryBalancingEfficiencyFactor > 0 &&
 		currentSOC >= mpc.Config.BatteryBalancingSOCThreshold {
-		efficiency *= mpc.Config.BatteryBalancingEfficiencyFactor
+		efficiency = mpc.Config.BatteryBalancingEfficiencyFactor
 	}
 
 	// Convert power (kW) to energy (kWh) by multiplying by time slot duration

mpc/mpc_balancing_test.go

@@ -133,21 +133,25 @@ func TestCVPhase_ReducedSOCIncrease(t *testing.T) {
 
 	// Use a small charge power so neither SOC trajectory overshoots BatteryMaxSOC
 	// and gets clamped, which would mask the efficiency difference we are testing.
-	// Below threshold: 0.989 + 0.01*1.0*0.9/10 = 0.9899  (< 1.0 ✓)
-	// At threshold:    0.999 + 0.01*1.0*0.27/10 = 0.99927 (< 1.0 ✓)
+	//
+	// Charge power is DC-side, so BatteryEfficiency does NOT appear here — it is
+	// accounted for on the AC side of the power balance. Only the CV-phase
+	// derate applies:
+	//   Below threshold: 0.989 + 0.01*1.0*1.0/10  = 0.99    (< 1.0 ✓)
+	//   At threshold:    0.999 + 0.01*1.0*0.3/10  = 0.9993  (< 1.0 ✓)
 	chargeKW := 0.01 // kW for one hour
 
-	// ── Below threshold: normal efficiency ──────────────────────────────────
+	// ── Below threshold: no derate ──────────────────────────────────────────
 	socBelow := config.BatteryBalancingSOCThreshold - 0.01 // e.g. 98.9 %
 	newSOCBelow := ctrl.calculateNewSOC(socBelow, chargeKW, 0)
 
-	wantBelow := socBelow + chargeKW*config.TimeSlotDuration*config.BatteryEfficiency/config.BatteryCapacity
+	wantBelow := socBelow + chargeKW*config.TimeSlotDuration/config.BatteryCapacity
 	if math.Abs(newSOCBelow-wantBelow) > 1e-9 {
 		t.Errorf("Below threshold: calculateNewSOC=%.8f, want %.8f", newSOCBelow, wantBelow)
 	}
 
 	// ── At threshold: reduced (CV-phase) efficiency ──────────────────────────
-	cvEff := config.BatteryEfficiency * config.BatteryBalancingEfficiencyFactor
+	cvEff := config.BatteryBalancingEfficiencyFactor
 	socAt := config.BatteryBalancingSOCThreshold
 	newSOCAt := ctrl.calculateNewSOC(socAt, chargeKW, 0)
 

scheduler/config.go

@@ -91,6 +91,24 @@ type Config struct {
 	BatteryBalancingEfficiencyFactor float64 `json:"battery_balancing_efficiency_factor"` // multiplier on BatteryEfficiency during CV phase (e.g. 0.3); 0 disables
 	BatteryBalancingBonus            float64 `json:"battery_balancing_bonus"`             // one-time profit bonus awarded when battery first reaches BatteryMaxSOC within the horizon; 0 disables
 
+	// Top-of-charge hold parameters.
+	//
+	// When the battery sits at/above BatteryBalancingSOCThreshold and weekly
+	// cell-balancing is not due, opportunistic charging is blocked so the pack
+	// is not pushed into its low-efficiency CV phase.  Releasing that block the
+	// moment SOC dips back below the threshold produces a limit cycle: the
+	// inverter's auxiliary draw slowly depletes the pack, charging is
+	// re-enabled, PV tops it straight back up, and the block re-engages — the
+	// battery micro-cycles around the threshold for hours.
+	//
+	// BatteryBalancingSOCReleaseBand adds hysteresis: once blocked, charging is
+	// only re-enabled after SOC falls below (threshold - releaseBand).
+	// BatteryTopHoldPower allows a small trickle while blocked so the inverter's
+	// own consumption is served from PV/grid rather than from the pack, which
+	// removes the drift that drives the cycle in the first place.
+	BatteryBalancingSOCReleaseBand float64 `json:"battery_balancing_soc_release_band"` // SOC hysteresis band (0-1) below BatteryBalancingSOCThreshold; 0 disables hysteresis
+	BatteryTopHoldPower            float64 `json:"battery_top_hold_power"`             // kW trickle charge permitted while the top-of-charge block is engaged; 0 forces a hard idle
+
 	// Price adjustments
 	ImportPriceOperatorFee float64 `json:"import_price_operator_fee"` // EUR/MWh - Operator fee for import
 	ImportPriceDeliveryFee float64 `json:"import_price_delivery_fee"` // EUR/MWh - Delivery fee for import
@@ -151,6 +169,8 @@ func DefaultConfig() *Config {
 		BatteryBalancingSOCThreshold:     0.998,   // CV phase starts at 99.8%
 		BatteryBalancingEfficiencyFactor: 0.1,     // ~10× more input energy needed in CV phase
 		BatteryBalancingBonus:            1.1,     // $1.1 one-time optimisation bonus for reaching BatteryMaxSOC
+		BatteryBalancingSOCReleaseBand:   0.01,    // resume charging only once SOC drops 1% below the threshold (98.8% by default)
+		BatteryTopHoldPower:              0.2,     // 0.2 kW (200 W) trickle to cover inverter auxiliary draw while holding at the top
 	}
 }
 
@@ -413,6 +433,23 @@ func (c *Config) Validate() error {
 		return fmt.Errorf("battery_balancing_bonus must be non-negative, got: %f", c.BatteryBalancingBonus)
 	}
 
+	if c.BatteryBalancingSOCReleaseBand < 0 || c.BatteryBalancingSOCReleaseBand > 1 {
+		return fmt.Errorf("battery_balancing_soc_release_band must be between 0 and 1, got: %f", c.BatteryBalancingSOCReleaseBand)
+	}
+
+	if c.BatteryBalancingSOCThreshold != 0 && c.BatteryBalancingSOCReleaseBand >= c.BatteryBalancingSOCThreshold {
+		return fmt.Errorf("battery_balancing_soc_release_band (%f) must be smaller than battery_balancing_soc_threshold (%f), otherwise charging would never resume",
+			c.BatteryBalancingSOCReleaseBand, c.BatteryBalancingSOCThreshold)
+	}
+
+	if c.BatteryTopHoldPower < 0 {
+		return fmt.Errorf("battery_top_hold_power must be non-negative, got: %f", c.BatteryTopHoldPower)
+	}
+
+	if c.BatteryTopHoldPower > c.BatteryMaxCharge {
+		return fmt.Errorf("battery_top_hold_power (%f) must not exceed battery_max_charge (%f)", c.BatteryTopHoldPower, c.BatteryMaxCharge)
+	}
+
 	// Validate that MaxGridImport can handle battery charging with preheating
 	// When charging at maximum rate with battery preheating active, total grid import will be:
 	// BatteryMaxCharge/Efficiency + BatteryPreHeatPower (plus any load)

scheduler/mpc.go

@@ -668,6 +668,49 @@ type batteryAction struct {
 	setCharge      bool
 	setDischarge   bool
 	logMsg         string
+
+	// topBlocked reports the state of the top-of-charge latch after this
+	// decision.  The caller must persist it and feed it back in via
+	// topSOCGuard.blocked on the next call so the hysteresis works.
+	topBlocked bool
+}
+
+// topSOCGuard configures the top-of-charge hold that keeps the battery out of
+// its low-efficiency CV/balancing phase outside the weekly balancing window.
+//
+// It is a Schmitt trigger on SOC:
+//
+//	engage  when SOC >= threshold
+//	release when SOC <  threshold - releaseBand
+//
+// Without the releaseBand the guard chatters: blocking charge lets the
+// inverter's auxiliary load drain the pack a few tenths of a percent, SOC drops
+// back under the threshold, charging is re-enabled, PV refills it in a single
+// slot, and the guard engages again — a ~30-45 minute limit cycle that keeps
+// the pack pinned at the very top while micro-cycling it.
+//
+// holdPower is the trickle (kW) still permitted while engaged.  A hard 0 forces
+// the inverter to serve its own auxiliary consumption from the battery, which
+// is what produces the downward drift; allowing a small charge lets that draw
+// come from PV or the grid instead so SOC simply holds.
+type topSOCGuard struct {
+	threshold   float64 // SOC (0-1) at/above which charging is blocked; 0 disables the guard
+	releaseBand float64 // SOC hysteresis band below threshold; 0 means release as soon as SOC < threshold
+	holdPower   float64 // kW trickle permitted while blocked
+	blocked     bool    // latch state carried over from the previous execution
+}
+
+// engaged applies the Schmitt trigger to the given SOC and reports whether
+// charging should be blocked.
+func (g topSOCGuard) engaged(soc float64) bool {
+	if g.threshold <= 0 {
+		return false
+	}
+	if g.blocked {
+		// Stay blocked until SOC falls clear of the hysteresis band.
+		return soc >= g.threshold-g.releaseBand
+	}
+	return soc >= g.threshold
 }
 
 // decideBatteryAction translates an MPC control decision into a concrete battery
@@ -679,11 +722,11 @@ type batteryAction struct {
 // PV-only self-use mode instead.  Pass 0 to disable the gate (e.g. in tests
 // that are not exercising the cloud-recovery logic).
 //
-// balancingSOCThreshold is the SOC (0-1) at/above which the battery enters its
-// low-efficiency CV/balancing phase (config.BatteryBalancingSOCThreshold).
-// Pass 0 to disable the related guard in the default case below (e.g. in
-// tests, or when the feature is disabled in config).
-func decideBatteryAction(decision *mpc.ControlDecision, maxCharge float64, recentAvgPV float64, balancingSOCThreshold float64) batteryAction {
+// guard configures the top-of-charge hold applied in the default case below.
+// Pass the zero value to disable it (e.g. in tests, or when the feature is
+// disabled in config).
+func decideBatteryAction(decision *mpc.ControlDecision, maxCharge float64, recentAvgPV float64, guard topSOCGuard) batteryAction {
+
 	switch {
 	case decision.BatteryChargeFromGrid > 0.01:
 		totalPlannedCharge := decision.BatteryChargeFromPV + decision.BatteryChargeFromGrid
@@ -771,13 +814,24 @@ func decideBatteryAction(decision *mpc.ControlDecision, maxCharge float64, recen
 		// headroom up to BatteryMaxSOC. Doing so would push the battery into
 		// its low-efficiency CV/balancing phase every time PV surplus is
 		// available, rather than only once a week as intended.
+		//
+		// The guard is a Schmitt trigger (see topSOCGuard): it engages at the
+		// threshold and only releases once SOC has fallen clear of the
+		// hysteresis band, and it leaves a small trickle enabled so the
+		// inverter's auxiliary draw does not slowly empty the pack. Together
+		// these stop the battery micro-cycling around the threshold.
 		chargeLimit := maxCharge
 		logMsg := fmt.Sprintf("Setting battery to SELF-CONSUMPTION mode (no active charge/discharge planned, absorbing any actual PV excess up to %.1f kW): GridImport: %.1f kW, GridExport: %.1f kW",
 			maxCharge, decision.GridImport, decision.GridExport)
-		if balancingSOCThreshold > 0 && !decision.BalancingNeeded && decision.BatterySOC >= balancingSOCThreshold {
-			chargeLimit = 0
-			logMsg = fmt.Sprintf("Setting battery to SELF-CONSUMPTION mode (SOC %.1f%% already at/above balancing threshold %.1f%% and balancing not currently needed — capping charge at 0 to avoid unnecessary CV/balancing): GridImport: %.1f kW, GridExport: %.1f kW",
-				decision.BatterySOC*100, balancingSOCThreshold*100, decision.GridImport, decision.GridExport)
+
+		topBlocked := false
+		if !decision.BalancingNeeded {
+			topBlocked = guard.engaged(decision.BatterySOC)
+		}
+		if topBlocked {
+			chargeLimit = math.Min(guard.holdPower, maxCharge)
+			logMsg = fmt.Sprintf("Setting battery to SELF-CONSUMPTION mode (SOC %.1f%% within top-of-charge hold: engage >= %.1f%%, release < %.1f%%, balancing not currently needed — charge capped at %.2f kW to hold SOC without entering the CV/balancing phase): GridImport: %.1f kW, GridExport: %.1f kW",
+				decision.BatterySOC*100, guard.threshold*100, (guard.threshold-guard.releaseBand)*100, chargeLimit, decision.GridImport, decision.GridExport)
 		}
 		return batteryAction{
 			mode:           2,
@@ -786,6 +840,7 @@ func decideBatteryAction(decision *mpc.ControlDecision, maxCharge float64, recen
 			setCharge:      true,
 			setDischarge:   true,
 			logMsg:         logMsg,
+			topBlocked:     topBlocked,
 		}
 	}
 }
@@ -827,9 +882,24 @@ func (s *MinerScheduler) executeMPCDecision(ctx context.Context, decision *mpc.C
 	const pvGateWindow = 5 * time.Minute
 	recentAvgPV := s.dataSamples.AveragePVPowerLast(pvGateWindow)
 
-	action := decideBatteryAction(decision, config.BatteryMaxCharge, recentAvgPV, config.BatteryBalancingSOCThreshold)
+	s.mu.RLock()
+	topBlocked := s.topChargeBlocked
+	s.mu.RUnlock()
+
+	guard := topSOCGuard{
+		threshold:   config.BatteryBalancingSOCThreshold,
+		releaseBand: config.BatteryBalancingSOCReleaseBand,
+		holdPower:   config.BatteryTopHoldPower,
+		blocked:     topBlocked,
+	}
+
+	action := decideBatteryAction(decision, config.BatteryMaxCharge, recentAvgPV, guard)
 	s.logger.Print(action.logMsg)
 
+	s.mu.Lock()
+	s.topChargeBlocked = action.topBlocked
+	s.mu.Unlock()
+
 	// Enforce hardware-level grid export limit based on the current export price.
 	// When the export price is negative (or zero), set the inverter's grid-point
 	// export limit to 0 so no power can reach the grid regardless of ESS mode or