Update battery pool SoC calculation (#557)

Fix the SoC calculation such that it never exceeds 100%.

Author: matthias-wende-frequenz

RELEASE_NOTES.md

@@ -28,5 +28,6 @@
 
 - Fix formatting issue for `Quantity` objects with zero values.
 - Fix formatting isuse for `Quantity` when the base value is float.inf or float.nan.
+- Fix clamping to 100% for the battery pool SoC scaling calculation.
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->

src/frequenz/sdk/timeseries/battery_pool/_metric_calculator.py

@@ -424,7 +424,8 @@ def calculate(
             soc_scaled = (
                 (soc - soc_lower_bound) / (soc_upper_bound - soc_lower_bound) * 100
             )
-            soc_scaled = max(soc_scaled, 0)
+            # we are clamping here because the SoC might be out of bounds
+            soc_scaled = min(max(soc_scaled, 0), 100)
             timestamp = max(timestamp, metrics.timestamp)
             used_capacity_x100 += usable_capacity_x100 * soc_scaled
             total_capacity_x100 += usable_capacity_x100

src/frequenz/sdk/timeseries/battery_pool/battery_pool.py

@@ -347,16 +347,17 @@ def consumption_power(self) -> FormulaEngine[Power]:
     def soc(self) -> MetricAggregator[Sample[Percentage]]:
         """Fetch the normalized average weighted-by-capacity SoC values for the pool.
 
-        The values are normalized to the 0-100% range.
+        The values are normalized to the 0-100% range and clamped if the SoC is out of
+        bounds.
 
         Average soc is calculated with the formula:
         ```
         working_batteries: Set[BatteryData] # working batteries from the battery pool
 
-        soc_scaled = max(
+        soc_scaled = min(max(
             0,
             (soc - soc_lower_bound) / (soc_upper_bound - soc_lower_bound) * 100,
-        )
+        ), 100)
         used_capacity = sum(
             battery.usable_capacity * battery.soc_scaled
             for battery in working_batteries