Flow control model

CHANGELOG.rst

@@ -3,6 +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 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

doc/source/components.rst

@@ -40,4 +40,5 @@ following documentation:
     components/circulation_pump_pressure/circ_pump_pressure_component
     components/compressor/compressor_component
     components/heat_exchanger/heat_exchanger_component
-    components/storage/storage_component
+    components/storage/storage_component
+    components/flow_control/flow_control_component

doc/source/components/flow_control/flow_control_component.rst

@@ -0,0 +1,46 @@
+==============
+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.
+This is very helpful to control the mass flow in district heating networks.
+
+.. warning::
+
+    It is recommended to use the flow control components only in looped networks.
+    Using the flow controller in non-looped networks, in particular on stubs, can
+    likely lead to non-convergence of the pipeflow.
+
+
+Component Table Data
+====================
+
+*net.flow_control*
+
+.. tabularcolumns:: |p{0.10\linewidth}|p{0.10\linewidth}|p{0.25\linewidth}|p{0.40\linewidth}|
+
+.. csv-table::
+   :file: flow_control_par.csv
+   :delim: ;
+   :widths: 10, 10, 25, 40
+
+
+Result Table Data
+=================
+
+*net.res_flow_control*
+
+.. tabularcolumns:: |p{0.15\linewidth}|p{0.10\linewidth}|p{0.55\linewidth}|
+.. csv-table::
+   :file: flow_control_res.csv
+   :delim: ;
+   :widths: 15, 10, 55

doc/source/components/flow_control/flow_control_par.csv

