Merge branch 'v1.x.x' into generic-power-manager

The RELEASE_NOTES.md file has diverged and needs to be synced from the
main branch, before it can be updated without conflicts.

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

Author: shsms

RELEASE_NOTES.md

@@ -2,83 +2,16 @@
 
 ## Summary
 
-This version ships an experimental version of the **Power Manager**, adds preliminary support for n:m relations between inverters and batteries and includes user documentation.
+<!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-- `microgrid.battery_pool()` method now accepts a priority value.
-
-- `microgrid.grid()`
-
-  * Similar to `microgrid.battery_pool()`, the Grid is now similarily accessed.
-
-- `BatteryPool`'s control methods
-
-  * Original methods `{set_power/charge/discharge}` are now replaced by `propose_{power/charge/discharge}`
-  * The `propose_*` methods send power proposals to the `PowerManagingActor`, where it can be overridden by proposals from other actors.
-  * They no longer have the `adjust_power` flag, because the `PowerManagingActor` will always adjust power to fit within the available bounds.
-  * They no longer have a `include_broken_batteries` parameter.  The feature has been removed.
-
-- `BatteryPool`'s reporting methods
-
-  * `power_bounds` is replaced by `power_status`
-  * The `power_status` method streams objects containing:
-    + bounds adjusted to the actor's priorities
-    + the latest target power for the set of batteries
-    + the results from the power distributor for the last request
-
-- Move `microgrid.ComponentGraph` class to `microgrid.component_graph.ComponentGraph`, exposing only the high level interface functions through the `microgrid` package.
-
-- An actor that is crashing will no longer instantly restart but induce an artificial delay to avoid potential spam-restarting.
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 
-- New and improved documentation.
-
-  * A new *User Guide* section was added, with:
-
-    + A glossary.
-    + An introduction to actors.
-
-  * A new *Tutorials* section was added, with:
-
-    + A getting started tutorial.
-
-- In `OrderedRingBuffer`:
-  - Rename `datetime_to_index` to `to_internal_index` to avoid confusion between the internal index and the external index.
-  - Add `index_to_datetime` method to convert external index to corresponding datetime.
-  - Remove `__setitem__` method to enforce usage of dedicated `update` method only.
-- In `OrderedRingBuffer` and `MovingWindow`:
-  - Support for integer indices is added.
-  - Add `count_covered` method to count the number of elements covered by the used time range.
-  - Add `fill_value` option to window method to impute missing values. By default missing values are imputed with `NaN`.
-- Add `at` method to `MovingWindow` to access a single element and use it in `__getitem__` magic to fully support single element access.
-
-- The PowerDistributingActor now supports n:m relations between inverters and batteries.
-
-  This means that one or more inverters can be connected to one or more batteries.
-
-- A `PowerManagingActor` implementation.
-
-- Allow configuration of the `resend_latest` flag in channels owned by the `ChannelRegistry`.
-
-- Add consumption and production operators that will replace the logical meters production and consumption function variants.
-
-- Consumption and production power formulas have been removed.
-
-- The documentation was improved to:
-
-  * Show signatures with types.
-  * Show the inherited members.
-  * Documentation for pre-releases are now published.
-  * Show the full tag name as the documentation version.
-  * All development branches now have their documentation published (there is no `next` version anymore).
-  * Fix the order of the documentation versions.
+<!-- Here goes the main new features and examples or instructions on how to use them -->
 
 ## Bug Fixes
 
-- Fix rendering of diagrams in the documentation.
-- The `__getitem__` magic of the `MovingWindow` is fixed to support the same functionality that the `window` method provides.
-- Fixes incorrect implementation of single element access in `__getitem__` magic of `MovingWindow`.
-- Fix incorrect grid current calculations in locations where the calculations depended on current measurements from an inverter.
-- Fix power failure report to exclude any failed power from the succeeded power.
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

pyproject.toml

