Implementation:Rapidsai Cuml Spectral Embedding

Knowledge Sources	Rapidsai_Cuml
Domains	Machine_Learning, Dimensionality_Reduction
Last Updated	2026-02-08 12:00 GMT

Overview

Provides GPU-accelerated spectral embedding for dimensionality reduction, computing low-dimensional representations from dense feature matrices or sparse connectivity graphs using eigendecomposition of the graph Laplacian.

Description

The spectral_embedding.hpp header declares the C++ API for the spectral embedding algorithm in cuML. Spectral embedding transforms high-dimensional data into a lower-dimensional space by constructing a nearest-neighbors graph, computing its Laplacian, and extracting the leading eigenvectors.

The header defines:

• ML::SpectralEmbedding::params: A parameter struct controlling the embedding with fields for the number of output components (n_components), the number of neighbors for the graph (n_neighbors), whether to normalize the Laplacian (norm_laplacian), whether to drop the first eigenvector (drop_first), and an optional random seed (seed).
• to_cuvs: A conversion function that translates cuML spectral embedding parameters to the equivalent cuVS parameter struct.
• transform (three overloads):
  • From a dense device matrix: Accepts a row-major raft::device_matrix_view<float> and computes the embedding.
  • From a COO sparse connectivity graph: Accepts a raft::device_coo_matrix_view representing a precomputed connectivity graph.
  • From separate COO components: Accepts separate device vectors for row indices, column indices, and values of a sparse connectivity graph.

All three transform overloads produce a column-major output embedding matrix.

Usage

Use spectral embedding when you need to reduce the dimensionality of data while preserving the graph structure of nearest-neighbor relationships. This is commonly used as a preprocessing step for spectral clustering or as a standalone dimensionality reduction technique. The three overloads allow flexibility depending on whether raw data, a precomputed sparse connectivity matrix, or COO-format graph components are available.

Code Reference

Source Location

• Repository: Rapidsai_Cuml
• File: cpp/include/cuml/manifold/spectral_embedding.hpp

Signature

namespace ML::SpectralEmbedding {

struct params {
  int n_components;
  int n_neighbors;
  bool norm_laplacian;
  bool drop_first;
  std::optional<uint64_t> seed = std::nullopt;
};

cuvs::preprocessing::spectral_embedding::params to_cuvs(ML::SpectralEmbedding::params& config);

void transform(raft::resources const& handle,
               ML::SpectralEmbedding::params config,
               raft::device_matrix_view<float, int, raft::row_major> dataset,
               raft::device_matrix_view<float, int, raft::col_major> embedding);

void transform(raft::resources const& handle,
               ML::SpectralEmbedding::params config,
               raft::device_coo_matrix_view<float, int, int, int64_t> connectivity_graph,
               raft::device_matrix_view<float, int, raft::col_major> embedding);

void transform(raft::resources const& handle,
               ML::SpectralEmbedding::params config,
               raft::device_vector_view<int, int64_t> rows,
               raft::device_vector_view<int, int64_t> cols,
               raft::device_vector_view<float, int64_t> vals,
               raft::device_matrix_view<float, int, raft::col_major> embedding);

} // namespace ML::SpectralEmbedding

Import

#include <cuml/manifold/spectral_embedding.hpp>

I/O Contract

Inputs

params struct

Name	Type	Required	Description
n_components	int	Yes	Number of dimensions in the output embedding
n_neighbors	int	Yes	Number of neighbors for building the nearest neighbors graph
norm_laplacian	bool	Yes	Whether to normalize the graph Laplacian matrix
drop_first	bool	Yes	Whether to drop the first eigenvector (associated with trivial eigenvalue)
seed	std::optional<uint64_t>	No	Random seed for reproducibility; defaults to std::nullopt

transform (dense overload)

Name	Type	Required	Description
handle	raft::resources const&	Yes	RAFT resources handle for GPU execution context
config	ML::SpectralEmbedding::params	Yes	Embedding parameters
dataset	raft::device_matrix_view<float, int, raft::row_major>	Yes	Input feature matrix on device, shape [n_rows x n_cols]
embedding	raft::device_matrix_view<float, int, raft::col_major>	Yes	Output embedding matrix on device, shape [n_rows x n_components]

transform (COO matrix overload)

Name	Type	Required	Description
handle	raft::resources const&	Yes	RAFT resources handle
config	ML::SpectralEmbedding::params	Yes	Embedding parameters
connectivity_graph	raft::device_coo_matrix_view<float, int, int, int64_t>	Yes	Precomputed sparse connectivity graph in COO format
embedding	raft::device_matrix_view<float, int, raft::col_major>	Yes	Output embedding matrix

transform (separate COO components overload)

Name	Type	Required	Description
handle	raft::resources const&	Yes	RAFT resources handle
config	ML::SpectralEmbedding::params	Yes	Embedding parameters
rows	raft::device_vector_view<int, int64_t>	Yes	Row indices of the COO sparse graph
cols	raft::device_vector_view<int, int64_t>	Yes	Column indices of the COO sparse graph
vals	raft::device_vector_view<float, int64_t>	Yes	Values of the COO sparse graph
embedding	raft::device_matrix_view<float, int, raft::col_major>	Yes	Output embedding matrix

Outputs

Name	Type	Description
embedding	raft::device_matrix_view<float, int, raft::col_major>	The computed spectral embedding of shape [n_rows x n_components], column-major on device

Usage Examples

#include <cuml/manifold/spectral_embedding.hpp>
#include <raft/core/resources.hpp>
#include <raft/core/device_mdspan.hpp>

// Set up RAFT resources
raft::resources handle;

// Configure spectral embedding parameters
ML::SpectralEmbedding::params config;
config.n_components = 2;
config.n_neighbors = 10;
config.norm_laplacian = true;
config.drop_first = true;

// Assume d_dataset is a row-major device matrix view [1000 x 50]
// Assume d_embedding is a pre-allocated col-major device matrix view [1000 x 2]

ML::SpectralEmbedding::transform(handle, config, d_dataset, d_embedding);

Related Pages

• Environment:Rapidsai_Cuml_CUDA_GPU