Merge remote-tracking branch 'origin/main' into ac_emulation_outerloop

README.md

@@ -114,7 +114,7 @@ After adding a last Maven dependency on Open Load Flow implementation:
 <dependency>
     <groupId>com.powsybl</groupId>
     <artifactId>powsybl-open-loadflow</artifactId>
-    <version>1.9.0</version>
+    <version>1.11.0</version>
 </dependency>
 ```
 

docs/conf.py

@@ -86,7 +86,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md']
 
 # Reference sections generation
 autosectionlabel_prefix_document = True

docs/loadflow/parameters.md

@@ -31,7 +31,7 @@ The `lowImpedanceThreshold` property is an optional property that defines in per
 (when $Z$ is less than the `lowImpedanceThreshold` per-unit threshold).  
 The default value is $10^{-8}$ and it must be greater than `0`.
 
-**slackDistributionFailureBehavior**
+**slackDistributionFailureBehavior**  
 This option defines the behavior in case the slack distribution fails. Available options are:
 - `THROW` if you want an exception to be thrown in case of failure
 - `FAIL` if you want the OuterLoopStatus to be `FAILED` in case of failure
@@ -58,7 +58,7 @@ When `readSlackBus` is set to true, `slackBusSelectionMode` is still used and se
 - for e.g. synchronous components where no slack terminal extension is present.
 - for e.g. synchronous components where more than `maxSlackBusCount` slack terminal extensions are present.
 
-**mostMeshedSlackBusSelectorMaxNominalVoltagePercentile**
+**mostMeshedSlackBusSelectorMaxNominalVoltagePercentile**  
 This option is used when `slackBusSelectionMode` is set to `MOST_MESHED`. It sets the maximum nominal voltage percentile.
 The default value is `95` and it must be inside the interval [`0`, `100`].
 
@@ -137,7 +137,7 @@ When `useReactiveLimits` is set to `true`, this parameter is used to limit the n
 is switching from PQ to PV type. After this number of PQ/PV type switch, the equipment will not change PV/PQ type anymore.  
 The default value is `3` and it must be greater or equal to `0`.
 
-**phaseShifterControlMode**
+**phaseShifterControlMode**  
 - `CONTINUOUS_WITH_DISCRETISATION`: phase shifter control is solved by the Newton-Raphson inner-loop.
 - `INCREMENTAL`: phase shifter control is solved in the outer-loop
 
@@ -151,7 +151,7 @@ This parameter defines which kind of outer loops is used for transformer voltage
 
 The default value is `WITH_GENERATOR_VOLTAGE_CONTROL`.
 
-**transformerReactivePowerControl**
+**transformerReactivePowerControl**  
 This parameter enables the reactive power control of transformer through a dedicated incremental reactive power control outer loop. The default value is `false`.
 
 **incrementalTransformerRatioTapControlOuterLoopMaxTapShift**  
@@ -257,10 +257,20 @@ and its solution status is flagged as failed.
 The default values are `0.5` and `1.5` and they must be greater or equal to `0`.
 
 **reactiveRangeCheckMode**  
-This parameter defines how to check the reactive limits $MinQ$ and $MaxQ$ of a generator. If the range is too small, the generator is discarded from voltage control.
-- `MIN_MAX` mode checks if the reactive range at $MaxP$ is above a threshold and if the reactive range at $MinP$ is not zero.
-- `MAX` mode if the reactive range at $MaxP$ is above a threshold.
-- `TARGET_P` if the reactive range at $TargetP$ is above a threshold
+OpenLoadFlow discards voltage control for generators with a too small reactive power range, because in practice a too
+small reactive power ranger means limited to zero voltage control capability.
+
+For a given active power output, the reactive power range is defined as $MaxQ - MinQ$ (always a positive value).  
+The *maximum* and *minimum* reactive range of a generator is:
+- for generators without reactive limits: infinity 
+- for generators with reactive limits defined by a pair of [min/max values](inv:powsyblcore:*:*:#min-max-reactive-limits), both minimum and maximum reactive range are equal to $MaxQ - MinQ$ 
+- for generators with reactive limits defined by a [reactive capability curve](inv:powsyblcore:*:*:#reactive-capability-curve), the minimum (resp. maximum) reactive range is obtained by finding the curve point having the minimum (resp. maximum) $MaxQ - MinQ$.
+
+The `reactiveRangeCheckMode` parameter defines how generator reactive power range is to be tested. If the test does not pass,
+meaning the reactive power range is too small, then the voltage control is disabled:
+- `MIN_MAX` mode tests if the minimum reactive range is not `0 MVAr` and if the maximum reactive range is above `1 MVAr`.
+- `MAX` mode tests if the maximum reactive range is above `1 MVAr`.
+- `TARGET_P` tests if the reactive range at $TargetP$ is above `1 MVAr`.
 
 The default value is `MAX`.
 

pom.xml

@@ -20,7 +20,7 @@
     </parent>
 
     <artifactId>powsybl-open-loadflow</artifactId>
-    <version>1.11.0-SNAPSHOT</version>
+    <version>1.12.0-SNAPSHOT</version>
 
     <name>powsybl open loadflow</name>
     <description>An open source loadflow based on PowSyBl</description>

src/main/java/com/powsybl/openloadflow/ac/outerloop/IncrementalShuntVoltageControlOuterLoop.java

@@ -41,7 +41,7 @@ public class IncrementalShuntVoltageControlOuterLoop extends AbstractShuntVoltag
     public static final String NAME = "IncrementalShuntVoltageControl";
 
     // Maximum number of directional inversions for each controller during incremental outer loop
-    private static final int MAX_DIRECTION_CHANGE = 2;
+    private static final int MAX_DIRECTION_CHANGE = 3;
 
     private static final double MIN_TARGET_DEADBAND_KV = 0.1; // kV
 

src/main/java/com/powsybl/openloadflow/ac/outerloop/IncrementalTransformerReactivePowerControlOuterLoop.java

@@ -42,7 +42,7 @@ public class IncrementalTransformerReactivePowerControlOuterLoop extends Abstrac
 
     public static final String NAME = "IncrementalTransformerReactivePowerControl";
 
-    private static final int MAX_DIRECTION_CHANGE = 2;
+    private static final int MAX_DIRECTION_CHANGE = 3;
 
     private final int maxTapShift;
 

src/main/java/com/powsybl/openloadflow/ac/outerloop/IncrementalTransformerVoltageControlOuterLoop.java

@@ -42,7 +42,7 @@ public class IncrementalTransformerVoltageControlOuterLoop extends AbstractTrans
 
     public static final String NAME = "IncrementalTransformerVoltageControl";
 
-    private static final int MAX_DIRECTION_CHANGE = 2;
+    private static final int MAX_DIRECTION_CHANGE = 3;
 
     private final int maxTapShift;
 

src/main/java/com/powsybl/openloadflow/lf/outerloop/AbstractIncrementalPhaseControlOuterLoop.java

@@ -34,7 +34,7 @@ public abstract class AbstractIncrementalPhaseControlOuterLoop<V extends Enum<V>
                                                                O extends OuterLoopContext<V, E, P, C>>
         extends AbstractPhaseControlOuterLoop<V, E, P, C, O> {
 
-    public static final int MAX_DIRECTION_CHANGE = 2;
+    public static final int MAX_DIRECTION_CHANGE = 3;
     public static final int MAX_TAP_SHIFT = Integer.MAX_VALUE;
     public static final double MIN_TARGET_DEADBAND = 1 / PerUnit.SB; // 1 MW
     public static final double SENSI_EPS = 1e-6;

src/main/java/com/powsybl/openloadflow/lf/outerloop/IncrementalContextData.java

@@ -34,18 +34,19 @@ public ControllerContext(int maxDirectionChange) {
 
         private AllowedDirection allowedDirection = AllowedDirection.BOTH;
 
+        private Direction currentDirection;
+
         public AllowedDirection getAllowedDirection() {
             return allowedDirection;
         }
 
         public void updateAllowedDirection(Direction direction) {
-            if (directionChangeCount.getValue() <= maxDirectionChange) {
-                if (allowedDirection != direction.getAllowedDirection()) {
-                    // both vs increase or decrease
-                    // increase vs decrease
-                    // decrease vs increase
+            if (directionChangeCount.getValue() < maxDirectionChange) {
+                if (currentDirection != null && currentDirection != direction) {
                     directionChangeCount.increment();
                 }
+                currentDirection = direction;
+            } else {
                 allowedDirection = direction.getAllowedDirection();
             }
         }

src/test/java/com/powsybl/openloadflow/ac/AcLoadFlowTransformerReactivePowerControlTest.java

@@ -340,12 +340,12 @@ void transformerReactivePowerControl2T2wtTest2() {
 
         LoadFlowResult result = loadFlowRunner.run(network, parameters);
         assertTrue(result.isFullyConverged());
-        assertReactivePowerEquals(7.436, network.getLine("LINE_12").getTerminal1());
-        assertReactivePowerEquals(-6.891, network.getLine("LINE_12").getTerminal2());
-        assertReactivePowerEquals(-3.070, t2wt.getTerminal1());
-        assertReactivePowerEquals(2.665, t2wt.getTerminal2());
-        assertReactivePowerEquals(2.462, t2wt2.getTerminal1());
-        assertReactivePowerEquals(-2.665, t2wt2.getTerminal2());
+        assertReactivePowerEquals(7.419, network.getLine("LINE_12").getTerminal1());
+        assertReactivePowerEquals(-6.876, network.getLine("LINE_12").getTerminal2());
+        assertReactivePowerEquals(-3.077, t2wt.getTerminal1());
+        assertReactivePowerEquals(2.672, t2wt.getTerminal2());
+        assertReactivePowerEquals(2.455, t2wt2.getTerminal1());
+        assertReactivePowerEquals(-2.660, t2wt2.getTerminal2());
         assertEquals(0, t2wt.getRatioTapChanger().getTapPosition());
         assertEquals(3, t2wt2.getRatioTapChanger().getTapPosition());
     }