Split reduce method in 3 by usage (#1129)

Signed-off-by: Hugo KULESZA <[email protected]>

Author: HugoKulesza

docs/reference/network.rst

@@ -281,6 +281,9 @@ Miscellaneous network functions
    :nosignatures:
 
    Network.reduce
+   Network.reduce_by_ids
+   Network.reduce_by_voltage_range
+   Network.reduce_by_ids_and_depths
    Network.merge
    Network.get_single_line_diagram
    Network.write_single_line_diagram_svg

docs/user_guide/network.rst

@@ -946,7 +946,7 @@ For this example we will keep only voltage levels with voltage superior or equal
     S3VL1                 S3      400.0               440.0              390.0
     S4VL1                 S4      400.0               440.0              390.0
 
-    >>> net.reduce(v_min=400)
+    >>> net.reduce_by_voltage_range(v_min=400)
     >>> net.get_voltage_levels()
           name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
     id
@@ -969,7 +969,7 @@ For the next example we will keep voltage level S1VL1 with a depth of 1.
     S2VL1                 S2      400.0               440.0              390.0
     S3VL1                 S3      400.0               440.0              390.0
     S4VL1                 S4      400.0               440.0              390.0
-    >>> net.reduce(vl_depths=[['S1VL1', 1]])
+    >>> net.reduce_by_ids_and_depths(vl_depths=[('S1VL1', 1)])
     >>> net.get_voltage_levels()
           name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
     id
@@ -979,7 +979,7 @@ For the next example we will keep voltage level S1VL1 with a depth of 1.
 S1VL1 is connected to S1VL2 by the transformer TWT, so it is kept after the network reduction.
 It is the only voltage level connected to S1VL1 by one branch.
 
-the parameter "ids" can be used to specify the exact voltage levels that will be kept
+Reduction can also be done by specifying directly the list of voltage levels to keep using the :meth:reduce_by_ids method.
 
 Using operational limits
 ------------------------

java/pypowsybl/src/main/java/com/powsybl/python/network/NetworkCFunctions.java

@@ -458,9 +458,9 @@ public void run() {
                 }
                 if (depthsCount != 0) {
                     final List<Integer> depths = CTypeUtil.toIntegerList(depthsPtr, depthsCount);
-                    final List<String> voltageLeveles = toStringList(vlsPtrPtr, vlsCount);
+                    final List<String> voltageLevels = toStringList(vlsPtrPtr, vlsCount);
                     for (int i = 0; i < depths.size(); i++) {
-                        predicates.add(new SubNetworkPredicate(network.getVoltageLevel(voltageLeveles.get(i)), depths.get(i)));
+                        predicates.add(new SubNetworkPredicate(network.getVoltageLevel(voltageLevels.get(i)), depths.get(i)));
                     }
                 }
                 final OrNetworkPredicate orNetworkPredicate = new OrNetworkPredicate(predicates);

pypowsybl/network/impl/network.py

@@ -290,8 +290,11 @@ def save_to_binary_buffer(self, format: str = 'XIIDM', parameters: ParamsDict =
                                                             None if report_node is None else report_node._report_node))  # pylint: disable=protected-access
 
     def reduce(self, v_min: float = 0, v_max: float = sys.float_info.max, ids: Optional[List[str]] = None,
-               vl_depths: tuple = (), with_dangling_lines: bool = False) -> None:
+               vl_depths: Optional[List[tuple]] = None, with_dangling_lines: bool = False) -> None:
         """
+        .. deprecated:: 1.14.0
+          Use :meth:`reduce_by_voltage_range`, :meth:`reduce_by_ids` or :meth:`reduce_by_ids_and_depths` instead depending on your use case.
+        
         Reduce to a smaller network according to the following parameters
 
         :param v_min: minimum voltage of the voltage levels kept after reducing
@@ -300,15 +303,76 @@ def reduce(self, v_min: float = 0, v_max: float = sys.float_info.max, ids: Optio
         :param vl_depths: depth around voltage levels which are indicated by their id, that will be kept
         :param with_dangling_lines: keeping the dangling lines
         """
+        warnings.warn("reduce is deprecated, use `reduce_by_voltage_range`, `reduce_by_ids` or `reduce_by_ids_and_depths` instead depending on your use case", DeprecationWarning)
         if ids is None:
             ids = []
         vls = []
         depths = []
+        if vl_depths is None:
+            vl_depths = []
         for v in vl_depths:
             vls.append(v[0])
             depths.append(v[1])
         _pp.reduce_network(self._handle, v_min, v_max, ids, vls, depths, with_dangling_lines)
 
