Add microgrid metadata types

The microgrid metadata is needed to retrieve
the ID and location of the microgrid.

Signed-off-by: Daniel Zullo <[email protected]>

Author: daniel-zullo-frequenz

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/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."""