Rename parameter in_shifting_group → set_operating_point

This is part of the public interface in the constructors for the
`*_pool`s in the data pipeline, but other than that, all changes are
internal, except for the documentation.

This commit updates all occurrences, docstrings, documentation and
release notes to reflect the new name.

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

Author: shsms

RELEASE_NOTES.md

@@ -24,7 +24,7 @@
 
 ## New Features
 
-- Calls to `microgrid.*_pool` methods now accept an optional `in_shifting_group` parameter.  Power requests sent to `*_pool` instances that have the `in_shifting_group` flag set, will get resolved separately, and their target power will be added to the target power calculated from regular actors, if any, which would, in effect, shift the zero for the regular actors by the target power from the shifting group.
+- Calls to `microgrid.*_pool` methods now accept an optional `set_operating_point` parameter, for setting an operating point for the other actors.  This would shift the target power by the operating point before actually applying it to the components.
 
 ## Bug Fixes
 

src/frequenz/sdk/actor/_power_managing/_base_classes.py

@@ -33,8 +33,8 @@ class ReportRequest:
     priority: int
     """The priority of the actor ."""
 
-    in_shifting_group: bool
-    """Whether the proposal gets sent to the shifting group of the power manager."""
+    set_operating_point: bool
+    """Whether this proposal sets the operating point power or the normal power."""
 
     def get_channel_name(self) -> str:
         """Get the channel name for the report request.
@@ -219,8 +219,8 @@ class Proposal:
     request_timeout: datetime.timedelta = datetime.timedelta(seconds=5.0)
     """The maximum amount of time to wait for the request to be fulfilled."""
 
-    in_shifting_group: bool
-    """Whether the proposal gets sent to the shifting group of the power manager."""
+    set_operating_point: bool
+    """Whether this proposal sets the operating point power or the normal power."""
 
     def __lt__(self, other: Proposal) -> bool:
         """Compare two proposals by their priority.

src/frequenz/sdk/actor/_power_managing/_power_managing_actor.py