@@ -0,0 +1,10 @@
+**Parameter**;**Datatype**;**Value Range**;**Explanation**
+net;pandapipesNet;;The pandapipes net object in whose :code:`flow_control` table the new unit will be added
+from_junction;integer;:math:`>` 0;Index of junction at which the flow control unit starts
+to_junction;integer;:math:`>` 0;Index of junction at which the flow control unit ends
+controlled_mdot_kg_per_s;float;;The mass flow set point [kg/s]
+diameter;float;> 0;diameter to derive the cross-sectional area
+control_active;boolean;;If false, the unit behaves like an open valve
+name;string;;Name of the flow control unit
+in_service;boolean;True / False;If false, the unit behaves like a closed valve.
+type;string;;Type variable to classify different kinds of flow control units (not considered by pandapipes' calculations)

doc/source/components/flow_control/flow_control_res.csv

@@ -0,0 +1,10 @@
+**Parameter**;**Datatype**;**Explanation**
+v_mean_m_per_s;float;The mean velocity of fluid in the flow control unit [m/s]
+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_from_kg_per_s;float;Mass flow into flow control unit [kg/s]
+mdot_to_kg_per_s;float;Mass flow out of flow control unit [kg/s]
+vdot_norm_m3_per_s;float;Norm volume flow [m^3/s]
+reynolds;float;Average Reynolds number

pandapipes/component_models/abstract_models/branch_models.py

@@ -143,13 +143,13 @@ def adaption_before_derivatives_hydraulic(cls, net, branch_pit, node_pit, idx_lo
         pass
 
     @classmethod
-    def calculate_temperature_lift(cls, net, branch_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         """
 
         :param net:
         :type net:
-        :param branch_pit:
-        :type branch_pit:
+        :param branch_component_pit:
+        :type branch_component_pit:
         :param node_pit:
         :type node_pit:
         :return:

pandapipes/component_models/abstract_models/branch_w_internals_models.py

@@ -3,13 +3,11 @@
 # Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
 
 import numpy as np
+
 from pandapipes.component_models.abstract_models.branch_models import BranchComponent
 from pandapipes.component_models.component_toolbox import set_entry_check_repeat
-from pandapipes.idx_branch import ACTIVE
-from pandapipes.idx_branch import FROM_NODE, TO_NODE, TINIT, RHO, ETA, \
-    CP, ELEMENT_IDX
-from pandapipes.idx_node import L, node_cols
-from pandapipes.idx_node import TINIT as TINIT_NODE
+from pandapipes.idx_branch import ACTIVE, FROM_NODE, TO_NODE, TINIT, RHO, ETA, CP, ELEMENT_IDX
+from pandapipes.idx_node import L, node_cols, TINIT as TINIT_NODE
 from pandapipes.pf.pipeflow_setup import add_table_lookup, get_lookup, get_table_number
 from pandapipes.properties.fluids import get_fluid
 
@@ -43,7 +41,7 @@ def active_identifier(cls):
         raise NotImplementedError
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pipe_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         raise NotImplementedError
 
     @classmethod

pandapipes/component_models/abstract_models/branch_wo_internals_models.py

@@ -92,7 +92,7 @@ def create_pit_branch_entries(cls, net, branch_pit):
         return branch_wo_internals_pit
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pipe_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         raise NotImplementedError
 
     @classmethod

pandapipes/component_models/abstract_models/branch_wzerolength_models.py

@@ -65,5 +65,5 @@ def extract_results(cls, net, options, branch_results, nodes_connected, branches
         raise NotImplementedError
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pipe_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         raise NotImplementedError

pandapipes/component_models/component_toolbox.py

@@ -4,6 +4,7 @@
 
 import numpy as np
 import pandas as pd
+
 from pandapipes.constants import NORMAL_PRESSURE, TEMP_GRADIENT_KPM, AVG_TEMPERATURE_K, \
     HEIGHT_EXPONENT
 

pandapipes/component_models/flow_control_component.py

@@ -0,0 +1,144 @@
+# Copyright (c) 2020-2021 by Fraunhofer Institute for Energy Economics
+# and Energy System Technology (IEE), Kassel. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
+
+import numpy as np
+from numpy import dtype
+
+from pandapipes.component_models.junction_component import Junction
+from pandapipes.component_models.abstract_models import BranchWZeroLengthComponent, get_fluid
+from pandapipes.idx_branch import D, AREA, TL, JAC_DERIV_DP, JAC_DERIV_DP1, JAC_DERIV_DV, VINIT, \
+    RHO, LOAD_VEC_BRANCHES, ELEMENT_IDX
+from pandapipes.pf.result_extraction import extract_branch_results_without_internals
+
+
+class FlowControlComponent(BranchWZeroLengthComponent):
+    """
+
+    """
+
+    @classmethod
+    def table_name(cls):
+        return "flow_control"
+
+    @classmethod
+    def active_identifier(cls):
+        return "in_service"
+
+    @classmethod
+    def from_to_node_cols(cls):
+        return "from_junction", "to_junction"
+
+    @classmethod
+    def get_connected_node_type(cls):
+        return Junction
+
+    @classmethod
+    def create_pit_branch_entries(cls, net, branch_pit):
+        """
+        Function which creates pit branch entries with a specific table.
+        :param net: The pandapipes network
+        :type net: pandapipesNet
+        :param branch_pit:
+        :type branch_pit:
+        :return: No Output.
+        """
+        fc_pit = super().create_pit_branch_entries(net, branch_pit)
+        fc_pit[:, D] = net[cls.table_name()].diameter_m.values
+        fc_pit[:, AREA] = fc_pit[:, D] ** 2 * np.pi / 4
+        fc_pit[:, VINIT] = net[cls.table_name()].controlled_mdot_kg_per_s.values / \
+            (fc_pit[:, AREA] * fc_pit[:, RHO])
+
+    @classmethod
+    def adaption_before_derivatives_hydraulic(cls, net, branch_pit, node_pit, idx_lookups, options):
+        pass
+
+    @classmethod
+    def adaption_after_derivatives_hydraulic(cls, net, branch_pit, node_pit, idx_lookups, options):
+        # set all pressure derivatives to 0 and velocity to 1; load vector must be 0, as no change
+        # of velocity is allowed during the pipeflow iteration
+        f, t = idx_lookups[cls.table_name()]
+        fc_pit = branch_pit[f:t, :]
+        in_service_elm = np.isin(net[cls.table_name()].index.values,
+                                 fc_pit[:, ELEMENT_IDX].astype(np.int32))
+        active = net[cls.table_name()].control_active.values[in_service_elm]
+        fc_pit[active, JAC_DERIV_DP] = 0
+        fc_pit[active, JAC_DERIV_DP1] = 0
+        fc_pit[active, JAC_DERIV_DV] = 1
+        fc_pit[active, LOAD_VEC_BRANCHES] = 0
+
+    @classmethod
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
+        """
+
+        :param net:
+        :type net:
+        :param branch_component_pit:
+        :type branch_component_pit:
+        :param node_pit:
+        :type node_pit:
+        :return:
+        :rtype:
+        """
+        branch_component_pit[:, TL] = 0
+
+    @classmethod
+    def extract_results(cls, net, options, branch_results, nodes_connected, branches_connected):
+        required_results = [
+            ("p_from_bar", "p_from"), ("p_to_bar", "p_to"), ("t_from_k", "temp_from"),
+            ("t_to_k", "temp_to"), ("mdot_to_kg_per_s", "mf_to"), ("mdot_from_kg_per_s", "mf_from"),
+            ("vdot_norm_m3_per_s", "vf"), ("lambda", "lambda"), ("reynolds", "reynolds")
+        ]
+
+        if get_fluid(net).is_gas:
+            required_results.extend([
+                ("v_from_m_per_s", "v_gas_from"), ("v_to_m_per_s", "v_gas_to"),
+                ("v_mean_m_per_s", "v_gas_mean"), ("normfactor_from", "normfactor_from"),
+                ("normfactor_to", "normfactor_to")
+            ])
+        else:
+            required_results.extend([("v_mean_m_per_s", "v_mps")])
+
+        extract_branch_results_without_internals(net, branch_results, required_results,
+                                                 cls.table_name(), branches_connected)
+
+    @classmethod
+    def get_component_input(cls):
+        """
+
+        Get component input.
+
+        :return:
+        :rtype:
+        """
+        return [("name", dtype(object)),
+                ("from_junction", "u4"),
+                ("to_junction", "u4"),
+                ("controlled_mdot_kg_per_s", "f8"),
+                ("diameter_m", "f8"),
+                ("control_active", "bool"),
+                ("in_service", 'bool'),
+                ("type", dtype(object))]
+
+    @classmethod
+    def get_result_table(cls, net):
+        """
+
+        Gets the result table.
+
+        :param net: The pandapipes network
+        :type net: pandapipesNet
+        :return: (columns, all_float) - the column names and whether they are all float type. Only
+                if False, returns columns as tuples also specifying the dtypes
+        :rtype: (list, bool)
+        """
+        if get_fluid(net).is_gas:
+            output = ["v_from_m_per_s", "v_to_m_per_s", "v_mean_m_per_s", "p_from_bar", "p_to_bar",
+                      "t_from_k", "t_to_k", "mdot_from_kg_per_s", "mdot_to_kg_per_s",
+                      "vdot_norm_m3_per_s", "reynolds", "lambda", "normfactor_from",
+                      "normfactor_to"]
+        else:
+            output = ["v_mean_m_per_s", "p_from_bar", "p_to_bar", "t_from_k", "t_to_k",
+                      "mdot_from_kg_per_s", "mdot_to_kg_per_s", "vdot_norm_m3_per_s", "reynolds",
+                      "lambda"]
+        return output, True

pandapipes/component_models/heat_exchanger_component.py

@@ -80,19 +80,19 @@ def extract_results(cls, net, options, branch_results, nodes_connected, branches
                                                  cls.table_name(), branches_connected)
 
     @classmethod
-    def calculate_temperature_lift(cls, net, he_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         """
 
         :param net:
         :type net:
-        :param he_pit:
-        :type he_pit:
+        :param branch_component_pit:
+        :type branch_component_pit:
         :param node_pit:
         :type node_pit:
         :return:
         :rtype:
         """
-        he_pit[:, TL] = 0
+        branch_component_pit[:, TL] = 0
 
     @classmethod
     def get_component_input(cls):

pandapipes/component_models/pipe_component.py

@@ -155,19 +155,19 @@ def create_pit_branch_entries(cls, net, branch_pit):
         pipe_pit[:, AREA] = pipe_pit[:, D] ** 2 * np.pi / 4
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pipe_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         """
 
         :param net:
         :type net:
-        :param pipe_pit:
-        :type pipe_pit:
+        :param branch_component_pit:
+        :type branch_component_pit:
         :param node_pit:
         :type node_pit:
         :return:
         :rtype:
         """
-        pipe_pit[:, TL] = 0
+        branch_component_pit[:, TL] = 0
 
     @classmethod
     def extract_results(cls, net, options, branch_results, nodes_connected, branches_connected):

pandapipes/component_models/pressure_control_component.py

@@ -80,19 +80,19 @@ def adaption_after_derivatives_hydraulic(cls, net, branch_pit, node_pit, idx_loo
         press_pit[pc_branch, JAC_DERIV_DV] = 0
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pc_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         """
 
         :param net:
         :type net:
-        :param pc_pit:
-        :type pc_pit:
+        :param branch_component_pit:
+        :type branch_component_pit:
         :param node_pit:
         :type node_pit:
         :return:
         :rtype:
         """
-        pc_pit[:, TL] = 0
+        branch_component_pit[:, TL] = 0
 
     @classmethod
     def extract_results(cls, net, options, branch_results, nodes_connected, branches_connected):

pandapipes/component_models/pump_component.py

@@ -95,19 +95,19 @@ def adaption_before_derivatives_hydraulic(cls, net, branch_pit, node_pit, idx_lo
         pump_pit[:, PL] = pl
 
     @classmethod
-    def calculate_temperature_lift(cls, net, pump_pit, node_pit):
+    def calculate_temperature_lift(cls, net, branch_component_pit, node_pit):
         """
 
         :param net:
         :type net:
-        :param pump_pit:
-        :type pump_pit:
+        :param branch_component_pit:
+        :type branch_component_pit:
         :param node_pit:
         :type node_pit:
         :return:
         :rtype:
         """
-        pump_pit[:, TL] = 0
+        branch_component_pit[:, TL] = 0
 
     @classmethod
     def extract_results(cls, net, options, branch_results, nodes_connected, branches_connected):