Move grid power and current formulas to Grid

Now that there is a microgrid.grid object,
the grid metrics are published there.

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

Author: daniel-zullo-frequenz

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.

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/grid.py

@@ -18,7 +18,10 @@
 from ..microgrid import connection_manager
 from ..microgrid.component._component import ComponentCategory
 from . import Fuse
+from ._quantities import Current, Power
+from .formula_engine import FormulaEngine, FormulaEngine3Phase
 from .formula_engine._formula_engine_pool import FormulaEnginePool
+from .formula_engine._formula_generators import GridCurrentFormula, GridPowerFormula
 
 if TYPE_CHECKING:
     # Break circular import
@@ -29,14 +32,90 @@
 
 @dataclass(frozen=True)
 class Grid:
-    """A grid connection point."""
+    """A grid connection point.
+
+    !!! note
+        The `Grid` instance is not meant to be created directly by users.
+        Use the [`microgrid.grid`][frequenz.sdk.microgrid.grid] method for
+        creating or getting the `Grid` instance.
+
+    Example:
+        ```python
+        from datetime import timedelta
+
+        from frequenz.sdk import microgrid
+        from frequenz.sdk.timeseries import ResamplerConfig
+
+        await microgrid.initialize(
+            "127.0.0.1",
+            50051,
+            ResamplerConfig(resampling_period=timedelta(seconds=1))
+        )
+
+        grid = microgrid.grid()
+        assert grid, "Grid is not initialized"
+
+        # Get a receiver for a builtin formula
+        grid_power_recv = grid.power.new_receiver()
+        async for grid_power_sample in grid_power_recv:
+            print(grid_power_sample)
+        ```
+    """
 
     fuse: Fuse
     """The fuse protecting the grid connection point."""
 
     _formula_pool: FormulaEnginePool
     """The formula engine pool to generate grid metrics."""
 
+    @property
+    def power(self) -> FormulaEngine[Power]:
+        """Fetch the grid power for the microgrid.
+
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
+        If a formula engine to calculate grid power is not already running, it will be
+        started.
+
+        A receiver from the formula engine can be created using the `new_receiver`
+        method.
+
+        Returns:
+            A FormulaEngine that will calculate and stream grid power.
+        """
+        engine = self._formula_pool.from_power_formula_generator(
+            "grid_power",
+            GridPowerFormula,
+        )
+        assert isinstance(engine, FormulaEngine)
+        return engine
+
+    @property
+    def current(self) -> FormulaEngine3Phase[Current]:
+        """Fetch the grid power for the microgrid.
+
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
+        If a formula engine to calculate grid current is not already running, it will be
+        started.
+
+        A receiver from the formula engine can be created using the `new_receiver`
+        method.
+
+        Returns:
+            A FormulaEngine that will calculate and stream grid current.
+        """
+        engine = self._formula_pool.from_3_phase_current_formula_generator(
+            "grid_current",
+            GridCurrentFormula,
+        )
+        assert isinstance(engine, FormulaEngine3Phase)
+        return engine
+
+    async def stop(self) -> None:
+        """Stop all formula engines."""
+        await self._formula_pool.stop()
+
 
 _GRID: Grid | None = None
 

src/frequenz/sdk/timeseries/logical_meter/_logical_meter.py

@@ -10,14 +10,12 @@
 
 from ...actor import ChannelRegistry, ComponentMetricRequest
 from ...microgrid.component import ComponentMetricId
-from .._quantities import Current, Power, Quantity
-from ..formula_engine import FormulaEngine, FormulaEngine3Phase
+from .._quantities import Power, Quantity
+from ..formula_engine import FormulaEngine
 from ..formula_engine._formula_engine_pool import FormulaEnginePool
 from ..formula_engine._formula_generators import (
     CHPPowerFormula,
     ConsumerPowerFormula,
-    GridCurrentFormula,
-    GridPowerFormula,
     ProducerPowerFormula,
     PVPowerFormula,
 )
@@ -49,17 +47,17 @@ class LogicalMeter:
         )
 
         logical_meter = microgrid.logical_meter()
+        grid = microgrid.grid()
 
         # Get a receiver for a builtin formula
-        grid_power_recv = logical_meter.grid_power.new_receiver()
-        async for grid_power_sample in grid_power_recv:
-            print(grid_power_sample)
+        consumer_power_recv = logical_meter.consumer_power.new_receiver()
+        async for consumer_power_sample in consumer_power_recv:
+            print(consumer_power_sample)
 
         # or compose formulas to create a new formula
         net_power_recv = (
             (
-                logical_meter.grid_power
-                - logical_meter.pv_power
+                grid.power - logical_meter.pv_power
             )
             .build("net_power")
             .new_receiver()
@@ -128,50 +126,6 @@ def start_formula(
             formula, component_metric_id, nones_are_zeros=nones_are_zeros
         )
 
-    @property
-    def grid_power(self) -> FormulaEngine[Power]:
-        """Fetch the grid power for the microgrid.
-
-        This formula produces values that are in the Passive Sign Convention (PSC).
-
-        If a formula engine to calculate grid power is not already running, it will be
-        started.
-
-        A receiver from the formula engine can be created using the `new_receiver`
-        method.
-
-        Returns:
-            A FormulaEngine that will calculate and stream grid power.
-        """
-        engine = self._formula_pool.from_power_formula_generator(
-            "grid_power",
-            GridPowerFormula,
-        )
-        assert isinstance(engine, FormulaEngine)
-        return engine
-
-    @property
-    def grid_current(self) -> FormulaEngine3Phase[Current]:
-        """Fetch the grid power for the microgrid.
-
-        This formula produces values that are in the Passive Sign Convention (PSC).
-
-        If a formula engine to calculate grid current is not already running, it will be
-        started.
-
-        A receiver from the formula engine can be created using the `new_receiver`
-        method.
-
-        Returns:
-            A FormulaEngine that will calculate and stream grid current.
-        """
-        engine = self._formula_pool.from_3_phase_current_formula_generator(
-            "grid_current",
-            GridCurrentFormula,
-        )
-        assert isinstance(engine, FormulaEngine3Phase)
-        return engine
-
     @property
     def consumer_power(self) -> FormulaEngine[Power]:
         """Fetch the consumer power for the microgrid.