Merge pull request #783 from ie3-institute/sp/#774-em-documentation

EmAgent documentation for related protocols and algorithms

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implemented scaling of all relevant input parameters [#764](https://github.com/ie3-institute/simona/issues/764)
 - Consider scaling factor with flex options [#734](https://github.com/ie3-institute/simona/issues/734)
 - Implementation of Energy Management Agents [#204](https://github.com/ie3-institute/simona/issues/204)
+- Providing documentation for EmAgent protocols and algorithms [#774](https://github.com/ie3-institute/simona/issues/774)
 
 ### Changed
 - Adapted to changed data source in PSDM [#435](https://github.com/ie3-institute/simona/issues/435)

docs/readthedocs/models.md

@@ -32,6 +32,7 @@ models/hp_model
 models/load_model
 models/pv_model
 models/wec_model
+models/em
 ```
 
 ## Measurement and Control

docs/readthedocs/models/em.md

@@ -0,0 +1,38 @@
+(em)=
+
+# Energy Management
+
+Energy Management Agents (EmAgents) control power feed-in and load of system participants or other EmAgents in a hierarchical fashion.
+
+## Protocol
+
+During simulation, EmAgents send `RequestFlexOptions` and `IssueFlexControl` messages and receive `ProvideFlexOptions` and `FlexCompletion` messages.
+After having been requested to calculate flex options via `RequestFlexOptions`, controllable assets send back their flex options to the controlling unit using `ProvideFlexOptions`. 
+Eventually the controlling EmAgent responds with some type of `IssueFlexControl` messages, setting a power set point for operation.
+The asset then tries to realize the set power as best as it can and replies with a `FlexCompletion` messages.
+If an EmAgent is itself controlled by another EmAgent, it also behaves like a system participant (sends `RequestFlexOptions` and `IssueFlexControl` messages etc.).
+
+
+Every EmAgent aggregates flex options and power of its connected assets and disaggregates flex control among the connected assets. 
+It also functions as a scheduler for all connected assets by processing information on the ticks of the next desired activations and conveying such information to the controlling EmAgent or a central scheduler respectively.
+
+Uncontrolled EmAgents answer to a scheduler with regards to their activation.
+
+![](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/ie3-institute/simona/dev/docs/uml/protocol/em/UncontrolledEm.puml)
+
+Controlled EmAgents are scheduled and activated by another EmAgent, which is thus placed higher up in hierarchy.
+
+![](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/ie3-institute/simona/dev/docs/uml/protocol/em/ControlledEm.puml)
+
+## Model strategies
+
+When disaggregating flex control, a multitude of strategies is conceivable.
+An exemplary implemented strategy is the prioritized flex strategy, which prioritizes flexibility usage by asset type.
+For each asset type, flexibility can only be used if such an asset is actually connected and able to provide the requested flexibility.
+Otherwise, the next asset type is automatically considered.
+
+An excess feed-in should be reduced by either decreasing feed-in or increasing load, first the charging power of connected EVs is increased, then connected battery storage is charged, then the heat pump might be turned on and finally renewables (PV and WEC) are curtailed.
+If an excess load is detected, first connected battery storage is discharged, after which the batteries of connected EVs might be discharged, while finally a running heat pump might be turned off.
+As stated above, asset types that are not connected are skipped.
+
+![](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/ie3-institute/simona/dev/docs/uml/main/em/PrioritizedFlexStrat.puml)

docs/uml/main/em/PrioritizedFlexStrat.puml

@@ -0,0 +1,59 @@
+@startuml
+'https://plantuml.com/activity-diagram-beta
+
+start
+
+if () then (excess feed-in)
+  if (EVCS exists?) then (yes)
+    :asset = EVCS;
+    (A)
+  endif
+  if (Battery exists?) then (yes)
+    :asset = Battery;
+    (A)
+  endif
+  if (Heat pump exists?) then (yes)
+    :asset = Heat pump;
+    (A)
+  endif
+  if (PV exists?) then (yes)
+    :asset = PV;
+    (A)
+  endif
+  if (WEC exists?) then (yes)
+    :asset = WEC;
+    (A)
+  endif
+else (excess load)
+  if (Battery exists?) then (yes)
+    :asset = Battery;
+    (A)
+  endif
+  if (EVCS exists?) then (yes)
+    :asset = EVCS;
+    (A)
+  endif
+  if (Heat pump exists?) then (yes)
+    :asset = Heat pump;
+    (A)
+  endif
+endif
+
+stop
+
+(A)
+if (flexibility demand already satisfied?) then (no)
+  if (asset offers flexibility) then (yes)
+    if (flexibility covers demand) then (fully)
+      :remainingDemand = 0;
+    else (partially)
+      :remainingDemand -= flex;
+    endif
+  else (no)
+  endif
+else (yes)
+endif
+
+stop
+
+@enduml

docs/uml/protocol/em/ControlledEm.puml

@@ -0,0 +1,128 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+' set fixed order
+participant Scheduler
+participant EmAgent1
+participant EmAgent2
+participant PvAgent
+participant StorageAgent
+participant WeatherService
+
+autonumber
+
+==Init==
+
+PvAgent -> WeatherService: RegisterForWeatherMessage
+activate PvAgent
+activate WeatherService
+PvAgent -> EmAgent2: RegisterParticipant
+deactivate PvAgent
+
+WeatherService -> PvAgent: RegistrationSuccessfulMessage
+deactivate WeatherService
+activate PvAgent
+PvAgent -> EmAgent2: ScheduleFlexRequest(tick=0)
+deactivate PvAgent
+activate EmAgent2
+
+EmAgent2 -> EmAgent1: ScheduleFlexRequest(tick=0)
+deactivate EmAgent2
+activate EmAgent1
+EmAgent1 -> Scheduler: ScheduleActivation(tick=0)
+deactivate EmAgent1
+
+StorageAgent -> EmAgent2: RegisterParticipant
+StorageAgent -> EmAgent2: ScheduleFlexRequest(tick=0)
+
+note left
+EmAgent2 has already been
+scheduled for tick 0, thus
+we don't do it again here
+end note
+
+==Tick 0==
+
+Scheduler -> WeatherService: Activation(tick=0)
+activate WeatherService
+
+WeatherService -> PvAgent: ProvideWeatherMessage
+
+WeatherService -> Scheduler: Completion(nextTick=0)
+deactivate WeatherService
+
+Scheduler -> EmAgent1: Activation(tick=0)
+activate EmAgent1
+
+EmAgent1 -> EmAgent2: RequestFlexOptions(tick=0)
+activate EmAgent2
+
+EmAgent2 -> StorageAgent: RequestFlexOptions(tick=0)
+activate StorageAgent
+
+EmAgent2 -> PvAgent: RequestFlexOptions(tick=0)
+activate PvAgent
+
+PvAgent -> EmAgent2: ProvideFlexOptions
+deactivate PvAgent
+
+StorageAgent -> EmAgent2: ProvideFlexOptions
+deactivate StorageAgent
+
+EmAgent2 -> EmAgent1: ProvideFlexOptions
+deactivate EmAgent2
+
+EmAgent1 -> EmAgent2: IssuePowerControl(tick=0)
+activate EmAgent2
+
+EmAgent2 -> PvAgent: IssueNoControl(tick=0)
+activate PvAgent
+
+EmAgent2 -> StorageAgent: IssuePowerControl(tick=0)
+activate StorageAgent
+
+PvAgent -> EmAgent2: FlexCompletion(nextTick=3600)
+deactivate PvAgent
+
+StorageAgent -> EmAgent2: FlexCompletion(nextTick=1805)
+deactivate StorageAgent
+
+EmAgent2 -> EmAgent1: FlexCompletion(nextTick=1805)
+deactivate EmAgent2
+
+EmAgent1 -> Scheduler: Completion(nextTick=1805)
+deactivate EmAgent1
+
+==Tick 1805==
+
+Scheduler -> EmAgent1: Activation(tick=1805)
+activate EmAgent1
+
+EmAgent1 -> EmAgent2: RequestFlexOptions(tick=1805)
+activate EmAgent2
+
+EmAgent2 -> StorageAgent: RequestFlexOptions(tick=1805)
+activate StorageAgent
+
+StorageAgent -> EmAgent2: ProvideFlexOptions
+deactivate StorageAgent
+
+EmAgent2 -> EmAgent1: ProvideFlexOptions
+deactivate EmAgent2
+
+EmAgent1 -> EmAgent2: IssuePowerControl(tick=1805)
+activate EmAgent2
+
+EmAgent2 -> StorageAgent: IssuePowerControl(tick=1805)
+activate StorageAgent
+
+StorageAgent -> EmAgent2: FlexCompletion(nextTick=10800)
+deactivate StorageAgent
+
+EmAgent2 -> EmAgent1: FlexCompletion(nextTick=3600)
+deactivate EmAgent2
+
+EmAgent1 -> Scheduler: Completion(nextTick=3600)
+deactivate EmAgent1
+
+@enduml

docs/uml/protocol/em/UncontrolledEm.puml

@@ -0,0 +1,80 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+' set fixed order
+participant Scheduler
+participant EmAgent
+participant PvAgent
+participant StorageAgent
+participant WeatherService
+
+autonumber
+
+==Init==
+
+PvAgent -> WeatherService: RegisterForWeatherMessage
+activate PvAgent
+activate WeatherService
+PvAgent -> EmAgent: RegisterParticipant
+deactivate PvAgent
+
+WeatherService -> PvAgent: RegistrationSuccessfulMessage
+deactivate WeatherService
+activate PvAgent
+PvAgent -> EmAgent: ScheduleFlexRequest(tick=0)
+deactivate PvAgent
+activate EmAgent
+
+EmAgent -> Scheduler: ScheduleActivation(tick=0)
+deactivate EmAgent
+
+StorageAgent -> EmAgent: RegisterParticipant
+StorageAgent -> EmAgent: ScheduleFlexRequest(tick=0)
+
+note left
+EmAgent has already been
+scheduled for tick 0, thus
+we don't do it again here
+end note
+
+==Tick 0==
+
+Scheduler -> WeatherService: Activation(tick=0)
+activate WeatherService
+
+WeatherService -> PvAgent: ProvideWeatherMessage
+
+WeatherService -> Scheduler: Completion(nextTick=3600)
+deactivate WeatherService
+
+Scheduler -> EmAgent: Activation(tick=0)
+activate EmAgent
+
+EmAgent -> StorageAgent: RequestFlexOptions(tick=0)
+activate StorageAgent
+
+EmAgent -> PvAgent: RequestFlexOptions(tick=0)
+activate PvAgent
+
+PvAgent -> EmAgent: ProvideFlexOptions
+deactivate PvAgent
+
+StorageAgent -> EmAgent: ProvideFlexOptions
+deactivate StorageAgent
+
+EmAgent -> PvAgent: IssueNoControl(tick=0)
+activate PvAgent
+
+EmAgent -> StorageAgent: IssuePowerControl(tick=0)
+activate StorageAgent
+
+PvAgent -> EmAgent: FlexCompletion(nextTick=3600)
+deactivate PvAgent
+
+StorageAgent -> EmAgent: FlexCompletion(nextTick=8400)
+deactivate StorageAgent
+
+EmAgent -> Scheduler: Completion(nextTick=3600)
+deactivate EmAgent
+
+@enduml