Access and conversion of contingency voltage level id (#3223)

* Add SidedContingencyElement interface for ContingencyElement with Voltage level id
* Add SidedContingencyElement static methods to get TwoSides enum from SidedContingencyElement

Signed-off-by: lisrte <[email protected]>

contingency/contingency-api/src/main/java/com/powsybl/contingency/AbstractSidedContingency.java

@@ -12,7 +12,7 @@
 /**
  * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
  */
-public abstract class AbstractSidedContingency implements ContingencyElement {
+public abstract class AbstractSidedContingency implements SidedContingencyElement {
 
     protected final String id;
 
@@ -32,6 +32,7 @@ public String getId() {
         return id;
     }
 
+    @Override
     public String getVoltageLevelId() {
         return voltageLevelId;
     }

contingency/contingency-api/src/main/java/com/powsybl/contingency/SidedContingencyElement.java

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2024, 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/.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+package com.powsybl.contingency;
+
+import com.powsybl.iidm.network.*;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.function.Function;
+
+/**
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public interface SidedContingencyElement extends ContingencyElement {
+
+    Logger LOGGER = LoggerFactory.getLogger(SidedContingencyElement.class);
+
+    String getVoltageLevelId();
+
+    static TwoSides getContingencySide(Network network, SidedContingencyElement element) {
+        String voltageLevelId = element.getVoltageLevelId();
+        if (voltageLevelId != null) {
+            Function<TwoSides, Terminal> terminalSupplier = getTerminalSupplier(network, element);
+            if (terminalSupplier != null) {
+                if (voltageLevelId.equals(terminalSupplier.apply(TwoSides.ONE).getVoltageLevel().getId())) {
+                    return TwoSides.ONE;
+                } else if (voltageLevelId.equals(terminalSupplier.apply(TwoSides.TWO).getVoltageLevel().getId())) {
+                    return TwoSides.TWO;
+                } else {
+                    LOGGER.warn("Voltage id '{}' of contingency '{}' not found", voltageLevelId, element.getId());
+                }
+            } else {
+                LOGGER.warn("Id of contingency '{}' not found", element.getId());
+            }
+        }
+        return null;
+    }
+
+    private static Function<TwoSides, Terminal> getTerminalSupplier(Network network, SidedContingencyElement element) {
+        return switch (element.getType()) {
+            case BRANCH -> getBranchTerminalSupplier(network, element.getId());
+            case HVDC_LINE -> getHvdcLineTerminalSupplier(network, element.getId());
+            case LINE -> getLineTerminalSupplier(network, element.getId());
+            case TIE_LINE -> getTieLineTerminalSupplier(network, element.getId());
+            case TWO_WINDINGS_TRANSFORMER -> getTransformerTerminalSupplier(network, element.getId());
+            default -> null;
+        };
+    }
+
+    private static Function<TwoSides, Terminal> getBranchTerminalSupplier(Network network, String id) {
+        Branch<?> eq = network.getBranch(id);
+        return eq != null ? eq::getTerminal : null;
+    }
+
+    private static Function<TwoSides, Terminal> getLineTerminalSupplier(Network network, String id) {
+        Line eq = network.getLine(id);
+        return eq != null ? eq::getTerminal : null;
+    }
+
+    private static Function<TwoSides, Terminal> getTieLineTerminalSupplier(Network network, String id) {
+        TieLine eq = network.getTieLine(id);
+        return eq != null ? eq::getTerminal : null;
+    }
+
+    private static Function<TwoSides, Terminal> getTransformerTerminalSupplier(Network network, String id) {
+        TwoWindingsTransformer eq = network.getTwoWindingsTransformer(id);
+        return eq != null ? eq::getTerminal : null;
+    }
+
+    private static Function<TwoSides, Terminal> getHvdcLineTerminalSupplier(Network network, String id) {
+        HvdcLine eq = network.getHvdcLine(id);
+        return eq != null ? s -> eq.getConverterStation(s).getTerminal() : null;
+    }
+}

contingency/contingency-api/src/test/java/com/powsybl/contingency/SidedContingencyTest.java

@@ -0,0 +1,81 @@
+/**
+ * Copyright (c) 2024, 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/.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+package com.powsybl.contingency;
+
+import com.powsybl.iidm.network.Network;
+import com.powsybl.iidm.network.TwoSides;
+import com.powsybl.iidm.network.test.EurostagTutorialExample1Factory;
+import com.powsybl.iidm.network.test.HvdcTestNetwork;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.util.stream.Stream;
+
+import static com.powsybl.iidm.network.test.EurostagTutorialExample1Factory.*;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+/**
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public class SidedContingencyTest {
+
+    private static Network eurostagNetwork;
+
+    @BeforeAll
+    public static void setup() {
+        eurostagNetwork = EurostagTutorialExample1Factory.create();
+    }
+
+    @ParameterizedTest(name = "{1}")
+    @MethodSource("sidedElementProvider")
+    void testSideGetter(Network network, SidedContingencyElement element, TwoSides expectedSide) {
+        assertEquals(expectedSide, SidedContingencyElement.getContingencySide(network, element));
+    }
+
+    @Test
+    void testIdNotFound() {
+        SidedContingencyElement element = new BranchContingency("WRONG_ID", VLHV2);
+        assertNull(SidedContingencyElement.getContingencySide(eurostagNetwork, element));
+    }
+
+    @Test
+    void testVoltageIdNotFound() {
+        SidedContingencyElement element = new BranchContingency(NHV1_NHV2_2, "WRONG_ID");
+        assertNull(SidedContingencyElement.getContingencySide(eurostagNetwork, element));
+    }
+
+    @Test
+    void testNullVoltageId() {
+        SidedContingencyElement element = new BranchContingency(NHV1_NHV2_2);
+        assertNull(SidedContingencyElement.getContingencySide(eurostagNetwork, element));
+    }
+
+    private static Stream<Arguments> sidedElementProvider() {
+        return Stream.of(
+                Arguments.of(eurostagNetwork,
+                        new TwoWindingsTransformerContingency(NGEN_NHV1, VLGEN),
+                        TwoSides.ONE),
+                Arguments.of(eurostagNetwork,
+                        new LineContingency(NHV1_NHV2_1, VLHV1),
+                        TwoSides.ONE),
+                Arguments.of(eurostagNetwork,
+                        new BranchContingency(NHV1_NHV2_2, VLHV2),
+                        TwoSides.TWO),
+                Arguments.of(EurostagTutorialExample1Factory.createWithTieLine(),
+                        new TieLineContingency(NHV1_NHV2_1, VLHV2),
+                        TwoSides.TWO),
+                Arguments.of(HvdcTestNetwork.createVsc(),
+                        new HvdcLineContingency("L", "VL2"),
+                        TwoSides.TWO)
+        );
+    }
+}

iidm/iidm-test/src/main/java/com/powsybl/iidm/network/test/EurostagTutorialExample1Factory.java

@@ -18,8 +18,8 @@
  */
 public final class EurostagTutorialExample1Factory {
 
-    private static final String VLGEN = "VLGEN";
-    private static final String VLLOAD = "VLLOAD";
+    public static final String VLGEN = "VLGEN";
+    public static final String VLLOAD = "VLLOAD";
     public static final String CASE_DATE = "2018-01-01T11:00:00+01:00";
     public static final String DANGLING_LINE_XNODE1_1 = "NHV1_XNODE1";
     public static final String DANGLING_LINE_XNODE1_2 = "XNODE1_NHV2";