dhd.connect

Module to initialize the dataframes vertices and terminals used in the evolutive algorithm from the module dhd.evolve to design the heating district network.

The dataframe terminals lists for each terminal (source or sink) all possible connection to the streets network. These connection nodes are added to the streets graph and saved into the dataframe vertices.

Procedure

https://gitlab.com/crem-repository/dhd/raw/master/docs/images/connection.png

When connecting a terminal to the streets, first a projection of the terminal geometry is applied on all edges of the graph. Then only the projections lying inside a buffer of length R around the terminal (thin green rectangle on the figure) are retained. Finally, starting with the closest connection, a circle of radius r (thin blue circle on the figure) is drawn around the selected connection and all other connections inside the circle are removed from the selection.

Also, the nomenclature used in the connection process is the following:

  • the projection on the terminal is labeled ‘T’,
  • the projection on the vertex is labeled ‘C’,
  • the first edge end of the vertex is labeled ‘A’,
  • the second edge end of the vertex is labeled ‘B’.

Inputs

The user must provide dataframes of the streets graph (streets), of the sinks to be connected (sinks) and of the heating source(s) (sources). A dataframe of the natural barriers (barriers) may also be provided. These four dataframes can be obtained from OSM for a given city using the module dhd.city.

The connection procedure depends on the optional parameters R and r being respectively the maximal connection length between a terminal and the heating network and the minimal distance between two connections to the same terminal.

If the edges weights are not specified, their length is used. Also a function connection_weight_function can be provided to set the weight of the connections between the terminals and the streets network.

The original indices of the dataframe sinks are preserved by default, but new indices may be generated by setting ignore_index=True.

Outputs

The dataframes vertices and terminals are returned by the function dhd.connect.connect_terminals.

Functions

dhd.connect.add_connection_to_terminal(terminal, coords, idC, func)[source]

Append the connection list of terminal with connection of coordinates coords and index ‘idC’ ; in-place.

Parameters:
  • terminal (Series) – Row of the terminals dataframe.
  • coords (dict) – Tuple coordinates of the connection edge ends (‘A’ and ‘B’), the terminal (‘T’) and the connection point on the vertex edge (‘C’).
  • idC (str) – Index of the new connection.
  • func (function) – Function of the connection length returning its weight.
dhd.connect.append_superpositions(superpositions, idx1, idx2)[source]

Add indices idx1 and idx2 (associted to the new superposed sink) in the appropriate set of indices ; in-place.

Parameters:
  • superpositions (list) – List of sets. Each set arguments are the indices of the sinks located at a same location.
  • idx1 (int) – Index of the first superposed sink.
  • idx2 (int) – Index of the second superposed sink.
dhd.connect.check_data_structure(sinks, streets, sources, barriers, ignore_index)[source]

Ensure that the provided dataframes have the required structure.

Parameters:
  • streets (DataFrame) – Dataframe of the street network.
  • sinks (DataFrame) – Dataframe of the heating sinks.
  • sources (DataFrame) – Dataframe of the heating source(s).
  • barriers (DataFrame) – Dataframe of the natural barriers.
Returns:

True if the assertion are passed.
Return type:

bool
dhd.connect.check_index_repetition(df)[source]

Check that there is no repetition amongst the indices of the given dataframe.

Parameters:df (DataFrame) –
Returns:True if the assertion is passed.
Return type:bool
dhd.connect.clean_superpositions(sinks, epsilon=0.01)[source]

Remove superposed sinks.

If multiple sink geometries are located at the same location (for example because of a bad time evolution documentation) only one of them is retained.

Parameters:
  • sinks (DataFrame) – Dataframe of the heating sinks.
  • epsilon (float, optional) – Only sinks whose superposition area is larger than epsilon times the area of the smallest sink area are considered in superposition. Default is 0.01.
Returns:

Updated sinks dataframe.
Return type:

DataFrame
dhd.connect.connect_terminal(vertices, terminal, barriers, R, r, func)[source]

Span the graph to find the possible connections to the given terminal and then update the dataframes vertices and terminals accordingly ; in-place.

Parameters:
  • vertices (DataFrame) – Dataframe of the vertices.
  • terminal (Series) – Row of the dataframe terminal.
  • barriers (DataFrame) – Dataframe of the natural barriers.
  • R (float) – Maximal connection length.
  • r (float) – Minimal distance between two connections to the same terminal.
  • func (function) – Function of the connection length returning its weight.
dhd.connect.connect_terminals(streets, sinks, sources, barriers=None, R=75, r=25, ignore_index=False, connection_weight_function=None)[source]

Construct the dataframes vertices and terminals needed for the district heating design evolutive algorithm in the module dhd.evolve.

The original street graph is enlarged with the connection nodes between the terminals and the graph edges. All the possible connection edges are stored in terminals.

Parameters:
  • streets (DataFrame) –

    Dataframe of the street network with the following structure:

    • INDEX: Integers.
    • COLUMNS:
      • ’idA’: index of the first edge end (A),
      • ’idB’: index of the second edge end (B),
      • ’geometry’: shapely LineString of the edge between A and B (it must go from A to B).
      • ’weight’: edge weight (optional, if not specified the edge length is used instead).
      • …
  • sinks (DataFrame) –

    Dataframe of the heating sinks with mandatory structure:

    • INDEX: If index is True, set of indices disjoint from the set of indices of sources. Otherwise the indices are generated.
    • COLUMNS:
      • ’geometry’: shapely geometry of the sink,
      • ’load’: heating load of the sink (optional, if not specified the module dhd.load cannot be used.)
      • …
  • sources (DataFrame) –

    Dataframe of the heating source(s) of the district heating network with the following structure:

    • INDEX: If index is True, set of indices disjoint from the set of indices of sinks. Otherwise the indices are generated.
    • COLUMNS:
      • ’geometry’: shapely geometry of the source.
      • …
  • barriers (DataFrame, optional) –

    Dataframe of the natural barriers (railways, rivers,…) which cannot be crossed when connecting a sink to the heating network. Default is None. The dataframe must have the following structure:

    • INDEX: Integers.
    • COLUMNS:
      • ’geometry’: shapely LineString of the barrier.
      • …
  • R (float, optional) – Maximal connection length. Default is 50 m.
  • r (float, optional) – Minimal distance between two connections to the same terminal. Default is 20 m.
  • ignore_index (bool, optional) – If False, use indices from the dataframes sources and sinks, otherwise generate new indices. Default is True. Note that the indices of sinks and the indices of sources must be two disjoint set.
  • connection_weight_function (function, optional) – Function of the connection length returning its weight. If None the weight is set equal to the length. Default is None.
Returns:

  • vertices (DataFrame) – Dataframe of the street network plus the possible connection nodes to the terminals with the following structure:

    • INDEX: Integers

    • COLUMNS:

      • ’idA’: first node index (from streets),
      • ’idB’: second node index (from streets),
      • ’idE’: edge index,
      • ’xA’, ‘yA’: first node coordinates,
      • ’xB’, ‘yB’: second node coordinates,
      • ’geometry’: edge geometry (shapely LineString),
      • ’weight’: edge weight,
      • … additional columns from streets.

  • terminals (DataFrame) – Dataframe of the terminals to connect to the streets network and their possible connections with the following structure:

    • INDEX: If index is True, indices from sources and sinks, generated indices : [‘0S’,…,’NS’,‘0B’,…,’MB’] for N sources and M sinks.

    • COLUMNS:

      • ’_id’: list of the possible connections indices,
      • ’_weight’: list of the possible connections weights,
      • ’_geometry’: list of the possible connections geometries,
      • ’geometry’: geometry of the terminal,
      • ’kind’: terminal kind (‘source’ or ‘sink’),
      • ’load’: terminal heating load (only if provided in sinks).
dhd.connect.connection_weight(line, func)[source]

Return the weight of the connection line according to weight function func.

If func is None, the weight is set equal to the connection length.

Parameters:
  • line (LineString) – Geometry of the connection.
  • func (function) – Function of the connection length returning its weight.
Returns:

Weight of the connection.
Return type:

float
dhd.connect.find_vertex(vertices, connection)[source]

Find which vertex of vertices corresponds to connection.

Parameters:
  • vertices (DataFrame) – Dataframe of the vertices.
  • connection (Series) – Row of the dataframe connections obtained with the function dhd.connect.second_selection.
Returns:

Series of the dataframe vertices corresponding to connection.
Return type:

Series
dhd.connect.first_selection(vertices, terminal, R, barriers)[source]

Select the orthogonal projection on the edges of vertices within the distance R from the geometry of terminal.

If not None the geometric constraint barriers prevent any connection crossing it.

Parameters:
  • vertices (DataFrame) – Dataframe of the vertices.
  • terminal (Series) – Row of the terminal dataframe.
  • R (float) – Maximal connection length.
  • barriers (DataFrame) – Dataframe of the natural barriers.
Returns:

