GSoC 2022: Shobhit Chaurasia Week 5

configuration.conf

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

doc/ordering/CMakeLists.txt

@@ -1,5 +1,5 @@
 SET(LOCAL_FILES
-    pgr_cuthillMckeeOrdering.rst
+    cuthillMckeeOrdering.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/ordering/cuthillMckeeOrdering.rst

@@ -0,0 +1,139 @@
+..
+   ****************************************************************************
+    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 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:
+
+    * ``cuthillMckeeOrdering`` (`Cuthill-Mckee Ordering`_)
+
+
+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.
+
+**The main Characteristics are:**
+
+- The implementation is for **undirected** graphs.
+- The running time complexity is: :math: `O(m log(m)|V|)` where m = max{degree(v)|v in V}.
+
+Signatures
+------------------------------------------------------------------------------
+
+.. index::
+    single: cuthillMckeeOrdering - Experimental on v3.4
+
+.. parsed-literal::
+
+    cuthillMckeeOrdering(`Edges SQL`_, **start vid**)
+
+    RETURNS SET OF (seq, ordering)
+    OR EMPTY SET
+
+:Example:
+
+.. literalinclude:: cuthillMckeeOrdering.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+.. Parameters, Inner Queries & result columns
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+   :start-after: basic_edges_sql_start
+   :end-before: basic_edges_sql_end
+
+
+Optional parameters
+-------------------------------------------------------------------------------
+TBD
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+   :start-after: basic_edges_sql_start
+   :end-before: basic_edges_sql_end   
+
+Return columns
+-------------------------------------------------------------------------------
+
+.. list-table::
+   :width: 81
+   :widths: auto
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Description
+   * - ``seq``
+     - ``BIGINT``
+     - Sequential value starting from ``1``
+   * - ``ordering``
+     - ``BIGINT``
+     - Reverse Cuthill-McKee Ordering.
+
+See Also
+-------------------------------------------------------------------------------
+
+* The queries use the :doc:`sampledata` network.
+
+.. see also start
+
+* `Boost: Cuthill-McKee Ordering Algorithm documentation
+  <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/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 experimental from here
+   :end-before: index experimental to here
+
 :doc:`TRSP-family`
 
 .. include:: TRSP-family.rst

docqueries/ordering/cuthillMckeeOrdering.result

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

docqueries/ordering/cuthillMckeeOrdering.test.sql

@@ -15,7 +15,7 @@ CREATE TABLE expected_result (
 INSERT INTO expected_result (seq, ordering) VALUES
 (1, 8),
 (2, 3),
-(3, 0),   
+(3, 0), 
 (4, 9),
 (5, 2),
 (6, 5),

include/ordering/cuthillMckeeOrdering.hpp

@@ -83,7 +83,8 @@ class CuthillMckeeOrdering : public Pgr_messages{
       * @see [boost::cuthill_mckee_ordering]
       * (https://www.boost.org/libs/graph/doc/cuthill_mckee_ordering.html)
       */
-    std::vector<II_t_rt>cuthillMckeeOrdering(G & /*graph*/, int64_t) {
+    std::vector<II_t_rt>
+    cuthillMckeeOrdering(G & /*graph*/, int64_t) {
         std::vector<II_t_rt>results;
 
         /* TODO
@@ -97,7 +98,7 @@ class CuthillMckeeOrdering : public Pgr_messages{
          auto i_map = boost::get(boost::vertex_index, graph.graph);
 
          // vector which will store the ordering of the graph
-         std::vector < vertices_size_type > ordering(boost::num_vertices(graph.graph));
+         std::vector<vertices_size_type> ordering(boost::num_vertices(graph.graph));
 
          // An iterator property map which records the ordering 
          auto ordering_map = boost::make_iterator_property_map(ordering.begin(), i_map);

sql/sigs/pgrouting--3.4.sig

@@ -90,6 +90,8 @@ _pgr_createindex(text,text,text,integer,text)
 _pgr_createindex(text,text,text,text,integer,text)
 pgr_createtopology(text,double precision,text,text,text,text,text,boolean)
 pgr_createverticestable(text,text,text,text,text)
+_pgr_cuthillMckeeOrdering(text,bigint)
+pgr_cuthillMckeeOrdering(text,bigint)
 pgr_dagshortestpath(text,anyarray,anyarray)
 _pgr_dagshortestpath(text,anyarray,anyarray,boolean,boolean)
 pgr_dagshortestpath(text,anyarray,bigint)