DataFusion Nexus cuGraph fork

This repository is forked from NVIDIA RAPIDS cuGraph at v26.06.00.

The upstream project is maintained at: https://github.com/rapidsai/cugraph.

This fork keeps the upstream cuGraph codebase as its base and carries local changes needed by datafusion-nexus (check diff).

Base

• Upstream: NVIDIA RAPIDS cuGraph
• Base tag: v26.06.00
• Base commit in this repository: b0294312c108c137af26ba746a13189b09e18028

Local Changes

Predicate-aware breadth-first search

This fork adds predicate-aware breadth-first search support across the C++, C, and Python cuGraph layers:

• cugraph::bfs_with_predicates for storage-aligned edge predicates, local vertex allow bitmaps, target predicates, and level-synchronous target discovery metadata.
• cugraph_bfs_with_predicates in the C API, including include/exclude vertex sets, target vertices, include edge IDs, optional predecessor output, and explicit target-discovery result accessors.
• Python cugraph.bfs extensions for include_vertices, exclude_vertices, target_vertices, include_edge_ids, and return_target_info. Supplying target_vertices automatically stops the traversal after the first depth at which a target is found.
• pylibcugraph.bfs_with_predicates bindings for the new C API surface and predicate metadata.
• BFS traversal implementation support for predicate filtering, target early-stop behavior, and predecessor/distance output compatibility with the existing BFS contract.

Predicate-aware BFS currently supports single-GPU graphs only. At the C API layer, converting an include_edge_ids set into a storage-aligned edge mask is performed on the host in O(E log N) time, where N is the number of included edge IDs. Target distance metadata is meaningful only when the corresponding target_found value is true.

The fork includes focused C++, C API, and Python tests for predicate-aware BFS behavior, including edge filtering, vertex filtering, target discovery, invalid inputs, and public Python API coverage.

Single-GPU SCC host fallback

Locally source-built libcugraph v26.06 can fail inside cugraph_strongly_connected_components with the following CUB DeviceSelect launch error:

cugraph_strongly_connected_components failed:
  copy_if failed on 2nd step: cudaErrorInvalidDeviceFunction: invalid device function

The failure was reproduced on sm_89 and sm_120 and was unchanged by switching between native and explicit SASS/PTX architecture settings. The same call succeeds with the official rapidsai/base:26.06-cuda13 artifact, which points to a CCCL 3.4.0/CUB select-tuning difference in the locally built library rather than a missing GPU code object.

For single-GPU graphs, the fork recognizes exceptions whose messages contain invalid device function, cudaErrorInvalidDeviceFunction, or copy_if failed, clears the non-sticky CUDA launch error, and falls back to serial host-side Kosaraju. The fallback returns the normal C API labeling-result shape and an equivalent SCC partition. It copies the graph to host, uses O(V+E) host memory, and can be substantially slower on large graphs, so it emits a warning when triggered.

Multi-GPU SCC continues to use the native implementation. Symmetric graphs are rejected with CUGRAPH_INVALID_INPUT and should use weakly connected components instead. Exceptions that do not match the fallback conditions continue through the normal C API error handling path.

Implementation: cpp/src/c_api/strongly_connected_components.cpp.

C API error reporting

The shared C API algorithm dispatcher maps cugraph::logic_error failures identified as invalid arguments to CUGRAPH_INVALID_INPUT, allowing callers to distinguish invalid requests from unknown failures. The current classification recognizes the Invalid input argument phrase in the exception message, so changes to those messages must preserve that contract or replace it with a typed error category.

cugraph_pagerank and cugraph_personalized_pagerank now return dispatcher failures before checking convergence. Invalid precomputed or personalization vertex IDs therefore return CUGRAPH_INVALID_INPUT with a null result instead of continuing through the success path.

RMM device-allocation failures and standard host-allocation failures are reported as CUGRAPH_ALLOC_ERROR by the shared algorithm dispatcher and the single- and multi-GPU graph creation paths. Callers can use this code to distinguish resource exhaustion from CUGRAPH_UNKNOWN_ERROR; the associated error object retains the allocator's diagnostic message.