Security Analysis: add distributedActivePower to results (#1351)

jeandemanged · web-flow · commit 6f892b055255 · 2026-03-23T15:53:56.000+01:00
Signed-off-by: Damien Jeandemange &lt;damien.jeandemange@artelys.com&gt;
diff --git a/docs/advanced_programming/contingency_active_power_loss.md b/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
diff --git a/src/main/java/com/powsybl/openloadflow/lf/AbstractLoadFlowResult.java b/src/main/java/com/powsybl/openloadflow/lf/AbstractLoadFlowResult.java
@@ -50,6 +50,7 @@ public OuterLoopResult getOuterLoopResult() {
         return outerLoopResult;
     }
 
+    @Override
     public double getDistributedActivePower() {
         return distributedActivePower;
     }
diff --git a/src/main/java/com/powsybl/openloadflow/lf/LoadFlowResult.java b/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();
 }
diff --git a/src/main/java/com/powsybl/openloadflow/sa/AbstractSecurityAnalysis.java b/src/main/java/com/powsybl/openloadflow/sa/AbstractSecurityAnalysis.java
@@ -227,9 +227,10 @@ SecurityAnalysisResult runSimulationsOnAllComponents(LfNetworkList networks, Lis
         }
 
         // run simulation on first lfNetwork to initialize results structures
-        LfNetwork firstNetwork = networkToSimulate.remove(0);
+        LfNetwork firstNetwork = networkToSimulate.removeFirst();
         SecurityAnalysisResult result = runSimulations(firstNetwork, propagatedContingencies, parameters, securityAnalysisParameters,
                 operatorStrategies, actions, limitReductions, contingencyActivePowerLossDistribution);
+        double preContingencyDistributedActivePower = result.getPreContingencyResult().getDistributedActivePower();
 
         List<PostContingencyResult> postContingencyResults = result.getPostContingencyResults();
         List<OperatorStrategyResult> operatorStrategyResults = result.getOperatorStrategyResults();
@@ -249,6 +250,7 @@ SecurityAnalysisResult runSimulationsOnAllComponents(LfNetworkList networks, Lis
                     operatorStrategies, actions, limitReductions, contingencyActivePowerLossDistribution);
 
             // Merge into first result
+            preContingencyDistributedActivePower += resultOtherComponent.getPreContingencyResult().getDistributedActivePower();
             // PreContingency results first
             preContingencyViolations.addAll(resultOtherComponent.getPreContingencyResult().getLimitViolationsResult().getLimitViolations());
             mergedPreContingencyNetworkResult = mergeNetworkResult(mergedPreContingencyNetworkResult, resultOtherComponent.getPreContingencyResult().getNetworkResult());
@@ -262,7 +264,7 @@ SecurityAnalysisResult runSimulationsOnAllComponents(LfNetworkList networks, Lis
         PreContingencyResult mergedPrecontingencyResult =
             new PreContingencyResult(result.getPreContingencyResult().getStatus(),
                 new LimitViolationsResult(preContingencyViolations),
-                mergedPreContingencyNetworkResult, Double.NaN);
+                mergedPreContingencyNetworkResult, preContingencyDistributedActivePower);
         return new SecurityAnalysisResult(mergedPrecontingencyResult, postContingencyResults, operatorStrategyResults);
     }
 
