dhd.load

Module to reorganize the Terminal Steiner Tree (TST) computed with the module dhd.evolve with a pipeline structure. A pipeline is defined as a merged series of TST edges sharing the same load. The load of a pipeline is equal to the sum of the heating loads of all the sinks it eventually leads to.

Functions to compute the pipelines diameters and nominal diameters are also implemented.

Inputs

The user must provide the dataframe of the TST to load (tst) and the dataframe of the terminals (terminals) with the loads. These two dataframes are computed within the module dhd.evolve.

Outputs

All the pipeline information is saved in a dataframe (pipelines) returned by the function dhd.load.load_the_pipelines.

Functions

dhd.load.add_next_pipe(ordered_pipes, pipe, reverse)

Append pipe to the dataframe ordered_pipes ; in-place.

Parameters:

• ordered_pipes (DataFrame) – Dataframe of the pipes belonging to the same pipeline disposed from one pipeline end to the other.
• pipe (Series) – Row of the TST dataframe pipes corresponding to the pipe to append.
• reverse (bool) – True if the pipe LineString must be inversed.

dhd.load.add_pipelines(pipelines, pipes)

Select pipes belonging to the same pipeline, construct the pipelines and add them to the dataframe pipelines ; in-place.

Once the pipes have been selected they are removed from the dataframe pipes.

Its is possible to select and construct multiple pipelines if they have the same load.

Parameters:

• pipelines (DataFrame) – Dataframe of the TST pipelines.
• pipes (DataFrame) – Dataframe of the TST pipes.

dhd.load.add_terminal_to_pipes(pipes, terminal, idS)

Add the load of terminal to the dataframe pipes ; in-place.

The shortest path between the source and terminal is first computed and then all pipes on the way are updated.

Parameters:

• pipes (DataFrame) – Dataframe of the TST.
• terminal (Series) – Row of the dataframe terminals describing the considered terminal.
• idS (string) – Index of the dataframe terminals referring to the unique source.

dhd.load.construct_pipeline(pipes_selection)

Find the pipes belonging to the same pipeline in the dataframe pipes_selection and stick them together to form a pipeline.

Parameters:pipes_selection (DataFrame) – Dataframe of the selected pipes (same load as the first pipe). Returns:Row of the dataframe pipelines with information on the pipeline to add. Return type:Series

dhd.load.find_next_pipe(pipes_selection, ordered_pipes)

Find the pipe connected to the ‘B’ node of the last pipe of the dataframe ordered_pipes from the dataframe pipes_selection.

Parameters:

• pipes_selection (DataFrame) – Dataframe of the selected pipes (same load as the first pipe).
• ordered_pipes (DataFrame) – Dataframe of the pipes belonging to the same pipeline disposed from one pipeline end to the other.

Returns:

• int – Index of the next pipe.
• Series – Row of the dataframe pipes_selection of the next pipe.
• bool – True if the pipe LineString must be reversed.

dhd.load.get_diameter_function(unit, rho, cp, vmax, dT)

Define the standard diameter function, which returns the diameter of a pipeline depending on its heating load.

Parameters:

• unit (string, optional) – Unit of the load power: ‘kW’ for kilowatts or ‘W’ for watts. Default is ‘kW’.
• rho (float, optional) – Mass density of the pipelines liquid in [kg/m^3]. Default is 1000.
• cp (float, optional) – Isobaric heat capacity of the pipelines liquide in [kJ/kg/K]. Default is 4.18.
• vmax (float, optional) – Design flow velocity in [m/s]. Default is 2.
• dT (float, optional) – Temperature difference between the supply and return pipe networks if [K]. Default is 30.

Returns:

Diameter function which returns the diameter of a pipeline depending on its heating load.

Return type:

function

dhd.load.get_first_end(pipes_selection)

Find an end node of one of the pipelines to build with the pipes from pipes_selection.

Look for a node which occurs only once amongst the ends of the pipes of pipes_selection. If this node is match to the label ‘A’ (‘B’) reverse is set to True (False).

Parameters:pipes_selection – Dataframe of the selected pipes (same load as the first pipe). Returns:

• int – Index of the dataframe pipes_selection referring to the end node.
• bool – True (False) if the node is at the ‘A’ (‘B’) end.

dhd.load.get_nominal_diameter(pipe_catalogue, diameter, DN, ID)

Compute the nominal diameter associated to a metric diameter according to the provided catalogue.

The metric diameter predicted by the module is matched to the nominal pipe with the minimal superior inner diameter.

Parameters:

• pipelines (DataFrame) – Dataframe of the TST pipelines.
• pipe_catalogue (DataFrame) – Catalogue of the nominal pipe size. It must at least contain a column of nominal diameters (DN) and a column of inner diameters (ID).
• DN (string) – Name of the nominal diameter column.
• ID (string) – Name of the inner diameter column.

dhd.load.get_ordered_pipes(pipes_selection)

Classify the selected pipes (rows of pipes_selection) from the one pipeline end to the other.

Parameters:pipes_selection (DataFrame) – Dataframe of the selected pipes (same load as the first pipe). Returns:Dataframe of the pipes belonging to the same pipeline disposed from one pipeline end to the other. Return type:DataFrame

dhd.load.get_pipeline_geometry(ordered_pipes)

Merge the geomteries of the pipes belonging to the same pipeline into a unique LineString geometry.

Parameters:ordered_pipes (DataFrame) – Dataframe of the pipes belonging to the same pipeline disposed from one pipeline end to the other. Returns:Geometry of the pipeline. Return type:LineString

dhd.load.get_source_index(terminals)

Find the source index in the terminals dataframe.

If there is no source or if it is not unique, an error is raised.

Parameters:terminals (DataFrame) – Dataframe of the terminals. Returns:Index of the terminal dataframe referring to the unique source. Return type:string

dhd.load.init_pipelines()

Initialize the dataframe pipelines used to store the pipelines, namely the merged pipes of identical load.

Returns:Empty dataframe with columns ‘idA’, ‘idB’, ‘length’, ‘weight’, ‘geometry’, ‘load’, ‘n_sink’, ‘pA’, ‘pB’. Return type:DataFrame

dhd.load.init_pipes(tst)

Convert the dataframe tst into its graph with source ‘idA’ and target ‘idB’.

tst must come with the columns ‘geometry’, ‘weight’, ‘pA’ and ‘pB’. Two arguments (‘load’, ‘n_sink’) are added to the graph edges and set to 0.

Parameters:tst (DataFrame) – DataFrame of the Terminal Steiner Tree. Returns:Graph of the Terminal Steiner Tree. Return type:Graph

dhd.load.init_terminals(terminals)

Initialize the dataframe of the terminals (terminals) by removing the columns ‘_id’, ‘_geometry’, ‘_weight’ and adding the column ‘connected’ ; in-place.

The ‘connected’ column is filled with booleans, True if the terminal is connected to the district heating network and false otherwise.

Parameters:terminals (DataFrame) – Dataframe of the terminals as returned by the module dhd.evolve, namely with all possible connections.

dhd.load.load_the_pipelines(tst, terminals)

Function to class the pipes into pipelines and store them in a dataframe.

A pipeline is a series of pipes connecting two droppings (sinks or intersections). All the pipes of a pipeline share the same load and serve the same number of sikns n_sink. The length (weight) of a pipeline are given by the sum of the length (weight) of its constituent pipes.

Parameters:

• tst (DataFrame) – DataFrame of the Terminal Steiner Tree.
• terminals (DataFrame) – Dataframe of the terminals.

Returns:

pipelines –

Dataframe of the TST pipelines with the following structure:

• INDEX: Integers.

• COLUMNS:

  • ’idA’: first pipeline end node index,
  • ’idB’: second pipeline end node index,
  • ’pA’: coordinates (shapely Point) of the node ‘idA’,
  • ’pB’: coordinates (shapely Point) of the node ‘idB’,
  • ’length’: pipeline length,
  • ’weight’: pipeline weight,
  • ’load’: heating load served by the pipeline,
  • ’n_sink’: number of buildings served by the pipeline,
  • ’geometry’: pipeline geometry.

Return type:

GeoDataFrame

dhd.load.load_the_pipes(tst, terminals)

Define a dataframe of the pipes (edges) of the TST with loads associated to the number of served sinks and the served heating load.

Parameters:

• tst (DataFrame) – DataFrame of the TST as returned by the module dhd.evolve.
• terminals (DataFrame) – Dataframe of the terminals as returned by the module dhd.evolve, namely with all possible connections.

Returns:

Dataframe of the TST with the edges loads.

Return type:

DataFrame

dhd.load.order_geometries(pipes)

Inverse all edges geometry which direction is opposite to its associated edge end coordinates ‘pA’ and ‘pB’ ; in-place.

Parameters:pipes (DataFrame) – Dataframe of the TST pipes.

dhd.load.remove_pipe_from_pipes_selection(pipes_selection, idx)

Remove the pipe of index idx from the dataframe of pipes of equal load ; in-place.

Parameters:

• pipes_selection (DataFrame) – Dataframe of the selected pipes (same load as the first pipe).
• idx (int) – Index of the pipe to remove.

dhd.load.remove_pipes(pipes, pipes_selection)

Remove the selected pipes (pipes_selection) from the dataframe pipes ; in-place

Parameters:

• pipes (DataFrame) – Dataframe of the TST pipes.
• pipes_selection – Dataframe of the selected pipes (same load as the first pipe).

dhd.load.select_pipes(pipes)

Select pipes which have the same load as the first pipe of the dataframe pipes.

Parameters:pipes (DataFrame) – Dataframe of the TST pipes. Returns:Dataframe of the selected pipes (same load as the first pipe). Return type:DataFrame

dhd.load.set_diameter(pipelines, diameter_function=None, unit='kW', rho=1000, cp=4.18, vmax=2, dT=30)

Compute the diameters of the pipelines according to a function depending on its heating load ; in-place.

If not provided the standard relation

\[P [kW] = \dot{m} [kg/s]\: c_p[kJ/kg/K]\: \Delta T[K]\]

is used to define the diameter function.

Parameters:

• diameter_function (function) – Function of a pipeline heating load returning its diameter. If not specified the standard function from dhd.load.get_diameter_function is used. Default is None.
• unit (string, optional) – Unit of the load power: ‘kW’ for kilowatts or ‘W’ for watts. Default is ‘kW’.
• rho (float, optional) – Mass density of the pipelines liquid in [kg/m^3]. Default is 1000.
• cp (float, optional) – Isobaric heat capacity of the pipelines liquide in [kJ/kg/K]. Default is 4.18.
• vmax (float, optional) – Design flow velocity in [m/s]. Default is 2.
• dT (float, optional) – Temperature difference between the supply and return pipe networks if [K]. Default is 30.

dhd.load.set_nominal_diameter(pipelines, pipe_catalogue, DN='DN', ID='ID')

Add a column of nominal diameters to the pipelines dataframe.

The metric diameter predicted by the module is matched to the nominal pipe with the minimal superior inner diameter as listed in the dataframe pipe_catalogue.

Parameters:

• pipe_catalogue (DataFrame) – Catalogue of the nominal pipe size. It must at least contain a column of nominal diameters (DN) and a column of inner diameters (ID).
• diameter (float) – Metric diameter predicted by the module.
• DN (string, optional) – Name of the nominal diameter column. Default is ‘DN’.
• ID (string, optional) – Name of the inner diameter column. Default is ‘ID’.

dhd.load.stick_ordered_pipes(ordered_pipes)

Merge all pipes of a pipeline.

Parameters:ordered_pipes (DataFrame) – Dataframe of the pipes belonging to the same pipeline disposed from one pipeline end to the other. Returns:Row of the dataframe pipelines with information on the pipeline to add. Return type:Series

dhd.load.update_loads(shortest_path, pipes, terminal)

Update the loads of all pipes on the shortest path between the considered terminal and the source ; in-place.

The attributes ‘load’ and ‘n_sink’ of each pipes on the path are respectively incremented by the load of the selected building and one.

Parameters:

• shortest_path (list) – List of the nodes on the shortest path.
• pipes (DataFrame) – Dataframe of the TST.
• terminal (Series) – Row of the dataframe terminals describing the considered terminal.