Merge fast-forwarded files from cugraph into nx-cugraph (#13)

> Keep the nx-cugraph repo in sync with any relevant changes made to the cugraph codebase

Part of rapidsai/graph_dl#578

This PR updates branch-24.12 with any updates that were made since the last fast-forward ([PR on Oct 3, 2024](#4))

This was done by running `git log --since="2024-10-03" --name-only --pretty=format: -- python/nx-cugraph/ | sort | uniq` inside the cugraph repo to see which files were modified since the last fast-forward.

These files were then copied over while preserving their history

```bash
git filter-repo \
    --path python/nx-cugraph/_nx_cugraph/__init__.py \
    --path python/nx-cugraph/nx_cugraph/tests/test_ego_graph.py \
    --path python/nx-cugraph/README.md \
    --path-rename python/nx-cugraph/_nx_cugraph/__init__.py:_nx_cugraph/__init__.py \
    --path-rename python/nx-cugraph/nx_cugraph/tests/test_ego_graph.py:nx_cugraph/tests/test_ego_graph.py \
    --path-rename python/nx-cugraph/README.md:README.md
```

Authors:
  - Ralph Liu (https://github.com/nv-rliu)
  - Erik Welch (https://github.com/eriknw)
  - Ray Douglass (https://github.com/raydouglass)
  - Rick Ratzel (https://github.com/rlratzel)
  - gpuCI (https://github.com/GPUtester)
  - Jake Awe (https://github.com/AyodeAwe)
  - Kyle Edwards (https://github.com/KyleFromNVIDIA)
  - James Lamb (https://github.com/jameslamb)

Approvers:
  - Erik Welch (https://github.com/eriknw)

URL: #13

README.md

@@ -1,7 +1,7 @@
 # nx-cugraph
 
 ## Description
-[RAPIDS](https://rapids.ai) nx-cugraph is a [backend to NetworkX](https://networkx.org/documentation/stable/reference/utils.html#backends)
+[RAPIDS](https://rapids.ai) nx-cugraph is a [backend to NetworkX](https://networkx.org/documentation/stable/backends.html)
 to run supported algorithms with GPU acceleration.
 
 ## System Requirements
@@ -10,7 +10,7 @@ nx-cugraph requires the following:
  * NVIDIA GPU, Volta architecture or later, with [compute capability](https://developer.nvidia.com/cuda-gpus) 7.0+
  * CUDA 11.4-11.8 or 12.0-12.5
  * Python version 3.10, 3.11, or 3.12
- * NetworkX >= version 3.0 (version 3.2 or higher recommended)
+ * NetworkX >= version 3.0 (version 3.4 or higher recommended)
 
 More details about system requirements can be found in the [RAPIDS System Requirements documentation](https://docs.rapids.ai/install#system-req).
 
@@ -45,18 +45,20 @@ Notes:
 NetworkX will use nx-cugraph as the graph analytics backend if any of the
 following are used:
 
-### `NETWORKX_AUTOMATIC_BACKENDS` environment variable.
-The `NETWORKX_AUTOMATIC_BACKENDS` environment variable can be used to have NetworkX automatically dispatch to specified backends an API is called that the backend supports.
-Set `NETWORKX_AUTOMATIC_BACKENDS=cugraph` to use nx-cugraph to GPU accelerate supported APIs with no code changes.
+### `NX_CUGRAPH_AUTOCONFIG` environment variable.
+By setting `NX_CUGRAPH_AUTOCONFIG=True`, NetworkX will automatically dispatch algorithm calls to nx-cugraph (if the backend is supported). This allows users to GPU accelerate their code with zero code change.
+
+Read more on [Networkx Backends and How They Work](https://networkx.org/documentation/stable/reference/backends.html).
+
 Example:
 ```
-bash> NETWORKX_AUTOMATIC_BACKENDS=cugraph python my_networkx_script.py
+bash> NX_CUGRAPH_AUTOCONFIG=True python my_networkx_script.py
 ```
 
 ### `backend=` keyword argument
 To explicitly specify a particular backend for an API, use the `backend=`
 keyword argument. This argument takes precedence over the
-`NETWORKX_AUTOMATIC_BACKENDS` environment variable. This requires anyone
+`NX_CUGRAPH_AUTOCONFIG` environment variable. This requires anyone
 running code that uses the `backend=` keyword argument to have the specified
 backend installed.
 

_nx_cugraph/__init__.py

@@ -301,6 +301,45 @@ def get_info():
         .lower()
         == "true",
     }
+
+    # Enable zero-code change usage with a simple environment variable
+    # by setting or updating other NETWORKX environment variables.
+    if os.environ.get("NX_CUGRAPH_AUTOCONFIG", "").strip().lower() == "true":
+        from itertools import chain
+
+        def update_env_var(varname):
+            """Add "cugraph" to a list of backend names environment variable."""
+            if varname not in os.environ:
+                os.environ[varname] = "cugraph"
+                return
+            string = os.environ[varname]
+            vals = [
+                stripped for x in string.strip().split(",") if (stripped := x.strip())
+            ]
+            if "cugraph" not in vals:
+                # Should we append or prepend? Let's be first!
+                os.environ[varname] = ",".join(chain(["cugraph"], vals))
+
+        # Automatically convert NetworkX Graphs to nx-cugraph for algorithms
+        if (varname := "NETWORKX_BACKEND_PRIORITY_ALGOS") in os.environ:
+            # "*_ALGOS" is given priority in NetworkX >=3.4
+            update_env_var(varname)
+            # But update this too to "just work" if users mix env vars and nx versions
+            os.environ["NETWORKX_BACKEND_PRIORITY"] = os.environ[varname]
+        else:
+            update_env_var("NETWORKX_BACKEND_PRIORITY")
+        # And for older NetworkX versions
+        update_env_var("NETWORKX_AUTOMATIC_BACKENDS")  # For NetworkX 3.2
+        update_env_var("NETWORKX_GRAPH_CONVERT")  # For NetworkX 3.0 and 3.1
+        # Automatically create nx-cugraph Graph from graph generators
+        update_env_var("NETWORKX_BACKEND_PRIORITY_GENERATORS")
+        # Run default NetworkX implementation (in >=3.4) if not implemented by nx-cugraph
+        if (varname := "NETWORKX_FALLBACK_TO_NX") not in os.environ:
+            os.environ[varname] = "true"
+        # Cache graph conversions (default is False in NetworkX 3.2
+        if (varname := "NETWORKX_CACHE_CONVERTED_GRAPHS") not in os.environ:
+            os.environ[varname] = "true"
+
     return d
 
 

nx_cugraph/tests/test_ego_graph.py

@@ -78,15 +78,14 @@ def test_ego_graph_cycle_graph(
             nx.ego_graph(Gnx, n, **kwargs, backend="cugraph")
         with pytest.raises(NotImplementedError, match="ego_graph"):
             nx.ego_graph(Gcg, n, **kwargs, backend="cugraph")
-        if _nxver < (3, 4):
+        if _nxver < (3, 4) or not nx.config.fallback_to_nx:
             with pytest.raises(NotImplementedError, match="ego_graph"):
                 nx.ego_graph(Gcg, n, **kwargs)
         else:
             # This is an interesting case. `nxcg.ego_graph` is not implemented for
             # these arguments, so it falls back to networkx. Hence, as it is currently
             # implemented, the input graph is `nxcg.CudaGraph`, but the output graph
             # is `nx.Graph`. Should networkx convert back to "cugraph" backend?
-            # TODO: make fallback to networkx configurable.
             H2cg = nx.ego_graph(Gcg, n, **kwargs)
             assert type(H2nx) is type(H2cg)
             assert_graphs_equal(H2nx, nxcg.from_networkx(H2cg, preserve_all_attrs=True))