Add support for grid frequency

Marenz · Marenz · commit 5f694aa5be05 · 2023-09-05T12:09:21.000+02:00
Signed-off-by: Mathias L. Baumann &lt;mathias.baumann@frequenz.com&gt;
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -16,6 +16,8 @@
 
   Note that a microgrid is allowed to have zero or one grid connection point. Microgrids configured as islands will have zero grid connection points, and microgrids configured as grid-connected will have one grid connection point.
 
+- A new method `microgrid.frequeny()` was added to allow easy access to the current frequency of the grid.
+
 - A new class `Fuse` has been added to represent fuses. This class has a member variable `max_current` which represents the maximum current that can course through the fuse. If the current flowing through a fuse is greater than this limit, then the fuse will break the circuit.
 
 
diff --git a/src/frequenz/sdk/microgrid/__init__.py b/src/frequenz/sdk/microgrid/__init__.py
@@ -9,7 +9,7 @@
 
 from ..actor import ResamplerConfig
 from . import _data_pipeline, client, component, connection_manager, fuse, grid
-from ._data_pipeline import battery_pool, ev_charger_pool, logical_meter
+from ._data_pipeline import battery_pool, ev_charger_pool, frequency, logical_meter
 from ._graph import ComponentGraph
 
 
@@ -39,5 +39,6 @@ async def initialize(host: str, port: int, resampler_config: ResamplerConfig) ->
     "ev_charger_pool",
     "fuse",
     "grid",
+    "frequency",
     "logical_meter",
 ]
diff --git a/src/frequenz/sdk/microgrid/_data_pipeline.py b/src/frequenz/sdk/microgrid/_data_pipeline.py
@@ -17,6 +17,8 @@
 
 from frequenz.channels import Broadcast, Sender
 
+from ..microgrid.component import Component
+from ..timeseries._grid_frequency import GridFrequency
 from . import connection_manager
 from .component import ComponentCategory
 
