feat(telemetry): CP-090 driving battery stress per trip and month

Hard discharge at low charge or in the cold, and cold regeneration,
measured per trip with the power sign oriented by the trip's own
falling charge; unknown stays null.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: malys

CHANGELOG.md

@@ -48,6 +48,13 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- **What a drive asked of the pack at the moments it minds most (CP-090).** `DrivingStress.of`
+  measures, per trip, the minutes of hard discharge (above 60 % of the trip's own peak) below
+  20 % charge or below 0 °C outside, and the energy regenerated below 0 °C. The pack power sign
+  is unvalidated (RI-002), so each trip orients itself from its falling charge; a trip that
+  cannot, or with more than a tenth of its time undecidable, gives null rather than zero.
+  `DrivingStress.monthly` sums the trips that could say, per local month. Measured quantities,
+  never a wear figure.
 - **How long the rest of a charge takes (CP-089).** `ChargeDuration.estimate` sums, band by
   10-point band, the minutes per point the driver's own watched charges took: the median, and the
   fastest and slowest charge as the range. Charges at a similar outside temperature (±8 °C) are

lib/src/main/java/com/evsuite/hardware/telemetry/DrivingStress.kt

@@ -0,0 +1,108 @@
+package com.evsuite.hardware.telemetry
+
+import java.time.Instant
+import java.time.YearMonth
+import java.time.ZoneId
+
+/**
+ * What a drive asked of the pack at the moments a pack minds most (CP-090): hard discharge at a
+ * low charge or in the cold, and regeneration pushed into a cold pack.
+ *
+ * Measured quantities only, never a wear figure. "Hard" is the trip's own: discharge above
+ * [HARD_SHARE] of that trip's peak, so a gentle driver's hardest moments count as well as a
+ * heavy one's.
+ *
+ * [TripSample.batteryPowerKw]'s sign is unvalidated on this car (RI-002), so each trip orients
+ * itself: the charge fell, so the way the power integral moved over the trip is discharge. A trip
+ * whose charge did not fall, or whose integral did not move, cannot say which way is which and
+ * gives no figure.
+ */
+data class DrivingStress(
+    /** Minutes of hard discharge below [LOW_SOC_PERCENT] charge or below [COLD_CELSIUS] outside. */
+    val stressedMinutes: Double,
+    /** Energy regenerated below [COLD_CELSIUS] outside; null when the temperature was never read. */
+    val coldRegeneratedKwh: Double?,
+) {
+    companion object {
+
+        /**
+         * Null when the trip cannot say: no orientation, or more than [MAX_UNDECIDED_SHARE] of
+         * its time with an unread power, or a hard moment with an unread charge or temperature.
+         */
+        fun of(samples: List<TripSample>): DrivingStress? {
+            val socs = samples.mapNotNull { it.socPercent }
+            if (socs.size < 2 || socs.first() - socs.last() < MIN_SOC_DROP) return null
+            val segments = samples.zipWithNext().filter { (a, b) -> b.atMs - a.atMs in 1..MAX_GAP_MS }
+            val net = segments.sumOf { (a, b) -> (a.batteryPowerKw ?: 0f) * hours(a, b) }
+            val orientation = when {
+                net >= MIN_NET_KWH -> 1.0
+                net <= -MIN_NET_KWH -> -1.0
+                else -> return null
+            }
+            val peak = samples.mapNotNull { it.batteryPowerKw }.maxOfOrNull { it * orientation } ?: return null
+            if (peak <= 0.0) return null
+
+            var totalMs = 0L
+            var undecidedMs = 0L
+            var stressedMs = 0L
+            var coldKnown = false
+            var coldRegen = 0.0
+            segments.forEach { (a, b) ->
+                val ms = b.atMs - a.atMs
+                totalMs += ms
+                // An unread power could have been a hard one.
+                val power = a.batteryPowerKw ?: run { undecidedMs += ms; return@forEach }
+                val discharge = power * orientation
+                val cold = a.outsideTempCelsius?.let { it < COLD_CELSIUS }
+                val low = a.socPercent?.let { it < LOW_SOC_PERCENT }
+                if (cold != null) coldKnown = true
+                if (cold == true && discharge < 0.0) coldRegen += -discharge * hours(a, b)
+                if (discharge <= HARD_SHARE * peak) return@forEach
+                when {
+                    cold == true || low == true -> stressedMs += ms
+                    cold == null || low == null -> undecidedMs += ms
+                }
+            }
+            if (totalMs == 0L || undecidedMs > MAX_UNDECIDED_SHARE * totalMs) return null
+            return DrivingStress(stressedMs / MINUTE_MS, coldRegen.takeIf { coldKnown })
+        }
+
+        /** Per local month, over the trips that could say; a month none could say is absent. */
+        fun monthly(trips: List<StoredTrip>, zone: ZoneId): List<MonthlyDrivingStress> = trips
+            .mapNotNull { trip -> of(trip.samples.orEmpty())?.let { trip.summary.startedAtMs to it } }
+            .groupBy { (atMs, _) -> YearMonth.from(Instant.ofEpochMilli(atMs).atZone(zone)) }
+            .map { (month, list) ->
+                val regen = list.mapNotNull { it.second.coldRegeneratedKwh }
+                MonthlyDrivingStress(
+                    month = month,
+                    stressedMinutes = list.sumOf { it.second.stressedMinutes },
+                    coldRegeneratedKwh = regen.takeIf { it.isNotEmpty() }?.sum(),
+                    trips = list.size,
+                )
+            }
+            .sortedBy { it.month }
+
+        private fun hours(a: TripSample, b: TripSample) = (b.atMs - a.atMs) / HOUR_MS
+
+        const val HARD_SHARE = 0.6
+        const val LOW_SOC_PERCENT = 20f
+        const val COLD_CELSIUS = 0f
+        /** A trip that spent less than a point cannot orient its power. */
+        const val MIN_SOC_DROP = 1f
+        const val MIN_NET_KWH = 0.1
+        /** A longer hole in the track is a pause, not a stretch of known power. */
+        const val MAX_GAP_MS = 5 * 60_000L
+        /** A dropped reading here and there is not a blind trip; more than this is. */
+        const val MAX_UNDECIDED_SHARE = 0.1
+        private const val MINUTE_MS = 60_000.0
+        private const val HOUR_MS = 3_600_000.0
+    }
+}
+
+data class MonthlyDrivingStress(
+    val month: YearMonth,
+    val stressedMinutes: Double,
+    val coldRegeneratedKwh: Double?,
+    /** Trips that could say; the others are not counted as zero. */
+    val trips: Int,
+)

lib/src/test/java/com/evsuite/hardware/telemetry/DrivingStressTest.kt

@@ -0,0 +1,72 @@
+package com.evsuite.hardware.telemetry
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class DrivingStressTest {
+
+    /**
+     * Ten minutes at one sample every ten seconds, the charge falling two points. Minutes 0, 3
+     * and 6 pull 60 kW, minute 9 regenerates 10 kW, the rest cruise at 20 kW.
+     */
+    private fun track(
+        soc: Float?,
+        outside: Float?,
+        sign: Float = 1f,
+        power: (Int) -> Float? = { i ->
+            when (i / 6) {
+                0, 3, 6 -> 60f
+                9 -> -10f
+                else -> 20f
+            }
+        },
+    ) = (0 until 60).map { i ->
+        TripSample(
+            atMs = i * 10_000L,
+            speedKmh = 50f,
+            batteryPowerKw = power(i)?.times(sign),
+            socPercent = soc?.minus(i / 30f),
+            outsideTempCelsius = outside,
+            cabinTempCelsius = null,
+            batteryTempCelsius = null,
+            climatePowerOn = null,
+            climateAcOn = null,
+            climateFanLevel = null,
+        )
+    }
+
+    @Test
+    fun `hard power in the cold is counted, and cold regeneration summed`() {
+        val stress = DrivingStress.of(track(soc = 60f, outside = -5f))!!
+        assertEquals(3.0, stress.stressedMinutes, 1e-9)
+        assertEquals(50 * 10.0 / 3600.0, stress.coldRegeneratedKwh!!, 1e-9)
+    }
+
+    @Test
+    fun `the trip orients its own power sign`() {
+        assertEquals(DrivingStress.of(track(soc = 60f, outside = -5f)), DrivingStress.of(track(60f, -5f, sign = -1f)))
+    }
+
+    @Test
+    fun `a warm drive at a good charge is a measured zero`() {
+        assertEquals(DrivingStress(0.0, 0.0), DrivingStress.of(track(soc = 60f, outside = 15f)))
+    }
+
+    @Test
+    fun `low charge alone is enough, and an unread temperature leaves the regeneration unknown`() {
+        val stress = DrivingStress.of(track(soc = 19f, outside = null))!!
+        assertEquals(3.0, stress.stressedMinutes, 1e-9)
+        assertNull(stress.coldRegeneratedKwh)
+    }
+
+    @Test
+    fun `unknown is never zero`() {
+        // Hard moments at a good charge with no temperature: they cannot be decided.
+        assertNull(DrivingStress.of(track(soc = 60f, outside = null)))
+        assertNull(DrivingStress.of(track(soc = 60f, outside = -5f) { null }))
+        assertNull(DrivingStress.of(track(soc = null, outside = -5f)))
+        // A third of the power unread.
+        assertNull(DrivingStress.of(track(soc = 60f, outside = -5f) { i -> if (i % 3 == 0) null else 20f }))
+    }
+}