Add microgrid.frequency() (#579)

fixes #341

Author: Marenz

RELEASE_NOTES.md

@@ -18,6 +18,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.
 
 

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

@@ -3,8 +3,8 @@
 
 """The DataSourcingActor."""
 
+from ._component_metric_request import ComponentMetricRequest
 from .data_sourcing import DataSourcingActor
-from .microgrid_api_source import ComponentMetricRequest
 
 __all__ = [
     "ComponentMetricRequest",

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

@@ -0,0 +1,51 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""The ComponentMetricRequest class."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ...microgrid.component._component import ComponentMetricId
+
+
+@dataclass
+class ComponentMetricRequest:
+    """A request object to start streaming a metric for a component."""
+
+    namespace: str
+    """The namespace that this request belongs to.
+
+    Metric requests with a shared namespace enable the reuse of channels within
+    that namespace.
+
+    If for example, an actor making a multiple requests, uses the name of the
+    actor as the namespace, then requests from the actor will get reused when
+    possible.
+    """
+
+    component_id: int
+    """The ID of the requested component."""
+
+    metric_id: ComponentMetricId
+    """The ID of the requested component's metric."""
+
+    start_time: datetime | None
+    """The start time from which data is required.
+
+    When None, we will stream only live data.
+    """
+
+    def get_channel_name(self) -> str:
+        """Return a channel name constructed from Self.
+
+        This channel name can be used by the sending side and receiving sides to
+        identify the right channel from the ChannelRegistry.
+
+        Returns:
+            A string denoting a channel name.
+        """
+        return (
+            f"component-stream::{self.component_id}::{self.metric_id.name}::"
+            f"{self.start_time}::{self.namespace}"
+        )

src/frequenz/sdk/actor/_data_sourcing/data_sourcing.py

@@ -7,7 +7,8 @@
 
 from .._actor import Actor
 from .._channel_registry import ChannelRegistry
-from .microgrid_api_source import ComponentMetricRequest, MicrogridApiSource
+from ._component_metric_request import ComponentMetricRequest
+from .microgrid_api_source import MicrogridApiSource
 
 
 class DataSourcingActor(Actor):

src/frequenz/sdk/actor/_data_sourcing/microgrid_api_source.py

@@ -5,8 +5,6 @@
 
 import asyncio
 import logging
-from dataclasses import dataclass
-from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from frequenz.channels import Receiver, Sender
@@ -23,49 +21,7 @@
 from ...timeseries import Sample
 from ...timeseries._quantities import Quantity
 from .._channel_registry import ChannelRegistry
-
-
-@dataclass
-class ComponentMetricRequest:
-    """A request object to start streaming a metric for a component."""
-
-    namespace: str
-    """The namespace that this request belongs to.
-
-    Metric requests with a shared namespace enable the reuse of channels within
-    that namespace.
-
-    If for example, an actor making a multiple requests, uses the name of the
-    actor as the namespace, then requests from the actor will get reused when
-    possible.
-    """
-
-    component_id: int
-    """The ID of the requested component."""
-
-    metric_id: ComponentMetricId
-    """The ID of the requested component's metric."""
-
-    start_time: Optional[datetime]
-    """The start time from which data is required.
-
-    When None, we will stream only live data.
-    """
-
-    def get_channel_name(self) -> str:
-        """Return a channel name constructed from Self.
-
-        This channel name can be used by the sending side and receiving sides to
-        identify the right channel from the ChannelRegistry.
-
-        Returns:
-            A string denoting a channel name.
-        """
-        return (
-            f"component-stream::{self.component_id}::{self.metric_id.name}::"
-            f"{self.start_time}::{self.namespace}"
-        )
-
+from ._component_metric_request import ComponentMetricRequest
 
 _MeterDataMethods: Dict[ComponentMetricId, Callable[[MeterData], float]] = {
     ComponentMetricId.ACTIVE_POWER: lambda msg: msg.active_power,
@@ -75,6 +31,7 @@ def get_channel_name(self) -> str:
     ComponentMetricId.VOLTAGE_PHASE_1: lambda msg: msg.voltage_per_phase[0],
     ComponentMetricId.VOLTAGE_PHASE_2: lambda msg: msg.voltage_per_phase[1],
     ComponentMetricId.VOLTAGE_PHASE_3: lambda msg: msg.voltage_per_phase[2],
+    ComponentMetricId.FREQUENCY: lambda msg: msg.frequency,
 }
 
 _BatteryDataMethods: Dict[ComponentMetricId, Callable[[BatteryData], float]] = {
@@ -111,6 +68,7 @@ def get_channel_name(self) -> str:
     ComponentMetricId.ACTIVE_POWER_INCLUSION_UPPER_BOUND: lambda msg: (
         msg.active_power_inclusion_upper_bound
     ),
+    ComponentMetricId.FREQUENCY: lambda msg: msg.frequency,
 }
 
 _EVChargerDataMethods: Dict[ComponentMetricId, Callable[[EVChargerData], float]] = {
@@ -121,6 +79,7 @@ def get_channel_name(self) -> str:
     ComponentMetricId.VOLTAGE_PHASE_1: lambda msg: msg.voltage_per_phase[0],
     ComponentMetricId.VOLTAGE_PHASE_2: lambda msg: msg.voltage_per_phase[1],
     ComponentMetricId.VOLTAGE_PHASE_3: lambda msg: msg.voltage_per_phase[2],
+    ComponentMetricId.FREQUENCY: lambda msg: msg.frequency,
 }
 
 

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",
 ]

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
 
@@ -105,6 +107,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.
@@ -300,6 +325,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.
 

src/frequenz/sdk/microgrid/component/_component.py

@@ -206,6 +206,8 @@ class ComponentMetricId(Enum):
     VOLTAGE_PHASE_3 = "voltage_phase_3"
     """Voltage in phase 3."""
 
+    FREQUENCY = "frequency"
+
     SOC = "soc"
     """State of charge."""
     SOC_LOWER_BOUND = "soc_lower_bound"

src/frequenz/sdk/microgrid/component/_component_data.py

@@ -278,6 +278,9 @@ class InverterData(ComponentData):
     """
     # pylint: enable=line-too-long
 
+    frequency: float
+    """AC frequency, in Hertz (Hz)."""
+
     _component_state: inverter_pb.ComponentState.ValueType
     """State of the inverter."""
 
@@ -303,6 +306,7 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> InverterData:
             active_power_exclusion_lower_bound=raw_power.system_exclusion_bounds.lower,
             active_power_inclusion_upper_bound=raw_power.system_inclusion_bounds.upper,
             active_power_exclusion_upper_bound=raw_power.system_exclusion_bounds.upper,
+            frequency=raw.inverter.data.ac.frequency.value,
             _component_state=raw.inverter.state.component_state,
             _errors=list(raw.inverter.errors),
         )
@@ -332,6 +336,9 @@ class EVChargerData(ComponentData):
         wire for phase/line 1,2 and 3 respectively.
     """
 
+    frequency: float
+    """AC frequency, in Hertz (Hz)."""
+
     cable_state: EVChargerCableState
     """The state of the ev charger's cable."""
 
@@ -366,6 +373,7 @@ def from_proto(cls, raw: microgrid_pb.ComponentData) -> EVChargerData:
             component_state=EVChargerComponentState.from_pb(
                 raw.ev_charger.state.component_state
             ),
+            frequency=raw.ev_charger.data.ac.frequency.value,
         )
         ev_charger_data._set_raw(raw=raw)
         return ev_charger_data