SpectralClustering estimator

README.md

@@ -86,6 +86,7 @@ repo](https://github.com/rapidsai/notebooks-contrib).
 |  | Hierarchical Density-Based Spatial Clustering of Applications with Noise (HDBSCAN)  | |
 |  | K-Means | Multi-node multi-GPU via Dask |
 |  | Single-Linkage Agglomerative Clustering | |
+|  | Spectral Clustering | |
 | **Dimensionality Reduction** | Principal Components Analysis (PCA) | Multi-node multi-GPU via Dask|
 | | Incremental PCA | |
 | | Truncated Singular Value Decomposition (tSVD) | Multi-node multi-GPU via Dask |

cpp/CMakeLists.txt

@@ -513,7 +513,10 @@ if(BUILD_CUML_CPP_LIBRARY)
   endif()
 
   if(all_algo OR spectralclustering_algo)
-    target_sources(cuml_objs PRIVATE src/spectral/spectral.cu src/spectral/spectral_embedding.cu)
+    target_sources(
+      cuml_objs PRIVATE src/spectral/spectral.cu src/spectral/spectral_clustering.cu
+                        src/spectral/spectral_embedding.cu
+    )
   endif()
 
   if(all_algo OR svm_algo)

cpp/include/cuml/cluster/spectral_clustering.hpp

@@ -0,0 +1,79 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <raft/core/device_coo_matrix.hpp>
+#include <raft/core/device_mdspan.hpp>
+#include <raft/core/resources.hpp>
+
+namespace ML {
+namespace SpectralClustering {
+
+/**
+ * @brief Spectral clustering parameters
+ */
+struct params {
+  /** @brief Number of clusters to find */
+  int n_clusters;
+  /** @brief Number of eigenvectors to use */
+  int n_components;
+  /** @brief Number of times to run k-means with different seeds */
+  int n_init;
+  /** @brief Number of neighbors for kNN graph construction */
+  int n_neighbors;
+  /** @brief Tolerance for the eigensolver */
+  float eigen_tol;
+  /** @brief Random seed for reproducibility */
+  uint64_t seed;
+};
+
+/**
+ * @brief Perform spectral clustering on input dataset by constructing
+ * a k-nearest neighbors graph
+ *
+ * @param[in]  handle   cuML resources handle
+ * @param[in]  config   Parameters for spectral clustering
+ * @param[in]  dataset  Input dataset (row-major)
+ * @param[out] labels   Cluster labels for each sample
+ */
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_matrix_view<float, int, raft::row_major> dataset,
+                 raft::device_vector_view<int, int> labels);
+
+/**
+ * @brief Perform spectral clustering on a precomputed connectivity graph
+ * using COO sparse matrix view
+ *
+ * @param[in]  handle              cuML resources handle
+ * @param[in]  config              Parameters for spectral clustering
+ * @param[in]  connectivity_graph  COO sparse matrix view of the connectivity graph
+ * @param[out] labels              Cluster labels for each sample
+ */
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_coo_matrix_view<float, int, int, int> connectivity_graph,
+                 raft::device_vector_view<int, int> labels);
+
+/**
+ * @brief Perform spectral clustering on a precomputed connectivity graph
+ * using separate vector views for COO components
+ *
+ * @param[in]  handle   cuML resources handle
+ * @param[in]  config   Parameters for spectral clustering
+ * @param[in]  rows     Row indices of the COO sparse matrix
+ * @param[in]  cols     Column indices of the COO sparse matrix
+ * @param[in]  vals     Values of the COO sparse matrix
+ * @param[out] labels   Cluster labels for each sample
+ */
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_vector_view<int, int> rows,
+                 raft::device_vector_view<int, int> cols,
+                 raft::device_vector_view<float, int> vals,
+                 raft::device_vector_view<int, int> labels);
+
+}  // namespace SpectralClustering
+}  // namespace ML

cpp/src/spectral/spectral_clustering.cu