Dataframe of the selected connections with columns:
  • ’idA’: fist connection edge node index,
  • ’idB’: second connection edge node index,
  • ’idE’: connection edge index,
  • ’xT’, ‘yT’: coordinates of the connection point on the terminal,
  • ’xC’, ‘yC’: coordinates of the connection point on the vertex edge,
  • ’d’: length of the connection.
Return type:

DataFrame
dhd.connect.get_connection_coordinates(connection, vertex)[source]

Get the coordinates of the different points of the connection.

The vertex edges end are labeled ‘A’ and ‘B’, the terminal is labeld ‘T’ and the connection point on the vertex edge is labeled ‘C’.

Parameters:
  • connection (Series) – Row of the dataframe connections obtained from the function dhd.connect.second_selection. It contains all the information on the terminal to be connected.
  • vertex (Series) – Row of the dataframe vertices. It contains all the information on the edge to be connected.
Returns:

Dictionary of the four point tuple coordinates with keys: ‘A’, ‘B’, ‘T’ and ‘C’.
Return type:

dict
dhd.connect.get_connection_distances(coords)[source]

Measure the distances between the points ‘A’ and ‘C’ and the points ‘B’ and ‘C’ from the dictionary coords.

Parameters:coords (dict) – Tuple coordinates of the connection edge ends (‘A’ and ‘B’), the terminal (‘T’) and the connection point on the vertex edge (‘C’).
Returns:Dictionary of the two distances (‘A’-‘C’ and ‘B’-‘C’) with keys ‘A’ and ‘B’.
Return type:dict
dhd.connect.get_connection_index(connection, terminal, d)[source]

Find if the connection ‘C’ lies on the edge ‘A’-‘B’, on the edge end ‘A’ or on the edge end ‘B’ and return the associted connection index.

Parameters:
  • connection (Series) – Row of the dataframe connections obtained from the function dhd.connect.second_selection.
  • terminal (Series) – Row of the dataframe terminals.
  • d (dict) – Dictionary of the distances between the connection and the edge ends.
Returns:

  • bool – True if ‘C’ lies on ‘A’-‘B’, False otherwise.
  • str – Index of the connection ‘C’: index of ‘A’ if ‘C’=’A’, index of ‘B’ if ‘C’=’B’, concatenation of the terminal index and the connection index otherwise.
dhd.connect.get_nearest_point(series1, series2)[source]

Get tuple coordinates of the orthogonal projections between the geometries of the two given Series.

Parameters:
  • series1 (Series) – Series with a geometry key.
  • series2 (Series) – Series with a geometry key.
Returns:

  • tuple – Coordinates of the projection on series1 geometry,
  • tuple – Coordinates of the projection on series2 geometry.
dhd.connect.get_superpositions(sinks, epsilon)[source]

Find the sets of sinks superpositions.

Parameters:
  • sinks (DataFrame) – Dataframe of the heating sinks.
  • epsilon – Only sinks whose superposition area is larger than epsilon times the area of the smallest sink area are considered in superposition.
Returns:

List of sets. Each set arguments are the indices of the sinks located at a same location.
Return type:

list
dhd.connect.get_terminals_indices(sources, sinks, ignore_index)[source]

List the indices of the dataframe terminals from the dataframes sources and sinks.

If index is True, use the indices of the dataframes, otherwise generate new indices.

Parameters:
  • sources (DataFrame) – Dataframe of the heating source(s).
  • sinks (DataFrame) – Dataframe of the sinks.
  • ignore_index (bool) – If False, use indices from the dataframes sources and sinks, otherwise generate new indices.
Returns:

List of the dataframe terminals indices.
Return type:

list
dhd.connect.init_terminals(sources, sinks, ignore_index)[source]

Initialization of the dataframe terminals from the input dataframes sinks and sources.

Parameters:
  • sources (DataFrame) – Dataframe of the heating source(s).
  • sinks (DataFrame) – Dataframe of the sinks.
  • ignore_index (bool) – If False, use indices from the dataframes sources and sinks, otherwise generate new indices.
Returns:

Dataframe of the terminals.
Return type:

DataFrame
dhd.connect.init_vertices(streets)[source]

Initilization of the dataframe vertices from the input dataframe streets.

Parameters:streets (DataFrame) – Dataframe of the street network.
Returns:Dataframe of the vertices.
Return type:DataFrame
dhd.connect.is_crossing_a_barrier(p1, p2, barriers)[source]

Check if the two points p1 and p2 are on the same side of the list of barriers barriers.

Parameters:
  • p1 (tuple) – Coordinates of the first point.
  • p2 (tuple) – Coordinates of the second point.
  • barriers (DataFrame) – Dataframe of the natural barriers.
