Improve docs for the FormulaEngine class

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

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

@@ -1,7 +1,13 @@
 # License: MIT
 # Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
-"""A formula engine for applying formulas."""
+"""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
 

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

@@ -203,11 +203,68 @@ class FormulaEngine(
         QuantityT,
     ],
 ):
-    """
-    The FormulaEngine evaluates formulas and streams the results.
-
-    Use the `FormulaBuilder` to create `FormulaEngine` instances.
-    """
+    """[`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.
+
+    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 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,