Documentation for the FormulaEngine (#731)

Author: shsms

docs/user-guide/formula-engine.md

@@ -0,0 +1,15 @@
+# Formula Engine
+
+::: frequenz.sdk.timeseries.formula_engine.FormulaEngine
+    options:
+        members: None
+        show_bases: false
+        show_root_full_path: false
+        show_source: false
+
+::: frequenz.sdk.timeseries.formula_engine.FormulaEngine3Phase
+    options:
+        members: None
+        show_bases: false
+        show_root_full_path: false
+        show_source: false

docs/user-guide/glossary.md

@@ -158,6 +158,20 @@ of type `int`.
 
 For example, a battery with a component ID of **5**.
 
+### Component Graph
+
+A [graph](https://en.wikipedia.org/wiki/Graph_(abstract_data_type))
+representation of the configuration in which the electrical components in a
+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],
+[`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
+    {{glossary("EV charger", "EV chargers")}} at a site that can be controlled.
+
 ### Island
 
 A [microgrid](#microgrid) that is not connected to the public electricity

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

@@ -17,8 +17,8 @@
 from ..._internal._channels import ReceiverFetcher
 from ...actor import _power_managing
 from ...timeseries import Energy, Percentage, Power, Sample, Temperature
-from .._formula_engine import FormulaEngine
-from .._formula_engine._formula_generators import (
+from ..formula_engine import FormulaEngine
+from ..formula_engine._formula_generators import (
     BatteryPowerFormula,
     FormulaGeneratorConfig,
     FormulaType,

src/frequenz/sdk/timeseries/battery_pool/_battery_pool.py

@@ -17,7 +17,7 @@
 from ...actor.power_distributing._battery_pool_status import BatteryStatus
 from ...microgrid import connection_manager
 from ...microgrid.component import ComponentCategory
-from .._formula_engine import FormulaEnginePool
+from ..formula_engine._formula_engine_pool import FormulaEnginePool
 from ._methods import MetricAggregator
 
 

src/frequenz/sdk/timeseries/battery_pool/_battery_pool_reference_store.py

@@ -19,14 +19,15 @@
 from ...microgrid import connection_manager
 from ...microgrid.component import ComponentCategory, ComponentMetricId
 from .. import Sample, Sample3Phase
-from .._formula_engine import FormulaEngine, FormulaEngine3Phase, FormulaEnginePool
-from .._formula_engine._formula_generators import (
+from .._quantities import Current, Power, Quantity
+from ..formula_engine import FormulaEngine, FormulaEngine3Phase
+from ..formula_engine._formula_engine_pool import FormulaEnginePool
+from ..formula_engine._formula_generators import (
     EVChargerCurrentFormula,
     EVChargerPowerFormula,
     FormulaGeneratorConfig,
     FormulaType,
 )
-from .._quantities import Current, Power, Quantity
 from ._set_current_bounds import BoundsSetter, ComponentCurrentLimit
 from ._state_tracker import EVChargerState, StateTracker
 

src/frequenz/sdk/timeseries/ev_charger_pool/_ev_charger_pool.py

@@ -0,0 +1,17 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""The formula engine module.
+
+This module exposes the
+[FormulaEngine][frequenz.sdk.timeseries.formula_engine.FormulaEngine] and
+[FormulaEngine3Phase][frequenz.sdk.timeseries.formula_engine.FormulaEngine3Phase]
+classes.
+"""
+
+from ._formula_engine import FormulaEngine, FormulaEngine3Phase
+
+__all__ = [
+    "FormulaEngine",
+    "FormulaEngine3Phase",
+]

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

@@ -203,11 +203,68 @@ class FormulaEngine(
         QuantityT,
     ],
 ):
-    """
-    The FormulaEngine evaluates formulas and streams the results.
+    """[`FormulaEngine`][frequenz.sdk.timeseries.formula_engine.FormulaEngine]s are a
+    part of the SDK's data pipeline, and provide a way for the SDK to apply formulas on
+    resampled data streams.
 
-    Use the `FormulaBuilder` to create `FormulaEngine` instances.
-    """
+    They are used in the SDK to calculate and stream metrics like
+    [`grid_power`][frequenz.sdk.timeseries.logical_meter.LogicalMeter.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].
+
+    The SDK creates the formulas by analysing the configuration of components in the
+    {{glossary("Component Graph")}}.
+
+    ### Streaming Interface
+
+    The
+    [`FormulaEngine.new_receiver()`][frequenz.sdk.timeseries.formula_engine.FormulaEngine.new_receiver]
+    method can be used to create a
+    [Receiver](https://frequenz-floss.github.io/frequenz-channels-python/latest/reference/frequenz/channels/#frequenz.channels.Receiver)
+    that streams the [Sample][frequenz.sdk.timeseries.Sample]s calculated by the formula
+    engine.
+
+    ```python
+    from frequenz.sdk import microgrid
+
+    battery_pool = microgrid.battery_pool()
+
+    async for power in battery_pool.power.new_receiver():
+        print(f"{power=}")
+    ```
+
+    ### Composition
+
+    Composite `FormulaEngine`s can be built using arithmetic operations on
+    `FormulaEngine`s streaming the same type of data.
+
+    For example, if you're interested in a particular composite metric that can be
+    calculated by subtracting
+    [`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],
+    we can build a `FormulaEngine` that provides a stream of this calculated metric as
+    follows:
+
+    ```python
+    from frequenz.sdk import microgrid
+
+    logical_meter = microgrid.logical_meter()
+    battery_pool = microgrid.battery_pool()
+    ev_charger_pool = microgrid.ev_charger_pool()
+
+    # 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)
+    ).build("net_power")
+
+    async for power in net_power.new_receiver():
+        print(f"{power=}")
+    ```
+    """  # noqa: D400, D205
 
     def __init__(
         self,
@@ -356,11 +413,52 @@ class FormulaEngine3Phase(
         QuantityT,
     ]
 ):
-    """
-    The FormulaEngine evaluates formulas and streams the results.
+    """A
+    [`FormulaEngine3Phase`][frequenz.sdk.timeseries.formula_engine.FormulaEngine3Phase]
+    is similar to a
+    [`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],
+    [`EVChargerPool.current`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current],
+    etc.) are implemented as 3-phase formulas.
 
-    Use the `FormulaBuilder` to create `FormulaEngine` instances.
-    """
+    ### Streaming Interface
+
+    The
+    [`FormulaEngine3Phase.new_receiver()`][frequenz.sdk.timeseries.formula_engine.FormulaEngine3Phase.new_receiver]
+    method can be used to create a
+    [Receiver](https://frequenz-floss.github.io/frequenz-channels-python/latest/reference/frequenz/channels/#frequenz.channels.Receiver)
+    that streams the [Sample3Phase][frequenz.sdk.timeseries.Sample3Phase] values
+    calculated by the formula engine.
+
+    ```python
+    from frequenz.sdk import microgrid
+
+    ev_charger_pool = microgrid.ev_charger_pool()
+
+    async for sample in ev_charger_pool.current.new_receiver():
+        print(f"Current: {sample}")
+    ```
+
+    ### Composition
+
+    `FormulaEngine3Phase` instances can be composed together, just like `FormulaEngine`
+    instances.
+
+    ```python
+    from frequenz.sdk import microgrid
+
+    logical_meter = microgrid.logical_meter()
+    ev_charger_pool = microgrid.ev_charger_pool()
+
+    # 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")
+
+    async for sample in other_current.new_receiver():
+        print(f"Other current: {sample}")
+    ```
+    """  # noqa: D205, D400
 
     def __init__(
         self,

…imeseries/_formula_engine/_exceptions.py …timeseries/formula_engine/_exceptions.pysrc/frequenz/sdk/timeseries/_formula_engine/_exceptions.py renamed to src/frequenz/sdk/timeseries/formula_engine/_exceptions.py src/frequenz/sdk/timeseries/_formula_engine/_exceptions.py renamed to src/frequenz/sdk/timeseries/formula_engine/_exceptions.py

@@ -20,7 +20,7 @@
 
 if TYPE_CHECKING:
     # Break circular import by enclosing these type hints in a `TYPE_CHECKING` block.
-    from .._formula_engine import FormulaEngine, FormulaEngine3Phase
+    from ..formula_engine import FormulaEngine, FormulaEngine3Phase
 
 
 class FormulaEnginePool: