# Capacity Measurement Operation

Măsurarea şi calculul capacităţii unei baterii din sesiunile de încărcare.

## Responsabilități

- Determinarea capacităţii reale a unei baterii (mAh)

- Validarea completitudinii datelor (0% → 100%)

- Calculul din energie + voltaje nominal

- Tracking capacity degradation (baterie veche)

## Concepte

### Capacity vs Energy

- **Capacity (mAh)**: Cantitate de sarcină. Ex: 3000 mAh

- **Energy (Wh)**: Capacitate × voltaj nominal. Ex: 3000mAh × 3.7V = 11.1Wh

Formula:

```

Capacity (mAh) = Energy (Wh) × 1000 / Nominal Voltage (V)

```

Exemplu:

```

Energy = 11.1 Wh

Nominal voltage = 3.7V (typical Li-ion)

Capacity = 11.1 × 1000 / 3.7 = 3000 mAh

```

## Invarianţi

- **MUST**: Capacity > 0 mAh (nu poate fi 0 sau negativ)

- **MUST**: Capacity ≤ 10000 mAh pentru device-uri obişnuite

- **MUST**: Sesiune validă pentru capacity learning trebuie: battery 0% → 100%

- **MUST**: Nominal voltage trebuie specificat (nu se calculează)

- **MUST**: Capacity learning doar din **complete discharge cycles**

- **SHOULD**: Capacity măsurat ≥ 80% din rated capacity (bateria e "OK")

- **MAY**: Capacity < 80% = aged battery, notify user

## Types of sessions

### Full discharge (valid pentru learning)

```

Battery: 100% → ... → 0%

Device: ON throughout

Meter: record-ează energie totală

⟹ Capacity = Energy / Nominal_Voltage

```

**Invarianţi:**

- **MUST**: Start @ ~100%, end @ ~0%

- **MUST**: Fără interruption (meter disconnect = invalid)

- **MUST**: Device rămâne ON (nu suspend mid-session)

### Partial charge

```

Battery: 20% → 50%

Device: OFF (charging)

⟹ Cannot infer capacity (unknown starting level)

```

**MUST**: Ignore pentru capacity learning

### Trickle charge (edge case)

```

Battery: 95% → 100%

Current: <50mA (charging optimizer active)

Duration: >2 hours

⟹ Energy negligible, skip

```

## Algorithm

### Capacity learning from discharge

```swift

func learnCapacityFromDischarge(session: ChargeRecord) -> Double? {

    // 1. Validate session

    guard isCompleteDischargeSession(session) else { return nil }

    // 2. Extract energy

    let energyWh = session.totalEnergy

    // 3. Get nominal voltage

    let nominalVoltageV = device.nominalBatteryVoltage // 3.7, 5.0, etc

    // 4. Calculate capacity

    let capacityMah = energyWh * 1000 / nominalVoltageV

    // 5. Validate result

    guard capacityMah > 0 && capacityMah <= 10000 else {

        logWarning("Capacity outside bounds: \(capacityMah) mAh")

        return nil

    }

    return capacityMah

}

func isCompleteDischargeSession(_ session: ChargeRecord) -> Bool {

    // Check battery levels

    guard let startBattery = session.startBatteryPercent,

          let endBattery = session.endBatteryPercent else {

        return false

    }

    // Range must span ~100%

    let range = startBattery - endBattery

    guard range >= 90 else {

        logWarning("Incomplete discharge: \(range)% only")

        return false

    }

    // Device must be ON during discharge

    guard session.isCompletelyRecorded else {

        logWarning("Session incomplete (meter disconnect)")

        return false

    }

    return true

}

```

### Weighted moving average

Pentru stabilitate, combinaţi multiple measurements:

```swift

func estimateCapacity(from sessions: [ChargeRecord]) -> Double? {

    let validSessions = sessions.compactMap { session in

        learnCapacityFromDischarge(session)

    }

    guard !validSessions.isEmpty else { return nil }

    // Weight by recency: newer sessions count more

    let weights = validSessions.indices.map { i in

        Double(i + 1) / Double(validSessions.count)

    }

    let weightedSum = zip(validSessions, weights)

        .map { capacity, weight in capacity * weight }

        .reduce(0, +)

    let capacityMah = weightedSum / weights.reduce(0, +)

    return capacityMah

}

```

## API Public

