Merge pull request #2364 from shobhit162/cuthillMckeeOrdering

[GSoC-2022] Experimental Function - cuthillMckeeOrdering

configuration.conf

@@ -44,6 +44,7 @@ traversal           | Y | Y | Y
 coloring            | Y | Y | Y
 planar              | Y | Y | Y
 dominator           | Y | Y | Y
+ordering            | Y | Y | Y
 circuits            | Y | Y | Y
 #----------------------
 # SQL only directories

doc/conf.py.in

@@ -330,6 +330,8 @@ linkcheck_ignore = [
     r'https://docs.pgrouting.org/.*/.*/DFS-category.html',
     r'https://docs.pgrouting.org/.*/.*/reference.html',
     r'https://docs.pgrouting.org/.*/.*/pgr_degree.html',
+    r'https://docs.pgrouting.org/.*/.*/cuthillMckeeOrdering.html',
+    r'https://docs.pgrouting.org/.*/.*/ordering-family.html',
     r'https://docs.pgrouting.org/.*/.*/hawickCircuits.html',
     r'https://docs.pgrouting.org/.*/.*/pgr_findCloseEdges.html',
 

doc/ordering/CMakeLists.txt

@@ -0,0 +1,11 @@
+SET(LOCAL_FILES
+    ordering-family.rst
+    cuthillMckeeOrdering.rst
+    )
+
+foreach (f ${LOCAL_FILES})
+    configure_file(${f} "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}")
+    list(APPEND LOCAL_DOC_FILES  ${PGR_DOCUMENTATION_SOURCE_DIR}/${f})
+endforeach()
+
+set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)

doc/ordering/cuthillMckeeOrdering.rst

@@ -0,0 +1,132 @@
+..
+   ****************************************************************************
+    pgRouting Manual
+    Copyright(c) pgRouting Contributors
+
+    This documentation is licensed under a Creative Commons Attribution-Share
+    Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/
+   ****************************************************************************
+
+|
+
+* **Supported versions:**
+  `Latest <https://docs.pgrouting.org/latest/en/cuthillMckeeOrdering.html>`__
+  (`3.4 <https://docs.pgrouting.org/3.4/en/cuthillMckeeOrdering.html>`__)
+
+cuthillMckeeOrdering - Experimental
+===============================================================================
+
+``cuthillMckeeOrdering`` — Returns the reverse Cuthill-Mckee ordering of an undirected
+graphs
+
+.. figure:: images/boost-inside.jpeg
+   :target: https://www.boost.org/libs/graph/doc/cuthill_mckee_ordering.html
+
+   Boost Graph Inside
+
+.. include:: experimental.rst
+   :start-after: begin-warn-expr
+   :end-before: end-warn-exp
+
+.. rubric:: Availability
+
+* Version 3.4.0
+
+  * New **experimental** signature:
+
+
+Description
+-------------------------------------------------------------------------------
+
+In numerical linear algebra, the Cuthill-McKee algorithm (CM), named after
+Elizabeth Cuthill and James McKee, is an algorithm to permute a sparse
+matrix that has a symmetric sparsity pattern into a band matrix form with a
+small bandwidth. The reverse Cuthill-McKee algorithm (RCM) due to Alan George
+and Joseph Liu is the same algorithm but with the resulting index numbers reversed.
+In practice this generally results in less fill-in than the CM ordering when
+Gaussian elimination is applied.
+
+The vertices are basically assigned a breadth-first search order, except that at
+each step, the adjacent vertices are placed in the queue in order of increasing degree.
+
+There are 3 versions defined in the Boost Graph Library. Here, we have implemented only
+version 2 as it is most suitable and practical for users. In this version we don't have to 
+provide the starting vertex in the query. Whereas, in the version 1 we have to provide the 
+starting vertex and it gives result only for single component. Version 2 is applicable for one 
+and more than one components as it finds the starting vertex itself using the pseudo-peripheral
+pair heuiristic approach among each component. Maybe in future, we will also implemenent the 
+version 1.
+
+**The main Characteristics are:**
+
+- The implementation is for **undirected** graphs.
+- The bandwidth minimization problems are considered NP-complete problems. 
+- The running time complexity is: :math:`O(m log(m)|V|)`
+
+  - where :math:`|V|` is the number of vertices,
+  - :math:`m` is the maximum degree of the vertices in the graph.
+
+Signatures
+------------------------------------------------------------------------------
+
+.. index::
+    single: cuthillMckeeOrdering - Experimental on v3.4
+
+.. parsed-literal::
+
+    cuthillMckeeOrdering(`Edges SQL`_)
+
+    RETURNS SET OF (seq, node)
+    OR EMPTY SET
+
+:Example: Graph ordering of pgRouting :doc:`sampledata`
+
+.. literalinclude:: cuthillMckeeOrdering.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+.. Parameters, Inner Queries & result columns
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: ordering-family.rst
+   :start-after: parameters_start
+   :end-before: parameters_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+   :start-after: basic_edges_sql_start
+   :end-before: basic_edges_sql_end 
+
+Return columns
+-------------------------------------------------------------------------------
+
+.. include:: ordering-family.rst
+    :start-after: result_columns_start
+    :end-before: result_columns_end
+
+See Also
+-------------------------------------------------------------------------------
+
+* The queries use the :doc:`sampledata` network.
+
+.. see also start
+
+* `Boost: Cuthill-McKee Ordering
+  <https://www.boost.org/libs/graph/doc/cuthill_mckee_ordering.html>`__
+* `Wikipedia: Cuthill-McKee Ordering <https://en.wikipedia.org/wiki/Cuthill%E2%80%93McKee_algorithm>`__
+
+.. see also end
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`     
+
+

doc/ordering/ordering-family.rst

@@ -0,0 +1,90 @@
+..
+   ****************************************************************************
+    pgRouting Manual
+    Copyright(c) pgRouting Contributors
+
+    This documentation is licensed under a Creative Commons Attribution-Share
+    Alike 3.0 License: https://creativecommons.org/licenses/by-sa/3.0/
+   ****************************************************************************
+
+|
+
+* **Supported versions:**
+  `Latest <https://docs.pgrouting.org/latest/en/ordering-family.html>`__
+  (`3.4 <https://docs.pgrouting.org/3.4/en/ordering-family.html>`__)
+
+Ordering - Family of functions
+===============================================================================
+
+.. rubric:: Experimental
+
+.. include:: experimental.rst
+   :start-after: begin-warn-expr
+   :end-before: end-warn-expr
+
+
+.. index from here
+
+* :doc:`cuthillMckeeOrdering` - Return reverse Cuthill-McKee ordering of an undirected graph.
+
+.. index to here
+
+.. toctree::
+    :hidden:
+
+    cuthillMckeeOrdering
+
+Parameters
+...............................................................................
+
+.. parameters_start
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Description
+   * - `Edges SQL`_
+     - ``TEXT``
+     - `Edges SQL`_ as described below.
+
+.. parameters_end
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+   :start-after: basic_edges_sql_start
+   :end-before: basic_edges_sql_end
+
+Result Columns
+-------------------------------------------------------------------------------
+
+.. result_columns_start
+
+Returns SET OF ``(seq, node)``
+
+===============  =========== ======================================
+Column           Type        Description
+===============  =========== ======================================
+``seq``           ``BIGINT``  Sequence of the order starting from 1.
+``node``          ``BIGINT``  New ordering in reverse order.
+===============  =========== ======================================
+
+.. result_columns_end
+
+See Also
+-------------------------------------------------------------------------------
+
+.. include:: cuthillMckeeOrdering.rst
+    :start-after: see also start
+    :end-before: see also end
+
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/src/experimental.rst

