Add "saturation first" and "independent set" greedy node coloring strategies

docs/source/api/algorithm_functions/coloring.rst

@@ -6,6 +6,7 @@ Coloring
 .. autosummary::
    :toctree: ../../apiref
 
+   rustworkx.ColoringStrategy
    rustworkx.graph_greedy_color
    rustworkx.graph_bipartite_edge_color
    rustworkx.graph_greedy_edge_color

releasenotes/notes/saturation-greedy-color-109d40f189590d3a.yaml

@@ -0,0 +1,59 @@
+---
+features:
+  - Added a new class :class:`~.ColoringStrategy` used to specify the strategy used by 
+    the greedy node and edge coloring algorithms. 
+    The ``Degree`` strategy colors the nodes with higher degree first.
+    The ``Saturation`` strategy dynamically chooses the vertex that has the largest 
+    number of different colors already assigned to its neighbors, and, in case of a tie, 
+    the vertex that has the largest number of uncolored neighbors.
+    The ``IndependentSet`` strategy finds independent subsets of the graph, and assigns 
+    a different color to each of these subsets.
+  - |
+    The rustworkx-core ``coloring`` module has 2 new functions,
+    ``greedy_node_color_with_coloring_strategy`` and
+    ``greedy_edge_color_with_coloring_strategy``.
+    These functions color respectively the nodes or the edges of the graph
+    using the specified coloring strategy and handling the preset colors
+    when provided.
+  - |
+    Added a new keyword argument, ``strategy``, to :func:`.graph_greedy_color`
+    and to :func:`.graph_greedy_edge_color` to specify the greedy coloring strategy.
+
+    For example:
+
+    .. jupyter-execute::
+
+        import rustworkx as rx
+        from rustworkx.visualization import mpl_draw
+
+        graph = rx.generators.generalized_petersen_graph(5, 2)
+
+        coloring = rx.graph_greedy_color(graph, strategy=rx.ColoringStrategy.Saturation)
+        colors = [coloring[node] for node in graph.node_indices()]
+
+        layout = rx.shell_layout(graph, nlist=[[0, 1, 2, 3, 4],[6, 7, 8, 9, 5]])
+        mpl_draw(graph, node_color=colors, pos=layout)
+  - |
+    Added a new keyword argument, ``preset_color_fn``, to :func:`.graph_greedy_edge_color`
+    which is used to provide preset colors for specific edges when computing the graph
+    coloring. You can optionally pass a callable to that argument which will
+    be passed edge index from the graph and is either expected to return an
+    integer color to use for that edge, or `None` to indicate there is no
+    preset color for that edge. For example:
+
+    .. jupyter-execute::
+
+        import rustworkx as rx
+        from rustworkx.visualization import mpl_draw
+
+        graph = rx.generators.generalized_petersen_graph(5, 2)
+
+        def preset_colors(edge_index):
+            if edge_index == 0:
+                return 3
+
+        coloring = rx.graph_greedy_edge_color(graph, preset_color_fn=preset_colors)
+        colors = [coloring[edge] for edge in graph.edge_indices()]
+
+        layout = rx.shell_layout(graph, nlist=[[0, 1, 2, 3, 4], [6, 7, 8, 9, 5]])
+        mpl_draw(graph, edge_color=colors, pos=layout)