Shunt incremental voltage control (#692)

Signed-off-by: Hadrien <hadrien.godard@artelys.com>
Co-authored-by: Anne Tilloy <anne.tilloy@rte-france.com>
Co-authored-by: Geoffroy Jamgotchian <geoffroy.jamgotchian@rte-france.com>

src/main/java/com/powsybl/openloadflow/DefaultOuterLoopConfig.java

@@ -32,6 +32,17 @@ private static OuterLoop createTransformerVoltageControlOuterLoop(OpenLoadFlowPa
         }
     }
 
+    private static OuterLoop createShuntVoltageControlOuterLoop(OpenLoadFlowParameters parametersExt) {
+        switch (parametersExt.getShuntVoltageControlMode()) {
+            case WITH_GENERATOR_VOLTAGE_CONTROL:
+                return new ShuntVoltageControlOuterLoop();
+            case INCREMENTAL_VOLTAGE_CONTROL:
+                return new IncrementalShuntVoltageControlOuterLoop();
+            default:
+                throw new IllegalStateException("Unknown shunt voltage control mode: " + parametersExt.getShuntVoltageControlMode());
+        }
+    }
+
     private static OuterLoop createDistributedSlackOuterLoop(LoadFlowParameters parameters, OpenLoadFlowParameters parametersExt) {
         ActivePowerDistribution activePowerDistribution = ActivePowerDistribution.create(parameters.getBalanceType(), parametersExt.isLoadPowerFactorConstant());
         return new DistributedSlackOuterLoop(activePowerDistribution, parametersExt.isThrowsExceptionInCaseOfSlackDistributionFailure(), parametersExt.getSlackBusPMaxMismatch());
@@ -61,7 +72,7 @@ public List<OuterLoop> configure(LoadFlowParameters parameters, OpenLoadFlowPara
         }
         // shunt compensator voltage control
         if (parameters.isShuntCompensatorVoltageControlOn()) {
-            outerLoops.add(new ShuntVoltageControlOuterLoop());
+            outerLoops.add(createShuntVoltageControlOuterLoop(parametersExt));
         }
         return outerLoops;
     }

src/main/java/com/powsybl/openloadflow/OpenLoadFlowParameters.java

@@ -74,6 +74,8 @@ public class OpenLoadFlowParameters extends AbstractExtension<LoadFlowParameters
 
     public static final TransformerVoltageControlMode TRANSFORMER_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE = TransformerVoltageControlMode.WITH_GENERATOR_VOLTAGE_CONTROL;
 
+    public static final ShuntVoltageControlMode SHUNT_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE = ShuntVoltageControlMode.WITH_GENERATOR_VOLTAGE_CONTROL;
+
     public static final String SLACK_BUS_SELECTION_MODE_PARAM_NAME = "slackBusSelectionMode";
 
     public static final String SLACK_BUSES_IDS_PARAM_NAME = "slackBusesIds";
@@ -102,6 +104,8 @@ public class OpenLoadFlowParameters extends AbstractExtension<LoadFlowParameters
 
     public static final String TRANSFORMER_VOLTAGE_CONTROL_MODE_NAME = "transformerVoltageControlMode";
 
+    public static final String SHUNT_VOLTAGE_CONTROL_MODE_NAME = "shuntVoltageControlMode";
+
     public static final String DC_POWER_FACTOR_NAME = "dcPowerFactor";
 
     public static final String MIN_PLAUSIBLE_TARGET_VOLTAGE_NAME = "minPlausibleTargetVoltage";
@@ -147,6 +151,7 @@ private static <E extends Enum<E>> List<Object> getEnumPossibleValues(Class<E> e
         new Parameter(NEWTON_RAPHSON_CONV_EPS_PER_EQ_NAME, ParameterType.DOUBLE, "Newton-Raphson convergence epsilon per equation", DefaultNewtonRaphsonStoppingCriteria.DEFAULT_CONV_EPS_PER_EQ),
         new Parameter(VOLTAGE_INIT_MODE_OVERRIDE_NAME, ParameterType.STRING, "Voltage init mode override", VOLTAGE_INIT_MODE_OVERRIDE_DEFAULT_VALUE.name(), getEnumPossibleValues(VoltageInitModeOverride.class)),
         new Parameter(TRANSFORMER_VOLTAGE_CONTROL_MODE_NAME, ParameterType.STRING, "Transformer voltage control mode", TRANSFORMER_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE.name(), getEnumPossibleValues(TransformerVoltageControlMode.class)),
+        new Parameter(SHUNT_VOLTAGE_CONTROL_MODE_NAME, ParameterType.STRING, "Shunt voltage control mode", SHUNT_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE.name(), getEnumPossibleValues(ShuntVoltageControlMode.class)),
         new Parameter(DC_POWER_FACTOR_NAME, ParameterType.DOUBLE, "DC approximation power factor", DC_POWER_FACTOR_DEFAULT_VALUE),
         new Parameter(MIN_PLAUSIBLE_TARGET_VOLTAGE_NAME, ParameterType.DOUBLE, "Min plausible target voltage", LfNetworkParameters.MIN_PLAUSIBLE_TARGET_VOLTAGE_DEFAULT_VALUE),
         new Parameter(MAX_PLAUSIBLE_TARGET_VOLTAGE_NAME, ParameterType.DOUBLE, "Max plausible target voltage", LfNetworkParameters.MAX_PLAUSIBLE_TARGET_VOLTAGE_DEFAULT_VALUE),
@@ -174,6 +179,11 @@ public enum TransformerVoltageControlMode {
         INCREMENTAL_VOLTAGE_CONTROL
     }
 
+    public enum ShuntVoltageControlMode {
+        WITH_GENERATOR_VOLTAGE_CONTROL,
+        INCREMENTAL_VOLTAGE_CONTROL
+    }
+
     private SlackBusSelectionMode slackBusSelectionMode = SLACK_BUS_SELECTION_MODE_DEFAULT_VALUE;
 
     private List<String> slackBusesIds = Collections.emptyList();
@@ -207,6 +217,8 @@ public enum LowImpedanceBranchMode {
 
     private TransformerVoltageControlMode transformerVoltageControlMode = TRANSFORMER_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE;
 
+    private ShuntVoltageControlMode shuntVoltageControlMode = SHUNT_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE;
+
     private double dcPowerFactor = DC_POWER_FACTOR_DEFAULT_VALUE;
 
     private double minPlausibleTargetVoltage = LfNetworkParameters.MIN_PLAUSIBLE_TARGET_VOLTAGE_DEFAULT_VALUE;
@@ -380,6 +392,15 @@ public OpenLoadFlowParameters setTransformerVoltageControlMode(TransformerVoltag
         return this;
     }
 
+    public ShuntVoltageControlMode getShuntVoltageControlMode() {
+        return shuntVoltageControlMode;
+    }
+
+    public OpenLoadFlowParameters setShuntVoltageControlMode(ShuntVoltageControlMode shuntVoltageControlMode) {
+        this.shuntVoltageControlMode = Objects.requireNonNull(shuntVoltageControlMode);
+        return this;
+    }
+
     public double getDcPowerFactor() {
         return dcPowerFactor;
     }
@@ -536,6 +557,7 @@ public static OpenLoadFlowParameters load(PlatformConfig platformConfig) {
                 .setNewtonRaphsonConvEpsPerEq(config.getDoubleProperty(NEWTON_RAPHSON_CONV_EPS_PER_EQ_NAME, DefaultNewtonRaphsonStoppingCriteria.DEFAULT_CONV_EPS_PER_EQ))
                 .setVoltageInitModeOverride(config.getEnumProperty(VOLTAGE_INIT_MODE_OVERRIDE_NAME, VoltageInitModeOverride.class, VOLTAGE_INIT_MODE_OVERRIDE_DEFAULT_VALUE))
                 .setTransformerVoltageControlMode(config.getEnumProperty(TRANSFORMER_VOLTAGE_CONTROL_MODE_NAME, TransformerVoltageControlMode.class, TRANSFORMER_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE))
+                .setShuntVoltageControlMode(config.getEnumProperty(SHUNT_VOLTAGE_CONTROL_MODE_NAME, ShuntVoltageControlMode.class, SHUNT_VOLTAGE_CONTROL_MODE_DEFAULT_VALUE))
                 .setDcPowerFactor(config.getDoubleProperty(DC_POWER_FACTOR_NAME, DC_POWER_FACTOR_DEFAULT_VALUE))
                 .setMinPlausibleTargetVoltage(config.getDoubleProperty(MIN_PLAUSIBLE_TARGET_VOLTAGE_NAME, LfNetworkParameters.MIN_PLAUSIBLE_TARGET_VOLTAGE_DEFAULT_VALUE))
                 .setMaxPlausibleTargetVoltage(config.getDoubleProperty(MAX_PLAUSIBLE_TARGET_VOLTAGE_NAME, LfNetworkParameters.MAX_PLAUSIBLE_TARGET_VOLTAGE_DEFAULT_VALUE))
@@ -586,6 +608,8 @@ public OpenLoadFlowParameters update(Map<String, String> properties) {
                 .ifPresent(prop -> this.setVoltageInitModeOverride(VoltageInitModeOverride.valueOf(prop)));
         Optional.ofNullable(properties.get(TRANSFORMER_VOLTAGE_CONTROL_MODE_NAME))
                 .ifPresent(prop -> this.setTransformerVoltageControlMode(TransformerVoltageControlMode.valueOf(prop)));
+        Optional.ofNullable(properties.get(SHUNT_VOLTAGE_CONTROL_MODE_NAME))
+                .ifPresent(prop -> this.setShuntVoltageControlMode(ShuntVoltageControlMode.valueOf(prop)));
         Optional.ofNullable(properties.get(DC_POWER_FACTOR_NAME))
                 .ifPresent(prop -> this.setDcPowerFactor(Double.parseDouble(prop)));
         Optional.ofNullable(properties.get(MIN_PLAUSIBLE_TARGET_VOLTAGE_NAME))
@@ -632,6 +656,7 @@ public String toString() {
                 ", newtonRaphsonConvEpsPerEq=" + newtonRaphsonConvEpsPerEq +
                 ", voltageInitModeOverride=" + voltageInitModeOverride +
                 ", transformerVoltageControlMode=" + transformerVoltageControlMode +
+                ", shuntVoltageControlMode=" + shuntVoltageControlMode +
                 ", dcPowerFactor=" + dcPowerFactor +
                 ", minPlausibleTargetVoltage=" + minPlausibleTargetVoltage +
                 ", maxPlausibleTargetVoltage=" + maxPlausibleTargetVoltage +
@@ -931,6 +956,7 @@ public static boolean equals(LoadFlowParameters parameters1, LoadFlowParameters
                 extension1.getNewtonRaphsonConvEpsPerEq() == extension2.getNewtonRaphsonConvEpsPerEq() &&
                 extension1.getVoltageInitModeOverride() == extension2.getVoltageInitModeOverride() &&
                 extension1.getTransformerVoltageControlMode() == extension2.getTransformerVoltageControlMode() &&
+                extension1.getShuntVoltageControlMode() == extension2.getShuntVoltageControlMode() &&
                 extension1.getDcPowerFactor() == extension2.getDcPowerFactor() &&
                 extension1.getMinPlausibleTargetVoltage() == extension2.getMinPlausibleTargetVoltage() &&
                 extension1.getMaxPlausibleTargetVoltage() == extension2.getMaxPlausibleTargetVoltage() &&
@@ -981,6 +1007,7 @@ public static LoadFlowParameters clone(LoadFlowParameters parameters) {
                     .setNewtonRaphsonConvEpsPerEq(extension.getNewtonRaphsonConvEpsPerEq())
                     .setVoltageInitModeOverride(extension.getVoltageInitModeOverride())
                     .setTransformerVoltageControlMode(extension.getTransformerVoltageControlMode())
+                    .setShuntVoltageControlMode(extension.getShuntVoltageControlMode())
                     .setDcPowerFactor(extension.getDcPowerFactor())
                     .setMinPlausibleTargetVoltage(extension.getMinPlausibleTargetVoltage())
                     .setMaxPlausibleTargetVoltage(extension.getMaxPlausibleTargetVoltage())

src/main/java/com/powsybl/openloadflow/ac/IncrementalContextData.java

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2023, RTE (http://www.rte-france.com)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package com.powsybl.openloadflow.ac;
+
+import com.powsybl.openloadflow.network.AllowedDirection;
+import org.apache.commons.lang3.mutable.MutableInt;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * @author Geoffroy Jamgotchian <geoffroy.jamgotchian at rte-france.com>
+ */
+class IncrementalContextData {
+
+    static final class ControllerContext {
+
+        private final MutableInt directionChangeCount = new MutableInt();
+
+        private AllowedDirection allowedDirection = AllowedDirection.BOTH;
+
+        MutableInt getDirectionChangeCount() {
+            return directionChangeCount;
+        }
+
+        AllowedDirection getAllowedDirection() {
+            return allowedDirection;
+        }
+
+        void setAllowedDirection(AllowedDirection allowedDirection) {
+            this.allowedDirection = Objects.requireNonNull(allowedDirection);
+        }
+    }
+
+    private final Map<String, ControllerContext> controllersContexts = new HashMap<>();
+
+    Map<String, ControllerContext> getControllersContexts() {
+        return controllersContexts;
+    }
+}