New Function pgr_bandwidth()

NEWS.md

@@ -60,6 +60,10 @@ Summary of changes by function
 
   * Combinations signature promoted to official.
 
+* pgr_bandwidth
+
+  * New experimental function.
+
 * pgr_bdAstar
 
   * Combinations signature promoted to official.
@@ -288,6 +292,12 @@ Signatures promoted to official
 * [#2718](https://github.com/pgRouting/pgrouting/issues/2718): pgr_maxFlow(Combinations)
 * [#2718](https://github.com/pgRouting/pgrouting/issues/2718): pgr_pushRelabel(Combinations)
 
+New experimental functions
+
+* Metrics
+
+  * [#2951](https://github.com/pgRouting/pgrouting/issues/2951): pgr_bandwidth
+
 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,6 +15,7 @@ var titles = [
 
 
 var newpages = [
+    {v: '4.0', pages: ['pgr_bandwidth']},
     {v: '3.8', pages: ['pgr_contractionDeadEnd', 'pgr_contractionLinear', 'pgr_separateCrossing',
         'pgr_separateTouching']},
 

doc/metrics/CMakeLists.txt

@@ -3,6 +3,7 @@ SET(LOCAL_FILES
     metrics-family.rst
     pgr_betweennessCentrality.rst
     pgr_degree.rst
+    pgr_bandwidth.rst
    )
 
 foreach (f ${LOCAL_FILES})

doc/metrics/metrics-family.rst

@@ -31,13 +31,16 @@ Metrics - Family of functions
 * :doc:`pgr_betweennessCentrality` - Calculates relative betweenness centrality
   using Brandes Algorithm
 
+* :doc:`pgr_bandwidth` - Computes the bandwidth of a graph.
+
 .. experimental-end
 
 .. toctree::
     :hidden:
 
     pgr_degree
     pgr_betweennessCentrality
+    pgr_bandwidth
 
 See Also
 -------------------------------------------------------------------------------

doc/metrics/pgr_bandwidth.rst

@@ -0,0 +1,163 @@
+..
+   ****************************************************************************
+    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/
+   ****************************************************************************
+
+.. index::
+   single: Metrics Family ; pgr_bandwidth - Experimental
+   single: bandwidth - Experimental on v4.0
+
+|
+
+``pgr_bandwidth`` - Experimental
+===============================================================================
+
+``pgr_bandwidth`` - Calculates the bandwidth of the graph
+
+.. include:: experimental.rst
+   :start-after: warning-begin
+   :end-before: end-warning
+
+.. rubric:: Availability
+
+.. rubic:: Version 4.0.0
+
+* New experimental function.
+
+Description
+-------------------------------------------------------------------------------
+
+Bandwidth measures how "spread out" the connections are in a graph when vertices are arranged in a linear order (like numbering them 1, 2, 3, etc.).
+
+* For each edge in the graph, calculate the distance between the vertex numbers it connects
+* The bandwidth is the maximum of all these distances
+* The implementation is for undirected graphs
+* Run time is 0.160789 seconds
+
+|Boost| Boost Graph Inside
+
+Signatures
+-------------------------------------------------------------------------------
+
+.. rubric:: Summary
+
+.. admonition:: \ \
+   :class: signatures
+
+   pgr_bandwidth(`Edges SQL`_)
+
+   | Returns ``BIGINT``
+
+:Example: For an undirected graph with edges.
+
+.. literalinclude:: bandwidth.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+    :start-after: edges_start
+    :end-before: edges_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: basic_edges_sql_start
+    :end-before: basic_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+Returns a bigint ``(pgr_bandwidth)``
+
+=================  =========== ==========================================
+Column             Type        Description
+=================  =========== ==========================================
+``pgr_bandwidth``   ``BIGINT`` gives the bandwidth of the graph.
+=================  =========== ==========================================
+
+Additional Examples
+-------------------------------------------------------------------------------
+
+:Example: Undirected graph with edges before optimization.
+
+.. 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:: bandwidth.queries
+   :start-after: -- q2
+   :end-before: -- q5
+
+:Example: Undirected graph with edges after optimization.
+
+.. graphviz::
+
+   graph G {
+    node [shape=circle, style=filled, fillcolor=white, color=black, fontcolor=black, fontsize=12];
+    edge [color=black, penwidth=1];
+
+    0 -- 1;
+    1 -- 3;
+    1 -- 2;
+    2 -- 4;
+    4 -- 8;
+    8 -- 3;
+    3 -- 5;
+    3 -- 6;
+    3 -- 7;
+    8 -- 7;
+    6 -- 9;
+    7 -- 9;
+
+    {rank=same; 0; 5; 6;}
+    {rank=same; 1; 3; 9;}
+    {rank=same; 2; 4; 8; 7;}
+
+  }
+
+.. literalinclude:: bandwidth.queries
+   :start-after: -- q5
+   :end-before: -- q8
+
+See Also
+-------------------------------------------------------------------------------
+
+* :doc:`sampledata`
+* `Boost: bandwidth
+  <https://www.boost.org/libs/graph/doc/bandwidth.html>`_
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/src/pgRouting-introduction.rst

@@ -67,6 +67,7 @@ Individuals in this release v4.0.0 (in alphabetical order)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Regina Obe,
+Saloni kumari,
 Vicky Vergara
 
 
@@ -144,6 +145,7 @@ Rajat Shinde,
 Razequl Islam,
 Regina Obe,
 Rohith Reddy,
+Saloni Kumari,
 Sarthak Agarwal,
 Shobhit Chaurasia,
 Sourabh Garg,

doc/src/release_notes.rst

@@ -100,6 +100,12 @@ Summary of changes by function
      :start-after: Version 4.0.0
      :end-before: .. rubric
 
+* pgr_bandwidth
+
+  .. include:: pgr_bandwidth.rst
+     :start-after: Version 4.0.0
+     :end-before: Description
+
 * pgr_bdAstar
 
   .. include:: pgr_bdAstar.rst
@@ -341,6 +347,13 @@ Signatures promoted to official
 * :issue:`2718`: pgr_maxFlow(Combinations)
 * :issue:`2718`: pgr_pushRelabel(Combinations)
 
+New experimental functions
+...............................................................................
+
+* Metrics
+
+  * :issue:`2951`: pgr_bandwidth
+
 SQL signatures and output standardization
 ...............................................................................
 

docqueries/metrics/CMakeLists.txt

@@ -1,5 +1,6 @@
 # Do not use extensions
 SET(LOCAL_FILES
+    bandwidth
     betweennessCentrality
     degree
     )

docqueries/metrics/bandwidth.pg

@@ -0,0 +1,88 @@
+-- CopyRight(c) pgRouting developers
+-- Creative Commons Attribution-Share Alike 3.0 License : https://creativecommons.org/licenses/by-sa/3.0/
+
+/* -- q1 */
+SELECT * FROM pgr_bandwidth(
+'SELECT id, source, target, cost, reverse_cost
+FROM edges'
+);
+
+/* -- q2 */
+CREATE TABLE my_edges1 (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+/* -- q3 */
+INSERT INTO my_edges1 (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);
+/* -- q4 */
+SELECT * FROM pgr_bandwidth(
+    'SELECT id, source, target, cost, reverse_cost FROM my_edges1'
+);
+
+/* -- q5 */
+CREATE TABLE my_edges2 (
+    id SERIAL PRIMARY KEY,
+    source INTEGER,
+    target INTEGER,
+    cost DOUBLE PRECISION,
+    reverse_cost DOUBLE PRECISION
+);
+/* -- q6 */
+INSERT INTO my_edges2 (source, target, cost, reverse_cost) VALUES
+(0, 1, 1, 1),
+(1, 0, 1, 1),
+(1, 3, 1, 1),
+(3, 1, 1, 1),
+(1, 2, 1, 1),
+(2, 1, 1, 1),
+(2, 4, 1, 1),
+(4, 2, 1, 1),
+(4, 8, 1, 1),
+(8, 4, 1, 1),
+(8, 3, 1, 1),
+(3, 8, 1, 1),
+(3, 5, 1, 1),
+(5, 3, 1, 1),
+(3, 6, 1, 1),
+(6, 3, 1, 1),
+(3, 7, 1, 1),
+(7, 3, 1, 1),
+(8, 7, 1, 1),
+(7, 8, 1, 1),
+(6, 9, 1, 1),
+(9, 6, 1, 1),
+(7, 9, 1, 1),
+(9, 7, 1, 1);
+/* -- q7 */
+SELECT * FROM pgr_bandwidth(
+    'SELECT id, source, target, cost, reverse_cost FROM my_edges2'
+);
+
+/* -- q8 */