Update propose_power docs to refer to microgrid docs

With this we only have to write the details on how the power manager
works only once.

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

Author: shsms

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

@@ -89,35 +89,17 @@ async def propose_power(
         Power values need to follow the Passive Sign Convention (PSC). That is, positive
         values indicate charge power and negative values indicate discharge power.
 
-        If the same batteries are shared by multiple actors, the power manager will
-        consider the priority of the actors, the bounds they set, and their preferred
-        power, when calculating the target power for the batteries.
-
-        The preferred power of lower priority actors will take precedence as long as
-        they respect the bounds set by higher priority actors.  If lower priority actors
-        request power values outside of the bounds set by higher priority actors, the
-        target power will be the closest value to the preferred power that is within the
-        bounds.
-
-        When there are no other actors trying to use the same batteries, the actor's
-        preferred power would be set as the target power, as long as it falls within the
-        system power bounds for the batteries.
-
-        The result of the request can be accessed using the receiver returned from the
-        [`power_status`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power_status]
-        method, which also streams the bounds that an actor should comply with, based on
-        its priority.
+        Details on how the power manager handles proposals can be found in the
+        [Microgrid][frequenz.sdk.microgrid--setting-power] documentation.
 
         Args:
             power: The power to propose for the batteries in the pool.  If `None`, this
                 proposal will not have any effect on the target power, unless bounds are
-                specified.  If both are `None`, it is equivalent to not having a
-                proposal or withdrawing a previous one.
-            bounds: The power bounds for the proposal.  These bounds will apply to
-                actors with a lower priority, and can be overridden by bounds from
-                actors with a higher priority.  If None, the power bounds will be set
-                to the maximum power of the batteries in the pool.  This is currently
-                and experimental feature.
+                specified.  When specified without bounds, bounds for lower priority
+                actors will be shifted by this power.  If both are `None`, it is
+                equivalent to not having a proposal or withdrawing a previous one.
+            bounds: The power bounds for the proposal.  When specified, this will limit
+                the bounds for lower priority actors.
         """
         await self._pool_ref_store._power_manager_requests_sender.send(
             _power_managing.Proposal(
@@ -140,13 +122,9 @@ async def propose_charge(self, power: Power | None) -> None:
         method might be more convenient.
 
         If the same batteries are shared by multiple actors, the behaviour is the same
-        as that of the `propose_power` method.  The bounds for lower priority actors
-        can't be specified with this method.  If that's required, use the
-        `propose_power` method instead.
-
-        The result of the request can be accessed using the receiver returned from the
-        [`power_status`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power_status]
-        method.
+        as that of the `propose_power` method, when calling it with `None` bounds.  The
+        bounds for lower priority actors can't be specified with this method.  If that's
+        required, use the `propose_power` method instead.
 
         Args:
             power: The unsigned charge power to propose for the batteries in the pool.
@@ -179,13 +157,9 @@ async def propose_discharge(self, power: Power | None) -> None:
         method might be more convenient.
 
         If the same batteries are shared by multiple actors, the behaviour is the same
-        as that of the `propose_power` method.  The bounds for lower priority actors
-        can't be specified with this method.  If that's required, use the
-        `propose_power` method instead.
-
-        The result of the request can be accessed using the receiver returned from the
-        [`power_status`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power_status]
-        method.
+        as that of the `propose_power` method, when calling it with `None` bounds.  The
+        bounds for lower priority actors can't be specified with this method.  If that's
+        required, use the `propose_power` method instead.
 
         Args:
             power: The unsigned discharge power to propose for the batteries in the

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

@@ -77,39 +77,17 @@ async def propose_power(
         the pool.  The actual consumption might be lower based on the number of phases
         an EV is drawing power from, and its current state of charge.
 
-        Power values need to follow the Passive Sign Convention (PSC). That is, positive
-        values indicate charge power and negative values indicate discharge power.
-        Discharging from EV chargers is currently not supported.
-
-        If the same EV chargers are shared by multiple actors, the power manager will
-        consider the priority of the actors, the bounds they set, and their preferred
-        power, when calculating the target power for the EV chargers
-
-        The preferred power of lower priority actors will take precedence as long as
-        they respect the bounds set by higher priority actors.  If lower priority actors
-        request power values outside of the bounds set by higher priority actors, the
-        target power will be the closest value to the preferred power that is within the
-        bounds.
-
-        When there are no other actors trying to use the same EV chargers, the actor's
-        preferred power would be set as the target power, as long as it falls within the
-        system power bounds for the EV chargers.
-
-        The result of the request can be accessed using the receiver returned from the
-        [`power_status`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.power_status]
-        method, which also streams the bounds that an actor should comply with, based on
-        its priority.
+        Details on how the power manager handles proposals can be found in the
+        [Microgrid][frequenz.sdk.microgrid--setting-power] documentation.
 
         Args:
             power: The power to propose for the EV chargers in the pool.  If `None`,
                 this proposal will not have any effect on the target power, unless
-                bounds are specified.  If both are `None`, it is equivalent to not
-                having a proposal or withdrawing a previous one.
-            bounds: The power bounds for the proposal.  These bounds will apply to
-                actors with a lower priority, and can be overridden by bounds from
-                actors with a higher priority.  If None, the power bounds will be set to
-                the maximum power of the batteries in the pool.  This is currently and
-                experimental feature.
+                bounds are specified.  When specified without bounds, bounds for lower
+                priority actors will be shifted by this power.  If both are `None`, it
+                is equivalent to not having a proposal or withdrawing a previous one.
+            bounds: The power bounds for the proposal. When specified, these bounds will
+                limit the bounds for lower priority actors.
 
         Raises:
             EVChargerPoolError: If a discharge power for EV chargers is requested.

src/frequenz/sdk/timeseries/pv_pool/_pv_pool.py

@@ -58,7 +58,6 @@ def __init__(  # pylint: disable=too-many-arguments
     async def propose_power(
         self,
         power: Power | None,
-        *,
         bounds: Bounds[Power | None] = Bounds(None, None),
     ) -> None:
         """Send a proposal to the power manager for the pool's set of PV inverters.
@@ -67,38 +66,20 @@ async def propose_power(
         the pool.  The actual production might be lower.
 
         Power values need to follow the Passive Sign Convention (PSC). That is, positive
-        values indicate charge power and negative values indicate discharge power.
-        Only discharge powers are allowed for PV inverters.
-
-        If the same PV inverters are shared by multiple actors, the power manager will
-        consider the priority of the actors, the bounds they set, and their preferred
-        power, when calculating the target power for the PV inverters.
-
-        The preferred power of lower priority actors will take precedence as long as
-        they respect the bounds set by higher priority actors.  If lower priority actors
-        request power values outside of the bounds set by higher priority actors, the
-        target power will be the closest value to the preferred power that is within the
-        bounds.
-
-        When there are no other actors trying to use the same PV inverters, the actor's
-        preferred power would be set as the target power, as long as it falls within the
-        system power bounds for the PV inverters.
+        values indicate charge power and negative values indicate discharge power.  Only
+        discharge powers are allowed for PV inverters.
 
-        The result of the request can be accessed using the receiver returned from the
-        [`power_status`][frequenz.sdk.timeseries.pv_pool.PVPool.power_status]
-        method, which also streams the bounds that an actor should comply with, based on
-        its priority.
+        Details on how the power manager handles proposals can be found in the
+        [Microgrid][frequenz.sdk.microgrid--setting-power] documentation.
 
         Args:
             power: The power to propose for the PV inverters in the pool.  If `None`,
                 this proposal will not have any effect on the target power, unless
-                bounds are specified.  If both are `None`, it is equivalent to not
-                having a proposal or withdrawing a previous one.
-            bounds: The power bounds for the proposal.  These bounds will apply to
-                actors with a lower priority, and can be overridden by bounds from
-                actors with a higher priority.  If None, the power bounds will be set to
-                the maximum power of the batteries in the pool.  This is currently and
-                experimental feature.
+                bounds are specified.  When speficied without bounds, bounds for lower
+                priority actors will be shifted by this power.  If both are `None`, it
+                is equivalent to not having a proposal or withdrawing a previous one.
+            bounds: The power bounds for the proposal.  When specified, this will limit
+                the bounds for lower priority actors.
 
         Raises:
             PVPoolError: If a charge power for PV inverters is requested.