Update high-level public interfaces to concrete types (#607)

Fixes #188

Author: daniel-zullo-frequenz

RELEASE_NOTES.md

@@ -82,6 +82,14 @@ This release replaces the `@actor` decorator with a new `Actor` class.
 
 - The base actors (`ConfigManagingActor`, `ComponentMetricsResamplingActor`, `DataSourcingActor`, `PowerDistributingActor`) now inherit from the new `Actor` class, if you are using them directly, you need to start them manually with `await actor.start()` and you might need to do some other adjustments.
 
+- The `BatteryPool.power_distribution_results` method has been enhanced to provide power distribution results in the form of `Power` objects, replacing the previous use of `float` values.
+
+- In the `Request` class:
+  * The attribute `request_timeout_sec` has been updated and is now named `request_timeout` and it is represented by a `timedelta` object rather than a `float`.
+  * The attribute `power` is now presented as a `Power` object, as opposed to a `float`.
+
+- Within the `EVChargerPool.set_bounds` method, the parameter `max_amps` has been redefined as `max_current`, and it is now represented using a `Current` object instead of a `float`.
+
 ## New Features
 
 - Added `DFS` to the component graph

src/frequenz/sdk/actor/power_distributing/power_distributing.py

@@ -26,6 +26,8 @@
 import grpc
 from frequenz.channels import Peekable, Receiver, Sender
 
+from frequenz.sdk.timeseries._quantities import Power
+
 from ..._internal._math import is_close_to_zero
 from ...actor import ChannelRegistry
 from ...actor._actor import Actor
@@ -96,7 +98,7 @@ class PowerDistributingActor(Actor):
 
     It is recommended to wait for PowerDistributingActor output with timeout. Otherwise if
     the processing function fails then the response will never come.
-    The timeout should be Result:request_timeout_sec + time for processing the request.
+    The timeout should be Result:request_timeout + time for processing the request.
 
     Edge cases:
     * If there are 2 requests to be processed for the same subset of batteries, then
@@ -271,7 +273,9 @@ async def _run(self) -> None:
                 )
                 continue
 
-            distributed_power_value = request.power - distribution.remaining_power
+            distributed_power_value = (
+                request.power.as_watts() - distribution.remaining_power
+            )
             battery_distribution = {
                 self._inv_bat_map[bat_id]: dist
                 for bat_id, dist in distribution.distribution.items()
@@ -283,27 +287,27 @@ async def _run(self) -> None:
             )
 
             failed_power, failed_batteries = await self._set_distributed_power(
-                api, distribution, request.request_timeout_sec
+                api, distribution, request.request_timeout
             )
 
             response: Success | PartialFailure
             if len(failed_batteries) > 0:
                 succeed_batteries = set(battery_distribution.keys()) - failed_batteries
                 response = PartialFailure(
                     request=request,
-                    succeeded_power=distributed_power_value,
+                    succeeded_power=Power.from_watts(distributed_power_value),
                     succeeded_batteries=succeed_batteries,
-                    failed_power=failed_power,
+                    failed_power=Power.from_watts(failed_power),
                     failed_batteries=failed_batteries,
-                    excess_power=distribution.remaining_power,
+                    excess_power=Power.from_watts(distribution.remaining_power),
                 )
             else:
                 succeed_batteries = set(battery_distribution.keys())
                 response = Success(
                     request=request,
-                    succeeded_power=distributed_power_value,
+                    succeeded_power=Power.from_watts(distributed_power_value),
                     succeeded_batteries=succeed_batteries,
-                    excess_power=distribution.remaining_power,
+                    excess_power=Power.from_watts(distribution.remaining_power),
                 )
 
             asyncio.gather(
@@ -319,14 +323,14 @@ async def _set_distributed_power(
         self,
         api: MicrogridApiClient,
         distribution: DistributionResult,
-        timeout_sec: float,
+        timeout: timedelta,
     ) -> Tuple[float, Set[int]]:
         """Send distributed power to the inverters.
 
         Args:
             api: Microgrid api client
             distribution: Distribution result
-            timeout_sec: How long wait for the response
+            timeout: How long wait for the response
 
         Returns:
             Tuple where first element is total failed power, and the second element
@@ -339,13 +343,13 @@ async def _set_distributed_power(
 
         _, pending = await asyncio.wait(
             tasks.values(),
-            timeout=timeout_sec,
+            timeout=timeout.total_seconds(),
             return_when=ALL_COMPLETED,
         )
 
         await self._cancel_tasks(pending)
 
-        return self._parse_result(tasks, distribution.distribution, timeout_sec)
+        return self._parse_result(tasks, distribution.distribution, timeout)
 
     def _get_power_distribution(
         self, request: Request, inv_bat_pairs: List[InvBatPair]
@@ -367,11 +371,11 @@ def _get_power_distribution(
 
         if request.include_broken_batteries and not available_bat_ids:
             return self.distribution_algorithm.distribute_power_equally(
-                request.power, unavailable_inv_ids
+                request.power.as_watts(), unavailable_inv_ids
             )
 
         result = self.distribution_algorithm.distribute_power(
-            request.power, inv_bat_pairs
+            request.power.as_watts(), inv_bat_pairs
         )
 
         if request.include_broken_batteries and unavailable_inv_ids:
@@ -412,9 +416,11 @@ def _check_request(
 
         bounds = self._get_bounds(pairs_data)
 
+        power = request.power.as_watts()
+
         # Zero power requests are always forwarded to the microgrid API, even if they
         # are outside the exclusion bounds.
-        if is_close_to_zero(request.power):
+        if is_close_to_zero(power):
             return None
 
         if request.adjust_power:
@@ -423,15 +429,11 @@ def _check_request(
             #
             # If the requested power is in the exclusion bounds, it is NOT possible to
             # increase it so that it is outside the exclusion bounds.
-            if bounds.exclusion_lower < request.power < bounds.exclusion_upper:
+            if bounds.exclusion_lower < power < bounds.exclusion_upper:
                 return OutOfBounds(request=request, bounds=bounds)
         else:
-            in_lower_range = (
-                bounds.inclusion_lower <= request.power <= bounds.exclusion_lower
-            )
-            in_upper_range = (
-                bounds.exclusion_upper <= request.power <= bounds.inclusion_upper
-            )
+            in_lower_range = bounds.inclusion_lower <= power <= bounds.exclusion_lower
+            in_upper_range = bounds.exclusion_upper <= power <= bounds.inclusion_upper
             if not (in_lower_range or in_upper_range):
                 return OutOfBounds(request=request, bounds=bounds)
 
@@ -630,7 +632,7 @@ def _parse_result(
         self,
         tasks: Dict[int, asyncio.Task[None]],
         distribution: Dict[int, float],
-        request_timeout_sec: float,
+        request_timeout: timedelta,
     ) -> Tuple[float, Set[int]]:
         """Parse the results of `set_power` requests.
 
@@ -642,7 +644,7 @@ def _parse_result(
                 set the power for this inverter. Each task should be finished or cancelled.
             distribution: A dictionary where the key is the inverter ID and the value is how much
                 power was set to the corresponding inverter.
-            request_timeout_sec: The timeout that was used for the request.
+            request_timeout: The timeout that was used for the request.
 
         Returns:
             A tuple where the first element is the total failed power, and the second element is
@@ -676,7 +678,7 @@ def _parse_result(
                 _logger.warning(
                     "Battery %d didn't respond in %f sec. Mark it as broken.",
                     battery_id,
-                    request_timeout_sec,
+                    request_timeout.total_seconds(),
                 )
 
         return failed_power, failed_batteries

src/frequenz/sdk/actor/power_distributing/request.py

@@ -6,6 +6,9 @@
 
 import dataclasses
 from collections import abc
+from datetime import timedelta
+
+from ...timeseries._quantities import Power
 
 
 @dataclasses.dataclass
@@ -19,13 +22,13 @@ class Request:
     channel registry.
     """
 
-    power: float
-    """The requested power in watts."""
+    power: Power
+    """The requested power."""
 
     batteries: abc.Set[int]
     """The component ids of the batteries to be used for this request."""
 
-    request_timeout_sec: float = 5.0
+    request_timeout: timedelta = timedelta(seconds=5.0)
     """The maximum amount of time to wait for the request to be fulfilled."""
 
     adjust_power: bool = True

src/frequenz/sdk/actor/power_distributing/result.py

@@ -7,6 +7,8 @@
 
 import dataclasses
 
+from frequenz.sdk.timeseries._quantities import Power
+
 from .request import Request
 
 
@@ -34,13 +36,13 @@ class Result(_BaseResultMixin):
 class _BaseSuccessMixin:
     """Result returned when setting the power succeed for all batteries."""
 
-    succeeded_power: float
+    succeeded_power: Power
     """The part of the requested power that was successfully set."""
 
     succeeded_batteries: set[int]
     """The subset of batteries for which power was set successfully."""
 
-    excess_power: float
+    excess_power: Power
     """The part of the requested power that could not be fulfilled.
 
     This happens when the requested power is outside the available power bounds.
@@ -62,7 +64,7 @@ class Success(_BaseSuccessMixin, Result):  # Order matters here. See above.
 class PartialFailure(_BaseSuccessMixin, Result):
     """Result returned when any battery failed to perform the request."""
 
-    failed_power: float
+    failed_power: Power
     """The part of the requested power that failed to be set."""
 
     failed_batteries: set[int]

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

@@ -143,10 +143,10 @@ async def set_power(
         await self._power_distributing_sender.send(
             Request(
                 namespace=self._power_distributing_namespace,
-                power=power.as_watts(),
+                power=power,
                 batteries=self._batteries,
                 adjust_power=adjust_power,
-                request_timeout_sec=request_timeout.total_seconds(),
+                request_timeout=request_timeout,
                 include_broken_batteries=include_broken_batteries,
             )
         )
@@ -184,16 +184,15 @@ async def charge(
         Raises:
             ValueError: If the given power is negative.
         """
-        as_watts = power.as_watts()
-        if as_watts < 0.0:
+        if power < Power.zero():
             raise ValueError("Charge power must be positive.")
         await self._power_distributing_sender.send(
             Request(
                 namespace=self._power_distributing_namespace,
-                power=as_watts,
+                power=power,
                 batteries=self._batteries,
                 adjust_power=adjust_power,
-                request_timeout_sec=request_timeout.total_seconds(),
+                request_timeout=request_timeout,
                 include_broken_batteries=include_broken_batteries,
             )
         )
@@ -231,16 +230,15 @@ async def discharge(
         Raises:
             ValueError: If the given power is negative.
         """
-        as_watts = power.as_watts()
-        if as_watts < 0.0:
+        if power < Power.zero():
             raise ValueError("Discharge power must be positive.")
         await self._power_distributing_sender.send(
             Request(
                 namespace=self._power_distributing_namespace,
-                power=-as_watts,
+                power=-power,
                 batteries=self._batteries,
                 adjust_power=adjust_power,
-                request_timeout_sec=request_timeout.total_seconds(),
+                request_timeout=request_timeout,
                 include_broken_batteries=include_broken_batteries,
             )
         )

src/frequenz/sdk/timeseries/ev_charger_pool/_ev_charger_pool.py

@@ -240,19 +240,19 @@ def component_data(self, component_id: int) -> Receiver[EVChargerData]:
 
         return output_chan.new_receiver()
 
-    async def set_bounds(self, component_id: int, max_amps: float) -> None:
+    async def set_bounds(self, component_id: int, max_current: Current) -> None:
         """Send given max current bound for the given EV Charger to the microgrid API.
 
         Bounds are used to limit the max current drawn by an EV, although the exact
         value will be determined by the EV.
 
         Args:
             component_id: ID of EV Charger to set the current bounds to.
-            max_amps: maximum current in amps, that an EV can draw from this EV Charger.
+            max_current: maximum current that an EV can draw from this EV Charger.
         """
         if not self._bounds_setter:
             self._bounds_setter = BoundsSetter(self._repeat_interval)
-        await self._bounds_setter.set(component_id, max_amps)
+        await self._bounds_setter.set(component_id, max_current.as_amperes())
 
     def new_bounds_sender(self) -> Sender[ComponentCurrentLimit]:
         """Return a `Sender` for setting EV Charger current bounds with.