### Proprietăţi

| Proprietate | Tip | Descriere |

|---|---|---|

| `nominalBatteryVoltage` | Double | V (ex: 3.7) |

| `measuredCapacity` | Double? | mAh din learning |

| `ratedCapacity` | Double? | mAh din device spec |

| `capacity_Health` | Double | measured / rated (%) |

| `lastCapacityMeasurement` | Date? | When learned |

### Metode

```swift

// Learning

func learnCapacity(from session: ChargeRecord) -> Double?

func learnCapacity(from sessions: [ChargeRecord]) -> Double?

// Validation

func isValidCapacityMeasurement(_ mah: Double) -> Bool

func isCompleteDischargeSession(_ session: ChargeRecord) -> Bool

func estimateSessionCompleteness(_ session: ChargeRecord) -> Double

// Health

func batteryHealth() -> Double // measured / rated

func isAgedBattery() -> Bool // health < 80%

```

## Comportamente critice

### Incompletă sesiune → skip learning

```

Device: 30% → 15%

Meter: record-ează 5 Wh

⟹ Skip (partial discharge, nu putem infera capacity)

Device: 100% → 5% (but meter lost signal @ 20%)

⟹ Skip (incomplete recording)

```

**MUST**: Validate completeness înainte de learning

### Multiple discharge cycles

```

Session 1: 100% → 0%, measured 12 Wh → 3200 mAh

Session 2: 100% → 0%, measured 11.5 Wh → 3100 mAh

Session 3: 100% → 0%, measured 11.2 Wh → 3000 mAh

⟹ Average: 3100 mAh (weighted toward recent)

```

**SHOULD**: Combinaţi sesiuni (moving average)

**MUST**: Keep history pentru trend analysis

### Battery aging

```

Device created: 2024-01-01, rated 3000 mAh

Measured capacities:

  - 2024-01-15: 2950 mAh (98% health)

  - 2024-06-15: 2700 mAh (90% health)

  - 2025-01-15: 2400 mAh (80% health) ← aged

⟹ Notify user: "Battery health below 80%"

```

**SHOULD**: Track degradation curve

**SHOULD**: Notify @ 80% health

**MAY**: Suggest battery replacement @ 70%

## Testare

### Unit tests

```swift

test_learnCapacity_ValidDischargeSession()

test_learnCapacity_PartialDischarge_Ignored()

test_learnCapacity_IncompleteRecording_Ignored()

test_isCompleteDischargeSession_ValidRange()

test_isCompleteDischargeSession_MinRange()

test_estimateCapacity_MultiplesSessions()

test_estimateCapacity_WeightedByRecency()

test_capacityMustBePositive()

test_capacityMustBeBounded()

test_batteryHealth_Calculation()

test_isAgedBattery_Threshold()

```

### Integration tests

- [ ] Single complete discharge 100%→0%: capacity measured

- [ ] Partial discharge: capacity NOT measured

- [ ] Multiple sessions: weighted average

- [ ] Aged battery detected @ 80%

- [ ] Capacity persistent în Core Data

- [ ] Battery health calculated correctly

## Edge cases

### Rapid discharge (high power draw)

```

Battery: 100% → 0% in 30 minutes

Power draw: 50W constant

Energy: large, measured accurately

⟹ Normal discharge, capacity = energy / voltage

```

**SHOULD**: Accept și use pentru learning

### Trickle charge (low power)

```

Battery: 95% → 100%

Charging current: 10mA (very low)

Duration: 4 hours

Energy: negligible (~0.2Wh)

⟹ Skip (too little data)

```

**MUST**: Ignore (capacity = energy/voltage → false low)

### Voltage variance

```

Nominal voltage: 3.7V

But actual range: 3.2V (low) → 4.2V (full)

Energy measured: 11Wh

Capacity calculation: depends on which voltage used

```

**SHOULD**: Use nominal (convention)

**SHOULD**: Log warning dacă voltage deviates

## Dependencies

- [Charging Monitoring](./ChargingMonitoring.md): session data

- [Charge Curve Storage](./ChargeCurveStorage.md): historical curves

- Core Data: `ChargeSession.startBatteryPercent`, `endBatteryPercent`

## References

- [Powerbank Category](../Powerbank%20Category.md) — battery reporting modes

- Scientific: https://en.wikipedia.org/wiki/Battery_capacity