Merge branch 'main' into experiment/robustify-one-state-only-rao-result

# Conflicts:
#	ra-optimisation/search-tree-rao/src/main/java/com/powsybl/openrao/searchtreerao/castor/algorithm/CastorFullOptimization.java

Author: bqth29

docs/algorithms/castor/special-features.md

@@ -5,6 +5,7 @@
 special-features/loop-flows.md
 special-features/mnecs.md
 special-features/do-not-optimize-specific-cnecs.md
+special-features/pst-regulation.md
 ```
 
 Several special features can be included in the RAO optimisation:

docs/algorithms/castor/special-features/pst-regulation.md

@@ -0,0 +1,106 @@
+# PST Regulation
+
+## Presentation
+
+In some processes and/or regions, certain critical elements are operated in series with a PST such that when these
+elements are overloaded and there is still a possibility to change the tap position of the associated PST and if is not
+in abutment, the latter is used to secure the constrained elements.
+
+At the end of the curative optimization of the RAO, such critical lines can still be unsecure because they are not
+limiting elements. Indeed, some other lines can have a margin which is way more negative so the RAO cannot improve its
+objective function by changing the taps of the PSTs in series with overloaded critical elements. The results must then
+be post-processed to check if changing the taps of these PSTs of interest could help secure the critical element they
+monitor, even if this means increasing the flow in surrounding lines. This is called **PST regulation**.
+
+> Even if only one critical element is overloaded, all PSTs are regulated at once since they may have side effects on
+> other lines than the ones they protect.
+
+The set of PSTs to regulate can be provided in the
+[RAO parameters](../../../parameters/implementation-specific-parameters.md#pst-regulation-parameters). Then, for each curative
+scenario, if the most limiting element is a FlowCNEC in series with a PST, all the PSTs are regulated.
+
+Such monitored lines can be the PSTs themselves or lines connected in series. In the second case, the threshold of the
+FlowCNEC defined on this line in series is used as the regulation value.
+
+> ⚠️ **Remark: Sub-optimality**
+>
+> Note that there is a risk that PST regulation worsens the minimal margin.
+
+PST regulation is performed directly by the load flow engine provided
+by [PowSyBl Open Load Flow](https://powsybl.readthedocs.io/projects/powsybl-open-loadflow/en/stable/index.html). This
+basically consists in iterative load flow computations with the tap of one of the regulated PST moved in the direction
+that favors the security of the monitored line each time. As soon as the monitored line is secure, the tap does no
+longer need to be moved. When all taps have reached a fixed position, the iterations stop and the regulation is over.
+
+Regulation results are then merged with the RAO result to provide the final results. If a PST was moved during
+regulation, this will appear as a result from the curative optimization.
+
+## Example
+
+Let us consider a simple network of only two nodes and three parallel branches, one of these being a PST. We will denote
+these lines as `branch-1`, `branch-2` and `branch-3`; `branch-3` being the PST to regulate. All three branches are
+considered to have the same permanent limit (PATL) and the same impedance. The PST is initially on tap -5 and its
+neutral tap is 0.
+
+The first step is to fill the RAO parameters with
+[PST regulation parameters](../../../parameters/implementation-specific-parameters.md#pst-regulation-parameters) to indicate
+that the PST can be regulated.
+
+```json
+{
+  "version": "3.2.1",
+  "extensions": {
+    "open-rao-search-tree-parameters": {
+      "pst-regulation-parameters" : {
+        "psts-to-regulate": { "branch-3" : "branch-3" }
+      }
+    }
+  }
+}
+```
+
+We will consider that there is a contingency on `branch-1` and that when it occurs, there is no way to secure both
+`branch-2` and `branch-3` at the same time.
+
+As these two branches have the same impedance and the same permanent limit, the status quo found by the RAO during
+curative optimization is to set the PST on its neutral tap (position 0). That way, both branches are overloaded but the
+minimal margin is maximized, because no branch is relieved to the detriment of the other.
+
+If the RAO were to stop here, the activation of the PST in the RAO result would look like:
+
+```json
+{
+  "rangeActionId": "pstRangeAction",
+  "initialTap": -5,
+  "activatedStates": [
+    {
+      "instant": "curative",
+      "contingencyId": "contingency-branch-1",
+      "tap": 0
+    }
+  ]
+}
+```
+
+However, the PST on `branch-3` can be regulated. As it is overloaded and is also the most limiting element, regulation
+can be performed to try to secure the PST. We will consider that in the network configuration, the PST can be secured
+from tap position 7, though it increases the overload on `branch-2`.
+
+Thus, the regulation algorithm will move the tap of the PST from position 0 to position 7 and the final RAO result will
+contain this activation result instead of the previous one:
+
+```json
+{
+  "rangeActionId": "pstRangeAction",
+  "initialTap": -5,
+  "activatedStates": [
+    {
+      "instant": "curative",
+      "contingencyId": "contingency-branch-1",
+      "tap": 7
+    }
+  ]
+}
+```
+
+The flows will also be updated and the limiting element is now `branch-2` alone with a greater overload than previously.

docs/parameters.md

@@ -36,7 +36,7 @@ Examples of rao parameters with business and implementation specific parameters
 :::{group-tab} JSON
 ~~~json
 {
-  "version" : "3.2",
+  "version" : "3.2.1",
   "objective-function" : {
     "type" : "SECURE_FLOW",
     "unit" : "A",

docs/parameters/business-parameters.md

@@ -183,7 +183,7 @@ See also: [Modelling the maximum minimum relative margin objective function](../
 :::{group-tab} JSON
 ~~~json
 {
-  "version" : "3.2",
+  "version" : "3.2.1",
   "objective-function" : {
     "type" : "SECURE_FLOW",
     "unit" : "A",

docs/parameters/implementation-specific-parameters.md

@@ -396,6 +396,14 @@ These parameters are meant to be used in costly optimization only.
 - **Default value**: 5
 - **Usage**: If `add-unsecure-cnecs` is enabled, a CNEC will be considered unsecure if its margin is lower than `margin-limit`.
 
+#### PST regulation parameters
+
+##### psts-to-regulate
+
+- **Expected value**: a map with string keys (each being the identifier of a PST in the network) and string values (each being the line secured by the regulated PST)
+- **Default value**: empty map
+- **Usage**: List of PSTs to regulate at the end of curative optimization if a FlowCNEC defined on any of their associated elements is overloaded and is the most limiting element.
+
 ## Examples
 > ⚠️  **NOTE**  
 > The following examples in json and yaml are not equivalent
@@ -404,7 +412,7 @@ These parameters are meant to be used in costly optimization only.
 :::{group-tab} JSON
 ~~~json
 {
-  "version" : "3.2",
+  "version" : "3.2.1",
   "extensions" : {
     "fast-rao-parameters" : {
       "number-of-cnecs-to-add" : 20,
@@ -511,6 +519,12 @@ These parameters are meant to be used in costly optimization only.
     "costly-min-margin-parameters" : {
       "shifted-violation-penalty": 1000.0,
       "shifted-violation-threshold": 0.0
+    },
+    "pst-regulation-parameters" : {
+      "psts-to-regulate": {
+        "pst-1": "line-1",
+        "pst-2": "line-2"
+      }
     }
   }
 }
@@ -565,4 +579,3 @@ fast-rao-parameters:
 ~~~
 :::
 ::::
-

ra-optimisation/rao-api/src/main/java/com/powsybl/openrao/raoapi/RaoParametersCommons.java

@@ -22,9 +22,10 @@ private RaoParametersCommons() {
         ---------------------------
         3.1: remove max-auto-search-tree-depth
         3.2: remove re-optimize-curative-range-actions
+        3.2.1: add pst-regulation-parameters
     */
 
-    public static final String RAO_PARAMETERS_VERSION = "3.2";
+    public static final String RAO_PARAMETERS_VERSION = "3.2.1";
 
     // header
     public static final String VERSION = "version";
@@ -143,4 +144,9 @@ public static PtdfApproximation stringToPtdfApproximation(String string) {
     public static final String ST_COSTLY_MIN_MARGIN_SECTION = "search-tree-costly-min-margin-parameters";
     public static final String SHIFTED_VIOLATION_PENALTY = "shifted-violation-penalty";
     public static final String SHIFTED_VIOLATION_THRESHOLD = "shifted-violation-threshold";
+
+    // -- PST regulation parameters
+    public static final String PST_REGULATION_PARAMETERS = "pst-regulation-parameters";
+    public static final String ST_PST_REGULATION_SECTION = "search-tree-pst-regulation-parameters";
+    public static final String PSTS_TO_REGULATE = "psts-to-regulate";
 }

ra-optimisation/rao-api/src/main/java/com/powsybl/openrao/raoapi/json/extensions/JsonOpenRaoSearchTreeParameters.java

@@ -39,6 +39,7 @@ public void serialize(OpenRaoSearchTreeParameters parameters, JsonGenerator json
         JsonRelativeMarginsParameters.serialize(parameters, jsonGenerator);
         JsonLoopFlowParameters.serialize(parameters, jsonGenerator);
         JsonMinMarginsParameters.serialize(parameters, jsonGenerator);
+        JsonSearchTreeRaoPstRegulationParameters.serialize(parameters, jsonGenerator);
         jsonGenerator.writeEndObject();
     }
 
@@ -91,7 +92,12 @@ public OpenRaoSearchTreeParameters deserializeAndUpdate(JsonParser parser, Deser
                     parser.nextToken();
                     JsonMinMarginsParameters.deserialize(parser, parameters);
                 }
-                default -> throw new OpenRaoException("Unexpected field in open rao search tree parameters: " + parser.getCurrentName());
+                case PST_REGULATION_PARAMETERS -> {
+                    parser.nextToken();
+                    JsonSearchTreeRaoPstRegulationParameters.deserialize(parser, parameters);
+                }
+                default ->
+                    throw new OpenRaoException("Unexpected field in open rao search tree parameters: " + parser.getCurrentName());
             }
         }
         return parameters;

ra-optimisation/rao-api/src/main/java/com/powsybl/openrao/raoapi/json/extensions/JsonSearchTreeRaoPstRegulationParameters.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025, 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.openrao.raoapi.json.extensions;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.core.JsonParser;
+import com.powsybl.openrao.commons.OpenRaoException;
+import com.powsybl.openrao.raoapi.parameters.extensions.OpenRaoSearchTreeParameters;
+import com.powsybl.openrao.raoapi.parameters.extensions.SearchTreeRaoPstRegulationParameters;
+
+import java.io.IOException;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import static com.powsybl.openrao.raoapi.RaoParametersCommons.PSTS_TO_REGULATE;
+import static com.powsybl.openrao.raoapi.RaoParametersCommons.PST_REGULATION_PARAMETERS;
+
+/**
+ * @author Thomas Bouquet {@literal <thomas.bouquet at rte-france.com>}
+ */
+public final class JsonSearchTreeRaoPstRegulationParameters {
+    private JsonSearchTreeRaoPstRegulationParameters() {
+    }
+
+    static void serialize(OpenRaoSearchTreeParameters parameters, JsonGenerator jsonGenerator) throws IOException {
+        Optional<SearchTreeRaoPstRegulationParameters> pstRegulationParameters = parameters.getPstRegulationParameters();
+        if (pstRegulationParameters.isPresent()) {
+            jsonGenerator.writeObjectFieldStart(PST_REGULATION_PARAMETERS);
+            jsonGenerator.writeObjectFieldStart(PSTS_TO_REGULATE);
+            for (Map.Entry<String, String> entry : pstRegulationParameters.get().getPstsToRegulate().entrySet().stream().sorted(Map.Entry.comparingByValue()).toList()) {
+                jsonGenerator.writeStringField(entry.getKey(), entry.getValue());
+            }
+            jsonGenerator.writeEndObject();
+            jsonGenerator.writeEndObject();
+        }
+
+    }
+
+    static void deserialize(JsonParser jsonParser, OpenRaoSearchTreeParameters searchTreeParameters) throws IOException {
+        SearchTreeRaoPstRegulationParameters pstRegulationParameters = new SearchTreeRaoPstRegulationParameters();
+        while (!jsonParser.nextToken().isStructEnd()) {
+            switch (jsonParser.getCurrentName()) {
+                case PSTS_TO_REGULATE:
+                    jsonParser.nextToken();
+                    pstRegulationParameters.setPstsToRegulate(jsonParser.readValueAs(HashMap.class));
+                    break;
+                default:
+                    throw new OpenRaoException(String.format("Cannot deserialize PST regulation parameters: unexpected field in %s (%s)", PST_REGULATION_PARAMETERS, jsonParser.getCurrentName()));
+            }
+            searchTreeParameters.setPstRegulationParameters(pstRegulationParameters);
+        }
+    }
+}

ra-optimisation/rao-api/src/main/java/com/powsybl/openrao/raoapi/parameters/extensions/OpenRaoSearchTreeParameters.java

@@ -28,6 +28,7 @@ public class OpenRaoSearchTreeParameters extends AbstractExtension<RaoParameters
     private Optional<SearchTreeRaoMnecParameters> mnecParameters = Optional.empty();
     private Optional<SearchTreeRaoRelativeMarginsParameters> relativeMarginsParameters = Optional.empty();
     private Optional<SearchTreeRaoLoopFlowParameters> loopFlowParameters = Optional.empty();
+    private Optional<SearchTreeRaoPstRegulationParameters> pstRegulationParameters = Optional.empty();
 
     // Getters and setters
     public void setObjectiveFunctionParameters(SearchTreeRaoObjectiveFunctionParameters objectiveFunctionParameters) {
@@ -70,6 +71,10 @@ public void setMinMarginsParameters(SearchTreeRaoCostlyMinMarginParameters minMa
         this.minMarginsParameters = Optional.of(minMarginsParameters);
     }
 
+    public void setPstRegulationParameters(SearchTreeRaoPstRegulationParameters pstRegulationParameters) {
+        this.pstRegulationParameters = Optional.of(pstRegulationParameters);
+    }
+
     public SearchTreeRaoObjectiveFunctionParameters getObjectiveFunctionParameters() {
         return objectiveFunctionParameters;
     }
@@ -110,6 +115,10 @@ public Optional<SearchTreeRaoLoopFlowParameters> getLoopFlowParameters() {
         return loopFlowParameters;
     }
 
+    public Optional<SearchTreeRaoPstRegulationParameters> getPstRegulationParameters() {
+        return pstRegulationParameters;
+    }
+
     @Override
     public String getName() {
         return SEARCH_TREE_PARAMETERS;

ra-optimisation/rao-api/src/main/java/com/powsybl/openrao/raoapi/parameters/extensions/OpenRaoSearchTreeParametersConfigLoader.java

@@ -27,7 +27,7 @@ public class OpenRaoSearchTreeParametersConfigLoader implements RaoParameters.Co
     @Override
     public OpenRaoSearchTreeParameters load(PlatformConfig platformConfig) {
         Objects.requireNonNull(platformConfig);
-        List<String> searchTreeParams = Arrays.asList(ST_OBJECTIVE_FUNCTION_SECTION, ST_RANGE_ACTIONS_OPTIMIZATION_SECTION, ST_TOPOLOGICAL_ACTIONS_OPTIMIZATION_SECTION, MULTI_THREADING_SECTION, SECOND_PREVENTIVE_RAO_SECTION, LOAD_FLOW_AND_SENSITIVITY_COMPUTATION_SECTION, ST_MNEC_PARAMETERS_SECTION, ST_RELATIVE_MARGINS_SECTION, ST_LOOP_FLOW_PARAMETERS_SECTION, ST_COSTLY_MIN_MARGIN_SECTION);
+        List<String> searchTreeParams = Arrays.asList(ST_OBJECTIVE_FUNCTION_SECTION, ST_RANGE_ACTIONS_OPTIMIZATION_SECTION, ST_TOPOLOGICAL_ACTIONS_OPTIMIZATION_SECTION, MULTI_THREADING_SECTION, SECOND_PREVENTIVE_RAO_SECTION, LOAD_FLOW_AND_SENSITIVITY_COMPUTATION_SECTION, ST_MNEC_PARAMETERS_SECTION, ST_RELATIVE_MARGINS_SECTION, ST_LOOP_FLOW_PARAMETERS_SECTION, ST_COSTLY_MIN_MARGIN_SECTION, ST_PST_REGULATION_SECTION);
         boolean anySearchTreeParams = searchTreeParams.stream().map(platformConfig::getOptionalModuleConfig).anyMatch(Optional::isPresent);
         if (!anySearchTreeParams) {
             return null;
@@ -43,6 +43,7 @@ public OpenRaoSearchTreeParameters load(PlatformConfig platformConfig) {
         SearchTreeRaoMnecParameters.load(platformConfig).ifPresent(parameters::setMnecParameters);
         SearchTreeRaoRelativeMarginsParameters.load(platformConfig).ifPresent(parameters::setRelativeMarginsParameters);
         SearchTreeRaoLoopFlowParameters.load(platformConfig).ifPresent(parameters::setLoopFlowParameters);
+        SearchTreeRaoPstRegulationParameters.load(platformConfig).ifPresent(parameters::setPstRegulationParameters);
         return parameters;
     }