Reset components to default power when all proposals are withdrawn

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

Author: shsms

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -19,7 +19,7 @@
 from frequenz.channels import Broadcast, Sender
 from frequenz.client.microgrid import ComponentCategory, InverterType
 
-from frequenz.sdk.microgrid._power_managing._base_classes import Algorithm
+from frequenz.sdk.microgrid._power_managing._base_classes import Algorithm, DefaultPower
 
 from .._internal._channels import ChannelRegistry
 from ..actor._actor import Actor
@@ -107,19 +107,22 @@ def __init__(
             api_power_request_timeout=api_power_request_timeout,
             power_manager_algorithm=Algorithm.SHIFTING_MATRYOSHKA,
             component_category=ComponentCategory.BATTERY,
+            default_power=DefaultPower.ZERO,
         )
         self._ev_power_wrapper = PowerWrapper(
             self._channel_registry,
             api_power_request_timeout=api_power_request_timeout,
             power_manager_algorithm=Algorithm.MATRYOSHKA,
             component_category=ComponentCategory.EV_CHARGER,
+            default_power=DefaultPower.MAX,
         )
         self._pv_power_wrapper = PowerWrapper(
             self._channel_registry,
             api_power_request_timeout=api_power_request_timeout,
             power_manager_algorithm=Algorithm.MATRYOSHKA,
             component_category=ComponentCategory.INVERTER,
             component_type=InverterType.SOLAR,
+            default_power=DefaultPower.MIN,
         )
 
         self._logical_meter: LogicalMeter | None = None

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

@@ -199,6 +199,19 @@ def __hash__(self) -> int:
         return hash((self.priority, self.source_id))
 
 
+class DefaultPower(enum.Enum):
+    """The default power for a component category."""
+
+    ZERO = "zero"
+    """The default power is 0 W."""
+
+    MIN = "min"
+    """The default power is the minimum power of the component."""
+
+    MAX = "max"
+    """The default power is the maximum power of the component."""
+
+
 class Algorithm(enum.Enum):
     """The available algorithms for the power manager."""
 

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

@@ -28,7 +28,7 @@
 
 from ... import timeseries
 from . import _bounds
-from ._base_classes import BaseAlgorithm, Proposal, _Report
+from ._base_classes import BaseAlgorithm, DefaultPower, Proposal, _Report
 
 if typing.TYPE_CHECKING:
     from ...timeseries._base_types import SystemBounds
@@ -39,9 +39,12 @@
 class Matryoshka(BaseAlgorithm):
     """The matryoshka algorithm."""
 
-    def __init__(self, max_proposal_age: timedelta) -> None:
+    def __init__(
+        self, max_proposal_age: timedelta, default_power: DefaultPower
+    ) -> None:
         """Create a new instance of the matryoshka algorithm."""
         self._max_proposal_age_sec = max_proposal_age.total_seconds()
+        self._default_power = default_power
         self._component_buckets: dict[frozenset[int], set[Proposal]] = {}
         self._target_power: dict[frozenset[int], Power] = {}
 
