Improve transformer voltage control AFTER_GNERATOR_VOLTAGE_CONTROL

docs/loadflow/parameters.md

@@ -396,6 +396,22 @@ If the user specifies only a sub-list of priorities, this sub-list is completed
 order defined by default. Thus, if the user specifies only `["TRANSFORMER"]`,
 it will be completed to `["TRANSFORMER", "GENERATOR", "SHUNT"]`.
 
+**transformerVoltageControlUseInitialTapPosition**  
+This parameter is only used if the transformer voltage control is enabled and of mode `AFTER_GENERATOR_VOLTAGE_CONTROL`.
+If this parameter is set to `true`, transformers of the same voltage control (meaning controlling the same bus) are merged
+and the algorithm tries to maintain the initial difference between rhos. If the voltage at controlled bus is closed to the
+target voltage at initial step of the outer loop, the algorithm blocks transformers at their initial tap positions.
+The default value of this parameter is `false`.
+
+**generatorVoltageControlMinNominalVoltage**
+This parameter is only used if the transformer voltage control is enabled and of mode `AFTER_GENERATOR_VOLTAGE_CONTROL`.
+In this mode, at the first step of the outer loop, the transformers that controlled voltage are disabled, only generators
+are participating to voltage control. At second step, generators controlling voltage at a controlled bus above
+`generatorVoltageControlMinNominalVoltage` have their voltage control disabled. This parameter overrides an automatic
+detection of the minimal nominal voltage based on an analysis of nominal voltages controlled by transformers. The default
+value of this parameter is $-1$: with this value the parameter is ignored and the outer loop relies only on the automatic
+detection.
+
 **fictitiousGeneratorVoltageControlCheckMode**  
 Specifies the active power checks exemption for fictitious generators voltage control.
 
@@ -410,6 +426,7 @@ The `fictitiousGeneratorVoltageControlCheckMode` option controls whether the abo
 
 The default mode is `FORCED`.
 
+
 ## Configuration file example
 See below an extract of a config file that could help:
 

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

@@ -55,12 +55,15 @@ protected static Optional<AcOuterLoop> createMonitoringVoltageOuterLoop(OpenLoad
         return Optional.empty();
     }
 
