Improve naming for per-phase component metric streams (#987)

Closes #880

Author: shsms

RELEASE_NOTES.md

@@ -11,6 +11,12 @@
   + `ev_charger_pool` -> `new_ev_charger_pool`
   + `pv_pool` -> `new_pv_pool`
 
+- The following component metric streams have been renamed to clarify that they stream per-phase values:
+  + `frequenz.sdk.microgrid.`
+    * `voltage` -> `voltage_per_phase`
+    * `grid.current` -> `grid.current_per_phase`
+    * `ev_charger_pool.current` -> `ev_charger_pool.current_per_phase`
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->

src/frequenz/sdk/actor/power_distributing/_component_managers/_ev_charger_manager/_ev_charger_manager.py

@@ -55,7 +55,7 @@ def __init__(
         self._ev_charger_ids = self._get_ev_charger_ids()
         self._evc_states = EvcStates()
         self._voltage_cache: LatestValueCache[Sample3Phase[Voltage]] = LatestValueCache(
-            microgrid.voltage().new_receiver(),
+            microgrid.voltage_per_phase().new_receiver(),
             unique_id=f"{type(self).__name__}«{hex(id(self))}»:voltage_cache",
         )
         self._config = EVDistributionConfig(component_ids=self._ev_charger_ids)

src/frequenz/sdk/microgrid/__init__.py

@@ -234,7 +234,7 @@
     new_ev_charger_pool,
     new_pv_pool,
     producer,
-    voltage,
+    voltage_per_phase,
 )
 
 
@@ -263,5 +263,5 @@ async def initialize(server_url: str, resampler_config: ResamplerConfig) -> None
     "new_ev_charger_pool",
     "new_pv_pool",
     "producer",
-    "voltage",
+    "voltage_per_phase",
 ]

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -139,8 +139,8 @@ def frequency(self) -> GridFrequency:
 
         return self._frequency_instance
 
-    def voltage(self) -> VoltageStreamer:
-        """Return the 3-phase voltage measuring point."""
+    def voltage_per_phase(self) -> VoltageStreamer:
+        """Return the per-phase voltage measuring point."""
         if not self._voltage_instance:
             self._voltage_instance = VoltageStreamer(
                 self._resampling_request_sender(),
@@ -506,9 +506,9 @@ def frequency() -> GridFrequency:
     return _get().frequency()
 
 
-def voltage() -> VoltageStreamer:
-    """Return the 3-phase voltage measuring point."""
-    return _get().voltage()
+def voltage_per_phase() -> VoltageStreamer:
+    """Return the per-phase voltage measuring point."""
+    return _get().voltage_per_phase()
 
 
 def logical_meter() -> LogicalMeter:

src/frequenz/sdk/timeseries/_voltage_streamer.py

@@ -44,7 +44,7 @@ class VoltageStreamer:
         )
 
         # Get a receiver for the phase-to-neutral voltage.
-        voltage_recv = microgrid.voltage().new_receiver()
+        voltage_recv = microgrid.voltage_per_phase().new_receiver()
 
         async for voltage_sample in voltage_recv:
             print(voltage_sample)

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

@@ -33,8 +33,8 @@ class EVChargerPool:
 
     Provides:
       - Aggregate [`power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.power]
-        and 3-phase
-        [`current`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current]
+        and
+        [`current_per_phase`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current_per_phase]
         measurements of the EV Chargers in the pool.
     """
 
@@ -147,7 +147,7 @@ def component_ids(self) -> abc.Set[int]:
         return self._pool_ref_store.component_ids
 
     @property
-    def current(self) -> FormulaEngine3Phase[Current]:
+    def current_per_phase(self) -> FormulaEngine3Phase[Current]:
         """Fetch the total current for the EV Chargers in the pool.
 
         This formula produces values that are in the Passive Sign Convention (PSC).

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

@@ -443,9 +443,9 @@ 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
-    [`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.
+    [`Grid.current_per_phase`][frequenz.sdk.timeseries.grid.Grid.current_per_phase],
+    [`EVChargerPool.current_per_phase`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current_per_phase],
+    etc.) are implemented as per-phase formulas.
 
     ### Streaming Interface
 