@@ -190,18 +193,33 @@ def calculate_target_power(
                 bucket.add(proposal)
             elif not bucket:
                 del self._component_buckets[component_ids]
-                _ = self._target_power.pop(component_ids, None)
 
         # If there has not been any proposal for the given components, don't calculate a
         # target power and just return `None`.
         proposals = self._component_buckets.get(component_ids)
-        if proposals is None:
-            return None
 
-        target_power = self._calc_target_power(proposals, system_bounds)
+        target_power = None
+        if proposals is not None:
+            target_power = self._calc_target_power(proposals, system_bounds)
 
         if target_power is not None:
             self._target_power[component_ids] = target_power
+        elif self._target_power.get(component_ids) is not None:
+            # If the target power was previously set, but is now `None`, then we send
+            # the default power of the component category, to reset it immediately.
+            del self._target_power[component_ids]
+            bounds = system_bounds.inclusion_bounds
+            if bounds is None:
+                return None
+            match self._default_power:
+                case DefaultPower.MIN:
+                    return bounds.lower
+                case DefaultPower.MAX:
+                    return bounds.upper
+                case DefaultPower.ZERO:
+                    return Power.zero()
+                case other:
+                    typing.assert_never(other)
 
         return target_power
 

src/frequenz/sdk/microgrid/_power_managing/_power_managing_actor.py

@@ -21,7 +21,14 @@
 from ...actor import Actor
 from ...timeseries._base_types import SystemBounds
 from .. import _data_pipeline, _power_distributing
-from ._base_classes import Algorithm, BaseAlgorithm, Proposal, ReportRequest, _Report
+from ._base_classes import (
+    Algorithm,
+    BaseAlgorithm,
+    DefaultPower,
+    Proposal,
+    ReportRequest,
+    _Report,
+)
 from ._matryoshka import Matryoshka
 from ._shifting_matryoshka import ShiftingMatryoshka
 
@@ -40,6 +47,7 @@ def __init__(  # pylint: disable=too-many-arguments
         power_distributing_results_receiver: Receiver[_power_distributing.Result],
         channel_registry: ChannelRegistry,
         algorithm: Algorithm,
+        default_power: DefaultPower,
         component_category: ComponentCategory,
         component_type: ComponentType | None = None,
     ):
@@ -54,6 +62,7 @@ def __init__(  # pylint: disable=too-many-arguments
                 results.
             channel_registry: The channel registry.
             algorithm: The power management algorithm to use.
+            default_power: The default power to use for the components.
             component_category: The category of the component this power manager
                 instance is going to support.
             component_type: The type of the component of the given category that this
@@ -66,6 +75,7 @@ def __init__(  # pylint: disable=too-many-arguments
         """
         self._component_category = component_category
         self._component_type = component_type
+        self._default_power = default_power
         self._bounds_subscription_receiver = bounds_subscription_receiver
         self._power_distributing_requests_sender = power_distributing_requests_sender
         self._power_distributing_results_receiver = power_distributing_results_receiver
@@ -79,11 +89,13 @@ def __init__(  # pylint: disable=too-many-arguments
         match algorithm:
             case Algorithm.MATRYOSHKA:
                 self._algorithm: BaseAlgorithm = Matryoshka(
-                    max_proposal_age=timedelta(seconds=60.0)
+                    max_proposal_age=timedelta(seconds=60.0),
+                    default_power=default_power,
                 )
             case Algorithm.SHIFTING_MATRYOSHKA:
                 self._algorithm = ShiftingMatryoshka(
-                    max_proposal_age=timedelta(seconds=60.0)
+                    max_proposal_age=timedelta(seconds=60.0),
+                    default_power=default_power,
                 )
             case _:
                 assert_never(algorithm)

src/frequenz/sdk/microgrid/_power_managing/_shifting_matryoshka.py

@@ -16,7 +16,7 @@
 
 from ... import timeseries
 from . import _bounds
-from ._base_classes import BaseAlgorithm, Proposal, _Report
+from ._base_classes import BaseAlgorithm, DefaultPower, Proposal, _Report
 
 if typing.TYPE_CHECKING:
     from ...timeseries._base_types import SystemBounds
@@ -55,8 +55,13 @@ class ShiftingMatryoshka(BaseAlgorithm):
     Details about the algorithm can be found in the [microgrid module documentation](https://frequenz-floss.github.io/frequenz-sdk-python/v1.0-dev/user-guide/microgrid-concepts/#frequenz.sdk.microgrid--setting-power).
     """  # noqa: E501 (line too long)
 
-    def __init__(self, max_proposal_age: timedelta) -> None:
+    def __init__(
+        self,
+        max_proposal_age: timedelta,
+        default_power: DefaultPower,
+    ) -> None:
         """Create a new instance of the matryoshka algorithm."""
+        self._default_power = default_power
         self._max_proposal_age_sec = max_proposal_age.total_seconds()
         self._component_buckets: dict[frozenset[int], set[Proposal]] = {}
         self._target_power: dict[frozenset[int], Power] = {}
@@ -250,12 +255,28 @@ def calculate_target_power(
                 bucket.add(proposal)
             elif not bucket:
                 del self._component_buckets[component_ids]
-                _ = self._target_power.pop(component_ids, None)
 
         target_power, _ = self._calc_targets(component_ids, system_bounds)
 
         if target_power is not None:
             self._target_power[component_ids] = target_power
+        elif self._target_power.get(component_ids) is not None:
+            # If the target power was previously set, but is now `None`, then we send
+            # the default power of the component category, to reset it immediately.
+            del self._target_power[component_ids]
+            bounds = system_bounds.inclusion_bounds
+            if bounds is None:
+                return None
+            match self._default_power:
+                case DefaultPower.MIN:
+                    return bounds.lower
+                case DefaultPower.MAX:
+                    return bounds.upper
+                case DefaultPower.ZERO:
+                    return Power.zero()
+                case other:
+                    typing.assert_never(other)
+
         return target_power
 
     @override

src/frequenz/sdk/microgrid/_power_wrapper.py

@@ -23,12 +23,12 @@
     Request,
     Result,
 )
-from ._power_managing._base_classes import Algorithm
+from ._power_managing._base_classes import Algorithm, DefaultPower
 
 _logger = logging.getLogger(__name__)
 
 
-class PowerWrapper:
+class PowerWrapper:  # pylint: disable=too-many-instance-attributes
     """Wrapper around the power managing and power distributing actors."""
 
     def __init__(  # pylint: disable=too-many-arguments
@@ -37,6 +37,7 @@ def __init__(  # pylint: disable=too-many-arguments
         *,
         api_power_request_timeout: timedelta,
         power_manager_algorithm: Algorithm,
+        default_power: DefaultPower,
         component_category: ComponentCategory,
         component_type: ComponentType | None = None,
     ):
@@ -47,6 +48,7 @@ def __init__(  # pylint: disable=too-many-arguments
             api_power_request_timeout: Timeout to use when making power requests to
                 the microgrid API.
             power_manager_algorithm: The power management algorithm to use.
+            default_power: The default power to use for the components.
             component_category: The category of the components that actors started by
                 this instance of the PowerWrapper will be responsible for.
             component_type: The type of the component of the given category that this
@@ -57,6 +59,7 @@ def __init__(  # pylint: disable=too-many-arguments
                 `None` when the component category is enough to uniquely identify the
                 component.
         """
+        self._default_power = default_power
         self._component_category = component_category
         self._component_type = component_type
         self._power_manager_algorithm = power_manager_algorithm
@@ -103,6 +106,7 @@ def _start_power_managing_actor(self) -> None:
             return
 
         self._power_managing_actor = _power_managing.PowerManagingActor(
+            default_power=self._default_power,
             component_category=self._component_category,
             component_type=self._component_type,
             algorithm=self._power_manager_algorithm,

tests/actor/_power_managing/test_matryoshka.py

@@ -12,6 +12,7 @@
 
 from frequenz.sdk import timeseries
 from frequenz.sdk.microgrid._power_managing import Proposal
+from frequenz.sdk.microgrid._power_managing._base_classes import DefaultPower
 from frequenz.sdk.microgrid._power_managing._matryoshka import Matryoshka
 from frequenz.sdk.timeseries import _base_types
 
@@ -28,7 +29,9 @@ def __init__(
         self._call_count = 0
         self._batteries = batteries
         self._system_bounds = system_bounds
-        self.algorithm = Matryoshka(max_proposal_age=timedelta(seconds=60.0))
+        self.algorithm = Matryoshka(
+            max_proposal_age=timedelta(seconds=60.0), default_power=DefaultPower.ZERO
+        )
 
     def tgt_power(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         self,
@@ -510,7 +513,7 @@ def ensure_overlapping_bucket_request_fails() -> None:
     ensure_overlapping_bucket_request_fails()
     tester.tgt_power(priority=3, power=None, bounds=(None, None), expected=25.0)
     ensure_overlapping_bucket_request_fails()
-    tester.tgt_power(priority=2, power=None, bounds=(None, None), expected=None)
+    tester.tgt_power(priority=2, power=None, bounds=(None, None), expected=0.0)
 
     # Overlapping battery bucket is dropped.
     tester.tgt_power(

tests/actor/_power_managing/test_shifting_matryoshka.py

@@ -14,6 +14,7 @@
 
 from frequenz.sdk import timeseries
 from frequenz.sdk.microgrid._power_managing import Proposal
+from frequenz.sdk.microgrid._power_managing._base_classes import DefaultPower
 from frequenz.sdk.microgrid._power_managing._shifting_matryoshka import (
     ShiftingMatryoshka,
 )
@@ -32,7 +33,9 @@ def __init__(
         self._call_count = 0
         self._batteries = batteries
         self._system_bounds = system_bounds
-        self.algorithm = ShiftingMatryoshka(max_proposal_age=timedelta(seconds=60.0))
+        self.algorithm = ShiftingMatryoshka(
+            max_proposal_age=timedelta(seconds=60.0), default_power=DefaultPower.ZERO
+        )
 
     def tgt_power(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         self,
@@ -543,7 +546,7 @@ def ensure_overlapping_bucket_request_fails() -> None:
     ensure_overlapping_bucket_request_fails()
     tester.tgt_power(priority=3, power=None, bounds=(None, None), expected=25.0)
     ensure_overlapping_bucket_request_fails()
-    tester.tgt_power(priority=2, power=None, bounds=(None, None), expected=None)
+    tester.tgt_power(priority=2, power=None, bounds=(None, None), expected=0.0)
 
     # Overlapping battery bucket is dropped.
     tester.tgt_power(

tests/timeseries/_battery_pool/test_battery_pool_control_methods.py

@@ -527,3 +527,26 @@ async def test_case_4(self, mocks: Mocks, mocker: MockerFixture) -> None:
                 result, _power_distributing.Success
             ),
         )
+
+        # Resetting the power should lead to default (zero) power getting set for all
+        # the batteries.
+        set_power.reset_mock()
+        await battery_pool.propose_power(None)
+        self._assert_report(
+            await bounds_rx.receive(), power=None, lower=-4000.0, upper=4000.0
+        )
+        await asyncio.sleep(0.0)
+        assert set_power.call_count == 4
+        assert sorted(set_power.call_args_list) == [
+            mocker.call(inv_id, 0.0) for inv_id in mocks.microgrid.battery_inverter_ids
+        ]
+        self._assert_report(
+            await bounds_rx.receive(),
+            power=None,
+            lower=-4000.0,
+            upper=4000.0,
+            dist_result=latest_dist_result.get(),
+            expected_result_pred=lambda result: isinstance(
+                result, _power_distributing.Success
+            ),
+        )

tests/timeseries/_pv_pool/test_pv_pool_control_methods.py

@@ -279,3 +279,23 @@ async def test_setting_power(  # pylint: disable=too-many-statements
             mocker.call(inv_ids[2], 0.0),
             mocker.call(inv_ids[3], 0.0),
         ]
+
+        # Resetting the power should lead to default (full) power getting set for all
+        # inverters.
+        set_power.reset_mock()
+        await pv_pool.propose_power(None)
+        report = await self._recv_reports_until(
+            bounds_rx,
+            lambda x: x.target_power is None,
+        )
+        self._assert_report(report, power=None, lower=-100000.0, upper=0.0)
+        await asyncio.sleep(0.0)
+
+        assert set_power.call_count == 4
+        inv_ids = mocks.microgrid.pv_inverter_ids
+        assert sorted(set_power.call_args_list, key=lambda x: x.args[0]) == [
+            mocker.call(inv_ids[0], -10_000.0),
+            mocker.call(inv_ids[1], -20_000.0),
+            mocker.call(inv_ids[2], -30_000.0),
+            mocker.call(inv_ids[3], -40_000.0),
+        ]