Move grid power and current metrics to Grid (#758)

Fixes #729

Author: daniel-zullo-frequenz

RELEASE_NOTES.md

@@ -20,6 +20,28 @@
 
 - The `Fuse` class has been moved to the `frequenz.sdk.timeseries` module.
 
+- `microgrid.grid()`
+  - A `Grid` object is always instantiated now, even if the microgrid is not connected to the grid (islanded microgrids).
+  - The rated current of the grid fuse is set to `Current.zero()` in case of islanded microgrids.
+  - The grid fuse is set to `None` when the grid connection component metadata lacks information about the fuse.
+  - Grid power and current metrics were moved from `microgrid.logical_meter()` to `microgrid.grid()`.
+
+    Previously,
+
+    ```python
+    logical_meter = microgrid.logical_meter()
+    grid_power_recv = logical_meter.grid_power.new_receiver()
+    grid_current_recv = logical_meter.grid_current.new_receiver()
+    ```
+
+    Now,
+
+    ```python
+    grid = microgrid.grid()
+    grid_power_recv = grid.power.new_receiver()
+    grid_current_recv = grid.current.new_receiver()
+    ```
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->

docs/tutorials/getting_started.md

@@ -87,7 +87,7 @@ async def run() -> None:
     ...
 
     # Define your application logic here
-    grid_meter = microgrid.logical_meter().grid_power.new_receiver()
+    grid_meter = microgrid.grid().power.new_receiver()
 
     async for power in grid_meter:
         print(power.value)
@@ -117,7 +117,7 @@ async def run() -> None:
     )
 
     # Define your application logic here
-    grid_meter = microgrid.logical_meter().grid_power.new_receiver()
+    grid_meter = microgrid.grid().power.new_receiver()
 
     async for power in grid_meter:
         print(power.value)

docs/user-guide/glossary.md

@@ -166,7 +166,7 @@ microgrid are connected with each other.  Some of the ways in which the SDK uses
 the component graph are:
 
   - figure out how to calculate high level metrics like
-[`grid_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.grid_power],
+[`grid_power`][frequenz.sdk.timeseries.grid.Grid.power],
 [`consumer_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.consumer_power],
 etc. for a microgrid, using the available components.
   - identify the available {{glossary("battery", "batteries")}} or

src/frequenz/sdk/microgrid/__init__.py

@@ -59,7 +59,7 @@
 
 This refers to a microgrid's connection to the external Grid.  The power flowing through
 this connection can be streamed through
-[`grid_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.grid_power].
+[`grid_power`][frequenz.sdk.timeseries.grid.Grid.power].
 
 In locations without a grid connection, this method remains accessible, and streams zero
 values.
@@ -123,7 +123,6 @@
 """  # noqa: D205, D400
 
 from ..actor import ResamplerConfig
-from ..timeseries.grid import initialize as initialize_grid
 from . import _data_pipeline, client, component, connection_manager, metadata
 from ._data_pipeline import (
     battery_pool,
@@ -143,11 +142,6 @@ async def initialize(host: str, port: int, resampler_config: ResamplerConfig) ->
         resampler_config: Configuration for the resampling actor.
     """
     await connection_manager.initialize(host, port)
-
-    api_client = connection_manager.get().api_client
-    components = await api_client.components()
-    initialize_grid(components)
-
     await _data_pipeline.initialize(resampler_config)
 
 

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -24,6 +24,7 @@
 from ..timeseries._grid_frequency import GridFrequency
 from ..timeseries.grid import Grid
 from ..timeseries.grid import get as get_grid
+from ..timeseries.grid import initialize as initialize_grid
 from . import connection_manager
 from .component import ComponentCategory
 
@@ -115,6 +116,7 @@ def __init__(
         self._power_managing_actor: _power_managing.PowerManagingActor | None = None
 
         self._logical_meter: LogicalMeter | None = None
+        self._grid: Grid | None = None
         self._ev_charger_pools: dict[frozenset[int], EVChargerPool] = {}
         self._battery_pools: dict[frozenset[int], BatteryPoolReferenceStore] = {}
         self._frequency_pool: dict[int, GridFrequency] = {}
@@ -189,17 +191,22 @@ def ev_charger_pool(
             )
         return self._ev_charger_pools[key]
 
-    def grid(
-        self,
-    ) -> Grid | None:
+    def grid(self) -> Grid:
         """Return the grid instance.
 
         If a Grid instance doesn't exist, a new one is created and returned.
 
         Returns:
             A Grid instance.
         """
-        return get_grid()
+        if self._grid is None:
+            initialize_grid(
+                channel_registry=self._channel_registry,
+                resampler_subscription_sender=self._resampling_request_sender(),
+            )
+            self._grid = get_grid()
+
+        return self._grid
 
     def battery_pool(
         self,
@@ -470,7 +477,7 @@ def battery_pool(
     return _get().battery_pool(battery_ids, name, priority)
 
 
-def grid() -> Grid | None:
+def grid() -> Grid:
     """Return the grid instance.
 
     Returns:

src/frequenz/sdk/timeseries/_periodic_feature_extractor.py

@@ -82,7 +82,7 @@ class PeriodicFeatureExtractor:
 
         async with MovingWindow(
             size=timedelta(days=35),
-            resampled_data_recv=microgrid.logical_meter().grid_power.new_receiver(),
+            resampled_data_recv=microgrid.grid().power.new_receiver(),
             input_sampling_period=timedelta(seconds=1),
         ) as moving_window:
             feature_extractor = PeriodicFeatureExtractor(

src/frequenz/sdk/timeseries/formula_engine/_formula_engine.py

@@ -231,7 +231,7 @@ class FormulaEngine(
     resampled data streams.
 
     They are used in the SDK to calculate and stream metrics like
-    [`grid_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.grid_power],
+    [`grid_power`][frequenz.sdk.timeseries.grid.Grid.power],
     [`consumer_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.consumer_power],
     etc., which are building blocks of the
     [Frequenz SDK Microgrid Model][frequenz.sdk.microgrid--frequenz-sdk-microgrid-model].
@@ -267,7 +267,7 @@ class FormulaEngine(
     [`battery_pool().power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power] and
     [`ev_charger_pool().power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool]
     from the
-    [`logical_meter().grid_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.grid_power],
+    [`grid().power`][frequenz.sdk.timeseries.grid.Grid.power],
     we can build a `FormulaEngine` that provides a stream of this calculated metric as
     follows:
 