@@ -461,7 +461,7 @@ class FormulaEngine3Phase(
 
     ev_charger_pool = microgrid.new_ev_charger_pool(priority=5)
 
-    async for sample in ev_charger_pool.current.new_receiver():
+    async for sample in ev_charger_pool.current_per_phase.new_receiver():
         print(f"Current: {sample}")
     ```
 
@@ -478,7 +478,9 @@ class FormulaEngine3Phase(
     grid = microgrid.grid()
 
     # Calculate grid consumption current that's not used by the EV chargers
-    other_current = (grid.current - ev_charger_pool.current).build("other_current")
+    other_current = (grid.current_per_phase - ev_charger_pool.current_per_phase).build(
+        "other_current"
+    )
 
     async for sample in other_current.new_receiver():
         print(f"Other current: {sample}")

src/frequenz/sdk/timeseries/grid.py

@@ -99,8 +99,8 @@ def power(self) -> FormulaEngine[Power]:
         return engine
 
     @property
-    def _power_3_phase(self) -> FormulaEngine3Phase[Power]:
-        """Fetch the grid 3-phase power for the microgrid.
+    def _power_per_phase(self) -> FormulaEngine3Phase[Power]:
+        """Fetch the per-phase grid power for the microgrid.
 
         This formula produces values that are in the Passive Sign Convention (PSC).
 
@@ -117,8 +117,8 @@ def _power_3_phase(self) -> FormulaEngine3Phase[Power]:
         return engine
 
     @property
-    def current(self) -> FormulaEngine3Phase[Current]:
-        """Fetch the grid current for the microgrid.
+    def current_per_phase(self) -> FormulaEngine3Phase[Current]:
+        """Fetch the per-phase grid current for the microgrid.
 
         This formula produces values that are in the Passive Sign Convention (PSC).
 

tests/microgrid/test_grid.py

@@ -200,8 +200,8 @@ async def test_grid_power_3_phase_side_meter(mocker: MockerFixture) -> None:
         assert grid, "Grid is not initialized"
         stack.push_async_callback(grid.stop)
 
-        grid_power_3_phase_recv = (
-            grid._power_3_phase.new_receiver()  # pylint: disable=protected-access
+        grid_power_per_phase_recv = (
+            grid._power_per_phase.new_receiver()  # pylint: disable=protected-access
         )
 
         for count in range(10):
@@ -216,7 +216,7 @@ async def test_grid_power_3_phase_side_meter(mocker: MockerFixture) -> None:
                 [watts_phases, watts_phases]
             )
 
-            val = await grid_power_3_phase_recv.receive()
+            val = await grid_power_per_phase_recv.receive()
             assert val is not None
             assert val.value_p1 and val.value_p2 and val.value_p3
             assert val.value_p1.as_watts() == watts_phases[0]
@@ -234,8 +234,8 @@ async def test_grid_power_3_phase_none_values(mocker: MockerFixture) -> None:
         assert grid, "Grid is not initialized"
         stack.push_async_callback(grid.stop)
 
-        grid_power_3_phase_recv = (
-            grid._power_3_phase.new_receiver()  # pylint: disable=protected-access
+        grid_power_per_phase_recv = (
+            grid._power_per_phase.new_receiver()  # pylint: disable=protected-access
         )
 
         for count in range(10):
@@ -250,7 +250,7 @@ async def test_grid_power_3_phase_none_values(mocker: MockerFixture) -> None:
                 [watts_phases, [None, None, None], [None, 219.8, 220.2]]
             )
 
-            val = await grid_power_3_phase_recv.receive()
+            val = await grid_power_per_phase_recv.receive()
             assert val is not None
             assert val.value_p1 and val.value_p2 and val.value_p3
             assert val.value_p1.as_watts() == watts_phases[0]

tests/timeseries/_formula_engine/test_formula_composition.py

@@ -428,10 +428,12 @@ async def test_3_phase_formulas(self, mocker: MockerFixture) -> None:
             grid = microgrid.grid()
             stack.push_async_callback(grid.stop)
 
-            grid_current_recv = grid.current.new_receiver()
-            ev_current_recv = ev_pool.current.new_receiver()
+            grid_current_recv = grid.current_per_phase.new_receiver()
+            ev_current_recv = ev_pool.current_per_phase.new_receiver()
 
-            engine = (grid.current - ev_pool.current).build("net_current")
+            engine = (grid.current_per_phase - ev_pool.current_per_phase).build(
+                "net_current"
+            )
             stack.push_async_callback(engine._stop)  # pylint: disable=protected-access
             net_current_recv = engine.new_receiver()