@@ -0,0 +1,80 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <cuml/cluster/spectral_clustering.hpp>
+
+#include <raft/core/device_coo_matrix.hpp>
+#include <raft/core/device_mdspan.hpp>
+#include <raft/core/resources.hpp>
+
+#include <cuvs/cluster/spectral.hpp>
+#include <cuvs/preprocessing/spectral_embedding.hpp>
+
+namespace cuvs::cluster::spectral {
+struct params;
+}  // end namespace cuvs::cluster::spectral
+
+namespace ML {
+namespace SpectralClustering {
+
+cuvs::cluster::spectral::params to_cuvs(ML::SpectralClustering::params& config)
+{
+  cuvs::cluster::spectral::params cuvs_params;
+  cuvs_params.n_clusters   = config.n_clusters;
+  cuvs_params.n_components = config.n_components;
+  cuvs_params.n_init       = config.n_init;
+  cuvs_params.n_neighbors  = config.n_neighbors;
+  cuvs_params.tolerance    = config.eigen_tol;
+  cuvs_params.rng_state    = raft::random::RngState(config.seed);
+
+  return cuvs_params;
+}
+
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_matrix_view<float, int, raft::row_major> dataset,
+                 raft::device_vector_view<int, int> labels)
+{
+  int n_samples = dataset.extent(0);
+
+  // Create connectivity graph from dataset using spectral embedding helpers
+  auto graph = raft::make_device_coo_matrix<float, int, int, int>(handle, n_samples, n_samples);
+
+  cuvs::preprocessing::spectral_embedding::params embed_params;
+  embed_params.n_neighbors = config.n_neighbors;
+  embed_params.seed        = config.seed;
+
+  cuvs::preprocessing::spectral_embedding::helpers::create_connectivity_graph(
+    handle, embed_params, dataset, graph);
+
+  // Call spectral clustering with the connectivity graph
+  ML::SpectralClustering::fit_predict(handle, config, graph.view(), labels);
+}
+
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_coo_matrix_view<float, int, int, int> connectivity_graph,
+                 raft::device_vector_view<int, int> labels)
+{
+  cuvs::cluster::spectral::fit_predict(handle, to_cuvs(config), connectivity_graph, labels);
+}
+
+void fit_predict(raft::resources const& handle,
+                 params config,
+                 raft::device_vector_view<int, int> rows,
+                 raft::device_vector_view<int, int> cols,
+                 raft::device_vector_view<float, int> vals,
+                 raft::device_vector_view<int, int> labels)
+{
+  auto connectivity_graph_view = raft::make_device_coo_matrix_view<float, int, int, int>(
+    vals.data_handle(),
+    raft::make_device_coordinate_structure_view<int, int, int>(
+      rows.data_handle(), cols.data_handle(), labels.size(), labels.size(), vals.size()));
+
+  ML::SpectralClustering::fit_predict(handle, config, connectivity_graph_view, labels);
+}
+
+}  // namespace SpectralClustering
+}  // namespace ML

docs/source/api.rst

@@ -429,6 +429,13 @@ HDBSCAN
 
 .. autofunction:: cuml.cluster.hdbscan.approximate_predict
 
+Spectral Clustering
+-------------------
+.. autoclass:: cuml.cluster.SpectralClustering
+    :members:
+
+.. autofunction:: cuml.cluster.spectral_clustering
+
 
 Dimensionality Reduction and Manifold Learning
 ==============================================

python/cuml/cuml/cluster/CMakeLists.txt

@@ -9,6 +9,7 @@ set(cython_sources "")
 add_module_gpu_default("agglomerative.pyx" ${agglomerative_algo} ${cluster_algo})
 add_module_gpu_default("dbscan.pyx" ${dbscan_algo} ${cluster_algo})
 add_module_gpu_default("kmeans.pyx" ${kmeans_algo} ${cluster_algo})
+add_module_gpu_default("spectral_clustering.pyx" ${cluster_algo})
 
 add_subdirectory(hdbscan)
 

python/cuml/cuml/cluster/__init__.py

@@ -7,3 +7,7 @@
 from cuml.cluster.dbscan import DBSCAN
 from cuml.cluster.hdbscan import HDBSCAN
 from cuml.cluster.kmeans import KMeans
+from cuml.cluster.spectral_clustering import (
+    SpectralClustering,
+    spectral_clustering,
+)