Add Misra-Gries edge coloring method (#902)

* initial implementation * cleanup * cleanup * changing to struct * cleanup * cleanup * cleanup * cleanup * cleanup * cleanup * a few comments from code review * switching to filter_map * suggestion from code review * minor * performance improvements * moving to rustworkx-core * moving checking function under test * improved tests * docs example * minor * removing unused use from testing * more unused * python tests and wrapper function * removing unused imports * release notes and docs fixes * merge fixes * switching from EdgeId to EdgeRef * aux functions to set/get edge color * cleanup * minor * cleanup signature of fan to only store edge reference * no need to explicitly specify type * api docs --------- Co-authored-by: Matthew Treinish <[email protected]>
Qiskit · Jan 10, 2024 · 6d82a11 · 6d82a11
1 parent 75dbca9
commit 6d82a11
Show file tree

Hide file tree

Showing 8 changed files with 533 additions and 10 deletions.
diff --git a/docs/source/api/algorithm_functions/coloring.rst b/docs/source/api/algorithm_functions/coloring.rst
@@ -0,0 +1,11 @@
+.. _coloring:
+
+Coloring
+========
+
+.. autosummary::
+   :toctree: ../../apiref
+
+   rustworkx.graph_greedy_color
+   rustworkx.graph_greedy_edge_color
+   rustworkx.graph_misra_gries_edge_color
diff --git a/docs/source/api/algorithm_functions/index.rst b/docs/source/api/algorithm_functions/index.rst
@@ -7,6 +7,7 @@ Algorithm Functions
    :maxdepth: 2
 
    centrality
+   coloring
    connectivity_and_cycles
    dag_algorithms
    graph_operations

diff --git a/docs/source/api/algorithm_functions/other.rst b/docs/source/api/algorithm_functions/other.rst
@@ -9,8 +9,6 @@ Other Algorithm Functions
    rustworkx.adjacency_matrix
    rustworkx.transitivity
    rustworkx.core_number
-   rustworkx.graph_greedy_color
-   rustworkx.graph_greedy_edge_color
    rustworkx.graph_line_graph
    rustworkx.metric_closure
    rustworkx.is_planar
diff --git a/releasenotes/notes/add-graph-misra-gries-edge-color-e55a27de2b667db1.yaml b/releasenotes/notes/add-graph-misra-gries-edge-color-e55a27de2b667db1.yaml
@@ -0,0 +1,20 @@
+---
+features:
+  - |
+    Added a new function, :func:`~.graph_misra_gries_edge_color` to color edges
+    of a :class:`~.PyGraph` object using the Misra-Gries edge coloring algorithm.
+    
+    The above algorithm is described in the paper paper: "A constructive proof of 
+    Vizing's theorem" by Misra and Gries, 1992.
+    
+    The coloring produces at most d + 1 colors where d is the maximum degree
+    of the graph.
+    
+    .. jupyter-execute::
+    
+        import rustworkx as rx
+    
+        graph = rx.generators.cycle_graph(7)
+        edge_colors = rx.graph_misra_gries_edge_color(graph)
+        assert edge_colors == {0: 0, 1: 1, 2: 2, 3: 0, 4: 1, 5: 0, 6: 2}
+