Update API to leverage cuVS Spectral clustering (#5326)

This PR integrates cuVS spectral clustering from upstream into cuGraph while maintaining full backward compatibility. The integration deprecates the legacy balanced cut clustering C++ and Python APIs in favor of spectral_modularity_maximization. In fact, cuVS consolidated the spectral clustering API to assign vertices to clusters that by default maximizes the modularity score

**Static Linking with Conda Fallback:**
- cuGraph is configured to statically link libcuvs for optimal performance
- The build system first attempts to use conda-installed libcuvs if available
- If libcuvs is not present in the conda environment or static linking is required, the build system automatically clones the main cuVS repository (rapidsai/cuvs) and builds it from source
- Uses the standard RAPIDS release branch (${rapids-cmake-checkout-tag}) ensuring version compatibility

Note: The header files `raft/spectral/partition.cuh` and `raft/spectral/modularity_maximization.cuh` are still necessary in `spectraly_clustering.cu` because APIs (like `raft::spectral::analyzePartition`, `raft::spectral::analyzeModularity`) are still being called in cuGraph and are not supported in cuVS. This is not an issue because those APIs are not deprecated in raft in contrary to `kmeans` and `solvers`

Authors:
  - Joseph Nke (https://github.com/jnke2016)

Approvers:
  - Anupam (https://github.com/aamijar)
  - Chuck Hastings (https://github.com/ChuckHastings)
  - Rick Ratzel (https://github.com/rlratzel)
  - Robert Maynard (https://github.com/robertmaynard)
  - Bradley Dice (https://github.com/bdice)

URL: #5326

Author: jnke2016

build.sh

@@ -240,7 +240,8 @@ if buildDefault || hasArg libcugraph || hasArg all; then
               -DBUILD_CUGRAPH_MG_TESTS=${BUILD_CPP_MG_TESTS} \
               -DBUILD_CUGRAPH_MTMG_TESTS=${BUILD_CPP_MTMG_TESTS} \
               "${CMAKE_GENERATOR_OPTION[@]}" \
-              "${CMAKE_VERBOSE_OPTION[@]}"
+              "${CMAKE_VERBOSE_OPTION[@]}" \
+              ${EXTRA_CMAKE_ARGS}
 
         cmake --build "${LIBCUGRAPH_BUILD_DIR}" "-j${PARALLEL_LEVEL}" "${INSTALL_TARGET[@]}" "${VERBOSE_FLAG}"
     fi

ci/release/update-version.sh

@@ -110,6 +110,7 @@ DEPENDENCIES=(
   libcugraph
   libcugraph_etl
   libcugraph-tests
+  libcuvs
   libraft
   librmm
   pylibcudf

conda/environments/all_cuda-129_arch-aarch64.yaml

@@ -32,6 +32,7 @@ dependencies:
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libcuvs==25.12.*,>=0.0.0a0
 - libraft==25.12.*,>=0.0.0a0
 - librmm==25.12.*,>=0.0.0a0
 - nbsphinx

conda/environments/all_cuda-129_arch-x86_64.yaml

@@ -32,6 +32,7 @@ dependencies:
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libcuvs==25.12.*,>=0.0.0a0
 - libraft==25.12.*,>=0.0.0a0
 - librmm==25.12.*,>=0.0.0a0
 - nbsphinx

conda/environments/all_cuda-130_arch-aarch64.yaml

@@ -32,6 +32,7 @@ dependencies:
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libcuvs==25.12.*,>=0.0.0a0
 - libraft==25.12.*,>=0.0.0a0
 - librmm==25.12.*,>=0.0.0a0
 - nbsphinx

conda/environments/all_cuda-130_arch-x86_64.yaml

@@ -32,6 +32,7 @@ dependencies:
 - libcurand-dev
 - libcusolver-dev
 - libcusparse-dev
+- libcuvs==25.12.*,>=0.0.0a0
 - libraft==25.12.*,>=0.0.0a0
 - librmm==25.12.*,>=0.0.0a0
 - nbsphinx

conda/recipes/libcugraph/recipe.yaml

@@ -38,6 +38,7 @@ cache:
         CMAKE_CUDA_COMPILER_LAUNCHER: ${{ env.get("CMAKE_CUDA_COMPILER_LAUNCHER") }}
         CMAKE_CXX_COMPILER_LAUNCHER: ${{ env.get("CMAKE_CXX_COMPILER_LAUNCHER") }}
         CMAKE_GENERATOR: ${{ env.get("CMAKE_GENERATOR") }}
+        EXTRA_CMAKE_ARGS: "-DCUGRAPH_COMPILE_CUVS=ON"
         PARALLEL_LEVEL: ${{ env.get("PARALLEL_LEVEL") }}
         SCCACHE_BUCKET: ${{ env.get("SCCACHE_BUCKET") }}
         SCCACHE_IDLE_TIMEOUT: ${{ env.get("SCCACHE_IDLE_TIMEOUT") }}

cpp/CMakeLists.txt

@@ -1,6 +1,8 @@
 #=============================================================================
+# cmake-format: off
 # SPDX-FileCopyrightText: Copyright (c) 2018-2025, NVIDIA CORPORATION.
 # SPDX-License-Identifier: Apache-2.0
+# cmake-format: on
 #=============================================================================
 
 cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
@@ -11,6 +13,7 @@ include(rapids-cpm)
 include(rapids-cuda)
 include(rapids-export)
 include(rapids-find)
+include(CMakeDependentOption)
 
 rapids_cuda_init_architectures(CUGRAPH)
 
@@ -41,8 +44,14 @@ option(BUILD_TESTS "Configure CMake to build tests" ON)
 option(USE_RAFT_STATIC "Build raft as a static library" OFF)
 option(CUGRAPH_COMPILE_RAFT_LIB "Compile the raft library instead of using it header-only" ON)
 option(CUDA_STATIC_RUNTIME "Statically link the CUDA toolkit runtime and libraries" OFF)
+option(CUGRAPH_COMPILE_CUVS "Always compile cuVS from source" OFF)
+cmake_dependent_option(CUGRAPH_USE_CUVS_STATIC
+  "Build and statically link the cuVS library" ON
+  "CUGRAPH_COMPILE_CUVS" OFF)
 
 message(VERBOSE "CUGRAPH: CUDA_STATIC_RUNTIME=${CUDA_STATIC_RUNTIME}")
+message(VERBOSE "CUGRAPH: CUGRAPH_COMPILE_CUVS=${CUGRAPH_COMPILE_CUVS}")
+message(VERBOSE "CUGRAPH: CUGRAPH_USE_CUVS_STATIC=${CUGRAPH_USE_CUVS_STATIC}")
 
 ################################################################################
 # - compiler options -----------------------------------------------------------
@@ -112,6 +121,9 @@ include(${rapids-cmake-dir}/cpm/cuco.cmake)
 rapids_cpm_cuco(BUILD_EXPORT_SET cugraph-exports INSTALL_EXPORT_SET cugraph-exports)
 include(cmake/thirdparty/get_raft.cmake)
 
+# Always include cuVS for spectral clustering enhancements
+include(cmake/thirdparty/get_cuvs.cmake)
+
 if (BUILD_CUGRAPH_MTMG_TESTS)
     if(NOT TARGET ucx::ucp)
         find_package(ucx REQUIRED)
@@ -474,6 +486,11 @@ if(CUGRAPH_COMPILE_RAFT_LIB)
   endif()
 endif()
 
+set(CUVS_LIB cuvs::cuvs)
+if(CUGRAPH_USE_CUVS_STATIC)
+  set(CUVS_LIB cuvs::cuvs_static)
+endif()
+
 ################################################################################
 # - link libraries -------------------------------------------------------------
 target_link_libraries(cugraph
@@ -483,6 +500,7 @@ target_link_libraries(cugraph
         $<BUILD_LOCAL_INTERFACE:CUDA::toolkit>
     PRIVATE
         ${COMPILED_RAFT_LIB}
+        ${CUVS_LIB}
         cuco::cuco
     )
 

cpp/cmake/thirdparty/get_cuvs.cmake

@@ -0,0 +1,61 @@
+#=============================================================================
+# cmake-format: off
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+# cmake-format: on
+#=============================================================================
+
+set(CUGRAPH_MIN_VERSION_cuvs "${CUGRAPH_VERSION_MAJOR}.${CUGRAPH_VERSION_MINOR}.00")
+
+function(find_and_configure_cuvs)
+    set(oneValueArgs VERSION FORK PINNED_TAG EXCLUDE_FROM_ALL USE_CUVS_STATIC CLONE_ON_PIN)
+    cmake_parse_arguments(PKG "${options}" "${oneValueArgs}"
+            "${multiValueArgs}" ${ARGN} )
+
+    if(PKG_CLONE_ON_PIN AND NOT PKG_PINNED_TAG STREQUAL "${rapids-cmake-checkout-tag}")
+        message(STATUS "CUGRAPH: Pinned tag found: ${PKG_PINNED_TAG}. Cloning cuVS locally.")
+        set(CPM_DOWNLOAD_cuvs ON)
+    elseif(PKG_USE_CUVS_STATIC AND (NOT CPM_cuvs_SOURCE))
+      message(STATUS "CUGRAPH: Cloning cuVS locally to build static libraries.")
+      set(CPM_DOWNLOAD_cuvs ON)
+    endif()
+
+    # Disable multi-GPU algorithms to avoid NCCL dependency
+    set(CUVS_BUILD_MG_ALGOS OFF)
+
+    rapids_cpm_find(cuvs ${PKG_VERSION}
+      GLOBAL_TARGETS      cuvs::cuvs
+      CPM_ARGS
+        GIT_REPOSITORY         https://github.com/${PKG_FORK}/cuvs.git
+        GIT_TAG                ${PKG_PINNED_TAG}
+        SOURCE_SUBDIR          cpp
+        EXCLUDE_FROM_ALL       ${PKG_EXCLUDE_FROM_ALL}
+        OPTIONS
+          "BUILD_TESTS OFF"
+          "BUILD_CAGRA_HNSWLIB OFF"
+          "BUILD_CUVS_BENCH OFF"
+          "BUILD_MG_ALGOS ${CUVS_BUILD_MG_ALGOS}"
+    )
+
+    if(cuvs_ADDED)
+        message(VERBOSE "CUGRAPH: Using cuVS located in ${cuvs_SOURCE_DIR}")
+    else()
+        message(VERBOSE "CUGRAPH: Using cuVS located in ${cuvs_DIR}")
+    endif()
+
+endfunction()
+
+# Change pinned tag and fork here to test a commit in CI
+# To use a different cuVS locally, set the CMake variable
+# CPM_cuvs_SOURCE=/path/to/local/cuvs
+find_and_configure_cuvs(VERSION          ${CUGRAPH_MIN_VERSION_cuvs}
+                        FORK             rapidsai
+                        PINNED_TAG       ${rapids-cmake-checkout-tag}
+
+                        # When PINNED_TAG above doesn't match cugraph,
+                        # force local cuVS clone in build directory
+                        # even if it's already installed.
+                        CLONE_ON_PIN     ON
+                        USE_CUVS_STATIC  ${CUGRAPH_USE_CUVS_STATIC}
+                        EXCLUDE_FROM_ALL ON
+                        )

cpp/include/cugraph/algorithms.hpp

@@ -873,6 +873,8 @@ std::unique_ptr<legacy::GraphCOO<VT, ET, WT>> extract_subgraph_vertex(
  * @ingroup community_cpp
  * @brief     Wrapper function for Nvgraph balanced cut clustering
  *
+ * @deprecated This API will be deprecated. Use spectralModularityMaximization instead.
+ *
  * @throws     cugraph::logic_error when an error occurs.
  *
  * @tparam VT                        Type of vertex identifiers. Supported value : int (signed,