nx-cugraph: add relabel_nodes and convert_node_labels_to_integers (#4531)

This was pretty tricky in places! This begins with `Graph` and `DiGraph`, which are probably tricker, because of the way edge data get merged when nodes are combined (and I wouldn't be surprised if there are other ways to do this operation).

This is one of the most heavily used functions in networkx and also networkx dependents.

Up next: multigraphs

Authors:
  - Erik Welch (https://github.com/eriknw)
  - Ralph Liu (https://github.com/nv-rliu)

Approvers:
  - Rick Ratzel (https://github.com/rlratzel)
  - Bradley Dice (https://github.com/bdice)

URL: #4531

Author: eriknw

python/nx-cugraph/.flake8

@@ -1,9 +1,10 @@
-# Copyright (c) 2023, NVIDIA CORPORATION.
+# Copyright (c) 2023-2024, NVIDIA CORPORATION.
 
 [flake8]
 max-line-length = 88
 inline-quotes = "
 extend-ignore =
+    B020,
     E203,
     SIM105,
     SIM401,

python/nx-cugraph/README.md

@@ -267,6 +267,9 @@ Below is the list of algorithms that are currently supported in nx-cugraph.
 <a href="https://networkx.org/documentation/stable/reference/convert.html#module-networkx.convert_matrix">convert_matrix</a>
  ├─ <a href="https://networkx.org/documentation/stable/reference/generated/networkx.convert_matrix.from_pandas_edgelist.html#networkx.convert_matrix.from_pandas_edgelist">from_pandas_edgelist</a>
  └─ <a href="https://networkx.org/documentation/stable/reference/generated/networkx.convert_matrix.from_scipy_sparse_array.html#networkx.convert_matrix.from_scipy_sparse_array">from_scipy_sparse_array</a>
+<a href="https://networkx.org/documentation/stable/reference/relabel.html#module-networkx.relabel">relabel</a>
+ ├─ <a href="https://networkx.org/documentation/stable/reference/generated/networkx.relabel.convert_node_labels_to_integers.html#networkx.relabel.convert_node_labels_to_integers">convert_node_labels_to_integers</a>
+ └─ <a href="https://networkx.org/documentation/stable/reference/generated/networkx.relabel.relabel_nodes.html#networkx.relabel.relabel_nodes">relabel_nodes</a>
 </pre>
 
 To request nx-cugraph backend support for a NetworkX API that is not listed

python/nx-cugraph/_nx_cugraph/__init__.py

@@ -69,6 +69,7 @@
         "complete_graph",
         "complete_multipartite_graph",
         "connected_components",
+        "convert_node_labels_to_integers",
         "core_number",
         "cubical_graph",
         "cycle_graph",
@@ -130,6 +131,7 @@
         "path_graph",
         "petersen_graph",
         "reciprocity",
+        "relabel_nodes",
         "reverse",
         "sedgewick_maze_graph",
         "shortest_path",

python/nx-cugraph/lint.yaml

@@ -50,15 +50,15 @@ repos:
       - id: black
       # - id: black-jupyter
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.1
+    rev: v0.5.4
     hooks:
       - id: ruff
         args: [--fix-only, --show-fixes]  # --unsafe-fixes]
   - repo: https://github.com/PyCQA/flake8
     rev: 7.1.0
     hooks:
       - id: flake8
-        args: ['--per-file-ignores=_nx_cugraph/__init__.py:E501', '--extend-ignore=SIM105']  # Why is this necessary?
+        args: ['--per-file-ignores=_nx_cugraph/__init__.py:E501', '--extend-ignore=B020,SIM105']  # Why is this necessary?
         additional_dependencies: &flake8_dependencies
           # These versions need updated manually
           - flake8==7.1.0
@@ -77,7 +77,7 @@ repos:
         additional_dependencies: [tomli]
         files: ^(nx_cugraph|docs)/
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.1
+    rev: v0.5.4
     hooks:
       - id: ruff
   - repo: https://github.com/pre-commit/pre-commit-hooks

python/nx-cugraph/nx_cugraph/__init__.py

@@ -23,6 +23,9 @@
 from . import convert_matrix
 from .convert_matrix import *
 
+from . import relabel
+from .relabel import *
+
 from . import generators
 from .generators import *
 

python/nx-cugraph/nx_cugraph/algorithms/operators/unary.py

@@ -51,5 +51,10 @@ def reverse(G, copy=True):
     if not G.is_directed():
         raise nx.NetworkXError("Cannot reverse an undirected graph.")
     if isinstance(G, nx.Graph):
+        if not copy:
+            raise RuntimeError(
+                "Using `copy=False` is invalid when using a NetworkX graph "
+                "as input to `nx_cugraph.reverse`"
+            )
         G = nxcg.from_networkx(G, preserve_all_attrs=True)
     return G.reverse(copy=copy)

python/nx-cugraph/nx_cugraph/algorithms/traversal/breadth_first_search.py

@@ -57,23 +57,41 @@ def _bfs(G, source, *, depth_limit=None, reverse=False):
     return distances[mask], predecessors[mask], node_ids[mask]
 
 
-@networkx_algorithm(is_incomplete=True, version_added="24.02", _plc="bfs")
-def generic_bfs_edges(G, source, neighbors=None, depth_limit=None, sort_neighbors=None):
-    """`neighbors` and `sort_neighbors` parameters are not yet supported."""
-    if neighbors is not None:
-        raise NotImplementedError(
-            "neighbors argument in generic_bfs_edges is not currently supported"
-        )
-    if sort_neighbors is not None:
-        raise NotImplementedError(
-            "sort_neighbors argument in generic_bfs_edges is not currently supported"
-        )
-    return bfs_edges(G, source, depth_limit=depth_limit)
-
-
-@generic_bfs_edges._can_run
-def _(G, source, neighbors=None, depth_limit=None, sort_neighbors=None):
-    return neighbors is None and sort_neighbors is None
+if nx.__version__[:3] <= "3.3":
+
+    @networkx_algorithm(is_incomplete=True, version_added="24.02", _plc="bfs")
+    def generic_bfs_edges(
+        G, source, neighbors=None, depth_limit=None, sort_neighbors=None
+    ):
+        """`neighbors` and `sort_neighbors` parameters are not yet supported."""
+        if neighbors is not None:
+            raise NotImplementedError(
+                "neighbors argument in generic_bfs_edges is not currently supported"
+            )
+        if sort_neighbors is not None:
+            raise NotImplementedError(
+                "sort_neighbors argument in generic_bfs_edges is not supported"
+            )
+        return bfs_edges(G, source, depth_limit=depth_limit)
+
+    @generic_bfs_edges._can_run
+    def _(G, source, neighbors=None, depth_limit=None, sort_neighbors=None):
+        return neighbors is None and sort_neighbors is None
+
+else:
+
+    @networkx_algorithm(is_incomplete=True, version_added="24.02", _plc="bfs")
+    def generic_bfs_edges(G, source, neighbors=None, depth_limit=None):
+        """`neighbors` parameter is not yet supported."""
+        if neighbors is not None:
+            raise NotImplementedError(
+                "neighbors argument in generic_bfs_edges is not currently supported"
+            )
+        return bfs_edges(G, source, depth_limit=depth_limit)
+
+    @generic_bfs_edges._can_run
+    def _(G, source, neighbors=None, depth_limit=None):
+        return neighbors is None
 
 
 @networkx_algorithm(is_incomplete=True, version_added="24.02", _plc="bfs")

python/nx-cugraph/nx_cugraph/convert.py

@@ -411,13 +411,21 @@ def func(it, edge_attr=edge_attr, dtype=dtype):
                 # Node values may be numpy or cupy arrays (useful for str, object, etc).
                 # Someday we'll let the user choose np or cp, and support edge values.
                 node_mask = np.fromiter(iter_mask, bool)
-                node_value = np.array(vals, dtype)
                 try:
-                    node_value = cp.array(node_value)
+                    node_value = np.array(vals, dtype)
                 except ValueError:
-                    pass
+                    # Handle e.g. list elements
+                    if dtype is None or dtype == object:
+                        node_value = np.fromiter(vals, object)
+                    else:
+                        raise
                 else:
-                    node_mask = cp.array(node_mask)
+                    try:
+                        node_value = cp.array(node_value)
+                    except ValueError:
+                        pass
+                    else:
+                        node_mask = cp.array(node_mask)
                 node_values[node_attr] = node_value
                 node_masks[node_attr] = node_mask
                 # if vals.ndim > 1: ...
@@ -431,7 +439,12 @@ def func(it, edge_attr=edge_attr, dtype=dtype):
                 # Node values may be numpy or cupy arrays (useful for str, object, etc).
                 # Someday we'll let the user choose np or cp, and support edge values.
                 if dtype is None:
-                    node_value = np.array(list(iter_values))
+                    vals = list(iter_values)
+                    try:
+                        node_value = np.array(vals)
+                    except ValueError:
+                        # Handle e.g. list elements
+                        node_value = np.fromiter(vals, object)
                 else:
                     node_value = np.fromiter(iter_values, dtype)
                 try:
@@ -477,6 +490,23 @@ def func(it, edge_attr=edge_attr, dtype=dtype):
     return rv
 
 
+def _to_tuples(ndim, L):
+    if ndim > 2:
+        L = list(map(_to_tuples.__get__(ndim - 1), L))
+    return list(map(tuple, L))
+
+
+def _array_to_tuples(a):
+    """Like ``a.tolist()``, but nested structures are tuples instead of lists.
+
+    This is only different from ``a.tolist()`` if ``a.ndim > 1``. It is used to
+    try to return tuples instead of lists for e.g. node values.
+    """
+    if a.ndim > 1:
+        return _to_tuples(a.ndim, a.tolist())
+    return a.tolist()
+
+
 def _iter_attr_dicts(
     values: dict[AttrKey, any_ndarray[EdgeValue | NodeValue]],
     masks: dict[AttrKey, any_ndarray[bool]],
@@ -485,7 +515,7 @@ def _iter_attr_dicts(
     if full_attrs:
         full_dicts = (
             dict(zip(full_attrs, vals))
-            for vals in zip(*(values[attr].tolist() for attr in full_attrs))
+            for vals in zip(*(_array_to_tuples(values[attr]) for attr in full_attrs))
         )
     partial_attrs = list(values.keys() & masks.keys())
     if partial_attrs:

python/nx-cugraph/nx_cugraph/interface.py

@@ -68,6 +68,13 @@ def key(testpath):
         louvain_different = "Louvain may be different due to RNG"
         no_string_dtype = "string edge values not currently supported"
         sssp_path_different = "sssp may choose a different valid path"
+        no_object_dtype_for_edges = (
+            "Edges don't support object dtype (lists, strings, etc.)"
+        )
+        tuple_elements_preferred = "elements are tuples instead of lists"
+        nx_cugraph_in_test_setup = (
+            "nx-cugraph Graph is incompatible in test setup in nx versions < 3.3"
+        )
 
         xfail = {
             # This is removed while strongly_connected_components() is not
@@ -91,6 +98,81 @@ def key(testpath):
                 "test_cycles.py:TestMinimumCycleBasis."
                 "test_gh6787_and_edge_attribute_names"
             ): sssp_path_different,
+            key(
+                "test_graph_hashing.py:test_isomorphic_edge_attr"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_graph_hashing.py:test_isomorphic_edge_attr_and_node_attr"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_graph_hashing.py:test_isomorphic_edge_attr_subgraph_hash"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_graph_hashing.py:"
+                "test_isomorphic_edge_attr_and_node_attr_subgraph_hash"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_summarization.py:TestSNAPNoEdgeTypes.test_summary_graph"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_summarization.py:TestSNAPUndirected.test_summary_graph"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_summarization.py:TestSNAPDirected.test_summary_graph"
+            ): no_object_dtype_for_edges,
+            key("test_gexf.py:TestGEXF.test_relabel"): no_object_dtype_for_edges,
+            key(
+                "test_gml.py:TestGraph.test_parse_gml_cytoscape_bug"
+            ): no_object_dtype_for_edges,
+            key("test_gml.py:TestGraph.test_parse_gml"): no_object_dtype_for_edges,
+            key("test_gml.py:TestGraph.test_read_gml"): no_object_dtype_for_edges,
+            key("test_gml.py:TestGraph.test_data_types"): no_object_dtype_for_edges,
+            key(
+                "test_gml.py:TestPropertyLists.test_reading_graph_with_list_property"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_relabel.py:"
+                "test_relabel_preserve_node_order_partial_mapping_with_copy_false"
+            ): "Node order is preserved when relabeling with partial mapping",
+            key(
+                "test_gml.py:"
+                "TestPropertyLists.test_reading_graph_with_single_element_list_property"
+            ): tuple_elements_preferred,
+            key(
+                "test_relabel.py:"
+                "TestRelabel.test_relabel_multidigraph_inout_merge_nodes"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multigraph_merge_inplace"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multidigraph_merge_inplace"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multidigraph_inout_copy"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multigraph_merge_copy"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multidigraph_merge_copy"
+            ): no_string_dtype,
+            key(
+                "test_relabel.py:TestRelabel.test_relabel_multigraph_nonnumeric_key"
+            ): no_string_dtype,
+            key("test_contraction.py:test_multigraph_path"): no_object_dtype_for_edges,
+            key(
+                "test_contraction.py:test_directed_multigraph_path"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_contraction.py:test_multigraph_blockmodel"
+            ): no_object_dtype_for_edges,
+            key(
+                "test_summarization.py:TestSNAPUndirectedMulti.test_summary_graph"
+            ): no_string_dtype,
+            key(
+                "test_summarization.py:TestSNAPDirectedMulti.test_summary_graph"
+            ): no_string_dtype,
         }
 
         from packaging.version import parse
@@ -118,6 +200,19 @@ def key(testpath):
                         "test_strongly_connected.py:"
                         "TestStronglyConnected.test_connected_raise"
                     ): "test is incompatible with pytest>=8",
+                    # NetworkX 3.3 introduced logic around functions that return graphs
+                    key(
+                        "test_vf2pp_helpers.py:TestGraphTinoutUpdating.test_updating"
+                    ): nx_cugraph_in_test_setup,
+                    key(
+                        "test_vf2pp_helpers.py:TestGraphTinoutUpdating.test_restoring"
+                    ): nx_cugraph_in_test_setup,
+                    key(
+                        "test_vf2pp_helpers.py:TestDiGraphTinoutUpdating.test_updating"
+                    ): nx_cugraph_in_test_setup,
+                    key(
+                        "test_vf2pp_helpers.py:TestDiGraphTinoutUpdating.test_restoring"
+                    ): nx_cugraph_in_test_setup,
                 }
             )