@@ -38,6 +38,7 @@ dependencies = [
   "numpy >= 1.24.2, < 2",
   "protobuf >= 4.21.6, < 5",
   "pydantic >= 2.3, < 3",
+  "timezonefinder >= 6.2.0, < 7",
   "tqdm >= 4.38.0, < 5",
   "typing_extensions >= 4.6.1, < 5",
   "watchfiles >= 0.15.0",

src/frequenz/sdk/microgrid/__init__.py

@@ -124,7 +124,7 @@
 
 from ..actor import ResamplerConfig
 from ..timeseries.grid import initialize as initialize_grid
-from . import _data_pipeline, client, component, connection_manager, fuse
+from . import _data_pipeline, client, component, connection_manager, fuse, metadata
 from ._data_pipeline import (
     battery_pool,
     ev_charger_pool,
@@ -161,4 +161,5 @@ async def initialize(host: str, port: int, resampler_config: ResamplerConfig) ->
     "grid",
     "frequency",
     "logical_meter",
+    "metadata",
 ]

src/frequenz/sdk/microgrid/client/_client.py

@@ -15,6 +15,7 @@
 from frequenz.api.microgrid import microgrid_pb2 as microgrid_pb
 from frequenz.api.microgrid.microgrid_pb2_grpc import MicrogridStub
 from frequenz.channels import Broadcast, Receiver, Sender
+from google.protobuf.empty_pb2 import Empty  # pylint: disable=no-name-in-module
 
 from ..._internal._constants import RECEIVER_MAX_SIZE
 from ..component import (
@@ -30,6 +31,7 @@
     _component_metadata_from_protobuf,
     _component_type_from_protobuf,
 )
+from ..metadata import Location, Metadata
 from ._connection import Connection
 from ._retry import LinearBackoff, RetryStrategy
 
@@ -62,6 +64,14 @@ async def components(self) -> Iterable[Component]:
             Iterator whose elements are all the components in the microgrid.
         """
 
+    @abstractmethod
+    async def metadata(self) -> Metadata:
+        """Fetch the microgrid metadata.
+
+        Returns:
+            the microgrid metadata.
+        """
+
     @abstractmethod
     async def connections(
         self,
@@ -259,6 +269,36 @@ async def components(self) -> Iterable[Component]:
 
         return result
 
+    async def metadata(self) -> Metadata:
+        """Fetch the microgrid metadata.
+
+        If there is an error fetching the metadata, the microgrid ID and
+        location will be set to None.
+
+        Returns:
+            the microgrid metadata.
+        """
+        microgrid_metadata: microgrid_pb.MicrogridMetadata | None = None
+        try:
+            microgrid_metadata = await self.api.GetMicrogridMetadata(
+                Empty(),
+                timeout=int(DEFAULT_GRPC_CALL_TIMEOUT),
+            )  # type: ignore[misc]
+        except grpc.aio.AioRpcError:
+            _logger.exception("The microgrid metadata is not available.")
+
+        if not microgrid_metadata:
+            return Metadata()
+
+        location: Location | None = None
+        if microgrid_metadata.location:
+            location = Location(
+                latitude=microgrid_metadata.location.latitude,
+                longitude=microgrid_metadata.location.longitude,
+            )
+
+        return Metadata(microgrid_id=microgrid_metadata.microgrid_id, location=location)
+
     async def connections(
         self,
         starts: set[int] | None = None,

src/frequenz/sdk/microgrid/connection_manager.py

@@ -16,6 +16,7 @@
 from .client import MicrogridApiClient
 from .client._client import MicrogridGrpcClient
 from .component_graph import ComponentGraph, _MicrogridComponentGraph
+from .metadata import Location, Metadata
 
 # Not public default host and port
 _DEFAULT_MICROGRID_HOST = "[::1]"
@@ -74,6 +75,24 @@ def component_graph(self) -> ComponentGraph:
             component graph
         """
 
+    @property
+    @abstractmethod
+    def microgrid_id(self) -> int | None:
+        """Get the ID of the microgrid if available.
+
+        Returns:
+            the ID of the microgrid if available, None otherwise.
+        """
+
+    @property
+    @abstractmethod
+    def location(self) -> Location | None:
+        """Get the location of the microgrid if available.
+
+        Returns:
+            the location of the microgrid if available, None otherwise.
+        """
+
     async def _update_api(self, host: str, port: int) -> None:
         self._host = host
         self._port = port
@@ -103,6 +122,9 @@ def __init__(
         # So create empty graph here, and update it in `run` method.
         self._graph = _MicrogridComponentGraph()
 
+        self._metadata: Metadata
+        """The metadata of the microgrid."""
+
     @property
     def api_client(self) -> MicrogridApiClient:
         """Get MicrogridApiClient.
@@ -112,6 +134,24 @@ def api_client(self) -> MicrogridApiClient:
         """
         return self._api
 
+    @property
+    def microgrid_id(self) -> int | None:
+        """Get the ID of the microgrid if available.
+
+        Returns:
+            the ID of the microgrid if available, None otherwise.
+        """
+        return self._metadata.microgrid_id
+
+    @property
+    def location(self) -> Location | None:
+        """Get the location of the microgrid if available.
+
+        Returns:
+            the location of the microgrid if available, None otherwise.
+        """
+        return self._metadata.location
+
     @property
     def component_graph(self) -> ComponentGraph:
         """Get component graph.
@@ -133,9 +173,11 @@ async def _update_api(self, host: str, port: int) -> None:
         target = f"{host}:{port}"
         grpc_channel = grpcaio.insecure_channel(target)
         self._api = MicrogridGrpcClient(grpc_channel, target)
+        self._metadata = await self._api.metadata()
         await self._graph.refresh_from_api(self._api)
 
     async def _initialize(self) -> None:
+        self._metadata = await self._api.metadata()
         await self._graph.refresh_from_api(self._api)
 
 

src/frequenz/sdk/microgrid/metadata.py

@@ -0,0 +1,50 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Metadata that describes a microgrid."""
+
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo
+
+from timezonefinder import TimezoneFinder
+
+_timezone_finder = TimezoneFinder()
+
+
+@dataclass(frozen=True, kw_only=True)
+class Location:
+    """Metadata for the location of microgrid."""
+
+    latitude: float | None = None
+    """The latitude of the microgrid in degree."""
+
+    longitude: float | None = None
+    """The longitude of the microgrid in degree."""
+
+    timezone: ZoneInfo | None = None
+    """The timezone of the microgrid.
+
+    The timezone will be set to None if the latitude or longitude points
+    are not set or the timezone cannot be found given the location points.
+    """
+
+    def __post_init__(self) -> None:
+        """Initialize the timezone of the microgrid."""
+        if self.latitude is None or self.longitude is None or self.timezone is not None:
+            return
+
+        timezone = _timezone_finder.timezone_at(lat=self.latitude, lng=self.longitude)
+        if timezone:
+            # The dataclass is frozen, so it needs to use __setattr__ to set the timezone.
+            object.__setattr__(self, "timezone", ZoneInfo(key=timezone))
+
+
+@dataclass(frozen=True, kw_only=True)
+class Metadata:
+    """Metadata for the microgrid."""
+
+    microgrid_id: int | None = None
+    """The ID of the microgrid."""
+
+    location: Location | None = None
+    """The location of the microgrid."""