Add formula power/current sign convention details to docstrings

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

Author: shsms

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

@@ -106,6 +106,8 @@ def battery_ids(self) -> Set[int]:
     def power(self) -> FormulaEngine:
         """Fetch the total power of the batteries in the pool.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate this metric is not already running, it will be
         started.
 
@@ -131,6 +133,8 @@ def power(self) -> FormulaEngine:
     def production_power(self) -> FormulaEngine:
         """Fetch the total production power of the batteries in the pool.
 
+        This formula produces positive values when producing power and 0 otherwise.
+
         If a formula engine to calculate this metric is not already running, it will be
         started.
 
@@ -156,6 +160,8 @@ def production_power(self) -> FormulaEngine:
     def consumption_power(self) -> FormulaEngine:
         """Fetch the total consumption power of the batteries in the pool.
 
+        This formula produces positive values when consuming power and 0 otherwise.
+
         If a formula engine to calculate this metric is not already running, it will be
         started.
 

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

@@ -109,6 +109,8 @@ def component_ids(self) -> abc.Set[int]:
     def current(self) -> FormulaEngine3Phase:
         """Fetch the total current for the EV Chargers in the pool.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate EV Charger current is not already running, it
         will be started.
 
@@ -131,6 +133,8 @@ def current(self) -> FormulaEngine3Phase:
     def power(self) -> FormulaEngine:
         """Fetch the total power for the EV Chargers in the pool.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate EV Charger power is not already running, it
         will be started.
 
@@ -156,6 +160,8 @@ def power(self) -> FormulaEngine:
     def production_power(self) -> FormulaEngine:
         """Fetch the total power produced by the EV Chargers in the pool.
 
+        This formula produces positive values when producing power and 0 otherwise.
+
         If a formula engine to calculate EV Charger power is not already running, it
         will be started.
 
@@ -181,6 +187,8 @@ def production_power(self) -> FormulaEngine:
     def consumption_power(self) -> FormulaEngine:
         """Fetch the total power consumed by the EV Chargers in the pool.
 
+        This formula produces positive values when consuming power and 0 otherwise.
+
         If a formula engine to calculate EV Charger power is not already running, it
         will be started.
 

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

@@ -139,6 +139,8 @@ def start_formula(
     def grid_power(self) -> FormulaEngine:
         """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.
 
@@ -159,6 +161,8 @@ def grid_power(self) -> FormulaEngine:
     def grid_consumption_power(self) -> FormulaEngine:
         """Fetch the grid consumption power for the microgrid.
 
+        This formula produces positive values when consuming power and 0 otherwise.
+
         If a formula engine to calculate grid consumption power is not already running,
         it will be started.
 
@@ -180,6 +184,8 @@ def grid_consumption_power(self) -> FormulaEngine:
     def grid_production_power(self) -> FormulaEngine:
         """Fetch the grid production power for the microgrid.
 
+        This formula produces positive values when producing power and 0 otherwise.
+
         If a formula engine to calculate grid production power is not already running,
         it will be started.
 
@@ -201,6 +207,8 @@ def grid_production_power(self) -> FormulaEngine:
     def grid_current(self) -> FormulaEngine3Phase:
         """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.
 
@@ -224,6 +232,8 @@ def consumer_power(self) -> FormulaEngine:
         Under normal circumstances this is expected to correspond to the gross
         consumption of the site excluding active parts and battery.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate consumer power is not already running, it will
         be started.
 
@@ -244,6 +254,8 @@ def consumer_power(self) -> FormulaEngine:
     def pv_power(self) -> FormulaEngine:
         """Fetch the PV power in the microgrid.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate PV power is not already running, it will be
         started.
 
@@ -265,6 +277,8 @@ def pv_power(self) -> FormulaEngine:
     def pv_production_power(self) -> FormulaEngine:
         """Fetch the PV power production in the microgrid.
 
+        This formula produces positive values when producing power and 0 otherwise.
+
         If a formula engine to calculate PV power production is not already running, it
         will be started.
 
@@ -286,6 +300,8 @@ def pv_production_power(self) -> FormulaEngine:
     def pv_consumption_power(self) -> FormulaEngine:
         """Fetch the PV power consumption in the microgrid.
 
+        This formula produces positive values when consuming power and 0 otherwise.
+
         If a formula engine to calculate PV power consumption is not already running, it
         will be started.
 
@@ -307,6 +323,8 @@ def pv_consumption_power(self) -> FormulaEngine:
     def chp_power(self) -> FormulaEngine:
         """Fetch the CHP power production in the microgrid.
 
+        This formula produces values that are in the Passive Sign Convention (PSC).
+
         If a formula engine to calculate CHP power production is not already running, it
         will be started.
 
@@ -328,6 +346,8 @@ def chp_power(self) -> FormulaEngine:
     def chp_production_power(self) -> FormulaEngine:
         """Fetch the CHP power production in the microgrid.
 
+        This formula produces positive values when producing power and 0 otherwise.
+
         If a formula engine to calculate CHP power production is not already running, it
         will be started.
 
@@ -351,6 +371,8 @@ def chp_production_power(self) -> FormulaEngine:
     def chp_consumption_power(self) -> FormulaEngine:
         """Fetch the CHP power consumption in the microgrid.
 
+        This formula produces positive values when consuming power and 0 otherwise.
+
         If a formula engine to calculate CHP power consumption is not already running,
         it will be started.