@@ -101,6 +103,29 @@ def __init__(
         self._logical_meter: "LogicalMeter" | None = None
         self._ev_charger_pools: dict[frozenset[int], "EVChargerPool"] = {}
         self._battery_pools: dict[frozenset[int], "BatteryPool"] = {}
+        self._frequency_pool: dict[int, GridFrequency] = {}
+
+    def frequency(self, component: Component | None = None) -> GridFrequency:
+        """Fetch the grid frequency for the microgrid.
+
+        Args:
+            component: The component to use when fetching the grid frequency.  If None,
+                the component will be fetched from the registry.
+
+        Returns:
+            A GridFrequency instance.
+        """
+        if component is None:
+            component = GridFrequency.find_frequency_component()
+
+        if component.component_id in self._frequency_pool:
+            return self._frequency_pool[component.component_id]
+
+        grid_frequency = GridFrequency(
+            self._data_sourcing_request_sender(), self._channel_registry, component
+        )
+        self._frequency_pool[component.component_id] = grid_frequency
+        return grid_frequency
 
     def logical_meter(self) -> LogicalMeter:
         """Return the logical meter instance.
@@ -296,6 +321,19 @@ async def initialize(resampler_config: ResamplerConfig) -> None:
     _DATA_PIPELINE = _DataPipeline(resampler_config)
 
 
+def frequency(component: Component | None = None) -> GridFrequency:
+    """Return the grid frequency.
+
+    Args:
+        component: Optional component to get the frequency for. If not specified,
+            the frequency of the grid is returned.
+
+    Returns:
+        The grid frequency.
+    """
+    return _get().frequency(component)
+
+
 def logical_meter() -> LogicalMeter:
     """Return the logical meter instance.
 
diff --git a/src/frequenz/sdk/timeseries/_grid_frequency.py b/src/frequenz/sdk/timeseries/_grid_frequency.py
@@ -0,0 +1,166 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Fetches the Grid Frequency."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from frequenz.channels import Receiver, Sender
+
+from ..actor import ChannelRegistry
+from ..microgrid import connection_manager
+from ..microgrid.component import Component, ComponentCategory, ComponentMetricId
+from ..timeseries._base_types import Sample
+from ..timeseries._quantities import Frequency
+
+if TYPE_CHECKING:
+    # Imported here to avoid a circular import.
+    from ..actor import ComponentMetricRequest
+
+
+def create_request(component_id: int) -> ComponentMetricRequest:
+    """Create a request for grid frequency.
+
+    Args:
+        component_id: The component id to use for the request.
+
+    Returns:
+        A component metric request for grid frequency.
+    """
+    # Imported here to avoid a circular import.
+    # pylint: disable=import-outside-toplevel
+    from ..actor import ComponentMetricRequest
+
+    return ComponentMetricRequest(
+        "grid-frequency", component_id, ComponentMetricId.FREQUENCY, None
+    )
+
+
+class GridFrequency:
+    """Grid Frequency."""
+
+    def __init__(
+        self,
+        data_sourcing_request_sender: Sender[ComponentMetricRequest],
+        channel_registry: ChannelRegistry,
+        component: Component,
+    ):
+        """Initialize the grid frequency formula generator.
+
+        Args:
+            data_sourcing_request_sender: The sender to use for requests.
+            channel_registry: The channel registry to use for the grid frequency.
+            component: The component to use for the grid frequency receiver. If not
+                provided, the first component that is either a meter, inverter or EV
+                charger will be used.
+        """
+        self._request_sender = data_sourcing_request_sender
+        self._channel_registry = channel_registry
+        self._component = component
+        self._component_metric_request = create_request(component.component_id)
+
+        self._task: None | asyncio.Task[None] = None
+
+    @property
+    def component(self) -> Component:
+        """The component that is used for grid frequency.
+
+        Returns:
+            The component that is used for grid frequency.
+        """
+        return self._component
+
+    def new_receiver(self) -> Receiver[Sample[Frequency]]:
+        """Create a receiver for grid frequency.
+
+        Returns:
+            A receiver that will receive grid frequency samples.
+        """
+        receiver = self._channel_registry.new_receiver(
+            self._component_metric_request.get_channel_name()
+        )
+
+        if not self._task:
+            self._task = asyncio.create_task(self._send_request())
+        else:
+            logging.info("Grid frequency request already sent: %s", self._component)
+
+        return receiver
+
+    async def _send_request(self) -> None:
+        """Send the request for grid frequency."""
+        logging.info("Sending request for grid frequency: %s", self._component)
+        await self._request_sender.send(self._component_metric_request)
+        logging.info("Sent request for grid frequency: %s", self._component)
+
+    @staticmethod
+    def find_frequency_component() -> Component:
+        """Find the component that will be used for grid frequency.
+
+        Uses the first meter it can find to gather the frequency. If no meter is
+        available, it will use the first inverter, then EV charger.
+
+        Returns:
+            The component that will be used for grid frequency.
+
+        Raises:
+            ValueError: when the component graph doesn't have a `GRID` component.
+        """
+        component_graph = connection_manager.get().component_graph
+        grid_component = next(
+            (
+                comp
+                for comp in component_graph.components()
+                if comp.category == ComponentCategory.GRID
+            ),
+            None,
+        )
+
+        if grid_component is None:
+            raise ValueError(
+                "Unable to find a GRID component from the component graph."
+            )
+
+        # Sort by component id to ensure consistent results
+        grid_successors = sorted(
+            component_graph.successors(grid_component.component_id),
+            key=lambda comp: comp.component_id,
+        )
+
+        def find_component(component_category: ComponentCategory) -> Component | None:
+            return next(
+                (
+                    comp
+                    for comp in grid_successors
+                    if comp.category == component_category
+                ),
+                None,
+            )
+
+        # Find the first component that is either a meter, inverter or EV charger
+        # with category priority in that order.
+        component = next(
+            filter(
+                None,
+                map(
+                    find_component,
+                    [
+                        ComponentCategory.METER,
+                        ComponentCategory.INVERTER,
+                        ComponentCategory.EV_CHARGER,
+                    ],
+                ),
+            ),
+            None,
+        )
+
+        if component is None:
+            raise ValueError(
+                "Unable to find a METER, INVERTER or EV_CHARGER component from the component graph."
+            )
+
+        return component
diff --git a/tests/timeseries/mock_resampler.py b/tests/timeseries/mock_resampler.py
@@ -58,11 +58,25 @@ def power_senders(
                 ]
             return senders
 
+        def frequency_senders(
+            comp_ids: list[int],
+        ) -> list[Sender[Sample[Quantity]]]:
+            senders: list[Sender[Sample[Quantity]]] = []
+            for comp_id in comp_ids:
+                name = f"{comp_id}:{ComponentMetricId.FREQUENCY}"
+                senders.append(self._channel_registry.new_sender(name))
+                self._basic_receivers[name] = [
+                    self._channel_registry.new_receiver(name) for _ in range(namespaces)
+                ]
+            return senders
+
         self._bat_inverter_power_senders = power_senders(bat_inverter_ids)
+        self._bat_inverter_frequency_senders = frequency_senders(bat_inverter_ids)
         self._pv_inverter_power_senders = power_senders(pv_inverter_ids)
         self._ev_power_senders = power_senders(evc_ids)
         self._chp_power_senders = power_senders(chp_ids)
         self._meter_power_senders = power_senders(meter_ids)
+        self._meter_frequency_senders = frequency_senders(meter_ids)
         self._non_existing_component_sender = power_senders(
             [NON_EXISTING_COMPONENT_ID]
         )[0]
@@ -159,6 +173,20 @@ async def send_pv_inverter_power(self, values: list[float | None]) -> None:
             sample = Sample(self._next_ts, None if not value else Quantity(value))
             await chan.send(sample)
 
+    async def send_meter_frequency(self, values: list[float | None]) -> None:
+        """Send the given values as resampler output for meter frequency."""
+        assert len(values) == len(self._meter_frequency_senders)
+        for sender, value in zip(self._meter_frequency_senders, values):
+            sample = Sample(self._next_ts, None if not value else Quantity(value))
+            await sender.send(sample)
+
+    async def send_bat_inverter_frequency(self, values: list[float | None]) -> None:
+        """Send the given values as resampler output for battery inverter frequency."""
+        assert len(values) == len(self._bat_inverter_frequency_senders)
+        for chan, value in zip(self._bat_inverter_frequency_senders, values):
+            sample = Sample(self._next_ts, None if not value else Quantity(value))
+            await chan.send(sample)
+
     async def send_evc_power(self, values: list[float | None]) -> None:
         """Send the given values as resampler output for EV Charger power."""
         assert len(values) == len(self._ev_power_senders)
diff --git a/tests/timeseries/test_logical_meter.py b/tests/timeseries/test_logical_meter.py