@@ -85,18 +85,18 @@ def __init__(  # pylint: disable=too-many-arguments
 
         self._system_bounds: dict[frozenset[int], SystemBounds] = {}
         self._bound_tracker_tasks: dict[frozenset[int], asyncio.Task[None]] = {}
-        self._non_shifting_subscriptions: dict[
+        self._set_power_subscriptions: dict[
             frozenset[int], dict[int, Sender[_Report]]
         ] = {}
-        self._shifting_subscriptions: dict[
+        self._set_op_power_subscriptions: dict[
             frozenset[int], dict[int, Sender[_Report]]
         ] = {}
         self._distribution_results: dict[frozenset[int], power_distributing.Result] = {}
 
-        self._non_shifting_group: BaseAlgorithm = Matryoshka(
+        self._set_power_group: BaseAlgorithm = Matryoshka(
             max_proposal_age=timedelta(seconds=60.0)
         )
-        self._shifting_group: BaseAlgorithm = Matryoshka(
+        self._set_op_power_group: BaseAlgorithm = Matryoshka(
             max_proposal_age=timedelta(seconds=60.0)
         )
 
@@ -113,25 +113,25 @@ async def _send_reports(self, component_ids: frozenset[int]) -> None:
         if bounds is None:
             _logger.warning("PowerManagingActor: No bounds for %s", component_ids)
             return
-        for priority, sender in self._shifting_subscriptions.get(
+        for priority, sender in self._set_op_power_subscriptions.get(
             component_ids, {}
         ).items():
-            status = self._shifting_group.get_status(
+            status = self._set_op_power_group.get_status(
                 component_ids,
                 priority,
                 bounds,
                 self._distribution_results.get(component_ids),
             )
             await sender.send(status)
-        for priority, sender in self._non_shifting_subscriptions.get(
+        for priority, sender in self._set_power_subscriptions.get(
             component_ids, {}
         ).items():
-            status = self._non_shifting_group.get_status(
+            status = self._set_power_group.get_status(
                 component_ids,
                 priority,
                 self._calculate_shifted_bounds(
                     bounds,
-                    self._shifting_group.get_target_power(component_ids),
+                    self._set_op_power_group.get_target_power(component_ids),
                 ),
                 self._distribution_results.get(component_ids),
             )
@@ -209,34 +209,34 @@ def _add_system_bounds_tracker(self, component_ids: frozenset[int]) -> None:
         )
 
     def _calculate_shifted_bounds(
-        self, bounds: SystemBounds, target_power: Power | None
+        self, bounds: SystemBounds, op_power: Power | None
     ) -> SystemBounds:
-        """Calculate the shifted bounds corresponding to shifting group's target power.
+        """Calculate the shifted bounds shifted by the operating point power.
 
         Any value regular actors choose within these bounds can be shifted by the
-        shifting power and still remain within the actual system bounds.
+        operating point power and still remain within the actual system bounds.
 
-          | system bounds |     shifting |    shifted |
-          |               | target power |     bounds |
-          |---------------+--------------+------------|
-          | -100 to 100   |           70 | -170 to 30 |
-          | -100 to 100   |          -50 | -50 to 150 |
+          | system bounds |   operating |    shifted |
+          |               | point power |     bounds |
+          |---------------+-------------+------------|
+          | -100 to 100   |          70 | -170 to 30 |
+          | -100 to 100   |         -50 | -50 to 150 |
 
         Args:
             bounds: The bounds to calculate the remaining bounds from.
-            target_power: The target power to apply.
+            op_power: The operating point power to shift by.
 
         Returns:
             The remaining bounds.
         """
-        if target_power is None:
+        if op_power is None:
             return bounds
 
         inclusion_bounds: Bounds[Power] | None = None
         if bounds.inclusion_bounds is not None:
             inclusion_bounds = Bounds(
-                bounds.inclusion_bounds.lower - target_power,
-                bounds.inclusion_bounds.upper - target_power,
+                bounds.inclusion_bounds.lower - op_power,
+                bounds.inclusion_bounds.upper - op_power,
             )
         return SystemBounds(
             timestamp=bounds.timestamp,
@@ -252,8 +252,7 @@ def _calculate_target_power(
     ) -> Power | None:
         """Calculate the target power for a set of components.
 
-        This is the power from the non-shifting group, shifted by the power from the
-        shifting group.
+        This is the target power, shifted by the operating point power.
 
         Args:
             component_ids: The component IDs for which to calculate the target power.
@@ -267,14 +266,14 @@ def _calculate_target_power(
         tgt_power_shift: Power | None = None
         tgt_power_no_shift: Power | None = None
         if proposal is not None:
-            if proposal.in_shifting_group:
-                tgt_power_shift = self._shifting_group.calculate_target_power(
+            if proposal.set_operating_point:
+                tgt_power_shift = self._set_op_power_group.calculate_target_power(
                     component_ids,
                     proposal,
                     self._system_bounds[component_ids],
                     must_send,
                 )
-                tgt_power_no_shift = self._non_shifting_group.calculate_target_power(
+                tgt_power_no_shift = self._set_power_group.calculate_target_power(
                     component_ids,
                     None,
                     self._calculate_shifted_bounds(
@@ -283,13 +282,13 @@ def _calculate_target_power(
                     must_send,
                 )
             else:
-                tgt_power_no_shift = self._non_shifting_group.calculate_target_power(
+                tgt_power_no_shift = self._set_power_group.calculate_target_power(
                     component_ids,
                     proposal,
                     self._system_bounds[component_ids],
                     must_send,
                 )
-                tgt_power_shift = self._shifting_group.calculate_target_power(
+                tgt_power_shift = self._set_op_power_group.calculate_target_power(
                     component_ids,
                     None,
                     self._calculate_shifted_bounds(
@@ -298,13 +297,13 @@ def _calculate_target_power(
                     must_send,
                 )
         else:
-            tgt_power_no_shift = self._non_shifting_group.calculate_target_power(
+            tgt_power_no_shift = self._set_power_group.calculate_target_power(
                 component_ids,
                 None,
                 self._system_bounds[component_ids],
                 must_send,
             )
-            tgt_power_shift = self._shifting_group.calculate_target_power(
+            tgt_power_shift = self._set_op_power_group.calculate_target_power(
                 component_ids,
                 None,
                 self._calculate_shifted_bounds(
@@ -378,12 +377,12 @@ async def _run(self) -> None:
                 sub = selected.message
                 component_ids = sub.component_ids
                 priority = sub.priority
-                in_shifting_group = sub.in_shifting_group
+                set_operating_point = sub.set_operating_point
 
                 subs_set = (
-                    self._shifting_subscriptions
-                    if in_shifting_group
-                    else self._non_shifting_subscriptions
+                    self._set_op_power_subscriptions
+                    if set_operating_point
+                    else self._set_power_subscriptions
                 )
 
                 if component_ids not in subs_set:
@@ -427,7 +426,9 @@ async def _run(self) -> None:
                 await self._send_reports(frozenset(result.request.component_ids))
 
             elif selected_from(selected, drop_old_proposals_timer):
-                self._non_shifting_group.drop_old_proposals(
+                self._set_power_group.drop_old_proposals(
+                    asyncio.get_event_loop().time()
+                )
+                self._set_op_power_group.drop_old_proposals(
                     asyncio.get_event_loop().time()
                 )
-                self._shifting_group.drop_old_proposals(asyncio.get_event_loop().time())

src/frequenz/sdk/microgrid/__init__.py

@@ -186,40 +186,39 @@
 [`propose_power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.propose_power]
 methods.
 
-### Shifting the target power by an offset
+### Shifting the target power by an Operating Point power
 
-There are cases where the target power needs to be shifted by a certain amount, for
-example, to make adjustments to the operating point.  This can be done by designating
-some actors to be part of the `shifting_group`.
+There are cases where the target power needs to be shifted by an operating point.  This
+can be done by designating some actors to be able to set only the operating point power.
 
 When creating a `*Pool` instance using the above-mentioned constructors, an optional
-`in_shifting_group` parameter can be passed to specify that this actor is special, and
-the target power of the regular actors will be shifted by the target power of all
-shifting actors together.
+`set_operating_point` parameter can be passed to specify that this actor is special, and
+the target power of the regular actors will be shifted by the target power of all actors
+with `set_operating_point` together.
 
-In a location with 2 regular actors and 1 shifting actor, here's how things
+In a location with 2 regular actors and 1 `set_operating_point` actor, here's how things
 would play out:
 
-1. When only non-shifting actors have made proposals, the power bounds available
-   from the batteries are available to them exactly.
+1. When only regular actors have made proposals, the power bounds available from the
+   batteries are available to them exactly.
 
-   | actor priority | in shifting group? | proposed power/bounds | available bounds |
-   |----------------|--------------------|-----------------------|------------------|
-   | 3              | No                 | 1000, -4000..2500     | -3000..3000      |
-   | 2              | No                 | 2500                  | -3000..2500      |
-   | 1              | Yes                | None                  | -3000..3000      |
+   | actor priority | in op group? | proposed power/bounds | available bounds |
+   |----------------|--------------|-----------------------|------------------|
+   | 3              | No           | 1000, -4000..2500     | -3000..3000      |
+   | 2              | No           | 2500                  | -3000..2500      |
+   | 1              | Yes          | None                  | -3000..3000      |
 
    Power actually distributed to the batteries: 2500W
 
-2. When the shifting actor has made proposals, the bounds available to the
-   regular actors gets shifted, and the final power that actually gets
-   distributed to the batteries is also shifted.
+2. When the `set_operating_point` actor has made proposals, the bounds available to the
+   regular actors gets shifted, and the final power that actually gets distributed to
+   the batteries is also shifted.
 
-   | actor priority | in shifting group? | proposed power/bounds | available bounds |
-   |----------------|--------------------|-----------------------|------------------|
-   | 3              | No                 | 1000, -4000..2500     | -2000..4000      |
-   | 2              | No                 | 2500                  | -2000..2500      |
-   | 1              | Yes                | -1000                 | -3000..3000      |
+   | actor priority | in op group? | proposed power/bounds | available bounds |
+   |----------------|--------------|-----------------------|------------------|
+   | 3              | No           | 1000, -4000..2500     | -2000..4000      |
+   | 2              | No           | 2500                  | -2000..2500      |
+   | 1              | Yes          | -1000                 | -3000..3000      |
 
    Power actually distributed to the batteries: 1500W
 """  # noqa: D205, D400