Accept Bounds object in set_power, instead of separate values

This allows users to specify `None` when they want to set bounds only
in one side, for example, if they only want a minimum charger power of
10kW, and don't care about the maximum.

This commit also makes the `Bounds` type generic without restrictions,
so that it can be specialized for more complex types like
`Bounds[Power | None]`.

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

src/frequenz/sdk/actor/_power_managing/_base_classes.py

@@ -79,7 +79,7 @@ class Proposal:
 
     source_id: str
     preferred_power: Power | None
-    bounds: tuple[Power, Power] | None
+    bounds: timeseries.Bounds[Power | None]
     battery_ids: frozenset[int]
     priority: int
     request_timeout: datetime.timedelta = datetime.timedelta(seconds=5.0)

src/frequenz/sdk/actor/_power_managing/_matryoshka.py

@@ -69,9 +69,11 @@ def _calc_target_power(
                     target_power = lower_bound
                 else:
                     target_power = next_proposal.preferred_power
-            if next_proposal.bounds:
-                lower_bound = max(lower_bound, next_proposal.bounds[0])
-                upper_bound = min(upper_bound, next_proposal.bounds[1])
+            low, high = next_proposal.bounds.lower, next_proposal.bounds.upper
+            if low is not None:
+                lower_bound = max(lower_bound, low)
+            if high is not None:
+                upper_bound = min(upper_bound, high)
 
         return target_power
 
@@ -176,15 +178,18 @@ def get_status(
         for next_proposal in reversed(self._battery_buckets.get(battery_ids, [])):
             if next_proposal.priority <= priority:
                 break
-            if next_proposal.bounds:
-                calc_lower_bound = max(lower_bound, next_proposal.bounds[0])
-                calc_upper_bound = min(upper_bound, next_proposal.bounds[1])
-                if calc_lower_bound <= calc_upper_bound:
-                    lower_bound = calc_lower_bound
-                    upper_bound = calc_upper_bound
-                else:
-                    break
-
+            low, high = next_proposal.bounds.lower, next_proposal.bounds.upper
+            calc_lower_bound = lower_bound
+            calc_upper_bound = upper_bound
+            if low is not None:
+                calc_lower_bound = max(calc_lower_bound, low)
+            if high is not None:
+                calc_upper_bound = min(calc_upper_bound, high)
+            if calc_lower_bound <= calc_upper_bound:
+                lower_bound = calc_lower_bound
+                upper_bound = calc_upper_bound
+            else:
+                break
         return Report(
             target_power,
             inclusion_bounds=timeseries.Bounds[Power](

src/frequenz/sdk/timeseries/_base_types.py

@@ -4,6 +4,7 @@
 """Timeseries basic types."""
 
 import functools
+import typing
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -137,12 +138,15 @@ def map(
         )
 
 
+_T = typing.TypeVar("_T")
+
+
 @dataclass(frozen=True)
-class Bounds(Generic[QuantityT]):
+class Bounds(Generic[_T]):
     """Lower and upper bound values."""
 
-    lower: QuantityT
+    lower: _T
     """Lower bound."""
 
-    upper: QuantityT
+    upper: _T
     """Upper bound."""

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

@@ -13,6 +13,7 @@
 from collections import abc
 from datetime import timedelta
 
+from ... import timeseries
 from ..._internal._channels import ReceiverFetcher
 from ...actor import _power_managing
 from ...timeseries import Energy, Percentage, Power, Sample, Temperature
@@ -62,7 +63,7 @@ async def set_power(
         *,
         request_timeout: timedelta = timedelta(seconds=5.0),
         include_broken_batteries: bool = False,
-        _bounds: tuple[Power, Power] | None = None,
+        _bounds: timeseries.Bounds[Power | None] = timeseries.Bounds(None, None),
     ) -> None:
         """Set the given power for the batteries in the pool.
 
@@ -136,7 +137,7 @@ async def charge(
             _power_managing.Proposal(
                 source_id=self._source_id,
                 preferred_power=power,
-                bounds=None,
+                bounds=timeseries.Bounds(None, None),
                 battery_ids=self._battery_pool._batteries,
                 priority=0,
                 request_timeout=request_timeout,
@@ -179,7 +180,7 @@ async def discharge(
             _power_managing.Proposal(
                 source_id=self._source_id,
                 preferred_power=power,
-                bounds=None,
+                bounds=timeseries.Bounds(None, None),
                 battery_ids=self._battery_pool._batteries,
                 priority=0,
                 request_timeout=request_timeout,

tests/actor/_power_managing/test_matryoshka.py

@@ -29,7 +29,7 @@ async def test_matryoshka_algorithm() -> None:  # pylint: disable=too-many-state
     def test_tgt_power(
         priority: int,
         power: float | None,
-        bounds: tuple[float, float] | None,
+        bounds: tuple[float | None, float | None],
         expected: float | None,
     ) -> None:
         nonlocal call_count
@@ -40,9 +40,10 @@ def test_tgt_power(
                 battery_ids=batteries,
                 source_id=f"actor-{priority}",
                 preferred_power=None if power is None else Power.from_watts(power),
-                bounds=(Power.from_watts(bounds[0]), Power.from_watts(bounds[1]))
-                if bounds
-                else None,
+                bounds=timeseries.Bounds(
+                    None if bounds[0] is None else Power.from_watts(bounds[0]),
+                    None if bounds[1] is None else Power.from_watts(bounds[1]),
+                ),
                 priority=priority,
             ),
             system_bounds,
@@ -91,18 +92,18 @@ def test_bounds(
     test_bounds(priority=2, expected_power=30.0, expected_bounds=(10.0, 50.0))
     test_bounds(priority=1, expected_power=30.0, expected_bounds=(25.0, 50.0))
 
-    test_tgt_power(priority=2, power=40.0, bounds=(40.0, 50.0), expected=40.0)
+    test_tgt_power(priority=2, power=40.0, bounds=(40.0, None), expected=40.0)
     test_bounds(priority=3, expected_power=40.0, expected_bounds=(-200.0, 200.0))
     test_bounds(priority=2, expected_power=40.0, expected_bounds=(10.0, 50.0))
     test_bounds(priority=1, expected_power=40.0, expected_bounds=(40.0, 50.0))
 
-    test_tgt_power(priority=2, power=0.0, bounds=(-200.0, 200.0), expected=30.0)
+    test_tgt_power(priority=2, power=0.0, bounds=(None, None), expected=30.0)
     test_bounds(priority=4, expected_power=30.0, expected_bounds=(-200.0, 200.0))
     test_bounds(priority=3, expected_power=30.0, expected_bounds=(-200.0, 200.0))
     test_bounds(priority=2, expected_power=30.0, expected_bounds=(10.0, 50.0))
     test_bounds(priority=1, expected_power=30.0, expected_bounds=(10.0, 50.0))
 
-    test_tgt_power(priority=4, power=-50.0, bounds=(-200.0, -50.0), expected=-50.0)
+    test_tgt_power(priority=4, power=-50.0, bounds=(None, -50.0), expected=-50.0)
     test_bounds(priority=4, expected_power=-50.0, expected_bounds=(-200.0, 200.0))
     test_bounds(priority=3, expected_power=-50.0, expected_bounds=(-200.0, -50.0))
     test_bounds(priority=2, expected_power=-50.0, expected_bounds=(-200.0, -50.0))
@@ -118,7 +119,7 @@ def test_bounds(
     test_tgt_power(priority=4, power=-180.0, bounds=(-200.0, -50.0), expected=None)
     test_bounds(priority=1, expected_power=-150.0, expected_bounds=(-200.0, -50.0))
 
-    test_tgt_power(priority=4, power=50.0, bounds=(50.0, 200.0), expected=50.0)
+    test_tgt_power(priority=4, power=50.0, bounds=(50.0, None), expected=50.0)
     test_bounds(priority=4, expected_power=50.0, expected_bounds=(-200.0, 200.0))
     test_bounds(priority=3, expected_power=50.0, expected_bounds=(50.0, 200.0))
     test_bounds(priority=2, expected_power=50.0, expected_bounds=(50.0, 200.0))

tests/timeseries/_battery_pool/test_battery_pool_control_methods.py

@@ -13,7 +13,7 @@
 from frequenz.channels import Sender
 from pytest_mock import MockerFixture
 
-from frequenz.sdk import microgrid
+from frequenz.sdk import microgrid, timeseries
 from frequenz.sdk.actor import ResamplerConfig, _power_managing, power_distributing
 from frequenz.sdk.actor.power_distributing import BatteryStatus
 from frequenz.sdk.actor.power_distributing._battery_pool_status import BatteryPoolStatus
@@ -337,7 +337,7 @@ async def test_case_3(self, mocks: Mocks, mocker: MockerFixture) -> None:
         )
         await battery_pool_1.set_power(
             Power.from_watts(-1000.0),
-            _bounds=(Power.from_watts(-1000.0), Power.from_watts(0.0)),
+            _bounds=timeseries.Bounds(Power.from_watts(-1000.0), Power.from_watts(0.0)),
         )
         self._assert_report(
             await bounds_1_rx.receive(), power=-1000.0, lower=-4000.0, upper=4000.0
@@ -355,7 +355,7 @@ async def test_case_3(self, mocks: Mocks, mocker: MockerFixture) -> None:
 
         await battery_pool_2.set_power(
             Power.from_watts(0.0),
-            _bounds=(Power.from_watts(0.0), Power.from_watts(1000.0)),
+            _bounds=timeseries.Bounds(Power.from_watts(0.0), Power.from_watts(1000.0)),
         )
         self._assert_report(
             await bounds_1_rx.receive(), power=0.0, lower=-4000.0, upper=4000.0