Merge branch 'main' into decomposed_flow_for_dangling_lines

# Conflicts:
#	flow-decomposition/src/test/java/com/powsybl/flow_decomposition/FlowDecompositionTests.java

balances-adjustment/src/test/java/com/powsybl/balances_adjustment/util/CountryAreaTest.java

@@ -107,7 +107,7 @@ void testGetLeavingFlowToCountry() {
     void testWithTieLine() {
         Network network = Network.read("controlArea.xiidm", getClass().getResourceAsStream("/controlArea.xiidm"));
         CountryArea countryAreaBE = countryAreaFactoryBE.create(network);
-        assertEquals(-261.858, countryAreaBE.getNetPosition(), 1e-3);
+        assertEquals(-261.863, countryAreaBE.getNetPosition(), 1e-3);
     }
 
     @Test

docs/flow_decomposition/algorithm-description.md

@@ -13,7 +13,21 @@ Below is the concrete description of the algorithm implemented in PowSyBl.
 Countries' net position computation is done once for all on base case using AC loadflow in the initial network, before any other alteration of the input.
 
 The net position of a country is calculated as the sum of the mean leaving flow of all AC and HVDC line interconnections
-(losses are shared equally between both countries)
+(losses are shared equally between both countries).
+
+Unpaired half lines contribute only to the net position of its physical terminal.
+
+For paired half lines, losses are not shared equally, they are split with respect to the boundary.
+
+The sum of net positions is equal to the opposite of the sum of the power on the boundary side of each unpaired half line.
+
+$$\sum_{\text{zone }z} \mathrm{NP}(z) = -\sum_{\text{unpaired half line }h} P_{\text{boundary side}}(h)$$
+
+where:
+- $\mathrm{NP}(\text{zone})$ is the net position of the zone $z$.
+- $P_{\text{boundary side}}(h)$ is the power on the boundary side of the unpaired half line $h$
+
+> **_NOTE:_** If all half lines are merged, the sum of net positions is zero.
 
 ## Losses compensation
 

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/FlowDecompositionComputer.java

@@ -17,6 +17,8 @@
 import com.powsybl.loadflow.LoadFlowParameters;
 import com.powsybl.sensitivity.SensitivityAnalysis;
 import com.powsybl.sensitivity.SensitivityVariableType;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.ArrayList;
 import java.util.Map;
@@ -28,8 +30,10 @@
  */
 public class FlowDecompositionComputer {
 
-    static final String DEFAULT_LOAD_FLOW_PROVIDER = null;
-    static final String DEFAULT_SENSITIVITY_ANALYSIS_PROVIDER = null;
+    private static final Logger LOGGER = LoggerFactory.getLogger(FlowDecompositionComputer.class);
+    static final String DEFAULT_LOAD_FLOW_PROVIDER = "OpenLoadFlow";
+    static final String DEFAULT_SENSITIVITY_ANALYSIS_PROVIDER = "OpenLoadFlow";
+    public static final LoadFlowParameters.ConnectedComponentMode MAIN_CONNECTED_COMPONENT = LoadFlowParameters.ConnectedComponentMode.MAIN;
     private final LoadFlowParameters loadFlowParameters;
     private final FlowDecompositionParameters parameters;
     private final LoadFlowRunningService loadFlowRunningService;
@@ -46,7 +50,12 @@ public FlowDecompositionComputer(FlowDecompositionParameters flowDecompositionPa
                                      LoadFlowParameters loadFlowParameters,
                                      String loadFlowProvider, String sensitivityAnalysisProvider) {
         this.parameters = flowDecompositionParameters;
-        this.loadFlowParameters = loadFlowParameters;
+        this.loadFlowParameters = loadFlowParameters.copy();
+        if (!MAIN_CONNECTED_COMPONENT.equals(this.loadFlowParameters.getConnectedComponentMode())) {
+            LOGGER.warn("Flow decomposition is currently available only on the main synchronous component. Changing connected component mode from {} to MAIN.",
+                    this.loadFlowParameters.getConnectedComponentMode());
+            this.loadFlowParameters.setConnectedComponentMode(MAIN_CONNECTED_COMPONENT);
+        }
         this.loadFlowRunningService = new LoadFlowRunningService(LoadFlow.find(loadFlowProvider));
         this.sensitivityAnalysisRunner = SensitivityAnalysis.find(sensitivityAnalysisProvider);
         this.lossesCompensator = parameters.isLossesCompensationEnabled() ? new LossesCompensator(parameters) : null;
@@ -273,4 +282,8 @@ private void computePstFlows(Network network,
         SparseMatrixWithIndexesCSC pstFlowMatrix = pstFlowComputer.run(network, networkMatrixIndexes, psdfMatrix);
         flowDecompositionResultBuilder.savePstFlowMatrix(pstFlowMatrix);
     }
+
+    protected LoadFlowParameters getLoadFlowParameters() {
+        return this.loadFlowParameters;
+    }
 }

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/FlowDecompositionObserver.java

@@ -62,9 +62,9 @@ public interface FlowDecompositionObserver {
     /**
      * Called when the PTDF matrix is computed (for base case or contingency)
      *
-     * @param pdtfMatrix the matrix of ptdf indexed by (line, node)
+     * @param ptdfMatrix the matrix of ptdf indexed by (line, node)
      */
-    void computedPtdfMatrix(Map<String, Map<String, Double>> pdtfMatrix);
+    void computedPtdfMatrix(Map<String, Map<String, Double>> ptdfMatrix);
 
     /**
      * Called when the PSDF matrix is computed (for base case or contingency)

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/LoadFlowRunningService.java

@@ -32,22 +32,22 @@ class LoadFlowRunningService {
     Result runAcLoadflow(Network network, LoadFlowParameters loadFlowParameters, boolean isDcFallbackEnabledAfterAcDivergence) {
         LoadFlowParameters acEnforcedParameters = enforceAcLoadFlowCalculation(loadFlowParameters);
         LoadFlowResult acLoadFlowResult = runner.run(network, acEnforcedParameters);
-        if (!acLoadFlowResult.isOk() && isDcFallbackEnabledAfterAcDivergence) {
+        if (!acLoadFlowResult.isFullyConverged() && isDcFallbackEnabledAfterAcDivergence) {
             LOGGER.warn("AC loadflow divergence. Running DC loadflow as fallback procedure.");
             return runDcLoadflow(network, loadFlowParameters)
                 .setFallbackHasBeenActivated(FALLBACK_HAS_BEEN_ACTIVATED);
         }
-        if (!acLoadFlowResult.isOk()) {
-            throw new PowsyblException("AC loadfow divergence without fallback procedure enabled.");
+        if (!acLoadFlowResult.isFullyConverged()) {
+            throw new PowsyblException("AC loadflow divergence without fallback procedure enabled.");
         }
         return new Result(acLoadFlowResult, FALLBACK_HAS_NOT_BEEN_ACTIVATED);
     }
 
     Result runDcLoadflow(Network network, LoadFlowParameters loadFlowParameters) {
         LoadFlowParameters dcEnforcedParameters = enforceDcLoadFlowCalculation(loadFlowParameters);
         LoadFlowResult dcLoadFlowResult = runner.run(network, dcEnforcedParameters);
-        if (!dcLoadFlowResult.isOk()) {
-            throw new PowsyblException("DC loadfow divergence.");
+        if (!dcLoadFlowResult.isFullyConverged()) {
+            throw new PowsyblException("DC loadflow divergence.");
         }
         return new Result(dcLoadFlowResult, FALLBACK_HAS_NOT_BEEN_ACTIVATED);
     }

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/NetPositionComputer.java

@@ -85,6 +85,6 @@ private static double getLeavingFlow(HvdcLine hvdcLine, Country country) {
     }
 
     private static double getLeavingFlow(DanglingLine danglingLine) {
-        return danglingLine.getTerminal().isConnected() && !Double.isNaN(danglingLine.getTerminal().getP()) ? danglingLine.getTerminal().getP() : 0;
+        return danglingLine.getTerminal().isConnected() && !Double.isNaN(danglingLine.getBoundary().getP()) ? -danglingLine.getBoundary().getP() : 0;
     }
 }

flow-decomposition/src/test/java/com/powsybl/flow_decomposition/CgmesIntegrationTests.java

@@ -6,17 +6,16 @@
  */
 package com.powsybl.flow_decomposition;
 
+import com.powsybl.cgmes.conformity.Cgmes3Catalog;
 import com.powsybl.cgmes.conformity.CgmesConformity1Catalog;
 import com.powsybl.flow_decomposition.xnec_provider.XnecProviderByIds;
-import com.powsybl.iidm.network.Bus;
-import com.powsybl.iidm.network.Importers;
-import com.powsybl.iidm.network.Load;
-import com.powsybl.iidm.network.Network;
+import com.powsybl.iidm.network.*;
 import com.powsybl.loadflow.LoadFlow;
 import com.powsybl.loadflow.LoadFlowParameters;
 import org.junit.jupiter.api.Test;
 
 import java.util.Map;
+import java.util.Properties;
 import java.util.Set;
 import java.util.function.Function;
 import java.util.stream.Collectors;
@@ -30,6 +29,7 @@
  */
 class CgmesIntegrationTests {
     private static final boolean AC_LOAD_FLOW = false;
+    private static final double DOUBLE_TOLERANCE = 1e-3;
 
     @Test
     void checkThatLossCompensationWorksWithNodeBreakerTopology() {
@@ -68,4 +68,18 @@ void checkFlowDecompositionWorksOnCgmesFile() {
         assertEquals(1, flowDecompositionResults.getDecomposedFlowMap().size());
         TestUtils.assertCoherenceTotalFlow(flowDecompositionParameters.getRescaleMode(), flowDecompositionResults);
     }
+
+    @Test
+    void testCoherentNetPosition() {
+        Properties importParams = new Properties();
+        Network network = Importers.importData("CGMES", Cgmes3Catalog.microGrid().dataSource(), importParams);
+        LoadFlow.run(network, new LoadFlowParameters().setDc(false));
+        assertEquals(0.0, network.getDanglingLineStream(DanglingLineFilter.PAIRED).filter(danglingLine -> Double.isFinite(danglingLine.getBoundary().getP())).mapToDouble(danglingLine -> danglingLine.getBoundary().getP()).sum(), DOUBLE_TOLERANCE);
+
+        Map<Country, Double> netPositions = NetPositionComputer.computeNetPositions(network);
+
+        assertEquals(0, netPositions.values().stream().mapToDouble(Double::doubleValue).sum(), DOUBLE_TOLERANCE);
+        assertEquals(-245.189, netPositions.get(Country.BE), DOUBLE_TOLERANCE);
+        assertEquals(245.189, netPositions.get(Country.NL), DOUBLE_TOLERANCE);
+    }
 }

flow-decomposition/src/test/java/com/powsybl/flow_decomposition/FlowDecompositionObserverTest.java

@@ -120,9 +120,9 @@ public void computedNodalInjectionsMatrix(Map<String, Map<String, Double>> nodal
         }
 
         @Override
-        public void computedPtdfMatrix(Map<String, Map<String, Double>> pdtfMatrix) {
+        public void computedPtdfMatrix(Map<String, Map<String, Double>> ptdfMatrix) {
             addEvent(Event.COMPUTED_PTDF_MATRIX);
-            this.ptdfs.put(currentContingency, pdtfMatrix);
+            this.ptdfs.put(currentContingency, ptdfMatrix);
         }
 
         @Override

flow-decomposition/src/test/java/com/powsybl/flow_decomposition/FlowDecompositionTests.java

@@ -40,12 +40,12 @@ void testFlowDecompositionOnNetworkWithBusBarSectionOnly() {
 
         FlowDecompositionResults flowDecompositionResults = runFlowDecomposition(network, new XnecProviderAllBranches());
         assertEquals(6, flowDecompositionResults.getDecomposedFlowMap().size());
-        validateFlowDecomposition(flowDecompositionResults, "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "", Country.BE, Country.BE, 105.367771, 115.127961, -8.071105, 30.705093, 33.029749, 59.464224, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "", Country.BE, Country.BE, -116.377022, -118.547677, -0.000000, 126.160372, -0.000000, -7.612696, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "b94318f6-6d24-4f56-96b9-df2531ad6543", "b94318f6-6d24-4f56-96b9-df2531ad6543", "", Country.BE, Country.BE, 0.330698, 0.287049, -4.994947, 76.274497, -33.029749, -37.962752, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "df16b3dd-c905-4a6f-84ee-f067be86f5da", "df16b3dd-c905-4a6f-84ee-f067be86f5da", "", Country.BE, Country.BE, -99.872370, -103.741300, 0.000000, 103.741300, -0.000000, -0.000000, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "e482b89a-fa84-4ea9-8e70-a83d44790957", "e482b89a-fa84-4ea9-8e70-a83d44790957", "", Country.BE, Country.BE, -94.838378, -84.584990, 13.066052, -106.979590, -0.000000, 178.498528, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "", Country.BE, Country.BE, -53.579738, -57.103247, -0.000000, 60.770208, -0.000000, -3.666960, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "", Country.BE, Country.BE, 105.349165, 115.128500, -8.895784, 30.705093, 33.029749, 60.289442, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "", Country.BE, Country.BE, -116.324382, -118.550024, -0.000000, 126.160372, -0.000000, -7.610348, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "b94318f6-6d24-4f56-96b9-df2531ad6543", "b94318f6-6d24-4f56-96b9-df2531ad6543", "", Country.BE, Country.BE, 0.298603, 0.288925, -5.505314, 76.274497, -33.029749, -37.450509, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "df16b3dd-c905-4a6f-84ee-f067be86f5da", "df16b3dd-c905-4a6f-84ee-f067be86f5da", "", Country.BE, Country.BE, -99.797280, -103.741300, 0.000000, 103.741300, -0.000000, -0.000000, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "e482b89a-fa84-4ea9-8e70-a83d44790957", "e482b89a-fa84-4ea9-8e70-a83d44790957", "", Country.BE, Country.BE, -94.889551, -84.582575, 14.401099, -106.979590, -0.000000, 177.161067, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "", Country.BE, Country.BE, -53.551022, -57.104378, -0.000000, 60.770208, -0.000000, -3.665830, 0.000000, 0.000000, 0.000000, 0.000000);
         assertEquals(1, flowDecompositionResults.getZoneSet().size());
         assertTrue(flowDecompositionResults.getZoneSet().contains(Country.BE));
 
@@ -57,12 +57,12 @@ void testFlowDecompositionOnNetworkWithShuntCompensatorOnly() {
 
         FlowDecompositionResults flowDecompositionResults = runFlowDecomposition(network, new XnecProviderAllBranches());
         assertEquals(6, flowDecompositionResults.getDecomposedFlowMap().size());
-        validateFlowDecomposition(flowDecompositionResults, "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "", Country.BE, Country.BE, 105.223381, 115.160484, -8.066648, 30.705093, 33.029749, 59.492290, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "", Country.BE, Country.BE, -116.362525, -118.534989, -0.000000, 126.160372, -0.000000, -7.625383, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "b94318f6-6d24-4f56-96b9-df2531ad6543", "b94318f6-6d24-4f56-96b9-df2531ad6543", "", Country.BE, Country.BE, -0.700299, 0.246463, -4.992189, 76.274497, -33.029749, -38.006096, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "df16b3dd-c905-4a6f-84ee-f067be86f5da", "df16b3dd-c905-4a6f-84ee-f067be86f5da", "", Country.BE, Country.BE, -99.868184, -103.741300, 0.000000, 103.741300, -0.000000, -0.000000, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "e482b89a-fa84-4ea9-8e70-a83d44790957", "e482b89a-fa84-4ea9-8e70-a83d44790957", "", Country.BE, Country.BE, -95.848612, -84.605325, 13.058837, -106.979590, -0.000000, 178.526079, 0.000000, 0.000000, 0.000000, 0.000000);
-        validateFlowDecomposition(flowDecompositionResults, "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "", Country.BE, Country.BE, -53.568417, -57.097136, -0.000000, 60.770208, -0.000000, -3.673072, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "a708c3bc-465d-4fe7-b6ef-6fa6408a62b0", "", Country.BE, Country.BE, 105.203730, 115.160115, -8.895784, 30.705093, 33.029749, 60.321057, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "b58bf21a-096a-4dae-9a01-3f03b60c24c7", "", Country.BE, Country.BE, -116.309968, -118.537339, -0.000000, 126.160372, -0.000000, -7.623033, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "b94318f6-6d24-4f56-96b9-df2531ad6543", "b94318f6-6d24-4f56-96b9-df2531ad6543", "", Country.BE, Country.BE, -0.732804, 0.247626, -5.505314, 76.274497, -33.029749, -37.491807, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "df16b3dd-c905-4a6f-84ee-f067be86f5da", "df16b3dd-c905-4a6f-84ee-f067be86f5da", "", Country.BE, Country.BE, -99.793176, -103.741300, 0.000000, 103.741300, -0.000000, -0.000000, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "e482b89a-fa84-4ea9-8e70-a83d44790957", "e482b89a-fa84-4ea9-8e70-a83d44790957", "", Country.BE, Country.BE, -95.900991, -84.604242, 14.401099, -106.979590, -0.000000, 177.182734, 0.000000, 0.000000, 0.000000, 0.000000);
+        validateFlowDecomposition(flowDecompositionResults, "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "ffbabc27-1ccd-4fdc-b037-e341706c8d29", "", Country.BE, Country.BE, -53.539743, -57.098268, -0.000000, 60.770208, -0.000000, -3.671940, 0.000000, 0.000000, 0.000000, 0.000000);
         assertEquals(1, flowDecompositionResults.getZoneSet().size());
         assertTrue(flowDecompositionResults.getZoneSet().contains(Country.BE));
 
@@ -198,6 +198,16 @@ void testFlowDecompositionOnHvdcNetwork() {
         assertTrue(flowDecompositionResults.getZoneSet().contains(Country.NL));
     }
 
+    @Test
+    void testConnectedComponentModeChangesFromAllToMain() {
+        LoadFlowParameters loadFlowParameters = new LoadFlowParameters().setConnectedComponentMode(LoadFlowParameters.ConnectedComponentMode.ALL);
+        FlowDecompositionComputer flowDecompositionComputer = new FlowDecompositionComputer(new FlowDecompositionParameters(), loadFlowParameters);
+        // lfParameters inside flow decomposition changed from all to main
+        assertEquals(FlowDecompositionComputer.MAIN_CONNECTED_COMPONENT, flowDecompositionComputer.getLoadFlowParameters().getConnectedComponentMode());
+        // original lfParameters didn't change
+        assertEquals(LoadFlowParameters.ConnectedComponentMode.ALL, loadFlowParameters.getConnectedComponentMode());
+    }
+
     @Test
     void testFlowDecompositionWithPairedDanglingLineResults() {
         String networkFileName = "NETWORK_SINGLE_LOAD_TWO_GENERATORS_WITH_XNODE.uct";