Internal Pipeflow Functions and Setup¶
Just for completeness, here is an overview over the auxiliary functions that are used internally in the pipeflow setup and were not yet described:
-
add_table_lookup
(table_lookup, table_name, table_number) Auxiliary function to add a lookup between table name in the pandapipes net and table number in the internal structure (pit).
- Parameters
table_lookup (dict) – The lookup dictionary from table names to internal number (n2t) and vice versa (t2n)
table_name (str) – name of the table that shall be mapped to number
table_number (int) – number under which the table is saved in the pit
- Returns
No ouput.
-
check_connectivity
(net, branch_pit, node_pit, check_heat) Perform a connectivity check which means that network nodes are identified that don’t have any connection to an external grid component. Quick overview over the steps of this function:
Build a sparse matrix graph (scipy.sparse.csr_matrix) from all branches that are in_service (nodes of this graph are taken from FROM_NODE and TO_NODE column in pit).
Add a node that represents all external grids and connect all nodes that are connected to external grids to that node.
Perform a breadth first order search to identify all nodes that are reachable from the added external grid node.
Create masks for exisiting nodes and branches to show if they are reachable from an external grid.
Compare the reachable nodes with the initial in_service nodes.
If nodes are reachable that were set out of service by the user, they are either set in_service or an error is raised. The behavior depends on the pipeflow option quit_on_inconsistency_connectivity.
If nodes are not reachable that were set in_service by the user, they will be set out of service automatically (this is the desired functionality of the connectivity check).
- Parameters
net (pandapipesNet) – The pandapipesNet for which to perform the check
branch_pit (np.array) – internal array with branch entries
node_pit (np.array) – internal array with node entries
check_heat (bool) – flag which determines whether to also check for connectivity to heat external grids
- Returns
(nodes_connected_hyd, branches_connected) - lookups of np.arrays stating which of the internal nodes and branches are reachable from any of the hyd_slacks (np mask).
- Return type
tuple(np.array)
-
create_empty_pit
(net) Creates an empty internal structure which is called pit (pandapipes internal tables). The structure is a dictionary which should contain one array for all nodes and one array for all branches of the net. It is very often referred to within the pipeflow. So the structure in general looks like this:
net[“_pit”] = {“node”: np.array((no_nodes, col_nodes), dtype=np.float64), “branch”: np.array((no_branches, col_branches), dtype=np.float64)}
- Parameters
net (pandapipesNet) – The pandapipesNet to which to add the empty structure
- Returns
pit - The dict of arrays with the internal node / branch structure
- Return type
dict
-
create_internal_results
(net) Initializes a dictionary that shall contain some internal results later.
- Parameters
net (pandapipesNet) – pandapipesNet to which internal result dict will be added
- Returns
No output.
-
create_lookups
(net, NodeComponent, BranchComponent, BranchWInternalsComponent) Create all lookups necessary for the pipeflow of the given net. The lookups are usually:
node_from_to: the start and end indices of all node component tables within the pit
branch_from_to: the start and end indices of all branch component tables within the pit
node_table: dict to determine indices for node component tables (e.g. {“junction”: 0}). Can be arbitrary and strongly depends on the component order given by get_component_list.
branch_table: dict to determine indices for branch component tables (e.g. {“pipe”: 0, “valve”: 1}). Can be arbitrary and strongly depends on the component order given by get_component_list.
node_index: Lookup from component index (e.g. junction 2) to pit index (e.g. 0) for nodes.
branch_index: Lookup from component index (e.g. pipe 1) to pit index (e.g. 5) for branches.
internal_nodes_lookup: Lookup for internal nodes of branch components that makes result extraction a lot easier.
- Parameters
net (pandapipesNet) – The pandapipesNet for which to create the lookups
- Returns
No output.
-
extract_all_results
(net, node_name) Extract results from branch pit and node pit and write them to the different tables of the net, as defined by the component models.
- Parameters
net (pandapipesNet) – pandapipesNet for which to extract results into net.res_xy
- Returns
No output.
-
extract_results_active_pit
(net, node_pit, branch_pit, nodes_connected, branches_connected) Extract the pipeflow results from the internal pit structure (“_active_pit”) to the general pit structure.
- Parameters
net (pandapipesNet) – The pandapipesNet that the internal structure belongs to
node_pit (np.array) – The internal structure node array
branch_pit (np.array) – The internal structure branch array
nodes_connected (np.array) – A mask array stating which nodes are actually connected to the rest of the net
branches_connected (np.array) – A mask array stating which branches are actually connected to the rest of the net
- Returns
No output.
-
get_lookup
(net, pit_type='node', lookup_type='index') Returns internal lookups which are mostly defined in the function create_lookups.
- Parameters
net (pandapipesNet) – The pandapipesNet for which the lookup is requested
pit_type (str) – identifier which of the two pits (“branch” or “node”) the lookup belongs to
lookup_type (str) – name of the lookup type
- Returns
lookup - A lookup (mostly a dict with mappings from pandapipesNet to internal structure)
- Return type
dict, np.array, ..
-
get_net_option
(net, option_name) Returns the requested option of the given net. Raises a UserWarning if the option was not found.
- Parameters
net (pandapipesNet) – pandapipesNet for which option is requested
option_name (str) – name of requested option
- Returns
option - The value of the option
-
get_net_options
(net, \*option_names) Returns several requested options of the given net. Raises a UserWarning if any of the options was not found.
- Parameters
net (pandapipesNet) – pandapipesNet for which option is requested
option_names (str) – names of requested options (as args)
- Returns
option - Tuple with values of the options
-
get_table_index_list
(net, pit_array, pit_indices, pit_type='node') Auxiliary function to get a list of tables and the table indices that belong to a number of pit indices.
- Parameters
net (pandapipesNet) – pandapipseNet for which the list is requested
pit_array (np.array) – internal structure from which to derive the tables and table indices
pit_indices (list, np.array, ..) – indices for which the table name and index list are requested
pit_type (str, default "node") – type of the pit (“node” or “branch”)
- Returns
list of table names and table indices belonging to the pit indices
-
get_table_name
(table_lookup, table_number) Auxiliary function to retrieve the pandapipesNet table name for a given internal pit number from the table lookup.
- Parameters
table_lookup (dict) – The lookup dictionary from table names to internal number (n2t) and vice versa (t2n)
table_number (int) – internal number of the table for which the name shall be retrieved
- Returns
table_name - pandapipesNet table name for the internal pit number
- Return type
str
-
get_table_number
(table_lookup, table_name) Auxiliary function to retrieve the internal pit number for a given pandapipesNet table name from the table lookup.
- Parameters
table_lookup (dict) – The lookup dictionary from table names to internal number (n2t) and vice versa (t2n)
table_name (str) – name of the table for which the internal number shall be retrieved
- Returns
table_number - internal number of the given table name within the pit
- Return type
int
-
init_options
(net, local_parameters) Initializes physical and mathematical constants included in Pandapipes. In addition, options for the nonlinear and time-dependent solver are also set.
Those are the options that can be set and their default values:
iter (int): 10 - If the simulation is terminated after a certain amount of iterations , this is the number of iterations.
tol_p (float): 1e-4 - The relative tolerance for the pressure. A result is accepted if the relative error is smaller than this factor.
tol_v (float): 1e-4 - The relative tolerance for the velocity. A result is accepted if the relative error is smaller than this factor.
tol_T (float): 1e-4 - The relative tolerance for the temperature. A result is accepted if the relative error is smaller than this factor.
tol_res (float): 1e-3 - The relative tolerance for the residual. A result is accepted if the relative error is smaller than this factor.
ambient_temperature (float): 293.0 - The assumed ambient temperature for the calculation of the barometric formula
friction_model (str): “nikuradse” - The friction model that shall be used to identify the value for lambda (can be “nikuradse” or “colebrook”)
alpha (float): 1 - The step width for the Newton iterations. If the Newton steps shall be damped, alpha can be reduced. See also the nonlinear_method parameter
nonlinear_method (str): “constant” - The option of how the damping factor alpha is determined in each iteration. It can be “constant” (i.e. alpha is always the same in each iteration) or “automatic”, in which case alpha is adapted automatically with respect to the convergence behaviour.
gas_impl (str): “pandapipes” - Implementation of the gas model. It can be set to “pandapipes” with calculations according to “Handbuch der Gasversorgungstechnik” or to “stanet” with calculations according to the stanet reference.
heat_transfer (bool): False - Flag to determine if the heat transfer shall be calculated.
only_update_hydraulic_matrix (bool): False - If true, the system matrix is not created in every iteration, but only the data isupdated according to a lookup that is identified in the first iteration. This speeds up calculation, but has not yet been tested extensively.
check_connectivity (bool): True - If true, a connectivity check is performed at the beginning of the pipeflow and parts of the net that are not connected to external grids are set inactive.
quit_on_inconsistency_connectivity (bool): False - If true, inconsistencies in the connectivity check raise an error, otherwise they are handled. Inconsistencies mean that out of service nodes are connected to in service branches. If that is the case and the flag is set to False, the connected nodes are activated.
- Parameters
net (pandapipesNet) – The pandapipesNet for which the options are initialized
local_parameters (dict) – dictionary with local parameters that were passed to the pipeflow call.
- Returns
No output
- EXAMPLE:
init_constants(net)
-
initialize_pit
(net, node_name, NodeComponent, NodeElementComponent, BranchComponent, BranchWInternalsComponent) Initializes and fills the internal structure which is called pit (pandapipes internal tables). The structure is a dictionary which should contain one array for all nodes and one array for all branches of the net (c.f. also create_empty_pit).
- Parameters
net (pandapipesNet) – The pandapipesNet for which to create and fill the internal structure
- Returns
(node_pit, branch_pit) - the two internal structure arrays
- Return type
tuple(np.array)
-
reduce_pit
(net, node_pit, branch_pit, nodes_connected, branches_connected) Create an internal (“active”) pit with all nodes and branches that are actually in_service. This is also done for different lookups (e.g. the from_to indices for this pit and the node index lookup). A specialty that needs to be considered is that from_nodes and to_nodes change to new indices.
- Parameters
net (pandapipesNet) – The pandapipesNet for which the pit shall be reduced
node_pit (np.array) – The internal structure node array
branch_pit (np.array) – The internal structure branch array
nodes_connected (np.array) – A mask array stating which nodes are actually connected to the rest of the net
branches_connected (np.array) – A mask array stating which branches are actually connected to the rest of the net
- Returns
No output
-
set_net_option
(net, option_name, option_value) Auxiliary function to set the value of a specific option (options are saved in a dict)
- Parameters
net (pandapipesNet) – pandapipesNet for which option shall be set
option_name (str) – name under which the option shall be saved
option_value – value that shall be set for the given option
- Returns
No output.
-
set_user_pf_options
(net, reset=False, \*\*kwargs) This function sets the ‘user_pf_options’ dict for net. These options overrule net.__internal_options once they are added to net. These options are used in configuration of load flow calculation. At the same time, user-defined arguments for pandapower.runpp() always have a higher priority. To remove user_pf_options, set overwrite=True and provide no additional arguments
- Parameters
net (pandapipesNet) – pandapipes network for which to create user options
reset (bool, default False) – specifies whether the user_pf_options is removed before setting new options
kwargs – pipeflow options that shall be set, e. g. tol_v = 1e-7
- Returns
No output
-
write_internal_results
(net, \*\*kwargs) Adds specified values to the internal result dictionary of the given pandapipesNet. If internal results are not yet defined for the net, they are created as well.
- Parameters
net (pandapipesNet) – pandapipesNet for which to update internal result dict
kwargs – additional keyword arguments with the internal result values
- Returns
No output.