Merge branch 'main' into hvdc_ac_emulation_outerloop

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

@@ -300,6 +300,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.

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);
                 });