===========
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
---------

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

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
---------

.. automodule:: dhd.connect
	:members:
	:private-members: