Update microgrid documentation with new power manager behaviour

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

Author: shsms

src/frequenz/sdk/microgrid/__init__.py

@@ -174,17 +174,132 @@
 controlling batteries, power could be distributed based on the `SoC` of the
 individual batteries, to keep the batteries in balance.
 
-### Resolving conflicting power proposals
+### How to work with other actors
 
-When there are multiple actors trying to control the same set of batteries, a
-target power is calculated based on the priorities of the actors making the
-requests.  Actors need to specify their priorities as parameters when creating
-the `*Pool` instances using the constructors mentioned above.
+If multiple actors are trying to control (by proposing power values) the same
+set of components, 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 algorithm used for resolving power conflicts based on actor priority can be
-found in the documentation for any of the
-[`propose_power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.propose_power]
-methods.
+The final target power can be accessed using the receiver returned from the
+[`power_status`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power_status]
+method available for all pools, which also streams the bounds that an actor
+should comply with, based on its priority.
+
+When designing actors to work with other actors, their interaction with other
+actors need to be planned.  When sending proposals, actors can either:
+
+- limit the available bounds for lower priority actors, or
+- shift the bounds available to lower priority actors by a specific value.
+
+#### Limiting bounds for lower priority actors
+
+When an actor A calls the `propose_power` method with bounds (either both lower
+and upper bounds or at least one of them), lower priority actors will see their
+bounds restricted and can only set power values within that range.  If there are
+no lower priority actors or if none of them are proposing a power value, the
+target power set by actor A is used.
+
+*Example 1*: Battery bounds available for use: -100kW to 100kW
+
+| actor | priority | available bounds | request bounds | request power |
+|-------|----------|------------------|----------------|---------------|
+| A     | 3        | -100kW .. 100kW  | -20kW .. 100kW | 50kW          |
+| B     | 2        | -20kW .. 100kW   | -50kW .. 0kW   | -10kW         |
+| C     | 1        | -20kW .. 0kW     | None           | -20kW         |
+|       |          |                  | target power   | -20kW         |
+
+Actor A with the highest priority has the entire battery bounds available to it.
+It sets limited bounds of -20kW .. 100kW.  Actor B can only set powers within
+this range, but actor B overrides the power set by actor A.
+
+Actor B tries to limit the bounds of actor C to -50kW .. 0kW, but it can only
+operate in the -20kW .. 100kW range because of bounds set by actor A, so actor C
+sees -20kW .. 0kW.  Actor C proposes a power, so it overrides the power proposed
+by actor B as well.  Because there are no subsequent actors, the power set by
+actor C is used as the target power.
+
+*Example 2*:
+
+| actor | priority | available bounds | request bounds | request power |
+|-------|----------|------------------|----------------|---------------|
+| A     | 3        | -100kW .. 100kW  | -20kW .. 100kW | 50kW          |
+| B     | 2        | -20kW .. 100kW   | -50kW .. 0kW   | -10kW         |
+|       |          |                  | target power   | -10kW         |
+
+When there is no third actor, the second actor's power is the target power.
+
+*Example 3*:
+
+| actor | priority | available bounds | request bounds | request power |
+|-------|----------|------------------|----------------|---------------|
+| A     | 3        | -100kW .. 100kW  | -20kW .. 100kW | 50kW          |
+| B     | 2        | -20kW .. 100kW   | -50kW .. 0kW   | -50kW         |
+|       |          |                  | target power   | -20kW         |
+
+When an actor requests a power that's outside its available bounds, the closest
+available becomes the target power.
+
+#### Adding the power proposals of individual actors
+
+When an actor A calls the `propose_power` method with a power, but without any bounds (or
+passes None values for both lower and upper bounds), the proposed power of the lower
+priority actor will get added to actor A's power.  This works as follows: the lower
+priority actor would see bounds shifted by the power proposed by actor A.  After lower
+priority actor B sets a power, it will get shifted back by the power set by actor A.
+This has the effect of adding the powers set by actors A and B.
+
+*Example 1*: Battery bounds available for use: -100kW to 100kW
+
+| actor | priority | available bounds | request bounds | request power | cumulative power |
+|-------|----------|------------------|----------------|---------------|------------------|
+| A     | 3        | -100kW .. 100kW  | None           | 20kW          |                  |
+| B     | 2        | -120kW .. 80kW   | None           | 50kW          | 70kW             |
+| C     | 1        | -170kW .. 30kW   | None           | 50kW          | 100kW            |
+|       |          |                  |                | target power  | 100kW            |
+
+Actor A proposes a power of `20kW`, but no bounds.  In this case, actor B sees
+bounds shifted by A's proposal.  Actor B proposes a power of `50kW` on this
+shifted range, and if this is applied on to the original bounds (aka shift the
+bounds back to the original range), it would be `20kW + 50kW = 70kW`.
+
+So Actor C sees bounds shifted by `70kW` from the original bounds, and sets
+`50kW` on this shifted range, but it can't exceed `30kW`, so its request gets
+limited to 30kW.  Shifting this back by `70kW`, the target power is calculated
+to be `100kW`.
+
+Irrespective of what any actor sets, the final power won't exceed the available
+battery bounds.
+
+*Example 2*:
+
+| actor | priority | available bounds | request bounds | request power | cumulative power |
+|-------|----------|------------------|----------------|---------------|------------------|
+| A     | 3        | -100kW .. 100kW  | None           | 20kW          |                  |
+| B     | 2        | -120kW .. 80kW   | None           | -20kW         | 0kW              |
+|       |          |                  |                | target power  | 0kW              |
+
+Actors with exactly opposite requests cancel each other out.
+
+
+#### Comprehensive example
+
+Battery bounds available for use: -100kW to 100kW
+
+| pri | available bounds | req bounds     | req power | s/l    | power in range | cumulative power |
+|-----|------------------|----------------|-----------|--------|----------------|------------------|
+| 7   | -100kW .. 100kW  | None           | 10kW      | shifts | 10kW           | 10kW             |
+| 6   | -110kW .. 90kW   | -110kW .. 80kW | 10kW      | limits |                |                  |
+| 5   | -110kW .. 80kW   | -100kW .. 80kW | 80kW      | limits |                |                  |
+| 4   | -100kW .. 80kW   | None           | -120kW    | shifts | -100kW         | -90kW            |
+| 3   | 0kW .. 180kW     | None           | 60kW      | shifts | 60kW           | -30kW            |
+| 2   | -60kW .. 120kW   | -40kW .. 30kW  | 20kW      | limits |                |                  |
+| 1   | -40kW .. 30kW    | None           | 12kW      | shifts | 12kW           | -18kW            |
+| 0   | -52kW .. 18kW    | -40kW .. -10kW | -10kW     | limits | -10kW          | -28kW            |
+|     |                  |                |           |        | target power   | -28kW            |
+
+In this example, there are some shifting and some limiting actors, and each of
+them affect the lower priority actors in the same patterns mentioned above.
 """  # noqa: D205, D400
 
 from datetime import timedelta