adding documentation for reduce function (#791)

---------

Signed-off-by: Etienne LESOT <[email protected]>

docs/user_guide/network.rst

@@ -877,3 +877,60 @@ parent network and become again a standalone network.
     :options: +NORMALIZE_WHITESPACE
 
     >>> nl_sub.detach()
+
+Reducing a network
+------------------
+
+Pypowsybl provides methods to reduce a network to a smaller one. It can be done with different parameters.
+It can be decided according to the voltage with the parameters v_min and v_max. It can also be by indicating the
+Voltage Levels that will be kept and also indicating the depth around these voltage levels.
+
+For this example we will keep only voltage levels with voltage superior or equal to 400 kV
+
+.. doctest::
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> net = pp.network.create_four_substations_node_breaker_network()
+    >>> net.get_voltage_levels()
+          name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
+    id
+    S1VL1                 S1      225.0               240.0              220.0
+    S1VL2                 S1      400.0               440.0              390.0
+    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(v_min=400)
+    >>> net.get_voltage_levels()
+          name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
+    id
+    S1VL2                 S1      400.0               440.0              390.0
+    S2VL1                 S2      400.0               440.0              390.0
+    S3VL1                 S3      400.0               440.0              390.0
+    S4VL1                 S4      400.0               440.0              390.0
+
+For the next example we will keep voltage level S1VL1 with a depth of 1.
+
+.. doctest::
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> net = pp.network.create_four_substations_node_breaker_network()
+    >>> net.get_voltage_levels()
+          name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
+    id
+    S1VL1                 S1      225.0               240.0              220.0
+    S1VL2                 S1      400.0               440.0              390.0
+    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.get_voltage_levels()
+          name substation_id  nominal_v  high_voltage_limit  low_voltage_limit
+    id
+    S1VL1                 S1      225.0               240.0              220.0
+    S1VL2                 S1      400.0               440.0              390.0
+
+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

pypowsybl/network/impl/network.py

@@ -252,6 +252,15 @@ def save_to_binary_buffer(self, format: str = 'XIIDM', parameters: ParamsDict =
 
     def reduce(self, v_min: float = 0, v_max: float = sys.float_info.max, ids: List[str] = None,
                vl_depths: tuple = (), with_dangling_lines: bool = False) -> None:
+        """
+        Reduce to a smaller network according to the following parameters
+
+        :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 ids: ids of the voltage levels that will be kept
+        :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
+        """
         if ids is None:
             ids = []
         vls = []