Update to use the microgrid API v0.18 (#1283)

This PR migrates the SDK from the old `frequenz-client-microgrid` using
the old microgrid API v0.15 to the new using the API v0.18. The main
changes involve updating component models, metrics, and data fetching
mechanisms to use the new client library structure.

Author: llucax

RELEASE_NOTES.md

@@ -6,7 +6,25 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+- The SDK now depends on the `frequenz-client-microgrid` v0.18.x series.
+
+    * Check the release notes for the client [v0.18].
+    * There were a lot of changes, so it might be also worth having a quick look at the microgrid API [v0.17][api-v0.17] and [v0.18][api-v0.17] releases.
+    * Checking out the API common releases [v0.6][common-v0.6], [v0.7][common-v0.7], [v0.8][common-v0.8] might also be worthwhile, at least if you find any errors about renamed or missing types.
+    * Although many of the changes in lower layer are hidden by the SDK, there are some changes that can't be hidden away. For example the `Metric` enum had some renames, and `Component.component_id` was renamed to `Component.id`. Also, there is a new component class hierarchy.
+
+- `ComponentGraph` methods arguments were renamed to better reflect what they expect.
+
+    * The `components()` method now uses `matching_ids` and `matching_types` instead of `component_ids` and `component_categories` respectively. `matching_types` takes types inheriting from `Component` instead of categories, for example `Battery` or `BatteryInverter`.
+    * The `connections()` methods now take `matching_sources` and `matching_destinations` instead of `start` and `end` respectively. This is to match the new names in `ComponentConnection`.
+    * All arguments for both methods can now receiver arbitrary iterables instead of `set`s, and can also accept a single value.
+
+[v0.18]: https://github.com/frequenz-floss/frequenz-client-microgrid-python/releases/tag/v0.18.0
+[api-v0.17]: https://github.com/frequenz-floss/frequenz-api-microgrid/releases/tag/v0.17.0
+[api-v0.18]: https://github.com/frequenz-floss/frequenz-api-microgrid/releases/tag/v0.18.0
+[common-v0.6]: https://github.com/frequenz-floss/frequenz-api-common/releases/tag/v0.6.0
+[common-v0.7]: https://github.com/frequenz-floss/frequenz-api-common/releases/tag/v0.7.0
+[common-v0.8]: https://github.com/frequenz-floss/frequenz-api-common/releases/tag/v0.8.0
 
 ## New Features
 

benchmarks/power_distribution/power_distributor.py

@@ -13,7 +13,7 @@
 
 from frequenz.channels import Broadcast
 from frequenz.client.common.microgrid.components import ComponentId
-from frequenz.client.microgrid import Component, ComponentCategory
+from frequenz.client.microgrid.component import Battery
 from frequenz.quantities import Power
 
 from frequenz.sdk import microgrid
@@ -116,8 +116,7 @@ async def run_test(  # pylint: disable=too-many-locals
     battery_status_channel = Broadcast[ComponentPoolStatus](name="battery-status")
     power_result_channel = Broadcast[Result](name="power-result")
     async with PowerDistributingActor(
-        component_category=ComponentCategory.BATTERY,
-        component_type=None,
+        component_type=Battery,
         requests_receiver=power_request_channel.new_receiver(),
         results_sender=power_result_channel.new_sender(),
         component_pool_status_sender=battery_status_channel.new_sender(),
@@ -143,10 +142,10 @@ async def run() -> None:
         ResamplerConfig2(resampling_period=timedelta(seconds=1.0)),
     )
 
-    all_batteries: set[Component] = connection_manager.get().component_graph.components(
-        component_categories={ComponentCategory.BATTERY}
+    all_batteries = connection_manager.get().component_graph.components(
+        matching_types=Battery
     )
-    batteries_ids = {c.component_id for c in all_batteries}
+    batteries_ids = {c.id for c in all_batteries}
     # Take some time to get data from components
     await asyncio.sleep(4)
     with open("/dev/stdout", "w", encoding="utf-8") as csvfile:

benchmarks/timeseries/benchmark_datasourcing.py

@@ -17,7 +17,7 @@
 from typing import Any
 
 from frequenz.channels import Broadcast, Receiver, ReceiverStoppedError
-from frequenz.client.microgrid import ComponentMetricId
+from frequenz.client.microgrid.metrics import Metric
 
 from frequenz.sdk import microgrid
 from frequenz.sdk._internal._channels import ChannelRegistry
@@ -37,9 +37,9 @@
     sys.exit(1)
 
 COMPONENT_METRIC_IDS = [
-    ComponentMetricId.CURRENT_PHASE_1,
-    ComponentMetricId.CURRENT_PHASE_2,
-    ComponentMetricId.CURRENT_PHASE_3,
+    Metric.AC_CURRENT_PHASE_1,
+    Metric.AC_CURRENT_PHASE_2,
+    Metric.AC_CURRENT_PHASE_3,
 ]
 
 

mkdocs.yml

@@ -119,7 +119,7 @@ plugins:
             - https://docs.python.org/3/objects.inv
             - https://frequenz-floss.github.io/frequenz-channels-python/v1/objects.inv
             - https://frequenz-floss.github.io/frequenz-client-common-python/v0.3/objects.inv
-            - https://frequenz-floss.github.io/frequenz-client-microgrid-python/v0.9/objects.inv
+            - https://frequenz-floss.github.io/frequenz-client-microgrid-python/v0.18/objects.inv
             - https://frequenz-floss.github.io/frequenz-core-python/v1/objects.inv
             - https://frequenz-floss.github.io/frequenz-quantities-python/v1/objects.inv
             - https://lovasoa.github.io/marshmallow_dataclass/html/objects.inv

pyproject.toml

@@ -29,8 +29,8 @@ dependencies = [
   # Make sure to update the mkdocs.yml file when
   # changing the version
   # (plugins.mkdocstrings.handlers.python.import)
-  "frequenz-client-microgrid >= 0.9.0, < 0.10.0",
-  "frequenz-client-common >= 0.3.2, < 0.4.0",
+  "frequenz-client-microgrid >= 0.18.0, < 0.19.0",
+  "frequenz-client-common >= 0.3.6, < 0.4.0",
   "frequenz-channels >= 1.6.1, < 2.0.0",
   "frequenz-quantities[marshmallow] >= 1.0.0, < 2.0.0",
   "networkx >= 2.8, < 4",

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -18,7 +18,7 @@
 
 from frequenz.channels import Broadcast, Sender
 from frequenz.client.common.microgrid.components import ComponentId
-from frequenz.client.microgrid import ComponentCategory, InverterType
+from frequenz.client.microgrid.component import Battery, EvCharger, SolarInverter
 
 from frequenz.sdk.microgrid._power_managing._base_classes import Algorithm, DefaultPower
 
@@ -105,23 +105,25 @@ def __init__(
             self._channel_registry,
             api_power_request_timeout=api_power_request_timeout,
             power_manager_algorithm=Algorithm.SHIFTING_MATRYOSHKA,
-            component_category=ComponentCategory.BATTERY,
             default_power=DefaultPower.ZERO,
+            component_class=Battery,
         )
         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,
+            component_class=EvCharger,
         )
         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,
+            # Using SolarInverter might be too specific, maybe we need to also pass
+            # HybridInverter, see
+            # https://github.com/frequenz-floss/frequenz-sdk-python/issues/1285
+            component_class=SolarInverter,
         )
 
         self._logical_meter: LogicalMeter | None = None

src/frequenz/sdk/microgrid/_data_sourcing/__init__.py

@@ -3,11 +3,13 @@
 
 """The DataSourcingActor."""
 
-from ._component_metric_request import ComponentMetricId, ComponentMetricRequest
+from frequenz.client.microgrid.metrics import Metric
+
+from ._component_metric_request import ComponentMetricRequest
 from .data_sourcing import DataSourcingActor
 
 __all__ = [
-    "ComponentMetricId",
+    "Metric",
     "ComponentMetricRequest",
     "DataSourcingActor",
 ]

src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py

@@ -7,9 +7,11 @@
 from datetime import datetime
 
 from frequenz.client.common.microgrid.components import ComponentId
-from frequenz.client.microgrid import ComponentMetricId
+from frequenz.client.microgrid.metrics import Metric
 
-__all__ = ["ComponentMetricRequest", "ComponentMetricId"]
+from frequenz.sdk.microgrid._old_component_data import TransitionalMetric
+
+__all__ = ["ComponentMetricRequest", "Metric"]
 
 
 @dataclass
@@ -25,7 +27,7 @@ class ComponentMetricRequest:
     metric. For example, requesters can use different `namespace` values to subscribe to
     raw or resampled data streams separately. This ensures that each requester receives
     the appropriate type of data without interference. Requests with the same
-    `namespace`, `component_id`, and `metric_id` will use the same channel, preventing
+    `namespace`, `component_id`, and `metric` will use the same channel, preventing
     unnecessary duplication of data streams.
 
     The requester and provider must use the same channel name so that they can
@@ -40,7 +42,7 @@ class ComponentMetricRequest:
     component_id: ComponentId
     """The ID of the requested component."""
 
-    metric_id: ComponentMetricId
+    metric: Metric | TransitionalMetric
     """The ID of the requested component's metric."""
 
     start_time: datetime | None
@@ -60,7 +62,7 @@ def get_channel_name(self) -> str:
             "component_metric_request<"
             f"namespace={self.namespace},"
             f"component_id={self.component_id},"
-            f"metric_id={self.metric_id.name}"
+            f"metric={self.metric.name}"
             f"{start}"
             ">"
         )