Add DanglingLine boundary side boundary_i (#926)

Signed-off-by: Damien Jeandemange <[email protected]>

docs/user_guide/per_unit.rst

@@ -31,7 +31,8 @@ The nominal apparent power is by default 100 MVA. It can be set like this :
 Per Unit formula
 ----------------
 
-#. Resistance R
+Resistance R
+~~~~~~~~~~~~
 
 for network elements with only one nominal voltage :
 
@@ -43,7 +44,8 @@ For lines, it is according to both sides :
 
 .. math:: \frac{S_n}{V_{nominal1} V_{nominal2}} R
 
-#. Reactance X
+Reactance X
+~~~~~~~~~~~
 
 for network elements with only one nominal voltage :
 
@@ -55,7 +57,8 @@ For lines, it is according to both sides :
 
 .. math:: \frac{S_n}{V_{nominal1} V_{nominal2}} X
 
-#. Susceptance B
+Susceptance B
+~~~~~~~~~~~~~
 
 for network elements with only one nominal voltage :
 
@@ -69,7 +72,8 @@ For lines, B is **on side one** according to both sides :
 
 where Y is the admittance (Y = 1/Z where Z is the impedance) and Im() the imaginary part
 
-#. Conductance G
+Conductance G
+~~~~~~~~~~~~~
 
 for network elements with only one nominal voltage :
 
@@ -84,30 +88,35 @@ For lines, G is **on side one** according to both sides :
 where Y is the admittance (Y = 1/Z where Z is the impedance) and Re() the real part
 for side 2 just inverse Vnominal1 and Vnominal2
 
-#. Voltage V
+Voltage V
+~~~~~~~~~
 
 .. math:: \frac{V}{V_{nominal}}
 
 the voltage is perunit by the nominal voltage. For network element with a target voltage, it per united by the nominal voltage of the target element.
 
-#. Active Power P
+Active Power P
+~~~~~~~~~~~~~~
 
 .. math:: \frac{P}{S_{n}}
 
 with Sn the nominal apparent power
 
-#. Reactive Power Q
+Reactive Power Q
+~~~~~~~~~~~~~~~~
 
 .. math:: \frac{Q}{S_{n}}
 
 with Sn the nominal apparent power
 
-#. Electric Current I
+Electric Current I
+~~~~~~~~~~~~~~~~~~
 
 .. math:: \frac{ \sqrt{3} V_{nominal}}{S_{n} 10^3} I
 
 with Sn the nominal apparent power
 
-#. Angle
+Angle
+~~~~~
 
-the angle are in degrees in PyPowSyBl, but when per-unit is activated it is in radian even if it is not really related to per-uniting.
+the angle are in degrees in PyPowSyBl, but when per-unit is activated it is in radian even if it is not really related to per-uniting.

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

@@ -660,6 +660,7 @@ static NetworkDataframeMapper danglingLines() {
                 .doubles("i", (dl, context) -> perUnitI(context, dl.getTerminal()))
                 .doubles("boundary_p", (dl, context) -> perUnitPQ(context, dl.getBoundary().getP()), false)
                 .doubles("boundary_q", (dl, context) -> perUnitPQ(context, dl.getBoundary().getQ()), false)
+                .doubles("boundary_i", (dl, context) -> perUnitI(context, dl.getBoundary().getI(), dl.getTerminal().getVoltageLevel().getNominalV()), false)
                 .doubles("boundary_v_mag", (dl, context) -> perUnitV(context, dl.getBoundary().getV(), dl.getTerminal()), false)
                 .doubles("boundary_v_angle", (dl, context) -> perUnitAngle(context, dl.getBoundary().getAngle()), false)
                 .strings("voltage_level_id", getVoltageLevelId())

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

@@ -332,7 +332,7 @@ void danglingLines() {
         assertThat(allAttributeSeries)
                 .extracting(Series::getName)
                 .containsExactly("id", "name", "r", "x", "g", "b", "p0", "q0", "p", "q", "i",
-                        "boundary_p", "boundary_q", "boundary_v_mag", "boundary_v_angle",
+                        "boundary_p", "boundary_q", "boundary_i", "boundary_v_mag", "boundary_v_angle",
                         "voltage_level_id", "bus_id", "bus_breaker_bus_id", "node", "connected", "pairing_key",
                         "ucte_xnode_code", "paired", "fictitious", "tie_line_id", "selected_limits_group");
     }

pypowsybl/network/impl/network.py

@@ -1331,6 +1331,7 @@ def get_dangling_lines(self, all_attributes: bool = False, attributes: List[str]
               - **i**: The current on the dangling line, ``NaN`` if no loadflow has been computed (in A)
               - **boundary_p** (optional): active flow on the dangling line at boundary bus side, ``NaN`` if no loadflow has been computed (in MW)
               - **boundary_q** (optional): reactive flow on the dangling line at boundary bus side, ``NaN`` if no loadflow has been computed (in MW)
+              - **boundary_i** (optional): current on the dangling line at boundary bus side, ``NaN`` if no loadflow has been computed (in A)
               - **boundary_v_mag** (optional): voltage magnitude of the boundary bus, ``NaN`` if no loadflow has been computed (in kV)
               - **boundary_v_angle** (optional): voltage angle of the boundary bus, ``NaN`` if no loadflow has been computed (in degree)
               - **voltage_level_id**: at which substation the dangling line is connected
@@ -1389,6 +1390,18 @@ def get_dangling_lines(self, all_attributes: bool = False, attributes: List[str]
             id
             DL NaN NaN NaN               VL   VL_0      True
             == === === === ================ ====== =========
+
+        .. note::
+
+            This note applies only if you are using the per-unit mode in your network (i.e., network.per_unit=True).
+
+            If two dangling lines are paired in a tie-line and have different nominal voltages, the per-unit values
+            for `boundary_i` and `boundary_v_mag` will differ between the two dangling lines.
+
+            Currently, PowSyBl network model does not support the concept of nominal voltage for the boundary
+            fictitious bus. Therefore, the nominal voltage at the dangling line network side is used for
+            per-unit calculations. While this is generally not an issue, this produces counterintuitive results
+            in the case of dangling lines of different nominal voltages.
         """
         return self.get_elements(ElementType.DANGLING_LINE, all_attributes, attributes, **kwargs)
 

tests/test_network.py

@@ -1221,19 +1221,19 @@ def test_dangling_lines():
     # test boundary point columns
     n = pp.network.create_micro_grid_be_network()
     dangling_lines = n.get_dangling_lines(attributes=['p', 'q',
-                                                      'boundary_p', 'boundary_q', 'boundary_v_mag', 'boundary_v_angle'])
+                                                      'boundary_p', 'boundary_q', 'boundary_i', 'boundary_v_mag', 'boundary_v_angle'])
     expected = pd.DataFrame(
         index=pd.Series(name='id', data=['17086487-56ba-4979-b8de-064025a6b4da',
                                          '78736387-5f60-4832-b3fe-d50daf81b0a6',
                                          'b18cd1aa-7808-49b9-a7cf-605eaf07b006',
                                          'a16b4a6c-70b1-4abf-9a9d-bd0fa47f9fe4',
                                          'ed0c5d75-4a54-43c8-b782-b20d7431630b']),
-        columns=['p', 'q', 'boundary_p', 'boundary_q', 'boundary_v_mag', 'boundary_v_angle'],
-        data=[[-25.77,  -2.82, 27.36,   -0.42,  224.86, -5.51],
-              [-36.59,  54.18, 46.81,  -79.19,  410.79, -6.56],
-              [-82.84, 138.45, 90.03, -148.60,  410.80, -6.57],
-              [-23.83,   1.27, 26.80,   -1.48,  224.81, -5.52],
-              [-36.85,  80.68, 43.68,  -84.87,  412.60, -6.74]])
+        columns=['p', 'q', 'boundary_p', 'boundary_q', 'boundary_i', 'boundary_v_mag', 'boundary_v_angle'],
+        data=[[-25.77,  -2.82, 27.36,   -0.42,   70.27,  224.86, -5.51],
+              [-36.59,  54.18, 46.81,  -79.19,  129.30,  410.79, -6.56],
+              [-82.84, 138.45, 90.03, -148.60,  244.20,  410.80, -6.57],
+              [-23.83,   1.27, 26.80,   -1.48,   68.95,  224.81, -5.52],
+              [-36.85,  80.68, 43.68,  -84.87,  133.58,  412.60, -6.74]])
     pd.testing.assert_frame_equal(expected, dangling_lines, check_dtype=False, atol=1e-2)