New function pgr contraction hierarchies 3.8

NEWS.md

@@ -43,6 +43,8 @@ milestone for 3.8.0
     pgr_contractionDeadEnd new contraction function
   * [#2791](https://github.com/pgRouting/pgrouting/issues/2791):
     pgr_contractionLinear new contraction function
+  * [#2536](https://github.com/pgRouting/pgrouting/issues/2536):
+    Support for contraction hierarchies (pgr_contractionHierarchies)
 
 * Utilities
 

doc/conf.py.in

@@ -381,6 +381,7 @@ rst_epilog="""
 .. |result-component-V| replace:: ``(seq, component, node)``
 .. |result-component-make| replace:: ``(seq, start_vid, end_vid)``
 .. |result-contract| replace:: ``(type, id, contracted_vertices, source, target, cost)``
+.. |result-contraction-hierarchies| replace:: ``(type, id, contracted_vertices, source, target, cost, metric, vertex_order)``
 .. |result-idom| replace:: ``(seq, vertex_id, idom)``
 .. |result-dij-dd| replace:: ``(seq, [from_v,] node, edge, cost, agg_cost)``
 .. |result-dij-dd-m| replace:: ``(seq, from_v, node, edge, cost, agg_cost)``

doc/contraction/CMakeLists.txt

@@ -4,6 +4,7 @@ SET(LOCAL_FILES
     pgr_contraction.rst
     pgr_contractionDeadEnd.rst
     pgr_contractionLinear.rst
+    pgr_contractionHierarchies.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/contraction/contraction-family.rst

@@ -28,43 +28,57 @@ Contraction - Family of functions
 .. proposed-start
 
 * :doc:`pgr_contractionDeadEnd`
+* :doc:`pgr_contractionLinear`
 
 .. proposed-end
 
+.. include:: experimental.rst
+    :start-after: warning-begin
+    :end-before: end-warning
+
+.. experimental-start
+
+* :doc:`pgr_contractionHierarchies`
+
+.. experimental-end
+
 .. toctree::
     :hidden:
 
     pgr_contraction
     pgr_contractionDeadEnd
     pgr_contractionLinear
+    pgr_contractionHierarchies
 
 
 Introduction
 -------------------------------------------------------------------------------
 
-In large graphs, like the road graphs, or electric networks, graph contraction
-can be used to speed up some graph algorithms.
-Contraction reduces the size of the graph by removing some of the vertices and
-edges and, for example, might add edges that represent a sequence of original
-edges decreasing the total time and space used in graph algorithms.
+In large graphs, like road graphs or electric networks, graph contraction
+can be used to speed up some graph algorithms. Contraction can reduce the size
+of the graph by removing some of the vertices and edges and adding edges
+that represent a sequence of original edges (the original ones can be kept
+in some methods). In this way, it decreases the total time and space used
+by graph algorithms, particularly those searching for an optimal path.
 
 This implementation gives a flexible framework for adding contraction algorithms
-in the future, currently, it supports two algorithms:
+in the future. Currently, it supports three algorithms.
 
 1. Dead end contraction
 2. Linear contraction
+3. Contraction hierarchies
 
-Allowing the user to:
+The two first ones can be combined through a iterative procedure, via the
+``pgr_contraction`` method. The third one is implemented on its own.
 
-- Forbid contraction on a set of nodes.
-- Decide the order of the contraction algorithms and set the maximum number of
-  times they are to be executed.
+All functions allow the user to forbid contraction on a set of nodes.
 
 See Also
 -------------------------------------------------------------------------------
 
 * https://www.cs.cmu.edu/afs/cs/academic/class/15210-f12/www/lectures/lecture16.pdf
-* https://algo2.iti.kit.edu/documents/routeplanning/geisberger_dipl.pdf
+* https://ae.iti.kit.edu/download/diploma_thesis_geisberger.pdf
+* https://jlazarsfeld.github.io/ch.150.project/contents/
 
 .. rubric:: Indices and tables
 

doc/contraction/images/CMakeLists.txt

@@ -3,6 +3,8 @@ SET(LOCAL_FILES
     undirected_sampledata_b.png
     undirected_sampledata_c.png
     newgraph.png
+    sample_graph.png
+    sample_graph_with_shortcuts.png
     )
 
 foreach (f ${LOCAL_FILES})