-    protected static Optional<AcOuterLoop> createTransformerVoltageControlOuterLoop(LoadFlowParameters parameters, OpenLoadFlowParameters.TransformerVoltageControlMode controlMode,
-                                                                                    int incrementalTransformerVoltageControlOuterLoopMaxTapShift, double generatorVoltageControlMinNominalVoltage) {
+    protected static Optional<AcOuterLoop> createTransformerVoltageControlOuterLoop(LoadFlowParameters parameters,
+                                                                                    boolean useInitialTapPosition,
+                                                                                    OpenLoadFlowParameters.TransformerVoltageControlMode controlMode,
+                                                                                    int incrementalTransformerVoltageControlOuterLoopMaxTapShift,
+                                                                                    double generatorVoltageControlMinNominalVoltage) {
         if (parameters.isTransformerVoltageControlOn()) {
             AcOuterLoop outerLoop = switch (controlMode) {
                 case WITH_GENERATOR_VOLTAGE_CONTROL -> new SimpleTransformerVoltageControlOuterLoop();
-                case AFTER_GENERATOR_VOLTAGE_CONTROL -> new TransformerVoltageControlOuterLoop(generatorVoltageControlMinNominalVoltage);
+                case AFTER_GENERATOR_VOLTAGE_CONTROL -> new TransformerVoltageControlOuterLoop(useInitialTapPosition, generatorVoltageControlMinNominalVoltage);
                 case INCREMENTAL_VOLTAGE_CONTROL -> new IncrementalTransformerVoltageControlOuterLoop(incrementalTransformerVoltageControlOuterLoopMaxTapShift);
             };
             return Optional.of(outerLoop);
@@ -70,6 +73,7 @@ protected static Optional<AcOuterLoop> createTransformerVoltageControlOuterLoop(
 
     protected static Optional<AcOuterLoop> createTransformerVoltageControlOuterLoop(LoadFlowParameters parameters, OpenLoadFlowParameters parametersExt) {
         return createTransformerVoltageControlOuterLoop(parameters,
+                                                        parametersExt.isTransformerVoltageControlUseInitialTapPosition(),
                                                         parametersExt.getTransformerVoltageControlMode(),
                                                         parametersExt.getIncrementalTransformerRatioTapControlOuterLoopMaxTapShift(),
                                                         parametersExt.getGeneratorVoltageControlMinNominalVoltage());

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

@@ -45,6 +45,7 @@ private static Optional<AcOuterLoop> createOuterLoop(String name, LoadFlowParame
             case IncrementalShuntVoltageControlOuterLoop.NAME -> createShuntVoltageControlOuterLoop(parameters,
                                                                                                     OpenLoadFlowParameters.ShuntVoltageControlMode.INCREMENTAL_VOLTAGE_CONTROL);
             case IncrementalTransformerVoltageControlOuterLoop.NAME -> createTransformerVoltageControlOuterLoop(parameters,
+                                                                                                                parametersExt.isTransformerVoltageControlUseInitialTapPosition(),
                                                                                                                 OpenLoadFlowParameters.TransformerVoltageControlMode.INCREMENTAL_VOLTAGE_CONTROL,
                                                                                                                 parametersExt.getIncrementalTransformerRatioTapControlOuterLoopMaxTapShift(),
                                                                                                                 parametersExt.getGeneratorVoltageControlMinNominalVoltage());
@@ -56,10 +57,12 @@ private static Optional<AcOuterLoop> createOuterLoop(String name, LoadFlowParame
             case ShuntVoltageControlOuterLoop.NAME -> createShuntVoltageControlOuterLoop(parameters,
                                                                                          OpenLoadFlowParameters.ShuntVoltageControlMode.WITH_GENERATOR_VOLTAGE_CONTROL);
             case SimpleTransformerVoltageControlOuterLoop.NAME -> createTransformerVoltageControlOuterLoop(parameters,
+                                                                                                           parametersExt.isTransformerVoltageControlUseInitialTapPosition(),
                                                                                                            OpenLoadFlowParameters.TransformerVoltageControlMode.WITH_GENERATOR_VOLTAGE_CONTROL,
                                                                                                            parametersExt.getIncrementalTransformerRatioTapControlOuterLoopMaxTapShift(),
                                                                                                            parametersExt.getGeneratorVoltageControlMinNominalVoltage());
             case TransformerVoltageControlOuterLoop.NAME -> createTransformerVoltageControlOuterLoop(parameters,
+                                                                                                     parametersExt.isTransformerVoltageControlUseInitialTapPosition(),
                                                                                                      OpenLoadFlowParameters.TransformerVoltageControlMode.AFTER_GENERATOR_VOLTAGE_CONTROL,
                                                                                                      parametersExt.getIncrementalTransformerRatioTapControlOuterLoopMaxTapShift(),
                                                                                                      parametersExt.getGeneratorVoltageControlMinNominalVoltage());

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

@@ -257,6 +257,8 @@ public enum FictitiousGeneratorVoltageControlCheckMode {
 
     public static final String VOLTAGE_TARGET_PRIORITIES_PARAM_NAME = "voltageTargetPriorities";
 
+    public static final String TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_PARAM_NAME = "transformerVoltageControlUseInitialTapPosition";
+
     public static final String GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_PARAM_NAME = "generatorVoltageControlMinNominalVoltage";
 
     public static final String FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE = "fictitiousGeneratorVoltageControlCheckMode";
@@ -331,6 +333,7 @@ public static <E extends Enum<E>> List<Object> getEnumPossibleValues(Class<E> en
         new Parameter(REFERENCE_BUS_SELECTION_MODE_PARAM_NAME, ParameterType.STRING, "Reference bus selection mode", ReferenceBusSelector.DEFAULT_MODE.name(), getEnumPossibleValues(ReferenceBusSelectionMode.class)),
         new Parameter(WRITE_REFERENCE_TERMINALS_PARAM_NAME, ParameterType.BOOLEAN, "Write Reference Terminals", WRITE_REFERENCE_TERMINALS_DEFAULT_VALUE),
         new Parameter(VOLTAGE_TARGET_PRIORITIES_PARAM_NAME, ParameterType.STRING_LIST, "Voltage target priorities for voltage controls", LfNetworkParameters.VOLTAGE_CONTROL_PRIORITIES_DEFAULT_VALUE, getEnumPossibleValues(VoltageControl.Type.class)),
+        new Parameter(TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_PARAM_NAME, ParameterType.BOOLEAN, "Maintain initial tap position if possible", LfNetworkParameters.TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_DEFAULT_VALUE),
         new Parameter(GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_PARAM_NAME, ParameterType.DOUBLE, "Nominal voltage under which generator voltage controls are disabled during transformer voltage control outer loop of mode AFTER_GENERATOR_VOLTAGE_CONTROL, < 0 means automatic detection", OpenLoadFlowParameters.GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_DEFAULT_VALUE),
         new Parameter(FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE, ParameterType.STRING, "Specifies fictitious generators active power checks exemption for voltage control", OpenLoadFlowParameters.FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE_DEFAULT_VALUE.name(), getEnumPossibleValues(FictitiousGeneratorVoltageControlCheckMode.class))
     );
@@ -504,6 +507,8 @@ public enum ReactiveRangeCheckMode {
 
     private List<String> voltageTargetPriorities = LfNetworkParameters.VOLTAGE_CONTROL_PRIORITIES_DEFAULT_VALUE;
 
+    private boolean transformerVoltageControlUseInitialTapPosition = LfNetworkParameters.TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_DEFAULT_VALUE;
+
     private double generatorVoltageControlMinNominalVoltage = GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_DEFAULT_VALUE;
 
     private FictitiousGeneratorVoltageControlCheckMode fictitiousGeneratorVoltageControlCheckMode = FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE_DEFAULT_VALUE;
@@ -1172,6 +1177,15 @@ public OpenLoadFlowParameters setVoltageTargetPriorities(List<String> voltageTar
         return this;
     }
 
+    public boolean isTransformerVoltageControlUseInitialTapPosition() {
+        return transformerVoltageControlUseInitialTapPosition;
+    }
+
+    public OpenLoadFlowParameters setTransformerVoltageControlUseInitialTapPosition(boolean transformerVoltageControlUseInitialTapPosition) {
+        this.transformerVoltageControlUseInitialTapPosition = transformerVoltageControlUseInitialTapPosition;
+        return this;
+    }
+
     /**
      * Only if transformer voltage control is active and with mode `AFTER_GENERATOR_VOLTAGE_CONTROL`. Set the nominal
      * voltage under which the generator voltage control are disabled during outer loop. This parameter overrides the
@@ -1269,6 +1283,7 @@ public static OpenLoadFlowParameters load(PlatformConfig platformConfig) {
                 .setReferenceBusSelectionMode(config.getEnumProperty(REFERENCE_BUS_SELECTION_MODE_PARAM_NAME, ReferenceBusSelectionMode.class, ReferenceBusSelector.DEFAULT_MODE))
                 .setWriteReferenceTerminals(config.getBooleanProperty(WRITE_REFERENCE_TERMINALS_PARAM_NAME, WRITE_REFERENCE_TERMINALS_DEFAULT_VALUE))
                 .setVoltageTargetPriorities(config.getStringListProperty(VOLTAGE_TARGET_PRIORITIES_PARAM_NAME, LfNetworkParameters.VOLTAGE_CONTROL_PRIORITIES_DEFAULT_VALUE))
+                .setTransformerVoltageControlUseInitialTapPosition(config.getBooleanProperty(TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_PARAM_NAME, LfNetworkParameters.TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_DEFAULT_VALUE))
                 .setGeneratorVoltageControlMinNominalVoltage(config.getDoubleProperty(GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_PARAM_NAME, GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_DEFAULT_VALUE)));
         return parameters;
     }
@@ -1418,6 +1433,8 @@ public OpenLoadFlowParameters update(Map<String, String> properties) {
                 .ifPresent(prop -> this.setWriteReferenceTerminals(Boolean.parseBoolean(prop)));
         Optional.ofNullable(properties.get(VOLTAGE_TARGET_PRIORITIES_PARAM_NAME))
                 .ifPresent(prop -> this.setVoltageTargetPriorities(parseStringListProp(prop)));
+        Optional.ofNullable(properties.get(TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_PARAM_NAME))
+                .ifPresent(prop -> this.setTransformerVoltageControlUseInitialTapPosition(Boolean.parseBoolean(prop)));
         Optional.ofNullable(properties.get(GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_PARAM_NAME))
                 .ifPresent(prop -> this.setGeneratorVoltageControlMinNominalVoltage(Double.parseDouble(prop)));
         Optional.ofNullable(properties.get(FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE))
@@ -1492,6 +1509,7 @@ public Map<String, Object> toMap() {
         map.put(REFERENCE_BUS_SELECTION_MODE_PARAM_NAME, referenceBusSelectionMode);
         map.put(WRITE_REFERENCE_TERMINALS_PARAM_NAME, writeReferenceTerminals);
         map.put(VOLTAGE_TARGET_PRIORITIES_PARAM_NAME, voltageTargetPriorities);
+        map.put(TRANSFORMER_VOLTAGE_CONTROL_USE_INITIAL_TAP_POSITION_PARAM_NAME, transformerVoltageControlUseInitialTapPosition);
         map.put(GENERATOR_VOLTAGE_CONTROL_MIN_NOMINAL_VOLTAGE_PARAM_NAME, generatorVoltageControlMinNominalVoltage);
         map.put(FICTITIOUS_GENERATOR_VOLTAGE_CONTROL_CHECK_MODE, fictitiousGeneratorVoltageControlCheckMode);
         return map;
@@ -1870,6 +1888,7 @@ public static boolean equals(LoadFlowParameters parameters1, LoadFlowParameters
                 extension1.getMaxSusceptanceMismatch() == extension2.getMaxSusceptanceMismatch() &&
                 extension1.getNewtonRaphsonStoppingCriteriaType() == extension2.getNewtonRaphsonStoppingCriteriaType() &&
                 Objects.equals(extension1.getVoltageTargetPriorities(), extension2.getVoltageTargetPriorities()) &&
+                extension1.isTransformerVoltageControlUseInitialTapPosition() == extension2.isTransformerVoltageControlUseInitialTapPosition() &&
                 extension1.getGeneratorVoltageControlMinNominalVoltage() == extension2.getGeneratorVoltageControlMinNominalVoltage() &&
                 extension1.getFictitiousGeneratorVoltageControlCheckMode() == extension2.getFictitiousGeneratorVoltageControlCheckMode();
     }
@@ -1962,6 +1981,7 @@ public static LoadFlowParameters clone(LoadFlowParameters parameters) {
                     .setNewtonRaphsonStoppingCriteriaType(extension.getNewtonRaphsonStoppingCriteriaType())
                     .setReferenceBusSelectionMode(extension.getReferenceBusSelectionMode())
                     .setVoltageTargetPriorities(extension.getVoltageTargetPriorities())
+                    .setTransformerVoltageControlUseInitialTapPosition(extension.isTransformerVoltageControlUseInitialTapPosition())
                     .setGeneratorVoltageControlMinNominalVoltage(extension.getGeneratorVoltageControlMinNominalVoltage())
                     .setFictitiousGeneratorVoltageControlCheckMode(extension.getFictitiousGeneratorVoltageControlCheckMode());
 

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

@@ -7,9 +7,9 @@
  */
 package com.powsybl.openloadflow.ac.outerloop;
 
-import com.powsybl.openloadflow.ac.AcOuterLoopContext;
 import com.powsybl.openloadflow.lf.outerloop.OuterLoopStatus;
 import com.powsybl.openloadflow.network.LfBranch;
+import com.powsybl.openloadflow.network.LfNetwork;
 import com.powsybl.openloadflow.network.PiModel;
 import com.powsybl.openloadflow.network.TransformerVoltageControl;
 import com.powsybl.openloadflow.network.VoltageControl;
@@ -32,9 +32,9 @@ public String getType() {
         return TYPE;
     }
 
-    protected OuterLoopStatus roundVoltageRatios(AcOuterLoopContext context) {
+    protected OuterLoopStatus roundVoltageRatios(LfNetwork network) {
         OuterLoopStatus status = OuterLoopStatus.STABLE;
-        for (LfBranch controllerBranch : context.getNetwork().<LfBranch>getControllerElements(VoltageControl.Type.TRANSFORMER)) {
+        for (LfBranch controllerBranch : network.<LfBranch>getControllerElements(VoltageControl.Type.TRANSFORMER)) {
             controllerBranch.setVoltageControlEnabled(false);
 
             // round the rho shift to the closest tap

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

@@ -40,7 +40,7 @@ public void initialize(AcOuterLoopContext context) {
     public OuterLoopResult check(AcOuterLoopContext context, ReportNode reportNode) {
         OuterLoopStatus status = OuterLoopStatus.STABLE;
         if (context.getIteration() == 0) {
-            status = roundVoltageRatios(context);
+            status = roundVoltageRatios(context.getNetwork());
         }
         return new OuterLoopResult(this, status);
     }