@@ -291,7 +293,8 @@ void mergeSecurityAnalysisResult(SecurityAnalysisResult resultToMerge, Map<Strin
 
                 PostContingencyResult mergedPostContingencyResult =
                         new PostContingencyResult(originalResult.getContingency(), originalResult.getStatus(),
-                                new LimitViolationsResult(violations), mergedNetworkResult, originalResult.getConnectivityResult(), Double.NaN);
+                                new LimitViolationsResult(violations), mergedNetworkResult, originalResult.getConnectivityResult(),
+                                originalResult.getDistributedActivePower() + postContingencyResult.getDistributedActivePower());
 
                 postContingencyResults.put(contingencyId, mergedPostContingencyResult);
             } else {
@@ -317,7 +320,8 @@ void mergeSecurityAnalysisResult(SecurityAnalysisResult resultToMerge, Map<Strin
 
                         OperatorStrategyResult.ConditionalActionsResult mergedConditionalActionResult
                                 = new OperatorStrategyResult.ConditionalActionsResult(conditionalActionsResult.getConditionalActionsId(),
-                                conditionalActionsResult.getStatus(), new LimitViolationsResult(violations), mergedNetworkResult, Double.NaN);
+                                conditionalActionsResult.getStatus(), new LimitViolationsResult(violations), mergedNetworkResult,
+                                originalRes.get().getDistributedActivePower() + conditionalActionsResult.getDistributedActivePower());
                         conditionalActionsResults.add(mergedConditionalActionResult);
 
                     } else {
@@ -750,12 +754,12 @@ protected SecurityAnalysisResult runSimulations(LfNetwork lfNetwork, List<Propag
 
                                 lfContingency.apply(loadFlowParameters.getBalanceType());
 
-                                contingencyActivePowerLossDistribution.run(lfNetwork, lfContingency, propagatedContingency.getContingency(), securityAnalysisParameters, contingencyLoadFlowParameters, postContSimReportNode);
+                                double preDistributedActivePower = contingencyActivePowerLossDistribution.run(lfNetwork, lfContingency, propagatedContingency.getContingency(), securityAnalysisParameters, contingencyLoadFlowParameters, postContSimReportNode);
 
                                 var postContingencyResult = runPostContingencySimulation(lfNetwork, context, propagatedContingency.getContingency(),
                                                                                          lfContingency, preContingencyLimitViolationManager,
                                                                                          securityAnalysisParameters,
-                                                                                         preContingencyNetworkResult, createResultExtension, limitReductions);
+                                                                                         preContingencyNetworkResult, createResultExtension, limitReductions, preDistributedActivePower);
                                 postContingencyResults.add(postContingencyResult);
 
                                 if (contingencyLoadFlowParameters != null &&
@@ -819,7 +823,8 @@ protected SecurityAnalysisResult runSimulations(LfNetwork lfNetwork, List<Propag
                             preContingencyLoadFlowResult.toComponentResultStatus().status(),
                             new LimitViolationsResult(preContingencyLimitViolationManager.getLimitViolations()),
                             new NetworkResult(preContingencyNetworkResult.getBranchResults(), preContingencyNetworkResult.getBusResults(),
-                            preContingencyNetworkResult.getThreeWindingsTransformerResults()), Double.NaN),
+                            preContingencyNetworkResult.getThreeWindingsTransformerResults()),
+                            preContingencyLoadFlowResult.getDistributedActivePower() * PerUnit.SB),
                     postContingencyResults, operatorStrategyResults);
         }
     }
@@ -865,13 +870,14 @@ protected PostContingencyResult runPostContingencySimulation(LfNetwork network,
                                                                  LimitViolationManager preContingencyLimitViolationManager,
                                                                  SecurityAnalysisParameters securityAnalysisParameters,
                                                                  PreContingencyNetworkResult preContingencyNetworkResult, boolean createResultExtension,
-                                                                 List<LimitReduction> limitReductions) {
+                                                                 List<LimitReduction> limitReductions, double preDistributedActivePower) {
         logPostContingencyStart(network, lfContingency);
 
         Stopwatch stopwatch = Stopwatch.createStarted();
 
         // restart LF on post contingency equation system
-        PostContingencyComputationStatus status = runActionLoadFlow(context); // FIXME: change name.
+        R result = createLoadFlowEngine(context).run();
+        PostContingencyComputationStatus status = postContingencyStatusFromLoadFlowResult(result);
         var postContingencyLimitViolationManager = new LimitViolationManager(preContingencyLimitViolationManager, limitReductions, securityAnalysisParameters.getIncreasedViolationsParameters());
 
         LoadFlowModel loadFlowModel = securityAnalysisParameters.getLoadFlowParameters().isDc() ? LoadFlowModel.DC : LoadFlowModel.AC;
@@ -893,12 +899,15 @@ protected PostContingencyResult runPostContingencySimulation(LfNetwork network,
                 lfContingency.getDisconnectedGenerationActivePower() * PerUnit.SB,
                 lfContingency.getDisconnectedElementIds());
 
-        return new PostContingencyResult(contingency, status,
+        return new PostContingencyResult(
+                contingency,
+                status,
                 new LimitViolationsResult(postContingencyLimitViolationManager.getLimitViolations()),
                 new NetworkResult(postContingencyNetworkResult.getBranchResults(),
                 postContingencyNetworkResult.getBusResults(),
                 postContingencyNetworkResult.getThreeWindingsTransformerResults()),
-                connectivityResult, Double.NaN);
+                connectivityResult,
+                (preDistributedActivePower + result.getDistributedActivePower()) * PerUnit.SB);
     }
 
     protected void logPostContingencyStart(LfNetwork network, LfContingency lfContingency) {
@@ -934,7 +943,8 @@ protected OperatorStrategyResult runActionSimulation(LfNetwork network, C contex
         Stopwatch stopwatch = Stopwatch.createStarted();
 
         // restart LF on post contingency and post actions equation system
-        PostContingencyComputationStatus status = runActionLoadFlow(context);
+        R result = createLoadFlowEngine(context).run();
+        PostContingencyComputationStatus status = postContingencyStatusFromLoadFlowResult(result);
         var postActionsViolationManager = new LimitViolationManager(preContingencyLimitViolationManager, limitReductions, securityAnalysisParameters.getIncreasedViolationsParameters());
         LoadFlowModel loadFlowModel = securityAnalysisParameters.getLoadFlowParameters().isDc() ? LoadFlowModel.DC : LoadFlowModel.AC;
         var postActionsNetworkResult = new PreContingencyNetworkResult(network, new AbstractNetworkResult.StateMonitorIndexes(monitorIndex, zeroImpedanceMonitoredIndex), createResultExtension,
@@ -958,7 +968,7 @@ protected OperatorStrategyResult runActionSimulation(LfNetwork network, C contex
                                           new NetworkResult(postActionsNetworkResult.getBranchResults(),
                                                             postActionsNetworkResult.getBusResults(),
                                                             postActionsNetworkResult.getThreeWindingsTransformerResults()),
-                        Double.NaN)
+                        result.getDistributedActivePower() * PerUnit.SB)
                 ));
     }
 
