Adding basic congestion management.

CHANGELOG.md

@@ -41,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update/enhance config documentation [#1013](https://github.com/ie3-institute/simona/issues/1013)
 - Create `CITATION.cff` [#1035](https://github.com/ie3-institute/simona/issues/1035)
 - Introduce ThermalDemandWrapper [#1049](https://github.com/ie3-institute/simona/issues/1049)
+- Adding basic congestion management consisting of congestion detection and transformer tapping [#953](https://github.com/ie3-institute/simona/issues/943)
 
 ### Changed
 - Adapted to changed data source in PSDM [#435](https://github.com/ie3-institute/simona/issues/435)

docs/readthedocs/config.md

@@ -245,6 +245,7 @@ Tba:
 
 ## Grid configuration 
 
+### Reference System
 The reference system contains a list of voltage levels. Each element includes the nominal apparent power, the nominal 
 voltage and the separate configuration of each voltage level. The voltage level configuration is composed of the identifier 
 and the nominal voltage.
@@ -268,6 +269,32 @@ simona.gridConfig.refSystems = [
 Further typical voltage levels which can be used in the simulation and the configuration of individual reference systems
 are described in the documentation of [reference system](models/reference_system).
 
+### Voltage limits
+
+The voltage limits contains a list of voltage levels. Each element includes the minimal and maximal allowed voltage and
+the separate configuration of each voltage level. The voltage level configuration is composed of the identifier and the
+nominal voltage. 
+
+The configuration of a voltage limits is optional. If no configuration is provided by the user, the default
+[voltage limits](models/voltage_limits) that includes all common german voltage levels is used. For those users
+who need other voltage levels than the common german voltage levels or different voltage limits, they can configure
+their limits as shown below.
+
+The voltage limits can be configured as follows:
+
+```
+simona.gridConfig.voltageLimits = [
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Lv", vNom = "0.4 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Mv", vNom = "20 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Hv", vNom = "110 kV"}]},
+  {vMin = 0.9, vMax = 1.05, voltLvls = [{id = "EHV", vNom = "380 kV"}]},
+]
+```
+
+Further typical voltage levels which can be used in the simulation and the configuration of individual voltage limits
+are described in the documentation of [voltage limits](models/voltage_limits).
+
+
 ## Power flow configuration 
 
 Maximum allowed deviation in power between two sweeps, before overall convergence is assumed:
@@ -286,6 +313,23 @@ Resolution of the power flow calculation:
 
   `simona.powerflow.resolution = "3600s"`
 
+## Congestion Management configuration
+
+By default the congestion management is disabled. The congestion management can be enabled with:
+
+`simona.congestionManagement.enable = true`
+
+Also all steps are disabled by default. To use one or more of the steps, they have to be enabled:
+
+`simona.congestionManagement.enableTransformerTapping = true`
+`simona.congestionManagement.enableTopologyChanges = true`
+`simona.congestionManagement.enableUsingFlexOptions = true`
+
+Maximum number of optimization iterations:
+
+`simona.congestionManagement.maxOptimizationIterations = 2`
+
+
 ## Transformer Control Group configuration
 
 It's possible to add a voltage control function to a transformer or group of transformers. This requires measurements within the network to be under voltage control and at least one corresponding transformer.

docs/readthedocs/features.md

@@ -0,0 +1,19 @@
+(features)=
+
+# Features
+
+This page gives an overview of some additional features in SIMONA.
+
+## Congestion management
+
+The congestion management is an optional feature of SIMONA, that is run after a power flow calculation. It can be used
+for example to mitigate voltage congestions by tapping transformers.
+
+The procedures of the congestion management is as follows:
+
+![Procedure of the congestion management](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/ie3-institute/simona/dev/docs/uml/main/CongestionManagement.puml)
+
+The congestion management consists of the steps `Transformer tapping`, `Topology change` and `Using flexibilities`. By
+default all steps are disabled. If the congestion management is enabled without enabling any step, only the congestion
+detection is run. It can be configured, which steps the congestion management can use. After each step a simulation is
+run to incorporate the changes.

docs/readthedocs/index.md

@@ -17,6 +17,7 @@ about
 usersguide
 config
 models
+features
 developersguide
 references
 ```

docs/readthedocs/models.md

@@ -17,6 +17,7 @@ models/three_winding_transformer_model
 models/reference_system
 models/thermal_grid_model
 models/thermal_house_model
+models/voltage_limits
 ```
 
 ## System Participant Related Models

docs/readthedocs/models/measurement_control.md

@@ -2,4 +2,9 @@
 
 # Transformer Control Groups
 
-Transformer control group can be used to implement control functionalities like long-range control for active voltage stability. For this purpose, network areas and transformers can be logically linked to a control group via measuring points. If a deviation from the target voltage magnitude is detected at one of the measuring points, the transformer is switched to the appropriate tap position to solve the deviation, provided that no limit values are violated at other measuring points. This requires that only measuring points are included in control groups that can also be influenced by the associated transformer.
+Transformer control group can be used to implement control functionalities like long-range control for active voltage
+stability. For this purpose, network areas and transformers can be logically linked to a control group via measuring
+points. If a deviation from the target voltage magnitude is detected at one of the measuring points, the transformer is
+switched to the appropriate tap position to solve the deviation, provided that no limit values are violated at other
+measuring points. This requires that only measuring points are included in control groups that can also be influenced by
+the associated transformer.

docs/readthedocs/models/voltage_limits.md

@@ -0,0 +1,61 @@
+(voltage_limits)=
+
+# Voltage Limits
+
+The voltage limits are built up by specifying the included voltage levels. The following table describes typical network
+levels and the corresponding parameterization. They are primarily used for the optional congestion management.
+
+## Default voltage limits
+
+```{list-table}
+:widths: auto
+:header-rows: 1
+
+* - Voltage level (id)
+  - Minimal voltage (vMin)
+  - Maximal voltage (vMax)
+
+* - LV
+  - 0.9 p.u.
+  - 1.1 p.u.
+
+* - MV (10 kV)
+  - 0.9 p.u.
+  - 1.1 p.u.
+
+* - MV (20 kV)
+  - 0.9 p.u.
+  - 1.1 p.u.
+
+* - MV (30 kV)
+  - 0.9 p.u.
+  - 1.1 p.u.
+
+* - HV
+  - 0.9 p.u.
+  - 1.1 p.u.
+
+* - EHV (220 kV)
+  - 0.9 p.u.
+  - 1.118 p.u.
+
+* - EHV (380 kV)
+  - 0.9 p.u.
+  - 1.05 p.u.
+```
+
+
+## Configuration of the voltage limits
+
+To configure the voltage limits, the voltage levels listed in the table above must be selected and integrated into the
+config. The individual voltage level configuration (voltLvls) according to the example below. Each voltage level is composed
+of the identifier and the nominal voltage.
+
+```
+simona.gridConfig.voltageLimits = [
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Lv", vNom = "0.4 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Mv", vNom = "20 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Hv", vNom = "110 kV"}]},
+  {vMin = 0.9, vMax = 1.05, voltLvls = [{id = "EHV", vNom = "380 kV"}]},
+]
+```

docs/uml/main/CongestionManagement.puml

@@ -0,0 +1,54 @@
+@startuml
+'https://plantuml.com/activity-diagram-beta
+
+label main [{{
+start
+
+if (enable) then (true)
+repeat
+    (A)
+    detach
+    (B)
+
+    if (Congestion detected?) then (true)
+    else (false)
+        stop
+    endif
+
+repeat while (iteration < maxIteration)
+
+if (enableUsingFlexOptions) then (true)
+    :Using Flexibilities;
+    :Run Simulation;
+else (false)
+endif
+
+else (false)
+endif
+
+stop
+}}]
+
+label optimization [{{
+(A)
+if (enableTransformerTapping) then (true)
+    if (Voltage and/or line congestion detected?) then (true)
+        :Use transformer tapping;
+        :Run Simulation;
+    else (false)
+    endif
+else (false)
+endif
+
+if (enableTopologyChanges) then (true)
+        if (Line congestion detected?) then (true)
+        :Use topology changes;
+        :Run Simulation;
+    else (false)
+    endif
+else (false)
+endif
+(B)
+}}]
+
+@enduml

input/samples/vn_simona/vn_simona.conf

@@ -61,6 +61,7 @@ simona.output.grid = {
   switches = false
   transformers2w = false
   transformers3w = false
+  congestions = false
 }
 simona.output.participant.defaultConfig = {
   notifier = "default"
@@ -202,6 +203,13 @@ simona.gridConfig.refSystems = [
   {sNom = "1000 MVA", vNom = "380 kV", voltLvls = [{id = "EHV", vNom = "380 kV"}]}
 ]
 
+simona.gridConfig.voltageLimits = [
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Lv", vNom = "0.4 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Mv", vNom = "20 kV"}]},
+  {vMin = 0.9, vMax = 1.1, voltLvls = [{id = "Hv", vNom = "110 kV"}]},
+  {vMin = 0.9, vMax = 1.05, voltLvls = [{id = "EHV", vNom = "380 kV"}]},
+]
+
 ##################################################################
 # Power Flow Configuration
 ##################################################################
@@ -224,3 +232,12 @@ simona.control.transformer = [
     vMax = 1.02
   }
 ]
+
+##################################################################
+# Congestion Management Configuration
+##################################################################
+
+simona.congestionManagement.enable = false
+simona.congestionManagement.enableTransformerTapping = false
+simona.congestionManagement.enableTopologyChanges = false
+simona.congestionManagement.enableUsingFlexOptions = false

src/main/resources/config/config-template.conf

@@ -14,6 +14,16 @@ RefSystemConfig {
   gridIds: [string]           # Sub grid numbers to apply to, expl.: 1,2,4..10
 }
 
+#@define
+VoltageLimitsConfig {
+  vMin: double                # minimal voltage
+  vMax: double                # maximal voltage
+  #@optional
+  voltLvls: [VoltLvlConfig]   # Voltage levels to apply to
+  #@optional
+  gridIds: [string]           # Sub grid numbers to apply to, expl.: 1,2,4..10
+}
+
 #@define abstract extends !java.io.Serializable
 BaseRuntimeConfig {
   uuids: [string]          # Unique id to identify the system participant models this config applies for
@@ -145,6 +155,7 @@ GridOutputConfig {
   switches: boolean | false
   transformers2w: boolean | false
   transformers3w: boolean | false
+  congestions: boolean | false
 }
 
 #@define
@@ -363,6 +374,9 @@ simona.powerflow.stopOnFailure = boolean | false
 #@optional
 simona.gridConfig.refSystems = [RefSystemConfig]
 
+#@optional
+simona.gridConfig.voltageLimits = [VoltageLimitsConfig]
+
 ##################################################################
 # Event Configuration
 ##################################################################
@@ -375,6 +389,17 @@ simona.event.listener = [
   }
 ]
 
+##################################################################
+# Congestion Management Configuration
+##################################################################
+
+simona.congestionManagement.enable = boolean | false
+simona.congestionManagement.enableTransformerTapping = boolean | false
+simona.congestionManagement.enableTopologyChanges = boolean | false
+simona.congestionManagement.enableUsingFlexOptions = boolean | false
+simona.congestionManagement.maxOptimizationIterations = int | 1
+simona.congestionManagement.timeout  = "duration:seconds | 30 seconds" // maximum timeout
+
 ##################################################################
 # Configuration of Control Schemes
 ##################################################################

src/main/scala/edu/ie3/simona/agent/grid/CongestionManagementParams.scala

@@ -0,0 +1,64 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.agent.grid
+
+import java.time.Duration
+
+/** Holds all congestion management configuration parameters used in
+  * [[edu.ie3.simona.agent.grid]]. If the parameter [[enabled]] is set to false,
+  * no congestion management is run and all the other parameters are ignored
+  *
+  * @param enabled
+  *   defines if the congestion management is active and can be run
+  * @param transformerTapping
+  *   defines if the transformer tapping should be used for tappable
+  *   transformers
+  * @param topologyChanges
+  *   defines if switches should be used to change the topology of the grid
+  * @param flexOptions
+  *   defines if available [[edu.ie3.simona.agent.em.EmAgent]] should be used to
+  *   resolve congestions
+  */
+final case class CongestionManagementParams(
+    enabled: Boolean,
+    transformerTapping: Boolean,
+    topologyChanges: Boolean,
+    flexOptions: Boolean,
+    maxOptimizationIterations: Int,
+    timeout: Duration,
+    iteration: Int = 0,
+    hasRunTransformerTapping: Boolean = false,
+    hasUsedFlexOptions: Boolean = false,
+) {
+
+  /** Returns true if the transformer tapping can be run.
+    */
+  def runTransformerTapping: Boolean =
+    transformerTapping && !hasRunTransformerTapping && runOptimization
+
+  /** Returns true if the topology change can be run.
+    */
+  def runTopologyChanges: Boolean = topologyChanges && runOptimization
+
+  /** Returns true if flex option can be used.
+    */
+  def useFlexOptions: Boolean = flexOptions && !hasUsedFlexOptions
+
+  /** Returns cleaned [[CongestionManagementParams]].
+    */
+  def clean: CongestionManagementParams = {
+    copy(
+      hasRunTransformerTapping = false,
+      hasUsedFlexOptions = false,
+      iteration = 0,
+    )
+  }
+
+  /** Returns tru if the optimization can be run.
+    */
+  private def runOptimization: Boolean = iteration < maxOptimizationIterations
+}