@@ -277,11 +277,12 @@ class FormulaEngine(
     logical_meter = microgrid.logical_meter()
     battery_pool = microgrid.battery_pool()
     ev_charger_pool = microgrid.ev_charger_pool()
+    grid = microgrid.grid()
 
     # apply operations on formula engines to create a formula engine that would
     # apply these operations on the corresponding data streams.
     net_power = (
-        logical_meter.grid_power - (battery_pool.power + ev_charger_pool.power)
+        grid.power - (battery_pool.power + ev_charger_pool.power)
     ).build("net_power")
 
     async for power in net_power.new_receiver():
@@ -442,7 +443,7 @@ class FormulaEngine3Phase(
     [`FormulaEngine`][frequenz.sdk.timeseries.formula_engine.FormulaEngine], except that
     they stream [3-phase samples][frequenz.sdk.timeseries.Sample3Phase].  All the
     current formulas (like
-    [`LogicalMeter.grid_current`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.grid_current],
+    [`Grid.current`][frequenz.sdk.timeseries.grid.Grid.current],
     [`EVChargerPool.current`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current],
     etc.) are implemented as 3-phase formulas.
 
@@ -474,9 +475,10 @@ class FormulaEngine3Phase(
 
     logical_meter = microgrid.logical_meter()
     ev_charger_pool = microgrid.ev_charger_pool()
+    grid = microgrid.grid()
 
     # Calculate grid consumption current that's not used by the EV chargers
-    other_current = (logical_meter.grid_current - ev_charger_pool.current).build("other_current")
+    other_current = (grid.current - ev_charger_pool.current).build("other_current")
 
     async for sample in other_current.new_receiver():
         print(f"Other current: {sample}")

src/frequenz/sdk/timeseries/formula_engine/_formula_engine_pool.py

@@ -9,7 +9,6 @@
 
 from frequenz.channels import Sender
 
-from ...actor import ChannelRegistry, ComponentMetricRequest
 from ...microgrid.component import ComponentMetricId
 from .._quantities import Current, Power, Quantity
 from ._formula_generators._formula_generator import (
@@ -20,6 +19,7 @@
 
 if TYPE_CHECKING:
     # Break circular import
+    from ...actor import ChannelRegistry, ComponentMetricRequest
     from ..formula_engine import FormulaEngine, FormulaEngine3Phase
 
 

src/frequenz/sdk/timeseries/formula_engine/_formula_generators/_formula_generator.py

@@ -3,23 +3,27 @@
 
 """Base class for formula generators that use the component graphs."""
 
+from __future__ import annotations
 
 import sys
 from abc import ABC, abstractmethod
 from collections import abc
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Generic
+from typing import TYPE_CHECKING, Generic
 
 from frequenz.channels import Sender
 
-from ....actor import ChannelRegistry, ComponentMetricRequest
 from ....microgrid import component, connection_manager
 from ....microgrid.component import ComponentMetricId
 from ..._quantities import QuantityT
 from .._formula_engine import FormulaEngine, FormulaEngine3Phase
 from .._resampled_formula_builder import ResampledFormulaBuilder
 
+if TYPE_CHECKING:
+    # Break circular import
+    from ....actor import ChannelRegistry, ComponentMetricRequest
+
 
 class FormulaGenerationError(Exception):
     """An error encountered during formula generation from the component graph."""

src/frequenz/sdk/timeseries/formula_engine/_resampled_formula_builder.py

@@ -3,19 +3,23 @@
 
 """A builder for creating formula engines that operate on resampled component metrics."""
 
+from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Generic
+from typing import TYPE_CHECKING, Generic
 
 from frequenz.channels import Receiver, Sender
 
-from ...actor import ChannelRegistry, ComponentMetricRequest
 from ...microgrid.component import ComponentMetricId
 from .. import Sample
 from .._quantities import QuantityT
 from ._formula_engine import FormulaBuilder, FormulaEngine
 from ._tokenizer import Tokenizer, TokenType
 
+if TYPE_CHECKING:
+    # Break circular import
+    from ...actor import ChannelRegistry, ComponentMetricRequest
+
 
 class ResampledFormulaBuilder(Generic[QuantityT], FormulaBuilder[QuantityT]):
     """Provides a way to build a FormulaEngine from resampled data streams."""
@@ -63,6 +67,9 @@ def _get_resampled_receiver(
         Returns:
             A receiver to stream resampled data for the given component id.
         """
+        # pylint: disable=import-outside-toplevel
+        from frequenz.sdk.actor import ComponentMetricRequest
+
         request = ComponentMetricRequest(self._namespace, component_id, metric_id, None)
         self._resampler_requests.append(request)
         return self._channel_registry.new_receiver(request.get_channel_name())