add missing docu for pressure controller

CHANGELOG.rst

@@ -3,7 +3,7 @@ Change Log
 
 [upcoming release] - 2023-..-..
 -------------------------------
-- [ADDED] new component flow controller: a branch component that controls the flow through itself. It adapts the pressure drop between two junctions to reflect the desired flow situation.
+- [ADDED] new component `flow controller`: a branch component that controls the flow through itself. It adapts the pressure drop between two junctions to reflect the desired flow situation.
 - [ADDED] new global variable `__format_version__` that shall only be increased in case of API changes (i.e. if the convert_format function for JSON I/O must be called)
 - [ADDED] toolbox function to extract the _pit (pandapipes internal tables) structure for nodes and branches as pandas tables with meaningful names for the stored columns as given in the node_idx and branch_idx files
 - [ADDED] new component `mass_storage` and tutorial how to use it
@@ -34,8 +34,8 @@ Change Log
 
 [0.6.0] - 2022-02-07
 -------------------------------
-- [ADDED] Adding pressure controller as new component
-- [ADDED] Adding compressor as new component
+- [ADDED] Adding `pressure controller` as new component
+- [ADDED] Adding `compressor` as new component
 - [ADDED] Compressing power of a pump component are returned as result
 - [ADDED] Adding polynomial fluids
 - [CHANGED] Removing irrelevant results in branch models with zero length (mean velocity, lambda, reynolds)

doc/source/about.rst

@@ -20,7 +20,7 @@ for the analysis and optimization of piping grids.
 |br|
 
 More information about pandapipes can be found on `www.pandapipes.org <https://www.pandapipes.org>`_
-or in our publication :cite:`Lohmeier2020`
+or in our publication :cite:`Lohmeier2020`. Please cite the paper if you use pandapipes.
 
 About pandapipes:
 

doc/source/components.rst

@@ -34,11 +34,12 @@ following documentation:
     components/valve/valve_component
     components/sink/sink_component
     components/source/source_component
+    components/storage/storage_component
     components/ext_grid/ext_grid_component
+    components/heat_exchanger/heat_exchanger_component
     components/pump/pump_component
     components/circulation_pump_mass/circ_pump_mass_component
     components/circulation_pump_pressure/circ_pump_pressure_component
     components/compressor/compressor_component
-    components/heat_exchanger/heat_exchanger_component
-    components/storage/storage_component
+    components/press_control/press_control_component
     components/flow_control/flow_control_component

doc/source/components/flow_control/flow_control_component.rst

@@ -2,13 +2,6 @@
 Flow Control
 ==============
 
-Create Function
-===============
-
-.. _create_flow_control:
-
-.. autofunction:: pandapipes.create_flow_control
-
 Physical Model
 ==============
 The flow control component enforces a specific mass flow between two junctions.
@@ -20,6 +13,19 @@ This is very helpful to control the mass flow in district heating networks.
     Using the flow controller in non-looped networks, in particular on stubs, can
     likely lead to non-convergence of the pipeflow.
 
+Create Function
+===============
+
+.. _create_flow_control:
+
+For creating a single flow control unit:
+
+.. autofunction:: pandapipes.create_flow_control
+
+For creating multiple flow control units at once:
+
+.. autofunction:: pandapipes.create_flow_controls
+
 
 Component Table Data
 ====================

doc/source/components/press_control/press_control_component.rst

@@ -0,0 +1,69 @@
+================
+Pressure Control
+================
+
+Physical Model
+==============
+The pressure control component enforces a specific pressure at the :code:`controlled_junction`.
+This is achieved by adding a required pressure lift or pressure drop between the
+:code:`from_junction` and :code:`to_junction`, so that :code:`controlled_p_bar` will be reached
+at the controlled junction. The controlled junction can be identical to
+the :code:`to_junction` to control the pressure directly at the outlet.
+
+Internally, the behaviour is achieved by fixing the pressure variable at
+:code:`controlled_junction` in the system matrix and keeping the pressure drop of the
+pressure control unit variable, so that is calculated during the Newton-Raphson-calculation.
+
+.. note::
+
+    The temperature at the inlet and outlet junction will not be adapted by the pressure control
+    unit. Therefore, these components usually operate isothermal (inlet temperature =
+    outlet temperature). It is assumed that temperature changes due to compression
+    or expansion (Joule-Thomson-effect) are balanced internally by adding or removing heat.
+
+
+.. warning::
+
+    A sufficient hydraulic connection between :code:`from_junction`, :code:`to_junction` and
+    :code:`controlled_junction` is crucial for proper operation of this component.
+    Hydraulically impossible configurations (e.g., if the controlled junction is on a different
+    stub) or contradicting other pressure control units will lead to non-convergence of the pipeflow.
+
+
+Create Function
+===============
+
+.. _create_press_control:
+
+For creating a single pressure control unit:
+
+.. autofunction:: pandapipes.create_pressure_control
+
+For creating multiple pressure control units at once:
+
+.. autofunction:: pandapipes.create_pressure_controls
+
+
+Component Table Data
+====================
+
+*net.press_control*
+
+.. tabularcolumns:: |p{0.10\linewidth}|p{0.10\linewidth}|p{0.25\linewidth}|p{0.40\linewidth}|
+
+.. csv-table::
+   :file: press_control_par.csv
+   :delim: ;
+   :widths: 10, 10, 25, 40
+
+
+Result Table Data
+=================
+
+*net.res_press_control*
+
+.. tabularcolumns:: |p{0.15\linewidth}|p{0.10\linewidth}|p{0.55\linewidth}|
+.. csv-table::
+   :file: press_control_res.csv
+   :delim: ;
+   :widths: 15, 10, 55

doc/source/components/press_control/press_control_par.csv

@@ -0,0 +1,12 @@
+**Parameter**;**Datatype**;**Value Range**;**Explanation**
+net;pandapipesNet;;The pandapipes net object in whose :code:`press_control` table the new unit will be added
+from_junction;integer;:math:`>` 0;Index of junction at which the pressure control unit starts
+to_junction;integer;:math:`>` 0;Index of junction at which the pressure control unit ends
+controlled_junction;integer;> 0;ID of the junction at which the pressure is controlled
+controlled_p_bar;float;> 0;Pressure set point [barg]
+control_active;boolean;;If false, the unit behaves like an open valve
+loss_coefficient;float;> ß;Pressure loss coefficient (only effective if control is not active)
+name;string;;Name of the pressure control unit
+index;integer;> 0;Force specific index the :code:`press_control`-DataFrame, if available
+in_service;boolean;True / False;If false, the unit behaves like a closed valve.
+type;string;;Type variable to classify different kinds of pressure control units (not considered by pandapipes' calculations)

doc/source/components/press_control/press_control_res.csv

@@ -0,0 +1,9 @@
+**Parameter**;**Datatype**;**Explanation**
+p_from_bar;float;Pressure at "from"-junction [bar]
+p_to_bar;float;Pressure  at "to"-junction [bar]
+t_from_k;float;Temperature at "from"-junction [K]
+t_to_k;float;Temperature at "to"-junction [K]
+mdot_to_kg_per_s;float;Mass flow out of pressure control unit [kg/s]
+mdot_from_kg_per_s;float;Mass flow into pressure control unit [kg/s]
+vdot_norm_m3_per_s;float;Norm volume flow [m^3/s]
+deltap_bar;float;Pressure difference between to- and from junction created by the pressure controller [bar]

pandapipes/create.py

@@ -359,8 +359,8 @@ def create_heat_exchanger(net, from_junction, to_junction, diameter_m, qext_w, l
     :rtype: int
 
     :Example:
-        >>> create_heat_exchanger(net, from_junction=0, to_junction=1, diameter_m=40e-3,\
-                                  qext_w=2000)
+        >>> create_heat_exchanger(net, from_junction=0, to_junction=1,
+        >>>                       diameter_m=40e-3, qext_w=2000)
     """
     add_new_component(net, HeatExchanger)
 
@@ -424,8 +424,8 @@ def create_pipe(net, from_junction, to_junction, std_type, length_km, k_mm=0.2,
     :rtype: int
 
     :Example:
-        >>> create_pipe(net, from_junction=0, to_junction=1, std_type='315_PE_80_SDR_17',\
-                        length_km=1)
+        >>> create_pipe(net, from_junction=0, to_junction=1,
+        >>>             std_type='315_PE_80_SDR_17', length_km=1)
 
     """
     add_new_component(net, Pipe)
@@ -499,8 +499,8 @@ def create_pipe_from_parameters(net, from_junction, to_junction, length_km, diam
     :rtype: int
 
     :Example:
-        >>> create_pipe_from_parameters(net, from_junction=0, to_junction=1, length_km=1,\
-                                        diameter_m=40e-3)
+        >>> create_pipe_from_parameters(net, from_junction=0, to_junction=1,
+        >>>                             length_km=1, diameter_m=40e-3)
 
     """
     add_new_component(net, Pipe)
@@ -673,8 +673,8 @@ def create_pump_from_parameters(net, from_junction, to_junction, new_std_type_na
     :rtype: int
 
     EXAMPLE:
-        >>> create_pump_from_parameters(net, 0, 1, 'pump1', pressure_list=[0,1,2,3],\
-                                        flowrate_list=[0,1,2,3], reg_polynomial_degree=1)
+        >>> create_pump_from_parameters(net, 0, 1, 'pump1', pressure_list=[0,1,2,3],
+        >>>                             flowrate_list=[0,1,2,3], reg_polynomial_degree=1)
         >>> create_pump_from_parameters(net, 0, 1, 'pump2', poly_coefficents=[1,0])
 
     """
@@ -737,7 +737,8 @@ def create_circ_pump_const_pressure(net, from_junction, to_junction, p_bar, plif
     :rtype: int
 
     :Example:
-        >>> create_circ_pump_const_pressure(net, 0, 1, p_bar=5, plift_bar=2, t_k=350, type="p")
+        >>> create_circ_pump_const_pressure(net, 0, 1, p_bar=5, plift_bar=2,
+        >>>                                 t_k=350, type="p")
 
     """
 
@@ -792,7 +793,8 @@ def create_circ_pump_const_mass_flow(net, from_junction, to_junction, p_bar, mdo
     :rtype: int
 
     :Example:
-        >>> create_circ_pump_const_mass_flow(net, 0, 1, p_bar=5, mdot_kg_per_s=2, t_k=350, type="p")
+        >>> create_circ_pump_const_mass_flow(net, 0, 1, p_bar=5, mdot_kg_per_s=2,
+        >>>                                  t_k=350, type="p")
 
     """
 
@@ -858,8 +860,12 @@ def create_compressor(net, from_junction, to_junction, pressure_ratio, name=None
 def create_pressure_control(net, from_junction, to_junction, controlled_junction, controlled_p_bar,
                             control_active=True, loss_coefficient=0., name=None, index=None,
                             in_service=True, type="pressure_control", **kwargs):
-    """
-    Adds one pressure control with a constant mass flow in table net["press_control"].
+    """Adds one pressure control that enforces a pressure at a specific junction.
+
+    The pressure control unit creates a pressure drop / lift between the 'from' and the 'to'
+    junction so that the pressure set point at the controlled junction is met.
+    It is required that the controlled junction is hydraulically properly connected to the from
+    and to junction and no other pessure control unit is inbetween.
 
     :param net: The net for which this pressure control should be created
     :type net: pandapipesNet
@@ -895,6 +901,8 @@ def create_pressure_control(net, from_junction, to_junction, controlled_junction
     :rtype: int
 
     :Example:
+        Connect junction 0 and 1 and set the pressure at junction 1 to 5 bar.
+
         >>> create_pressure_control(net, 0, 1, 1, controlled_p_bar=5)
 
     """
@@ -1022,7 +1030,8 @@ def create_junctions(net, nr_junctions, pn_bar, tfluid_k, height_m=0, name=None,
     :rtype: array(int)
 
     :Example:
-        >>> create_junctions(net, 200, pn_bar=5, tfluid_k=320, height_m=np.arange(200))
+        >>> create_junctions(net, 200, pn_bar=5, tfluid_k=320,
+        >>>                  height_m=np.arange(200))
     """
     add_new_component(net, Junction)
 
@@ -1072,7 +1081,8 @@ def create_sinks(net, junctions, mdot_kg_per_s, scaling=1., name=None, index=Non
     :rtype: array(int)
 
     :Example:
-        >>> new_sink_ids = create_sinks(net, junctions=[1, 5, 10], mdot_kg_per_s=[0.1, 0.05, 0.2])
+        >>> new_sink_ids = create_sinks(net, junctions=[1, 5, 10],
+        >>>                             mdot_kg_per_s=[0.1, 0.05, 0.2])
     """
     add_new_component(net, Sink)
 
@@ -1184,8 +1194,11 @@ def create_pipes(net, from_junctions, to_junctions, std_type, length_km, k_mm=0.
     :rtype: array(int)
 
     :Example:
-        >>> pipe_indices = create_pipes(net, from_junctions=[0, 2, 6], to_junctions=[1, 3, 7], \
-                                        std_type='315_PE_80_SDR_17', length_km=[0.2, 1, 0.3])
+        >>> pipe_indices = create_pipes(net,
+        >>>                             from_junctions=[0, 2, 6],
+        >>>                             to_junctions=[1, 3, 7],
+        >>>                             std_type='315_PE_80_SDR_17',
+        >>>                             length_km=[0.2, 1, 0.3])
 
     """
     add_new_component(net, Pipe)
@@ -1262,9 +1275,11 @@ def create_pipes_from_parameters(net, from_junctions, to_junctions, length_km, d
     :rtype: array(int)
 
     :Example:
-        >>> pipe_indices = create_pipes_from_parameters(\
-                net, from_junctions=[0, 2, 6], to_junctions=[1, 3, 7], length_km=[0.2, 1, 0.3],\
-                diameter_m=40e-3)
+        >>> pipe_indices = create_pipes_from_parameters(net,
+        >>>                                             from_junctions=[0, 2, 6],
+        >>>                                             to_junctions=[1, 3, 7],
+        >>>                                             length_km=[0.2, 1, 0.3],
+        >>>                                             diameter_m=40e-3)
 
     """
     add_new_component(net, Pipe)
@@ -1318,8 +1333,9 @@ def create_valves(net, from_junctions, to_junctions, diameter_m, opened=True, lo
     :rtype: array(int)
 
     :Example:
-        >>> create_valves(net, from_junctions=[0, 1, 4], to_junctions=[1, 5, 6], \
-                opened=[True, False, True], diameter_m=4e-3, name=["valve_%d" for d in range(3)])
+        >>> create_valves(net, from_junctions=[0, 1, 4], to_junctions=[1, 5, 6],
+        >>>               opened=[True, False, True], diameter_m=4e-3,
+        >>>               name=["valve_%d" for d in range(3)])
 
     """
     add_new_component(net, Valve)
@@ -1343,6 +1359,12 @@ def create_pressure_controls(net, from_junctions, to_junctions, controlled_junct
     and 'to_junctions' must be arrays of equal length. Other parameters may be either arrays of the\
     same length or single values.
 
+    Pressure control units enforce a pressure at a specific junction by creating a pressure drop /
+    lift between the 'from' and the 'to' junction so that the pressure set point at the
+    controlled junction is met.
+    It is required that the controlled junction is hydraulically properly connected to the from
+    and to junction and no other pessure control unit is inbetween.
+
     :param net: The net for which these pressure controls should be created
     :type net: pandapipesNet
     :param from_junctions: IDs of the junctions on one side which the pressure controls will be\
@@ -1377,7 +1399,14 @@ def create_pressure_controls(net, from_junctions, to_junctions, controlled_junct
     :rtype: array(int)
 
     :Example:
-        >>> create_pressure_controls(net, [0, 2], [1, 4], [1, 3], controlled_p_bar=[5, 4.9])
+        Create one unit to connect junction 0 and 1,
+        set the pressure at junction 1 to 5 bar.
+
+        And create a 2nd unit to connect junction 2 and 4,
+        set the pressure at junction 3 to 4.9 bar.
+
+        >>> create_pressure_controls(net, [0, 2], [1, 4], [1, 3],
+        >>>                          controlled_p_bar=[5, 4.9])
 
     """
     add_new_component(net, PressureControlComponent)
@@ -1442,6 +1471,9 @@ def create_flow_controls(net, from_junctions, to_junctions, controlled_mdot_kg_p
     :rtype: array(int)
 
     :Example:
+        Create two flow controllers with 0.8 m diameter between junction 0 and 1 with 0.5 kg/s and
+        junction 2 and 4 with 0.9 kg/s, respectively.
+
         >>> create_flow_controls(net, [0, 2], [1, 4], [0.5, 0.9], [0.8, 0.8])
 
     """