Merge branch 'main' into fix-slack-ac-dc

Author: SylvestreSakti

docs/advanced_programming/contingency_active_power_loss.md

@@ -14,7 +14,7 @@ To add another plugin, you will need to code (in Java) an implementation of the
 interface and make this implementation available to the Java ServiceLoader (e.g. using Google's AutoService):
 - the `getName()` method should provide the plugin name - which can then be used in the `contingencyActivePowerLossDistribution` security analysis parameter
 - the `run(...)` method will be called by the security analysis engine for each contingency and should provide the logic.
-  This method has access to:
+  This method must return the amount of distributed active power (in per-unit) and has access to:
     - the network
     - the contingency in open-loadflow representation, including among others information about disconnected network elements, and how much active power has been lost.
     - the contingency definition

docs/loadflow/loadflow.md

@@ -3,7 +3,7 @@
 ## Grid modeling
 
 Open Load Flow computes power flows from IIDM grid model in bus/view topology. From the view, a very simple network, composed
-of only buses and branches is created. In the graph vision, we rely on a $\Pi$ model for branches (lines, transformers, dangling lines, etc.):
+of only buses and branches is created. In the graph vision, we rely on a $\Pi$ model for branches (lines, transformers, boundary lines, etc.):
 
 - $R$ and $X$ are respectively the real part (resistance) and the imaginary part (reactance) of the complex impedance ;  
 - $G_1$ and $G_2$ are the real parts (conductance) on respectively side 1 and side 2 of the branch ;
@@ -272,9 +272,9 @@ In such cases the involved areas are not considered in the Area Interchange Cont
 
 In iIDM each area defines the boundary points to be considered in the interchange. iIDM supports two ways of modeling area boundaries:
 - either via an equipment terminal,
-- or via a DanglingLine boundary.
+- or via a BoundaryLine boundary.
 
-In the DanglingLine case, the flow at the boundary side is considered as it should be, for both unpaired DanglingLines and DanglingLines paired in a TieLine.
+In the BoundaryLine case, the flow at the boundary side is considered as it should be, for both unpaired BoundaryLines and BoundaryLines paired in a TieLine.
 
 ### Slack bus mismatch attribution
 Depending on the location of the slack bus(es), the role of distributing the active power mismatch will be attributed based on the following logic:
@@ -298,6 +298,10 @@ It is computed like this:
 $Factor = sign(Slack Bus Mismatch) * Area Total Mismatch + areaInterchangePMaxMismatch $  
 Then factors are normalized to have sum of factors equal to 1.
 
+The distribution is iterative (inside the same outer loop iteration). 
+Each area distributes its share, if some areas cannot fully distribute it, they are excluded from this distribution and the remaining slack is distributed among other areas at next iteration.
+The distribution iterates until all the mismatch has been distributed and fails if all areas cannot distribute anymore but some mismatch remains.
+
 ### Zero impedance boundary branches
 The following applies when the [`lowImpedanceBranchMode`](parameters.md) is set to `REPLACE_BY_ZERO_IMPEDANCE_LINE`.
 Currently, computations involving zero-impedance branches used as boundary branches are not supported.

docs/loadflow/parameters.md

@@ -383,7 +383,7 @@ small reactive power ranger means limited to zero voltage control capability. Th
 - Generators
 - Batteries
 - Voltage Source Converters
-- The optional generation part of a Dangling Line
+- The optional generation part of a Boundary Line
 - Static VAR compensators
 
 For a given active power output, the reactive power range is defined as $MaxQ - MinQ$ (always a positive value).  

docs/sensitivity/getting_started.md

@@ -47,10 +47,10 @@ Here is a table to summarize supported use cases:
 ## Input function types
 
 ### Branch sensitivity functions : 
-BRANCH_ACTIVE_POWER_#, BRANCH_REACTIVE_POWER_# or BRANCH_CURRENT_# are associated to branch objects (lines, transformers, dangling lines, tie lines). The # index corresponding to the side of the studied branch. 
+BRANCH_ACTIVE_POWER_#, BRANCH_REACTIVE_POWER_# or BRANCH_CURRENT_# are associated to branch objects (lines, transformers, boundary lines, tie lines). The # index corresponding to the side of the studied branch. 
 - If it is a line, a tie line, or a two windings transformer : The side is 1 or 2.
 - If it is a three windings transformer : The side is 1, 2 or 3 corresponding to the studied leg of the transformer.
-- If it is a dangling line : The side is 1 (network side) or 2 (boundary side). Note that if the dangling line is paired, only side 1 (network side) can be specified, and the sensitivity function is computed at the corresponding tie line side.
+- If it is a boundary line : The side is 1 (network side) or 2 (boundary side). Note that if the boundary line is paired, only side 1 (network side) can be specified, and the sensitivity function is computed at the corresponding tie line side.
 
 ### Bus sensitivity functions :
 BUS_VOLTAGE or BUS_REACTIVE_POWER are associated to the bus of the given network element.

pom.xml

@@ -53,7 +53,7 @@
         <slf4jtoys.version>1.6.3</slf4jtoys.version>
         <asciitable.version>0.3.2</asciitable.version>
 
-        <powsybl-core.version>7.1.1</powsybl-core.version>
+        <powsybl-core.version>7.2.0-RC1</powsybl-core.version>
 
         <!--  This is required for later correct replacement of argline -->
         <argLine/>

src/main/java/com/powsybl/openloadflow/lf/AbstractLoadFlowResult.java

@@ -50,6 +50,7 @@ public OuterLoopResult getOuterLoopResult() {
         return outerLoopResult;
     }
 
+    @Override
     public double getDistributedActivePower() {
         return distributedActivePower;
     }

src/main/java/com/powsybl/openloadflow/lf/LoadFlowResult.java

@@ -24,4 +24,6 @@ record Status(com.powsybl.loadflow.LoadFlowResult.ComponentResult.Status status,
     double getSlackBusActivePowerMismatch();
 
     Status toComponentResultStatus();
+
+    double getDistributedActivePower();
 }

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

@@ -26,7 +26,6 @@
 import java.util.Comparator;
 import java.util.HashMap;
 import java.util.HashSet;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -63,7 +62,17 @@ private enum ActivePowerDistributionType {
         AREA_INTERCHANGE, SLACK
     }
 
-    private record AreaActivePowerDistributionResult(String areaId, ActivePowerDistributionType type, double initialMismatch, ActivePowerDistribution.Result distributionResult) { }
+    private record AreaActivePowerDistributionResult(String areaId, ActivePowerDistributionType type, double distributedMismatch, int iteration, boolean movedBuses, double remainingMismatch) { }
+
+    private AreaActivePowerDistributionResult updateResult(AreaActivePowerDistributionResult previousResult, double addedMismatch, ActivePowerDistribution.Result lastDistributionResult) {
+        return new AreaActivePowerDistributionResult(
+                previousResult.areaId(),
+                previousResult.type(),
+                previousResult.distributedMismatch() + addedMismatch - lastDistributionResult.remainingMismatch(),
+                previousResult.iteration() + lastDistributionResult.iteration(),
+                previousResult.movedBuses() || lastDistributionResult.movedBuses(),
+                lastDistributionResult.remainingMismatch());
+    }
 
     protected AbstractAreaInterchangeControlOuterLoop(ActivePowerDistribution activePowerDistribution, OuterLoop<V, E, P, C, O> noAreaOuterLoop, double slackBusPMaxMismatch, double areaInterchangePMaxMismatch, Logger logger) {
         this.activePowerDistribution = Objects.requireNonNull(activePowerDistribution);
@@ -124,7 +133,7 @@ public OuterLoopResult check(O context, ReportNode reportNode) {
                 Set<LfBus> busesWithoutArea = contextData.getBusesWithoutArea();
                 Map<String, Pair<Set<LfBus>, Double>> busesNoAreaDistributionMap = Map.of(DEFAULT_NO_AREA_NAME, Pair.of(busesWithoutArea, slackBusActivePowerMismatch));
                 List<AreaActivePowerDistributionResult> busesNoAreaDistributionResult = distributeActivePower(busesNoAreaDistributionMap);
-                double remainingSlackBusMismatch = busesNoAreaDistributionResult.get(0).distributionResult.remainingMismatch();
+                double remainingSlackBusMismatch = busesNoAreaDistributionResult.get(0).remainingMismatch();
                 if (lessThanSlackBusMaxMismatch(remainingSlackBusMismatch)) {
                     return buildOuterLoopResult(busesNoAreaDistributionResult, reportNode, context);
                 } else {
@@ -148,21 +157,32 @@ private List<AreaActivePowerDistributionResult> distributeActivePower(Map<String
         for (Map.Entry<String, Pair<Set<LfBus>, Double>> e : areas.entrySet()) {
             double areaActivePowerMismatch = e.getValue().getRight();
             ActivePowerDistribution.Result distributionResult = activePowerDistribution.run(null, e.getValue().getLeft(), areaActivePowerMismatch);
-            areaResults.add(new AreaActivePowerDistributionResult(e.getKey(), ActivePowerDistributionType.AREA_INTERCHANGE, areaActivePowerMismatch, distributionResult));
+            areaResults.add(new AreaActivePowerDistributionResult(e.getKey(), ActivePowerDistributionType.AREA_INTERCHANGE, areaActivePowerMismatch - distributionResult.remainingMismatch(), distributionResult.iteration(), distributionResult.movedBuses(), distributionResult.remainingMismatch()));
         }
         return areaResults;
     }
 
     private List<AreaActivePowerDistributionResult> distributeRemainingSlackMismatch(double mismatch, LfNetwork network, Map<String, Double> slackDistributionFactorByAreaId) {
-        List<AreaActivePowerDistributionResult> resultByArea = new ArrayList<>();
-
-        Map<LfArea, Double> distributionFactorByArea = getSlackDistributionFactorByArea(mismatch, network.getAreas(), slackDistributionFactorByAreaId);
+        Map<LfArea, AreaActivePowerDistributionResult> resultByArea = new HashMap<>();
+        Map<LfArea, Double> interchangeMarginByArea = getSlackDistributionFactorByArea(mismatch, network.getAreas(), slackDistributionFactorByAreaId);
+        Map<LfArea, Double> distributionFactorByArea = normalizeSlackParticipationFactors(interchangeMarginByArea);
+        double remainingMismatch = mismatch;
+        while (distributionFactorByArea.values().stream().mapToDouble(f -> f).sum() > 0 && Math.abs(remainingMismatch) > ActivePowerDistribution.P_RESIDUE_EPS) {
+            remainingMismatch = distributeOnAreas(remainingMismatch, distributionFactorByArea, resultByArea);
+            distributionFactorByArea = normalizeSlackParticipationFactors(distributionFactorByArea);
+        }
+        return resultByArea.values().stream().toList();
+    }
 
+    private double distributeOnAreas(double mismatch, Map<LfArea, Double> distributionFactorByArea, Map<LfArea, AreaActivePowerDistributionResult> resultByArea) {
         Comparator<Map.Entry<LfArea, Double>> mismatchComparator = Comparator.comparingDouble(Map.Entry::getValue);
-        Iterator<LfArea> areaIteratorSortedByFactor = distributionFactorByArea.entrySet().stream().
-                sorted(mismatchComparator.reversed())
+        // create an iterator of all areas, even for those with 0 factor in order to have the last distribution result for each area
+        List<LfArea> areasSortedByFactor = distributionFactorByArea.entrySet().stream()
+                .sorted(mismatchComparator.reversed())
                 .map(Map.Entry::getKey)
-                .iterator();
+                .toList();
+
+        var areaIteratorSortedByFactor = areasSortedByFactor.iterator();
 
         double remainingMismatch = mismatch;
         while (areaIteratorSortedByFactor.hasNext() && Math.abs(remainingMismatch) > ActivePowerDistribution.P_RESIDUE_EPS) {
@@ -177,23 +197,45 @@ private List<AreaActivePowerDistributionResult> distributeRemainingSlackMismatch
                 areaActivePowerMismatch = Math.signum(mismatch) * 1.01 * ActivePowerDistribution.P_RESIDUE_EPS;
             }
             ActivePowerDistribution.Result distributionResult = activePowerDistribution.run(null, area.getBuses(), areaActivePowerMismatch);
-            resultByArea.add(new AreaActivePowerDistributionResult(area.getId(), ActivePowerDistributionType.SLACK, areaActivePowerMismatch, distributionResult));
+
+            if (Math.abs(distributionResult.remainingMismatch()) > ActivePowerDistribution.P_RESIDUE_EPS) {
+                // The area cannot distribute anymore, its factor is set to 0
+                distributionFactorByArea.put(area, 0.);
+            }
+            var previousResult = resultByArea.getOrDefault(area, new AreaActivePowerDistributionResult(area.getId(), ActivePowerDistributionType.SLACK, 0, 0, false, 0));
+            resultByArea.put(area, updateResult(previousResult, areaActivePowerMismatch, distributionResult));
+
             remainingMismatch = remainingMismatch - areaActivePowerMismatch + distributionResult.remainingMismatch();
         }
-        return resultByArea;
+
+        while (areaIteratorSortedByFactor.hasNext()) {
+            // Set remaining mismatch to 0 for areas that were not used for last distribution
+            LfArea area = areaIteratorSortedByFactor.next();
+            resultByArea.computeIfPresent(area, (a, previousResult) ->
+                new AreaActivePowerDistributionResult(
+                        previousResult.areaId(),
+                        previousResult.type(),
+                        previousResult.distributedMismatch(),
+                        previousResult.iteration(),
+                        previousResult.movedBuses(),
+                        0.));
+        }
+
+        return remainingMismatch;
     }
 
     private Map<LfArea, Double> getSlackDistributionFactorByArea(double mismatch, List<LfArea> areas, Map<String, Double> slackDistributionFactorByAreaId) {
         // Compute the "margin" that has the area = the amount of power it can distribute and still have target - maxMismatch < interchange < target + maxMismatch
         // We use the interchangeMismatchWithSlack here because:
         // For areas without slack bus it changes nothing compared to use interchangeMismatch
         // For areas with slack bus, the interchangeMismatchWithSlack is the interchange it would have if all the slack was distributed.
-        Map<LfArea, Double> interchangeMarginByArea = areas.stream()
+        return areas.stream()
                 .collect(Collectors.toMap(
                         a -> a,
                         a -> Math.signum(mismatch) * getInterchangeMismatchWithSlack(a, mismatch, slackDistributionFactorByAreaId) + this.areaInterchangePMaxMismatch / PerUnit.SB));
+    }
 
-        // normalize factors
+    private Map<LfArea, Double> normalizeSlackParticipationFactors(Map<LfArea, Double> interchangeMarginByArea) {
         double sumMargin = interchangeMarginByArea.values().stream().mapToDouble(aDouble -> aDouble).sum();
         return interchangeMarginByArea.entrySet().stream()
                 .collect(Collectors.toMap(Map.Entry::getKey, e -> e.getValue() / sumMargin));
@@ -221,8 +263,8 @@ protected double getSlackInjection(String areaId, double slackBusActivePowerMism
 
     private boolean hasRemainingMismatch(AreaActivePowerDistributionResult areaResult) {
         return switch (areaResult.type) {
-            case SLACK -> !lessThanSlackBusMaxMismatch(areaResult.distributionResult.remainingMismatch());
-            case AREA_INTERCHANGE -> !lessThanInterchangeMaxMismatch(areaResult.distributionResult.remainingMismatch());
+            case SLACK -> !lessThanSlackBusMaxMismatch(areaResult.remainingMismatch());
+            case AREA_INTERCHANGE -> !lessThanInterchangeMaxMismatch(areaResult.remainingMismatch());
         };
     }
 
@@ -234,9 +276,8 @@ private OuterLoopResult buildOuterLoopResult(List<AreaActivePowerDistributionRes
             if (hasRemainingMismatch(areaResult)) {
                 remainingMismatches.add(areaResult);
             }
-            ActivePowerDistribution.Result distributionResult = areaResult.distributionResult;
-            totalDistributedActivePower += areaResult.initialMismatch - distributionResult.remainingMismatch();
-            movedBuses |= distributionResult.movedBuses();
+            totalDistributedActivePower += areaResult.distributedMismatch;
+            movedBuses |= areaResult.movedBuses();
         }
 
         ReportNode iterationReportNode = Reports.createOuterLoopIterationReporter(reportNode, context.getOuterLoopTotalIterations() + 1);
@@ -273,8 +314,8 @@ private void reportAndLogAreaActivePowerDistributionSuccess(List<AreaActivePower
         areaResults.stream().sorted(Comparator.comparing(areaResult -> areaResult.areaId)).forEach(areaResult -> {
             boolean isInterchangeDistribution = ActivePowerDistributionType.AREA_INTERCHANGE.equals(areaResult.type);
             String distributionType = isInterchangeDistribution ? "interchange mismatch" : "slack distribution share";
-            logger.info("Area {} {} ({} MW) distributed in {} distribution iteration(s)", areaResult.areaId, distributionType, areaResult.initialMismatch * PerUnit.SB, areaResult.distributionResult.iteration());
-            Reports.reportAicAreaDistributionSuccess(iterationReportNode, areaResult.areaId, areaResult.initialMismatch * PerUnit.SB, areaResult.distributionResult.iteration(), isInterchangeDistribution);
+            logger.info("Area {} {} ({} MW) distributed in {} distribution iteration(s)", areaResult.areaId, distributionType, areaResult.distributedMismatch * PerUnit.SB, areaResult.iteration());
+            Reports.reportAicAreaDistributionSuccess(iterationReportNode, areaResult.areaId, areaResult.distributedMismatch * PerUnit.SB, areaResult.iteration(), isInterchangeDistribution);
         });
     }
 
@@ -286,7 +327,7 @@ private void reportAndLogAreaActivePowerDistributionFailure(ReportNode iteration
                 .forEach(areaResult -> {
                     boolean isInterchangeDistribution = ActivePowerDistributionType.AREA_INTERCHANGE.equals(areaResult.type);
                     String mismatchType = isInterchangeDistribution ? "interchange" : "slack distribution";
-                    double remainingMismatch = areaResult.distributionResult.remainingMismatch() * PerUnit.SB;
+                    double remainingMismatch = areaResult.remainingMismatch() * PerUnit.SB;
                     logger.error("Remaining {} mismatch for Area {}: {} MW", mismatchType, areaResult.areaId, remainingMismatch);
                     Reports.reportAicAreaDistributionMismatch(failureReportNode, areaResult.areaId, remainingMismatch, isInterchangeDistribution);
                 });

src/main/java/com/powsybl/openloadflow/network/LfBranch.java

@@ -30,7 +30,7 @@ enum BranchType {
         TRANSFO_3_LEG_1,
         TRANSFO_3_LEG_2,
         TRANSFO_3_LEG_3,
-        DANGLING_LINE,
+        BOUNDARY_LINE,
         SWITCH,
         TIE_LINE
     }

src/main/java/com/powsybl/openloadflow/network/LfBus.java

@@ -7,9 +7,9 @@
  */
 package com.powsybl.openloadflow.network;
 
+import com.powsybl.contingency.violations.ViolationLocation;
 import com.powsybl.iidm.network.Country;
 import com.powsybl.openloadflow.util.Evaluable;
-import com.powsybl.security.ViolationLocation;
 import com.powsybl.security.results.BusResult;
 
 import java.util.*;