Add producer power formula (#444)

Author: shsms

RELEASE_NOTES.md

@@ -10,6 +10,8 @@
 
 ## New Features
 
+- The logical meter has a new method that returns producer power, that is the sum of all energy producers.
+
 <!-- Here goes the main new features and examples or instructions on how to use them -->
 
 ## Bug Fixes

src/frequenz/sdk/timeseries/_formula_engine/_formula_generators/__init__.py

@@ -17,6 +17,7 @@
 )
 from ._grid_current_formula import GridCurrentFormula
 from ._grid_power_formula import GridPowerFormula
+from ._producer_power_formula import ProducerPowerFormula
 from ._pv_power_formula import PVPowerFormula
 
 __all__ = [
@@ -35,6 +36,7 @@
     "BatteryPowerFormula",
     "EVChargerPowerFormula",
     "PVPowerFormula",
+    "ProducerPowerFormula",
     #
     # Current formula generators
     #

src/frequenz/sdk/timeseries/_formula_engine/_formula_generators/_producer_power_formula.py

@@ -0,0 +1,82 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Formula generator from component graph for Producer Power."""
+
+from __future__ import annotations
+
+from ....microgrid import connection_manager
+from ....microgrid.component import ComponentCategory, ComponentMetricId
+from .._formula_engine import FormulaEngine
+from ._formula_generator import (
+    NON_EXISTING_COMPONENT_ID,
+    ComponentNotFound,
+    FormulaGenerator,
+)
+
+
+class ProducerPowerFormula(FormulaGenerator):
+    """Formula generator from component graph for calculating the Producer Power.
+
+    The producer power is calculated by summing up the power of all power producers,
+    which are CHP and PV.
+    """
+
+    def generate(self) -> FormulaEngine:
+        """Generate formula for calculating producer power from the component graph.
+
+        Returns:
+            A formula engine that will calculate the producer power.
+
+        Raises:
+            ComponentNotFound: If the component graph does not contain a producer power
+                component.
+            RuntimeError: If the grid component has a single successor that is not a
+                meter.
+        """
+        builder = self._get_builder("producer_power", ComponentMetricId.ACTIVE_POWER)
+        component_graph = connection_manager.get().component_graph
+        grid_component = next(
+            iter(
+                component_graph.components(component_category={ComponentCategory.GRID})
+            ),
+            None,
+        )
+
+        if grid_component is None:
+            raise ComponentNotFound("Grid component not found in the component graph.")
+
+        grid_successors = component_graph.successors(grid_component.component_id)
+        if not grid_successors:
+            raise ComponentNotFound("No components found in the component graph.")
+
+        if len(grid_successors) == 1:
+            grid_meter = next(iter(grid_successors))
+            if grid_meter.category != ComponentCategory.METER:
+                raise RuntimeError(
+                    "Only grid successor in the component graph is not a meter."
+                )
+            grid_successors = component_graph.successors(grid_meter.component_id)
+
+        first_iteration = True
+        for successor in iter(grid_successors):
+            # if in the future we support additional producers, we need to add them here
+            if component_graph.is_chp_chain(successor) or component_graph.is_pv_chain(
+                successor
+            ):
+                if not first_iteration:
+                    builder.push_oper("+")
+
+                first_iteration = False
+
+                builder.push_component_metric(
+                    successor.component_id,
+                    nones_are_zeros=successor.category != ComponentCategory.METER,
+                )
+
+        if first_iteration:
+            builder.push_component_metric(
+                NON_EXISTING_COMPONENT_ID, nones_are_zeros=True
+            )
+
+        return builder.build()

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

@@ -19,6 +19,7 @@
     FormulaType,
     GridCurrentFormula,
     GridPowerFormula,
+    ProducerPowerFormula,
     PVPowerFormula,
 )
 
@@ -261,6 +262,31 @@ def consumer_power(self) -> FormulaEngine:
         assert isinstance(engine, FormulaEngine)
         return engine
 
+    @property
+    def producer_power(self) -> FormulaEngine:
+        """Fetch the producer power for the microgrid.
+
+        Under normal circumstances this is expected to correspond to the production
+        of the sites active parts excluding ev chargers and batteries.
+
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
+        If a formula engine to calculate producer 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 producer power.
+        """
+        engine = self._formula_pool.from_generator(
+            "producer_power",
+            ProducerPowerFormula,
+        )
+        assert isinstance(engine, FormulaEngine)
+        return engine
+
     @property
     def pv_power(self) -> FormulaEngine:
         """Fetch the PV power in the microgrid.

tests/timeseries/test_logical_meter.py

@@ -185,3 +185,51 @@ async def test_consumer_power_no_grid_meter(self, mocker: MockerFixture) -> None
 
         await mockgrid.mock_data.send_meter_power([20.0, 2.0, 3.0, 4.0, 5.0])
         assert (await consumer_power_receiver.receive()).value == 20.0
+
+    async def test_producer_power(self, mocker: MockerFixture) -> None:
+        """Test the producer power formula."""
+        mockgrid = MockMicrogrid(grid_side_meter=False)
+        mockgrid.add_solar_inverters(2)
+        mockgrid.add_chps(2)
+        await mockgrid.start_mock_datapipeline(mocker)
+
+        logical_meter = microgrid.logical_meter()
+        producer_power_receiver = logical_meter.producer_power.new_receiver()
+
+        await mockgrid.mock_data.send_meter_power([20.0, 2.0, 3.0, 4.0, 5.0])
+        assert (await producer_power_receiver.receive()).value == 14.0
+
+    async def test_producer_power_no_chp(self, mocker: MockerFixture) -> None:
+        """Test the producer power formula without a chp."""
+        mockgrid = MockMicrogrid(grid_side_meter=False)
+        mockgrid.add_solar_inverters(2)
+        await mockgrid.start_mock_datapipeline(mocker)
+
+        logical_meter = microgrid.logical_meter()
+        producer_power_receiver = logical_meter.producer_power.new_receiver()
+
+        await mockgrid.mock_data.send_meter_power([20.0, 2.0, 3.0])
+        assert (await producer_power_receiver.receive()).value == 5.0
+
+    async def test_producer_power_no_pv(self, mocker: MockerFixture) -> None:
+        """Test the producer power formula without pv."""
+        mockgrid = MockMicrogrid(grid_side_meter=False)
+        mockgrid.add_chps(1)
+        await mockgrid.start_mock_datapipeline(mocker)
+
+        logical_meter = microgrid.logical_meter()
+        producer_power_receiver = logical_meter.producer_power.new_receiver()
+
+        await mockgrid.mock_data.send_meter_power([20.0, 2.0])
+        assert (await producer_power_receiver.receive()).value == 2.0
+
+    async def test_no_producer_power(self, mocker: MockerFixture) -> None:
+        """Test the producer power formula without producers."""
+        mockgrid = MockMicrogrid(grid_side_meter=False)
+        await mockgrid.start_mock_datapipeline(mocker)
+
+        logical_meter = microgrid.logical_meter()
+        producer_power_receiver = logical_meter.producer_power.new_receiver()
+
+        await mockgrid.mock_data.send_non_existing_component_value()
+        assert (await producer_power_receiver.receive()).value == 0.0