[GSoC-2021] Experimental Function - pgr_edgeColoring

doc/coloring/CMakeLists.txt

@@ -3,6 +3,7 @@ SET(LOCAL_FILES
     coloring-family.rst
     pgr_sequentialVertexColoring.rst
     pgr_bipartite.rst
+    pgr_edgeColoring.rst
     )
 
 foreach (f ${LOCAL_FILES})

doc/coloring/coloring-family.rst

@@ -25,6 +25,7 @@ Coloring - Family of functions (Experimental)
 
 * :doc:`pgr_sequentialVertexColoring` - Vertex coloring algorithm using greedy approach.
 * :doc:`pgr_bipartite` - Bipartite graph algorithm using a DFS-based coloring approach.
+* :doc:`pgr_edgeColoring` - Edge Coloring algorithm using Vizing's theorem.
 
 .. index to here
 
@@ -34,6 +35,7 @@ Coloring - Family of functions (Experimental)
 
     pgr_sequentialVertexColoring
     pgr_bipartite
+    pgr_edgeColoring
 
 
 Parameters
@@ -79,6 +81,24 @@ Column           Type        Description
 
 .. result columns end
 
+.. result columns start edgeColoring
+
+Returns SET OF ``(edge_id, color_id)``
+
+===============  =========== ====================================================
+Column           Type        Description
+===============  =========== ====================================================
+**edge_id**      ``BIGINT``  Identifier of the edge.
+**color_id**     ``BIGINT``  Identifier of the color of the edge.
+
+                             - The minimum value of color is 1.
+
+===============  =========== ====================================================
+
+.. result columns end edgeColoring
+
+
+
 
 See Also
 -------------------------------------------------------------------------------
@@ -94,6 +114,12 @@ See Also
     :end-before: see also end
 
 
+
+.. include:: pgr_edgeColoring.rst
+    :start-after: see also start
+    :end-before: see also end
+
+
 .. rubric:: Indices and tables
 
 * :ref:`genindex`

doc/coloring/pgr_edgeColoring.rst

@@ -0,0 +1,121 @@
+..
+   ****************************************************************************
+    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/pgr_edgeColoring.html>`__
+  (`3.3 <https://docs.pgrouting.org/3.3/en/pgr_edgeColoring.html>`__)
+
+pgr_edgeColoring - Experimental
+===============================================================================
+
+``pgr_edgeColoring`` — Returns the edge coloring of an undirected and loop-free (i.e *no self-loops and no parallel edges*) graph.
+
+.. figure:: images/boost-inside.jpeg
+   :target: https://www.boost.org/libs/graph/doc/edge_coloring.html
+
+   Boost Graph Inside
+
+.. include:: experimental.rst
+   :start-after: begin-warn-expr
+   :end-before: end-warn-exp
+
+.. rubric:: Availability
+
+* Version 3.3.0
+
+  * New **experimental** function
+
+
+Description
+-------------------------------------------------------------------------------
+
+Edge Coloring is an algorithm used for coloring of the edges for the vertices in the graph. It
+is an assignment of colors to the edges of the graph so that no two adjacent edges have the same
+color.
+
+**The main Characteristics are:**
+
+- The implementation is applicable only for **undirected** and **loop-free** (i.e *no self-loops and no parallel edges*) graphs.
+- Provides the color to be assigned to all the edges present in the graph.
+- At most **Δ + 1** colors are used, where **Δ** is the degree of the graph. This is optimal for some graphs, and by Vizing's theorem it uses at most one color more than the optimal for all others.
+- It can tell us whether a graph is **Bipartite**. If in a graph, the chromatic number **χ′(G)** i.e. minimum number of colors needed for proper edge coloring of graph is equal to degree **Δ** of the graph, (i.e. **χ′(G) = Δ**) then graph is said to be Bipartite. But, the vice-versa is not always true.
+- The algorithm tries to assign the least possible color to every edge.
+- Efficient graph coloring is an NP-Hard problem, and therefore, this algorithm
+  does not always produce optimal coloring.
+- The returned rows are ordered in ascending order of the edge value.
+- This algorithm is the fastest known almost-optimal algorithm for edge coloring.
+- Edge Coloring Running Time: :math:`O(|E||V|)`
+
+  - where :math:`|E|` is the number of edges in the graph,
+  - :math:`|V|` is the number of vertices in the graph.
+
+Signatures
+------------------------------------------------------------------------------
+
+.. code-block:: sql
+
+    pgr_edgeColoring(Edges SQL) -- Experimental on v3.3
+
+    RETURNS SET OF (edge_id, color_id)
+    OR EMPTY SET
+
+:Example: Graph coloring of pgRouting :doc:`sampledata`
+
+.. literalinclude:: doc-edgeColoring.queries
+   :start-after: -- q1
+   :end-before: -- q2
+
+.. index::
+    single: edgeColoring -- Experimental on v3.3
+
+.. Parameters, Inner query & result columns
+
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: coloring-family.rst
+    :start-after: parameters start
+    :end-before: parameters end
+
+Inner query
+-------------------------------------------------------------------------------
+
+:Edges SQL: an SQL query of an **undirected** graph, which should return
+            a set of rows with the following columns:
+
+.. include:: traversal-family.rst
+   :start-after: edges_sql_start
+   :end-before: edges_sql_end
+
+Result Columns
+-------------------------------------------------------------------------------
+
+.. include:: coloring-family.rst
+    :start-after: result columns start edgeColoring
+    :end-before: result columns end edgeColoring
+
+
+See Also
+-------------------------------------------------------------------------------
+
+* The queries use the :doc:`sampledata` network.
+
+.. see also start
+
+* `Boost: Edge Coloring Algorithm documentation <https://www.boost.org/libs/graph/doc/edge_coloring.html>`__
+* `Wikipedia: Graph Coloring <https://en.wikipedia.org/wiki/Graph_coloring>`__
+
+.. see also end
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/conf.py.in

