Experimental Function - kingOrdering

NEWS.md

@@ -138,6 +138,15 @@ Summary of changes by function
 * pgr_edwardMoore
 
   * Output columns standardized to ``(seq, path_seq, start_vid, end_vid, node, edge, cost, agg_cost)``
+  .. rubric:: Version 3.2.0
+  * New experimental signature:
+    * pgr_edwardMoore(Combinations)
+  .. rubric:: Version 3.0.0
+  * New experimental function.
+
+* pgr_kingOrdering
+
+    * New experimental function.
 
 * pgr_KSP
 
@@ -298,6 +307,10 @@ New experimental functions
 
   * [#2951](https://github.com/pgRouting/pgrouting/issues/2951): pgr_bandwidth
 
+* Ordering
+
+  * [#2954](https://github.com/pgRouting/pgrouting/issues/2954): pgr_kingOrdering
+
 SQL signatures and output standardization
 
 [#2904](https://github.com/pgRouting/pgrouting/issues/2904): Standardize output columns of functions with different output

doc/_static/page_history.js

@@ -15,7 +15,8 @@ var titles = [
 
 
 var newpages = [
-    {v: '4.0', pages: ['pgr_bandwidth']},
+    {v: '4.0', pages: ['pgr_bandwidth', 'pgr_kingOrdering']},
+
     {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing',
         'pgr_separateTouching']},
 

doc/ordering/CMakeLists.txt

@@ -2,6 +2,7 @@ SET(LOCAL_FILES
     ordering-family.rst
     pgr_cuthillMckeeOrdering.rst
     pgr_topologicalSort.rst
+    pgr_kingOrdering.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/ordering/ordering-family.rst

@@ -24,6 +24,8 @@ Ordering - Family of functions
 * :doc:`pgr_cuthillMckeeOrdering` - Return reverse Cuthill-McKee ordering of an undirected graph.
 * :doc:`pgr_topologicalSort` - Linear ordering of the vertices for directed
   acyclic graph.
+* :doc:`pgr_kingOrdering` - Returns the King ordering of an undirected graphs
+  acyclic graph.
 
 .. official-end
 
@@ -32,6 +34,7 @@ Ordering - Family of functions
 
     pgr_cuthillMckeeOrdering
     pgr_topologicalSort
+    pgr_kingOrdering
 
 See Also
 -------------------------------------------------------------------------------

doc/ordering/pgr_cuthillMckeeOrdering.rst

@@ -94,6 +94,8 @@ Edges SQL
 Result columns
 -------------------------------------------------------------------------------
 
+.. node_ordering_start
+
 Returns set of ``(seq, node)``
 
 ===============  =========== ======================================
@@ -103,6 +105,8 @@ Column           Type        Description
 ``node``          ``BIGINT``  New ordering in reverse order.
 ===============  =========== ======================================
 
+.. node_ordering_end
+
 See Also
 -------------------------------------------------------------------------------
 

doc/ordering/pgr_kingOrdering.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/
+   ****************************************************************************
+
+.. index::
+   single: Ordering Family ; pgr_kingOrdering
+   single: kingOrdering - Experimental on v4.0
+
+|
+
+``pgr_kingOrdering`` - Experimental
+===============================================================================
+
+``pgr_kingOrdering`` — Returns the King ordering of an undirected graphs
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. rubric:: Version 4.0.0
+
+  * New experimental function.
+
+Description
+-------------------------------------------------------------------------------
+
+In numerical linear algebra and graph theory, the King ordering algorithm
+is a heuristic designed to reorder the vertices of a graph so as to reduce
+its bandwidth. 
+
+The method follows a breadth-first search (BFS) traversal,but with a refinement:
+at each step, the unvisited neighbors of the current vertex are inserted into
+the queue in ascending order of their pseudo-degree, where the pseudo-degree of
+a vertex is the number of edges connecting it to yet-unvisited vertices. This
+prioritization often yields a smaller bandwidth compared to simpler BFS orderings.
+
+**The main characteristics are:**
+
+- The implementation targets undirected graphs.
+- Bandwidth minimization is an NP-complete problem; King ordering provides a practical local minimization approach.
+- The time complexity is: :math:`O(m^2 \log(m)|E|)`
+
+   - where :math:`|E|` is the number of edges,
+   - :math:`m` is the maximum degree among all vertices.
+
+|Boost| Boost Graph Inside
+
+Signatures
+------------------------------------------------------------------------------
+
+.. index::
+    single: kingOrdering - Experimental on v4.0
+
+.. admonition:: \ \
+   :class: signatures
+
+   | pgr_kingOrdering(`Edges SQL`_)
+
+   | Returns set of |result_node_order|
+   | OR EMPTY SET
+
+:Example: Graph ordering of pgRouting :doc:`sampledata`
+
+.. literalinclude:: kingOrdering.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+   :start-after: only_edge_param_start
+   :end-before: only_edge_param_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+   :start-after: basic_edges_sql_start
+   :end-before: basic_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+.. include:: pgr_cuthillMckeeOrdering.rst
+   :start-after: node_ordering_start
+   :end-before: node_ordering_end
+
+Additional Examples
+-------------------------------------------------------------------------------
+
+.. graphviz::
+
+   graph G {
+    node [shape=circle, style=filled, fillcolor=white, color=black, fontcolor=black, fontsize=10];
+    edge [color=black, penwidth=1];
+
+    4 -- 7;
+    7 -- 9;
+    7 -- 0;
+    0 -- 2;
+    2 -- 5;
+    5 -- 9;
+    9 -- 8;
+    9 -- 1;
+    5 -- 1;
+    9 -- 6;
+    6 -- 3;
+    1 -- 3;
+
+    {rank=same; 4; 8; 6;}
+    {rank=same; 7; 9; 3;}
+    {rank=same; 0; 2; 5; 1;}
+  }
+
+.. literalinclude:: kingOrdering.queries
+   :start-after: -- q2
+   :end-before: -- q3
+
+See Also
+-------------------------------------------------------------------------------
+
+* :doc:`sampledata`
+* `Boost: King Ordering
+  <https://www.boost.org/libs/graph/doc/king_ordering.html>`__
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`
+

doc/src/pgRouting-introduction.rst

@@ -66,6 +66,7 @@ This Release Contributors
 Individuals in this release v4.0.0 (in alphabetical order)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Fan Wu
 Regina Obe,
 Saloni kumari,
 Vicky Vergara
@@ -119,6 +120,7 @@ David Techer,
 Denis Rykov,
 Ema Miyawaki,
 Esteban Zimanyi,
+Fan Wu,
 Florian Thurkow,
 Frederic Junod,
 Gerald Fenoy,

doc/src/release_notes.rst

@@ -212,7 +212,13 @@ Summary of changes by function
 
   .. include:: pgr_edwardMoore.rst
      :start-after: Version 4.0.0
-     :end-before: .. rubric
+     :end-before: Description
+
+* pgr_kingOrdering
+
+  .. include:: pgr_kingOrdering.rst
+     :start-after: Version 4.0.0
+     :end-before: Description
 
 * pgr_KSP
 
@@ -354,6 +360,10 @@ New experimental functions
 
   * :issue:`2951`: pgr_bandwidth
 
+* Ordering
+
+  * :issue:`2954`: pgr_kingOrdering
+
 SQL signatures and output standardization
 ...............................................................................
 

docqueries/ordering/CMakeLists.txt

@@ -2,6 +2,7 @@
 SET(LOCAL_FILES
     cuthillMckeeOrdering
     topologicalSort
+    kingOrdering
     )
 
 foreach (f ${LOCAL_FILES})

docqueries/ordering/kingOrdering.pg

@@ -0,0 +1,47 @@
+-- CopyRight(c) pgRouting developers
+-- Creative Commons Attribution-Share Alike 3.0 License : https://creativecommons.org/licenses/by-sa/3.0/
+/* -- q1 */
+SELECT * FROM pgr_kingOrdering(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+  );
+
+/* -- q2 */
+CREATE TABLE additional_sample_1(
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+
+INSERT INTO additional_sample_1 (source, target, cost, reverse_cost) VALUES
+(4, 7, 1, 1),
+(7, 4, 1, 1),
+(7, 9, 1, 1),
+(9, 7, 1, 1),
+(7, 0, 1, 1),
+(0, 7, 1, 1),
+(0, 2, 1, 1),
+(2, 0, 1, 1),
+(2, 5, 1, 1),
+(5, 2, 1, 1),
+(5, 9, 1, 1),
+(9, 5, 1, 1),
+(9, 8, 1, 1),
+(8, 9, 1, 1),
+(9, 1, 1, 1),
+(1, 9, 1, 1),
+(5, 1, 1, 1),
+(1, 5, 1, 1),
+(9, 6, 1, 1),
+(6, 9, 1, 1),
+(6, 3, 1, 1),
+(3, 6, 1, 1),
+(1, 3, 1, 1),
+(3, 1, 1, 1);
+
+SELECT * FROM pgr_kingOrdering(
+    'SELECT id, source, target, cost, reverse_cost FROM additional_sample_1'
+);
+
+/* -- q3 */