@@ -972,8 +982,4 @@ protected void logActionEnd(LfNetwork network, OperatorStrategy operatorStrategy
                 operatorStrategy.getContingencyContext().getContingencyId(), network, stopwatch.elapsed(TimeUnit.MILLISECONDS));
     }
 
-    protected PostContingencyComputationStatus runActionLoadFlow(C context) {
-        R result = createLoadFlowEngine(context).run();
-        return postContingencyStatusFromLoadFlowResult(result);
-    }
 }
diff --git a/src/main/java/com/powsybl/openloadflow/sa/ContingencyActivePowerLossDistribution.java b/src/main/java/com/powsybl/openloadflow/sa/ContingencyActivePowerLossDistribution.java
@@ -21,6 +21,7 @@
 import java.util.ServiceLoader;
 
 /**
+ * Handling of active power injection lost by contingency.
  * @author Damien Jeandemange {@literal <damien.jeandemange at artelys.com>}
  */
 public interface ContingencyActivePowerLossDistribution {
@@ -37,6 +38,16 @@ static ContingencyActivePowerLossDistribution find(String name) {
 
     String getName();
 
-    void run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode);
+    /**
+     * Called by the security analysis engine for each contingency. Pre-distributes active power imbalances created by contingencies (disconnection of loads, of generators, ...).
+     * @param network the network
+     * @param lfContingency the contingency in open-loadflow representation, including among others information about disconnected network elements, and how much active power has been lost
+     * @param contingency the contingency definition
+     * @param securityAnalysisParameters the security analysis parameters
+     * @param loadFlowParametersOverride the contingency load flow parameters overrides if any
+     * @param reportNode the contingency report node - so that the plugin may add any report message needed
+     * @return the amount of distributed active power in per-unit
+     */
+    double run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode);
 
 }
diff --git a/src/main/java/com/powsybl/openloadflow/sa/DefaultContingencyActivePowerLossDistribution.java b/src/main/java/com/powsybl/openloadflow/sa/DefaultContingencyActivePowerLossDistribution.java
@@ -36,7 +36,7 @@ public String getName() {
     }
 
     @Override
-    public void run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode) {
+    public double run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode) {
         Objects.requireNonNull(network);
         Objects.requireNonNull(lfContingency);
         Objects.requireNonNull(contingency);
@@ -51,7 +51,9 @@ public void run(LfNetwork network, LfContingency lfContingency, Contingency cont
             ActivePowerDistribution activePowerDistribution = ActivePowerDistribution.create(paramsOverride.getBalanceType(loadFlowParameters), openLoadFlowParameters.isLoadPowerFactorConstant(), openLoadFlowParameters.isUseActiveLimits());
             var result = activePowerDistribution.run(network, mismatch);
             Reports.reportContingencyActivePowerLossDistribution(reportNode, mismatch * PerUnit.SB, result.remainingMismatch() * PerUnit.SB);
+            return mismatch - result.remainingMismatch();
         }
+        return 0.0;
     }
 
 }