@@ -90,6 +90,12 @@ Experimental Functions
    :start-after: index experimental from here
    :end-before: index experimental to here
 
+:doc:`ordering-family`
+
+.. include:: ordering-family.rst
+   :start-after: index from here
+   :end-before: index to here
+
 :doc:`TRSP-family`
 
 .. include:: TRSP-family.rst

doc/src/pgRouting-introduction.rst

@@ -87,6 +87,7 @@ Daniel Kastl,
 Nitish Chauhan,
 Rajat Shinde,
 Regina Obe,
+Shobhit Chaurasia,
 Swapnil Joshi,
 Virginia Vergara
 
@@ -156,6 +157,7 @@ Razequl Islam,
 Regina Obe,
 Rohith Reddy,
 Sarthak Agarwal,
+Shobhit Chaurasia,
 Sourabh Garg,
 Stephen Woodbridge,
 Swapnil Joshi,

docqueries/ordering/CMakeLists.txt

@@ -0,0 +1,11 @@
+# Do not use extensions
+SET(LOCAL_FILES
+    cuthillMckeeOrdering
+    )
+
+foreach (f ${LOCAL_FILES})
+    configure_file("${f}.result" "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
+    list(APPEND LOCAL_DOC_FILES  "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
+endforeach()
+
+set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)

docqueries/ordering/cuthillMckeeOrdering.result

@@ -0,0 +1,56 @@
+BEGIN;
+BEGIN
+SET client_min_messages TO NOTICE;
+SET
+/* -- q1 */
+SELECT * FROM pgr_cuthillMckeeOrdering(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+  );
+ seq | node
+-----+------
+   1 |   13
+   2 |   14
+   3 |    2
+   4 |    4
+   5 |    1
+   6 |    9
+   7 |    3
+   8 |    8
+   9 |    5
+  10 |    7
+  11 |   12
+  12 |    6
+  13 |   11
+  14 |   17
+  15 |   10
+  16 |   16
+  17 |   15
+(17 rows)
+
+/* -- q2 */
+
+CREATE TABLE expected_result (
+  seq BIGINT,
+  node BIGINT);
+CREATE TABLE
+INSERT INTO expected_result (seq, node) VALUES
+(1, 13),
+(2, 14),
+(3, 2),
+(4, 4),
+(5, 9),
+(6, 1),
+(7, 8),
+(8, 3),
+(9, 12),
+(10, 7),
+(11, 5),
+(12, 17),
+(13, 11),
+(14, 6),
+(15, 16),
+(16, 10),
+(17, 15);
+INSERT 0 17
+ROLLBACK;
+ROLLBACK

docqueries/ordering/cuthillMckeeOrdering.test.sql

@@ -0,0 +1,33 @@
+/* -- q1 */
+SELECT * FROM pgr_cuthillMckeeOrdering(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+  );
+/* -- q2 */
+
+
+
+-- added to pgtap test
+
+
+CREATE TABLE expected_result (
+  seq BIGINT,
+  node BIGINT);
+
+INSERT INTO expected_result (seq, node) VALUES
+(1, 13),
+(2, 14),
+(3, 2),
+(4, 4),
+(5, 9),
+(6, 1),
+(7, 8),
+(8, 3),
+(9, 12),
+(10, 7),
+(11, 5),
+(12, 17),
+(13, 11),
+(14, 6),
+(15, 16),
+(16, 10),
+(17, 15);