Returns:

True if the line p1-p2 crosses the barriers geometry, False otherwise.
Return type:

bool
dhd.connect.new_edge_weight(vertex, line)[source]

Compute the weight of the splitted edge of geometry line and original vertex row vertex.

Parameters:
  • vertex (Series) – Row of the dataframe vertices.
  • line (LineString) – One of the two geometries of the splitted edge.
Returns:

Weight of the new vertex.
Return type:

float
dhd.connect.order_superpositions(superpositions)[source]

Put all superposition indices in one single list and remove one index from each superposition set.

Parameters:superpositions (list) – List of sets. Each set arguments are the indices of the sinks located at a same location.
Returns:List of indices associated to the rows to remove from the dataframe sinks.
Return type:list
dhd.connect.remove_point(selection, idmin, r)[source]

Remove connections within distance r from the closest connection of index idmin ; in-place.

Parameters:
  • selection (DataFrame) – Dataframe of the connections selected by dhd.connect.first_selection.
  • idmin (int) – Index of the connection having the smallest distance d in selection.
  • r (float) – Minimal distance between two connections to the same terminal.
dhd.connect.second_selection(selection, r)[source]

Improve selection quality by removing connections within the distance d from each other.

Parameters:
  • selection (DataFrame) – Dataframe of the connections selected by dhd.connect.first_selection.
  • r (float) – Minimal distance between two conections to the same terminal.
Returns:

Dataframe of the possible connections to the considered terminal. The columns are identical to those of selection.
Return type:

DataFrame
dhd.connect.set_default_weight_to_length(vertices)[source]

Add weight column to the dataframe vertices with element equal to the length of the associated geometry ; in-place.

Parameters:vertices (DataFrame) – Dataframe of the vertices.
dhd.connect.set_line_coordinates(vertices)[source]

Add coordinates columns (‘xA’,’xB’,’yA’,’yB’) to the dataframe vertices ; in-place.

The end node coordinates of each geometry (edge) of vertices are computed and stored in their associated column (first end -> ‘A’, second end -> ‘B’).

Parameters:vertices (DataFrame) – Dataframe of the vertices.
dhd.connect.sort_lines(line1, line2, coords)[source]

Sort line1 and line2 such that the first line has either its first points equal to coords or its last point equal to coords.

Parameters:
  • line1 (LineString) – Geometry of the first line of the splitted edge.
  • line2 (LineString) – Geometry of the second line of the splitted edge.
  • coords (tuple) – Coordinates of the edge end ‘A’.
Returns:

  • LineString – Line with one end equal to the edge end ‘A’,
  • LineString – Line with one end equal to the edge end ‘B’.
dhd.connect.split_line(l, p, eps=0.1)[source]

Split the LineString l in two at a the Point p on the line.

Parameters:
  • l (LineString) – Vertex edge to split at the connection point.
  • p (Point) – Connection point on the vertex edge.
  • eps (float, optional) – Distance under which two points are considered identical. Default is 0.1 m.
Returns:

  • LineString – Geometry of the first line,
  • LineString – Geometry of the second line.
dhd.connect.update_edges(vertices, connection, vertex, coords, idC, func)[source]

Update the graph edges in vertices according to the new connection on the considered vertex ; in-place.

This function is only called when the parent edge is splitted in two child edges. The parent edge is removed and the child edges are appended.

Parameters:
  • vertices (DataFrame) – Dataframe of the vertices.
  • connection (Series) – Row of the dataframe connections obtained with the function dhd.connect.second_selection.
  • vertex (Series) – Row of the dataframe vertices.
  • coords (dict) – Tuple coordinates of the connection edge ends (‘A’ and ‘B’), the terminal (‘T’) and the connection point on the vertex edge (‘C’).
  • idC (str) – Index of the new connection.
  • func (function) – Function of the connection length returning its weight.
dhd.connect.update_graph(vertices, terminal, connections, func)[source]

Add the possible connections to the given terminal into the dataframe vertices ; in-place.

The list associated to the given terminal in the dataframe terminals are appended by each possible connection. Also the rows of the dataframe vertices are modified to coincide with the new graph when a connection occurs on a parent edge splitted in two child edges.

Parameters:
  • vertices (DataFrame) – Dataframe of the vertices.
  • vertex (Series) – Row of the dataframe vertices.
  • connections (DataFrame) – Dataframe of the possible connections to the considered terminal, obtained from the function dhd.connect.second_selection.
  • func (function) – Function of the connection length returning its weight.