diff --git a/src/main/java/com/powsybl/openloadflow/sa/WoodburyDcSecurityAnalysis.java b/src/main/java/com/powsybl/openloadflow/sa/WoodburyDcSecurityAnalysis.java
@@ -242,13 +242,16 @@ private PostContingencyResult computePostContingencyResultFromPostContingencySta
                 lfContingency.getDisconnectedGenerationActivePower() * PerUnit.SB,
                 lfContingency.getDisconnectedElementIds());
 
-        return new PostContingencyResult(contingency,
+        return new PostContingencyResult(
+                contingency,
                 PostContingencyComputationStatus.CONVERGED,
                 new LimitViolationsResult(postContingencyLimitViolationManager.getLimitViolations()),
                 new NetworkResult(postContingencyNetworkResult.getBranchResults(),
                 postContingencyNetworkResult.getBusResults(),
                 postContingencyNetworkResult.getThreeWindingsTransformerResults()),
-                connectivityResult, Double.NaN);
+                connectivityResult,
+                Double.NaN  // TODO: report distributed active power in Fast DC SA
+        );
     }
 
     /**
@@ -285,7 +288,7 @@ private OperatorStrategyResult computeOperatorStrategyResultFromPostContingencyA
                     new NetworkResult(postActionsNetworkResult.getBranchResults(),
                         postActionsNetworkResult.getBusResults(),
                         postActionsNetworkResult.getThreeWindingsTransformerResults()),
-                    Double.NaN)
+                    Double.NaN) // TODO: report distributed active power in Fast DC SA
             )
         );
     }
@@ -519,7 +522,8 @@ protected SecurityAnalysisResult runSimulations(LfNetwork lfNetwork, List<Propag
                     new PreContingencyResult(LoadFlowResult.ComponentResult.Status.CONVERGED,
                             new LimitViolationsResult(preContingencyLimitViolationManager.getLimitViolations()),
                             new NetworkResult(preContingencyNetworkResult.getBranchResults(), preContingencyNetworkResult.getBusResults(),
-                            preContingencyNetworkResult.getThreeWindingsTransformerResults()), Double.NaN),
+                            preContingencyNetworkResult.getThreeWindingsTransformerResults()),
+                            Double.NaN), // TODO: report distributed active power in Fast DC SA
                             postContingencyResults, operatorStrategyResults);
         }
     }
diff --git a/src/test/java/com/powsybl/openloadflow/sa/OpenSecurityAnalysisWithActionsTest.java b/src/test/java/com/powsybl/openloadflow/sa/OpenSecurityAnalysisWithActionsTest.java

Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,7 @@ public OuterLoopResult getOuterLoopResult() {`
`50`	`50`	`return outerLoopResult;`
`51`	`51`	`}`
`52`	`52`
	`53`	`+ @Override`
`53`	`54`	`public double getDistributedActivePower() {`
`54`	`55`	`return distributedActivePower;`
`55`	`56`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,4 +24,6 @@ record Status(com.powsybl.loadflow.LoadFlowResult.ComponentResult.Status status,`
`24`	`24`	`double getSlackBusActivePowerMismatch();`
`25`	`25`
`26`	`26`	`Status toComponentResultStatus();`
	`27`	`+`
	`28`	`+ double getDistributedActivePower();`
`27`	`29`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ public String getName() {`
`36`	`36`	`}`
`37`	`37`
`38`	`38`	`@Override`
`39`		`- public void run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode) {`
	`39`	`+ public double run(LfNetwork network, LfContingency lfContingency, Contingency contingency, SecurityAnalysisParameters securityAnalysisParameters, LoadFlowParametersOverride loadFlowParametersOverride, ReportNode reportNode) {`
`40`	`40`	`Objects.requireNonNull(network);`
`41`	`41`	`Objects.requireNonNull(lfContingency);`
`42`	`42`	`Objects.requireNonNull(contingency);`
`@@ -51,7 +51,9 @@ public void run(LfNetwork network, LfContingency lfContingency, Contingency cont`
`51`	`51`	`ActivePowerDistribution activePowerDistribution = ActivePowerDistribution.create(paramsOverride.getBalanceType(loadFlowParameters), openLoadFlowParameters.isLoadPowerFactorConstant(), openLoadFlowParameters.isUseActiveLimits());`
`52`	`52`	`var result = activePowerDistribution.run(network, mismatch);`
`53`	`53`	`Reports.reportContingencyActivePowerLossDistribution(reportNode, mismatch * PerUnit.SB, result.remainingMismatch() * PerUnit.SB);`
	`54`	`+ return mismatch - result.remainingMismatch();`
`54`	`55`	`}`
	`56`	`+ return 0.0;`
`55`	`57`	`}`
`56`	`58`
`57`	`59`	`}`