Replace ucte-x-node-code with pairing_key

docs/user_guide/sensitivity.rst

@@ -124,11 +124,13 @@ use the dangling line ID as the injection in the zone definition.
 
         >>> n = pp.network.load('simple-eu-xnode.uct')
         >>> n.get_dangling_lines()
-                            name    r     x    g    b   p0   q0   p   q   i voltage_level_id     bus_id  connected ucte-x-node-code isCoupler status_XNode geographicalName
+                            name    r     x    g    b   p0   q0   p   q   i voltage_level_id     bus_id  connected pairing_key ucte_xnode_code isCoupler status_XNode geographicalName
         id
-        NNL2AA1  XXXXXX11 1       0.0  10.0  0.0  0.0  0.0  0.0 NaN NaN NaN          NNL2AA1  NNL2AA1_0       True         XXXXXX11     false   EQUIVALENT         >>> zone_x = pp.sensitivity.create_empty_zone("X")
+        NNL2AA1         XXXXXX11    1   0.0 10.0  0.0  0.0  0.0 0.0 NaN NaN              NaN    NNL2AA1       True   NNL2AA1_0       NNL2AA1_0    True       XXXXXX11       EQUIVALENT
 
-We can see that the dangling line 'NNL2AA1  XXXXXX11 1' correspond to the X-Node XXXXXX11 (see column ucte-x-node-code of dangling line data frame).
+        >>> zone_x = pp.sensitivity.create_empty_zone("X")
+
+We can see that the dangling line 'NNL2AA1  XXXXXX11 1' correspond to the X-Node XXXXXX11 (see column pairing_key of dangling line data frame).
 To calculate to sensitivity of X-Node XXXXXX11 on tie line 'BBE2AA1  FFR3AA1  1':
 
 .. code-block:: python

java/src/main/java/com/powsybl/dataframe/network/NetworkDataframes.java

@@ -564,7 +564,8 @@ static NetworkDataframeMapper danglingLines() {
                 .strings("bus_breaker_bus_id", busBreakerViewBusId(), false)
                 .ints("node", dl -> getNode(dl.getTerminal()), false)
                 .booleans("connected", dl -> dl.getTerminal().isConnected(), connectInjection())
-                .strings("ucte-x-node-code", dl -> Objects.toString(dl.getPairingKey(), ""))
+                .strings("pairing_key", dl -> Objects.toString(dl.getPairingKey(), ""))
+                .strings("ucte_xnode_code", dl -> Objects.toString(dl.getPairingKey(), ""))
                 .booleans("fictitious", Identifiable::isFictitious, Identifiable::setFictitious, false)
                 .strings("tie_line_id", dl -> dl.getTieLine().map(Identifiable::getId).orElse(""))
                 .addProperties()
@@ -577,6 +578,7 @@ static NetworkDataframeMapper tieLines() {
                 .strings("name", tl -> tl.getOptionalName().orElse(""))
                 .strings("dangling_line1_id", tl -> tl.getDanglingLine1().getId())
                 .strings("dangling_line2_id", tl -> tl.getDanglingLine2().getId())
+                .strings("pairing_key", tl -> Objects.toString(tl.getPairingKey(), ""))
                 .strings("ucte_xnode_code", tl -> Objects.toString(tl.getPairingKey(), ""))
                 .booleans("fictitious", Identifiable::isFictitious, Identifiable::setFictitious, false)
                 .addProperties()

java/src/main/java/com/powsybl/dataframe/network/adders/DanglingLineDataframeAdder.java

@@ -40,7 +40,7 @@ public class DanglingLineDataframeAdder extends AbstractSimpleAdder {
             SeriesMetadata.doubles("x"),
             SeriesMetadata.doubles("g"),
             SeriesMetadata.doubles("b"),
-            SeriesMetadata.strings("ucte_xnode_code")
+            SeriesMetadata.strings("pairing_key")
     );
 
     @Override
@@ -58,7 +58,7 @@ private static class DanglingLineSeries extends InjectionSeries {
         private final DoubleSeries g;
         private final DoubleSeries b;
         private final StringSeries busOrBusbarSections;
-        private final StringSeries ucteXnodeCode;
+        private final StringSeries pairingKey;
 
         DanglingLineSeries(UpdatingDataframe dataframe) {
             super(dataframe);
@@ -70,7 +70,7 @@ private static class DanglingLineSeries extends InjectionSeries {
             this.g = dataframe.getDoubles("g");
             this.b = dataframe.getDoubles("b");
             this.busOrBusbarSections = dataframe.getStrings("bus_or_busbar_section_id");
-            this.ucteXnodeCode = dataframe.getStrings("ucte_xnode_code");
+            this.pairingKey = dataframe.getStrings("pairing_key");
         }
 
         DanglingLineAdder createAdder(Network network, int row) {
@@ -83,7 +83,7 @@ DanglingLineAdder createAdder(Network network, int row) {
             applyIfPresent(x, row, adder::setX);
             applyIfPresent(g, row, adder::setG);
             applyIfPresent(b, row, adder::setB);
-            applyIfPresent(ucteXnodeCode, row, adder::setPairingKey);
+            applyIfPresent(pairingKey, row, adder::setPairingKey);
             return adder;
         }
     }

java/src/test/java/com/powsybl/dataframe/network/NetworkDataframesTest.java

@@ -252,12 +252,12 @@ void danglingLines() {
         assertThat(series)
                 .extracting(Series::getName)
                 .containsExactly("id", "name", "r", "x", "g", "b", "p0", "q0", "p", "q", "i", "voltage_level_id", "bus_id",
-                        "connected", "ucte-x-node-code", "tie_line_id");
+                        "connected", "pairing_key", "ucte_xnode_code", "tie_line_id");
         List<Series> allAttributeSeries = createDataFrame(DANGLING_LINE, network, new DataframeFilter(ALL_ATTRIBUTES, Collections.emptyList()));
         assertThat(allAttributeSeries)
                 .extracting(Series::getName)
                 .containsExactly("id", "name", "r", "x", "g", "b", "p0", "q0", "p", "q", "i",
-                        "voltage_level_id", "bus_id", "bus_breaker_bus_id", "node", "connected", "ucte-x-node-code", "fictitious", "tie_line_id");
+                        "voltage_level_id", "bus_id", "bus_breaker_bus_id", "node", "connected", "pairing_key", "ucte_xnode_code", "fictitious", "tie_line_id");
     }
 
     @Test
@@ -267,11 +267,11 @@ void tieLines() {
 
         assertThat(series)
                 .extracting(Series::getName)
-                .containsExactly("id", "name", "dangling_line1_id", "dangling_line2_id", "ucte_xnode_code");
+                .containsExactly("id", "name", "dangling_line1_id", "dangling_line2_id", "pairing_key", "ucte_xnode_code");
         List<Series> allAttributeSeries = createDataFrame(TIE_LINE, network, new DataframeFilter(ALL_ATTRIBUTES, Collections.emptyList()));
         assertThat(allAttributeSeries)
                 .extracting(Series::getName)
-                .containsExactly("id", "name", "dangling_line1_id", "dangling_line2_id", "ucte_xnode_code", "fictitious");
+                .containsExactly("id", "name", "dangling_line1_id", "dangling_line2_id", "pairing_key", "ucte_xnode_code", "fictitious");
     }
 
     @Test

pypowsybl/network/impl/network.py

@@ -1130,7 +1130,8 @@ def get_dangling_lines(self, all_attributes: bool = False, attributes: List[str]
               - **node**  (optional): node where this line is connected, in node-breaker voltage levels
               - **connected**: ``True`` if the dangling line is connected to a bus
               - **fictitious** (optional): ``True`` if the dangling line is part of the model and not of the actual network
-              - **ucte-xnode-code**: the UCTE Xnode code associated to the dangling line, to be used for creating tie lines.
+              - **pairing_key**: the pairing key associated to the dangling line, to be used for creating tie lines.
+              - **ucte-xnode-code**: deprecated for pairing key.
               - **tie_line_id**: the ID of the tie line if the dangling line is paired
 
             This dataframe is indexed by the id of the dangling lines
@@ -3609,7 +3610,8 @@ def create_dangling_lines(self, df: DataFrame = None, **kwargs: ArrayLike) -> No
             - **x**: the reactance, in Ohms
             - **g**: the shunt conductance, in S
             - **b**: the shunt susceptance, in S
-            - **ucte-xnode-code**: the optional UCTE Xnode code associated to the dangling line, to be used for creating tie lines.
+            - **pairing-key**: the optional pairing key associated to the dangling line, to be used for creating tie lines.
+            - **ucte-x-node-code**: deprecated, use pairing-key instead.
 
         Examples:
             Using keyword arguments:
@@ -3619,6 +3621,16 @@ def create_dangling_lines(self, df: DataFrame = None, **kwargs: ArrayLike) -> No
                 network.create_dangling_lines(id='BAT-1', voltage_level_id='VL1', bus_id='B1',
                                               p0=10, q0=3, r=0, x=5, g=0, b=1e-6)
         """
+        ucte_xnode_code_str = 'ucte_xnode_code'
+        if df is not None:
+            if ucte_xnode_code_str in df.columns:
+                warnings.warn(ucte_xnode_code_str + " is deprecated, use pairing_key", DeprecationWarning)
+                df = df.rename(columns={ucte_xnode_code_str: 'pairing_key'})
+        ucte_x_node_code = kwargs.get(ucte_xnode_code_str)
+        if ucte_x_node_code is not None:
+            warnings.warn(ucte_xnode_code_str + " is deprecated, use pairing_key", DeprecationWarning)
+            kwargs['pairing_key'] = ucte_x_node_code
+            kwargs.pop(ucte_xnode_code_str)
         return self._create_elements(ElementType.DANGLING_LINE, [df], **kwargs)
 
     def create_lcc_converter_stations(self, df: DataFrame = None, **kwargs: ArrayLike) -> None:

tests/test_network.py

@@ -954,18 +954,18 @@ def test_dangling_lines():
     expected = pd.DataFrame(index=pd.Series(name='id', data=['DL']),
                             columns=['name', 'r', 'x', 'g', 'b', 'p0', 'q0', 'p', 'q', 'i', 'voltage_level_id',
                                      'bus_id',
-                                     'connected', 'ucte-x-node-code', 'tie_line_id'],
+                                     'connected', 'pairing_key', 'ucte_xnode_code', 'tie_line_id'],
                             data=[['', 10.0, 1.0, 0.0001, 0.00001, 50.0, 30.0, NaN, NaN, NaN, 'VL', 'VL_0', True,
-                                   '', '']])
+                                   '', '', '']])
     pd.testing.assert_frame_equal(expected, n.get_dangling_lines(), check_dtype=False)
     n.update_dangling_lines(
         pd.DataFrame(index=['DL'], columns=['r', 'x', 'g', 'b', 'p0', 'q0', 'connected'],
                      data=[[11.0, 1.1, 0.0002, 0.00002, 40.0, 40.0, False]]))
     updated = pd.DataFrame(index=pd.Series(name='id', data=['DL']),
                            columns=['name', 'r', 'x', 'g', 'b', 'p0', 'q0', 'p', 'q', 'i', 'voltage_level_id',
-                                    'bus_id',
-                                    'connected', 'ucte-x-node-code', 'tie_line_id'],
-                           data=[['', 11.0, 1.1, 0.0002, 0.00002, 40.0, 40.0, NaN, NaN, NaN, 'VL', '', False, '', '']])
+                                    'bus_id', 'connected', 'pairing_key', 'ucte_xnode_code', 'tie_line_id'],
+                           data=[['', 11.0, 1.1, 0.0002, 0.00002, 40.0, 40.0, NaN, NaN, NaN, 'VL', '', False,
+                                  '', '', '']])
     pd.testing.assert_frame_equal(updated, n.get_dangling_lines(), check_dtype=False)
     n = util.create_dangling_lines_network()
     dangling_lines = n.get_dangling_lines(attributes=['bus_breaker_bus_id', 'node'])

tests/test_network_elements_creation.py

@@ -873,7 +873,7 @@ def test_tie_line_creation_fail_if_xnodes_are_different():
     network.create_dangling_lines(id=['DL_TEST', 'DL_TEST2'], voltage_level_id=['VLTEST', 'VLTEST2'],
                                   bus_id=['BUS_TEST', 'BUS_TEST2'],
                                   p0=[100, 100], q0=[101, 101], r=[2, 2], x=[2, 2], g=[1, 1], b=[1, 1],
-                                  ucte_xnode_code=['XNODE1', 'XNODE'])
+                                  pairing_key=['XNODE1', 'XNODE'])
     df = pd.DataFrame.from_records(
         columns=['id', 'dangling_line1_id', 'dangling_line2_id'],
         data=[('TIE_LINE_TEST', 'DL_TEST', 'DL_TEST2')],
@@ -898,7 +898,44 @@ def test_tie_line_kwargs():
     assert 'TIE_LINE_TEST' in network.get_tie_lines().index
 
     network.update_tie_lines(id='TIE_LINE_TEST', fictitious=True)
-    assert network.get_tie_lines(True).loc['TIE_LINE_TEST'].fictitious == True
+    assert network.get_tie_lines(True).loc['TIE_LINE_TEST'].fictitious
 
     network.remove_elements('TIE_LINE_TEST')
     assert network.get_tie_lines().empty
+
+
+def test_deprecated_ucte_xnode_code_kwargs():
+    network = pn.create_empty()
+    network.create_substations(id=['S1', 'S2'], tso=['TERNA', 'RTE'])
+    network.create_voltage_levels(id=['VLTEST', 'VLTEST2'], high_voltage_limit=[250, 250],
+                                  low_voltage_limit=[200, 200],
+                                  nominal_v=[225, 225],
+                                  topology_kind=['BUS_BREAKER', 'BUS_BREAKER'])
+    network.create_buses(id=['BUS_TEST', 'BUS_TEST2'], voltage_level_id=['VLTEST', 'VLTEST2'])
+    with pytest.deprecated_call():
+        network.create_dangling_lines(id=['DL_TEST', 'DL_TEST2'], voltage_level_id=['VLTEST', 'VLTEST2'],
+                                      bus_id=['BUS_TEST', 'BUS_TEST2'],
+                                      p0=[100, 100], q0=[101, 101], r=[2, 2], x=[2, 2], g=[1, 1], b=[1, 1],
+                                      ucte_xnode_code=['XNODE1', 'XNODE'])
+    assert 'DL_TEST' in network.get_dangling_lines().index
+    assert 'DL_TEST2' in network.get_dangling_lines().index
+    assert 'ucte_xnode_code' in network.get_dangling_lines().columns
+
+
+def test_deprecated_ucte_xnode_code_dataframe():
+    network = pn.create_empty()
+    network.create_substations(id=['S1', 'S2'], tso=['TERNA', 'RTE'])
+    network.create_voltage_levels(id=['VLTEST', 'VLTEST2'], high_voltage_limit=[250, 250],
+                                  low_voltage_limit=[200, 200],
+                                  nominal_v=[225, 225],
+                                  topology_kind=['BUS_BREAKER', 'BUS_BREAKER'])
+    network.create_buses(id=['BUS_TEST', 'BUS_TEST2'], voltage_level_id=['VLTEST', 'VLTEST2'])
+    with pytest.deprecated_call():
+        network.create_dangling_lines(pd.DataFrame.from_records(
+            columns=['id', 'voltage_level_id', 'bus_id', 'p0', 'q0', 'r', 'x', 'g', 'b', 'ucte_xnode_code'],
+            data=[('DL_TEST', 'VLTEST', 'BUS_TEST', 100, 101, 2, 2, 1, 1, 'XNODE1'),
+                  ('DL_TEST2', 'VLTEST2', 'BUS_TEST2', 100, 101, 2, 2, 1, 1, 'XNODE')],
+            index='id'))
+    assert 'DL_TEST' in network.get_dangling_lines().index
+    assert 'DL_TEST2' in network.get_dangling_lines().index
+    assert 'ucte_xnode_code' in network.get_dangling_lines().columns

tests/test_per_unit.py

@@ -199,17 +199,17 @@ def test_dangling_lines_per_unit():
 
     expected = pd.DataFrame(index=pd.Series(name='id', data=['DL']),
                             columns=['name', 'r', 'x', 'g', 'b', 'p0', 'q0', 'p', 'q', 'i', 'voltage_level_id',
-                                     'bus_id', 'connected', 'ucte-x-node-code', 'tie_line_id'],
+                                     'bus_id', 'connected', 'pairing_key', 'ucte_xnode_code', 'tie_line_id'],
                             data=[['', 0.1, 0.01, 0.01, 0.001, 0.5, 0.3, 0.5482, 0.3029, 0.6263, 'VL', 'VL_0',
-                                   True, '', '']])
+                                   True, '', '', '']])
     dangling_lines = n.get_dangling_lines()
     pd.testing.assert_frame_equal(expected, dangling_lines, check_dtype=False, atol=10 ** -4)
     n.update_dangling_lines(pd.DataFrame(index=['DL'], columns=['p0', 'q0'], data=[[0.75, 0.25]]))
     expected = pd.DataFrame(index=pd.Series(name='id', data=['DL']),
                             columns=['name', 'r', 'x', 'g', 'b', 'p0', 'q0', 'p', 'q', 'i', 'voltage_level_id',
-                                     'bus_id', 'connected', 'ucte-x-node-code', 'tie_line_id'],
+                                     'bus_id', 'connected', 'pairing_key', 'ucte_xnode_code', 'tie_line_id'],
                             data=[['', 0.1, 0.01, 0.01, 0.001, 0.75, 0.25, 0.5482, 0.3029, 0.6263, 'VL', 'VL_0',
-                                   True, '', '']])
+                                   True, '', '', '']])
     dangling_lines = n.get_dangling_lines()
     pd.testing.assert_frame_equal(expected, dangling_lines, check_dtype=False, atol=10 ** -4)