@@ -340,6 +340,8 @@ linkcheck_ignore = [
     'https://docs.pgrouting.org/latest/en/traversal-family.html',
     'https://docs.pgrouting.org/latest/en/pgr_withPointsVia.html',
     'https://docs.pgrouting.org/latest/en/withPoints.html',
+    'https://docs.pgrouting.org/3.3/en/pgr_edgeColoring.html',
+    'https://docs.pgrouting.org/latest/en/pgr_edgeColoring.html',
 
 
 

docqueries/coloring/CMakeLists.txt

@@ -2,6 +2,7 @@
 SET(LOCAL_FILES
     doc-pgr_sequentialVertexColoring
     doc-bipartite
+    doc-edgeColoring
     )
 
 foreach (f ${LOCAL_FILES})

docqueries/coloring/doc-edgeColoring.result

@@ -0,0 +1,34 @@
+BEGIN;
+BEGIN
+SET client_min_messages TO NOTICE;
+SET
+-- q1
+SELECT * FROM pgr_edgeColoring(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table
+    ORDER BY id'
+);
+ edge_id | color_id
+---------+----------
+       1 |        3
+       2 |        2
+       3 |        3
+       4 |        4
+       5 |        4
+       6 |        1
+       7 |        2
+       8 |        1
+       9 |        2
+      10 |        5
+      11 |        5
+      12 |        3
+      13 |        2
+      14 |        1
+      15 |        3
+      16 |        1
+      17 |        1
+      18 |        1
+(18 rows)
+
+-- q2
+ROLLBACK;
+ROLLBACK

docqueries/coloring/doc-edgeColoring.test.sql

@@ -0,0 +1,6 @@
+\echo -- q1
+SELECT * FROM pgr_edgeColoring(
+    'SELECT id, source, target, cost, reverse_cost FROM edge_table
+    ORDER BY id'
+);
+\echo -- q2

docqueries/coloring/test.conf

@@ -7,10 +7,12 @@
         'tests' => [qw(
             doc-pgr_sequentialVertexColoring
             doc-bipartite
+            doc-edgeColoring
             )],
         'documentation' => [qw(
             doc-pgr_sequentialVertexColoring
             doc-bipartite
+            doc-edgeColoring
             )]
     },
 

include/coloring/pgr_edgeColoring.hpp

@@ -0,0 +1,82 @@
+/*PGR-GNU*****************************************************************
+File: pgr_edgeColoring.hpp
+
+Generated with Template by:
+Copyright (c) 2021 pgRouting developers
+Mail: project@pgrouting.org
+
+Function's developer:
+Copyright (c) 2021 Veenit Kumar
+Mail: 123sveenit@gmail.com
+------
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+********************************************************************PGR-GNU*/
+
+#ifndef INCLUDE_COLORING_PGR_EDGECOLORING_HPP_
+#define INCLUDE_COLORING_PGR_EDGECOLORING_HPP_
+#pragma once
+
+#include <boost/config.hpp>
+#include <boost/graph/adjacency_list.hpp>
+
+#include <iostream>
+#include <map>
+#include <vector>
+
+#include "c_types/edge_t.h"
+#include "c_types/pgr_vertex_color_rt.h"
+#include "cpp_common/pgr_assert.h"
+#include "cpp_common/pgr_messages.h"
+
+namespace pgrouting {
+namespace functions {
+
+class Pgr_edgeColoring : public Pgr_messages {
+ public:
+    using EdgeColoring_Graph =
+        boost::adjacency_list<boost::vecS, boost::vecS, boost::undirectedS, boost::no_property,
+        size_t, boost::no_property>;
+
+    using V       = boost::graph_traits<EdgeColoring_Graph>::vertex_descriptor;
+    using E       = boost::graph_traits<EdgeColoring_Graph>::edge_descriptor;
+    using V_it    = boost::graph_traits<EdgeColoring_Graph>::vertex_iterator;
+    using E_it    = boost::graph_traits<EdgeColoring_Graph>::edge_iterator;
+
+ public:
+    std::vector<pgr_vertex_color_rt> edgeColoring();
+
+    Pgr_edgeColoring(Edge_t*, size_t);
+    Pgr_edgeColoring() = delete;
+
+#if Boost_VERSION_MACRO >= 106800
+    friend std::ostream& operator<<(std::ostream &, const Pgr_edgeColoring&);
+#endif
+
+ private:
+    V get_boost_vertex(int64_t id) const;
+    int64_t get_vertex_id(V v) const;
+    int64_t get_edge_id(E e) const;
+
+
+ private:
+    EdgeColoring_Graph graph;
+    std::map<int64_t, V> id_to_V;
+    std::map<V, int64_t> V_to_id;
+    std::map<E, int64_t> E_to_id;
+};
+
+}  // namespace functions
+}  // namespace pgrouting
+
+#endif  // INCLUDE_COLORING_PGR_EDGECOLORING_HPP_