+    def reduce_by_voltage_range(self, v_min: float = 0, v_max: float = sys.float_info.max, with_dangling_lines: bool = False) -> None:
+        """
+        Reduce to a smaller network (only keeping all elements whose nominal voltage is in the specified voltage range)
+
+        :param v_min: minimum voltage of the voltage levels kept after reducing
+        :param v_max: voltage maximum of the voltage levels kept after reducing
+        :param with_dangling_lines: whether dangling lines should be created to replace lines cut at the boundary of reduction
+
+        Example:
+
+            .. code-block:: python
+
+                network.reduce_by_voltage_range(v_min=90, v_max=250, with_dangling_lines=True)
+
+            will only keep elements of voltage level between 90 and 250kV, replacing the lines cut at the boundary by dangling lines.
+        """
+        _pp.reduce_network(self._handle, v_min=v_min, v_max=v_max, ids=[], vls=[], depths=[], with_dangling_lines=with_dangling_lines)
+
+    def reduce_by_ids(self, ids: List[str], with_dangling_lines: bool = False) -> None:
+        """
+        Reduce to a smaller network (only keeping voltage levels whose id is in the specified list)
+
+        :param ids: list of the voltage level ids that should be kept in the reduced network
+        :param with_dangling_lines: whether dangling lines should be created to replace lines cut at the boundary of reduction
+
+        Example:
+
+            .. code-block:: python
+
+                network.reduce_by_ids(ids=["VL1", "VL2"])
+
+            will only keep voltage levels VL1 and VL2 and all network elements between them.
+        """
+        _pp.reduce_network(self._handle, v_min=0, v_max=sys.float_info.max, ids=ids, vls=[], depths=[], with_dangling_lines=with_dangling_lines)
+
+    def reduce_by_ids_and_depths(self, vl_depths: List[tuple[str, int]], with_dangling_lines: bool = False) -> None:
+        """
+        Reduce to a smaller network (keeping the specified voltage levels with all respective neighbours at most at the specified depth).
+
+        :param vl_depths: list of the voltage level ids that should be kept in the reduced network
+        :param with_dangling_lines: whether dangling lines should be created to replace lines cut at the boundary of reduction
+
+        Example:
+
+            .. code-block:: python
+
+                network.reduce_by_ids_and_depths(vl_depths=[("VL1", 1), ("VL25", 3)])
+
+            will only keep voltage levels VL1 and its neighbours, and VL25 with all elements around it with at most 3 connections between them.
+        """
+        vls = []
+        depths = []
+        for v in vl_depths:
+            vls.append(v[0])
+            depths.append(v[1])
+        _pp.reduce_network(self._handle, v_min=0, v_max=sys.float_info.max, ids=[], vls=vls, depths=depths, with_dangling_lines=with_dangling_lines)
+
+
     def write_single_line_diagram_svg(self, container_id: str, svg_file: PathOrStr, metadata_file: Optional[PathOrStr] = None,
                                       parameters: Optional[SldParameters] = None, sld_profile: Optional[SldProfile] = None) -> None:
         """

tests/test_network_reduction.py

@@ -5,6 +5,7 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 #
 import pytest
+import re
 
 import pypowsybl as pp
 import pathlib
@@ -21,21 +22,29 @@ def test_reduce_by_voltage():
     n = pp.network.create_eurostag_tutorial_example1_network()
     pp.loadflow.run_ac(n)
     assert 4 == len(n.get_buses())
-    n.reduce(v_min=240, v_max=400)
+    n.reduce_by_voltage_range(v_min=240, v_max=400)
     assert 2 == len(n.get_buses())
 
 
 def test_reduce_by_ids():
     n = pp.network.create_eurostag_tutorial_example1_network()
     pp.loadflow.run_ac(n)
     assert 4 == len(n.get_buses())
-    n.reduce(ids=['P2'])
+    n.reduce_by_ids(ids=['P2'])
     assert 2 == len(n.get_buses())
 
 
 def test_reduce_by_subnetwork():
     n = pp.network.create_eurostag_tutorial_example1_network()
     pp.loadflow.run_ac(n)
     assert 4 == len(n.get_buses())
-    n.reduce(vl_depths=(('VLGEN', 1), ('VLLOAD', 1)))
+    n.reduce_by_ids_and_depths(vl_depths=[('VLGEN', 1), ('VLLOAD', 1)])
     assert 4 == len(n.get_buses())
+
+def test_deprecated_reduce():
+    n = pp.network.create_eurostag_tutorial_example1_network()
+    pp.loadflow.run_ac(n)
+    assert 4 == len(n.get_buses())
+    with pytest.warns(DeprecationWarning, match=re.escape("reduce is deprecated, use `reduce_by_voltage_range`")):
+        n.reduce(v_min=240, v_max=400)
+    assert 2 == len(n.get_buses())