Implementation:Rapidsai Cuml Manifold Common

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

Overview

Defines common data structures used as inputs to GPU-accelerated manifold learning algorithms in cuML, including containers for dense, sparse, and precomputed KNN graph inputs.

Description

The common.hpp header provides the foundational type definitions and templated structs required by manifold learning algorithms (such as UMAP and t-SNE) in the cuML library. It defines:

• knn_indices_dense_t and knn_indices_sparse_t: Type aliases for KNN index types used in dense (int64_t) and sparse (int) neighbor lookups. The dense type uses int64_t to align with FAISS conventions.
• knn_graph: A simple templated container that holds pointers to KNN index and distance arrays along with row count and neighbor count metadata.
• manifold_inputs_t: An abstract base struct representing generic manifold input data with a label pointer, row count, and dimensionality. It declares a pure virtual method alloc_knn_graph() used by derived types.
• manifold_dense_inputs_t: Extends manifold_inputs_t for dense (row-major) feature matrices, carrying a pointer to the dense data array X.
• manifold_sparse_inputs_t: Extends manifold_inputs_t for sparse CSR-format inputs, holding indptr, indices, data pointers and the total number of non-zero entries.
• manifold_precomputed_knn_inputs_t: Extends manifold_inputs_t for cases where a precomputed KNN graph is provided directly, wrapping a knn_graph member.

All types reside in the ML namespace.

Usage

Use these types when constructing inputs for cuML manifold learning algorithms such as UMAP or t-SNE. Choose the appropriate derived struct based on whether the input data is dense, sparse (CSR), or a precomputed KNN graph. These structs serve as the interface contract between user code and the underlying GPU manifold implementations.

Code Reference

Source Location

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

Signature

namespace ML {

typedef int64_t knn_indices_dense_t;
typedef int knn_indices_sparse_t;

template <typename value_idx, typename value_t>
struct knn_graph {
  knn_graph(value_idx n_rows_, int n_neighbors_);
  knn_graph(value_idx n_rows_, int n_neighbors_, value_idx* knn_indices_, value_t* knn_dists_);

  value_idx* knn_indices;
  value_t* knn_dists;
  value_idx n_rows;
  int n_neighbors;
};

template <typename T>
struct manifold_inputs_t {
  T* y;
  int n;
  int d;
  manifold_inputs_t(T* y_, int n_, int d_);
  virtual bool alloc_knn_graph() const = 0;
};

template <typename T>
struct manifold_dense_inputs_t : public manifold_inputs_t<T> {
  T* X;
  manifold_dense_inputs_t(T* x_, T* y_, int n_, int d_);
  bool alloc_knn_graph() const;
};

template <typename value_idx, typename T>
struct manifold_sparse_inputs_t : public manifold_inputs_t<T> {
  value_idx* indptr;
  value_idx* indices;
  T* data;
  size_t nnz;
  manifold_sparse_inputs_t(value_idx* indptr_, value_idx* indices_, T* data_, T* y_,
                           size_t nnz_, int n_, int d_);
  bool alloc_knn_graph() const;
};

template <typename value_idx, typename value_t>
struct manifold_precomputed_knn_inputs_t : public manifold_inputs_t<value_t> {
  manifold_precomputed_knn_inputs_t(value_idx* knn_indices_, value_t* knn_dists_,
                                     value_t* y_, int n_, int d_, int n_neighbors_);
  knn_graph<value_idx, value_t> knn_graph;
  bool alloc_knn_graph() const;
};

} // namespace ML

Import

#include <cuml/manifold/common.hpp>

I/O Contract

Inputs

knn_graph

Name	Type	Required	Description
n_rows_	value_idx	Yes	Number of rows (data points) in the KNN graph
n_neighbors_	int	Yes	Number of nearest neighbors per data point
knn_indices_	value_idx*	No	Device pointer to the KNN index array (optional, nullptr by default)
knn_dists_	value_t*	No	Device pointer to the KNN distance array (optional, nullptr by default)

manifold_dense_inputs_t

Name	Type	Required	Description
x_	T*	Yes	Device pointer to the dense feature matrix of shape [n x d]
y_	T*	Yes	Device pointer to the label array of length n
n_	int	Yes	Number of data points (rows)
d_	int	Yes	Number of dimensions (columns)

manifold_sparse_inputs_t

Name	Type	Required	Description
indptr_	value_idx*	Yes	Device pointer to CSR row pointer array of size [n + 1]
indices_	value_idx*	Yes	Device pointer to CSR column indices array of size [nnz]
data_	T*	Yes	Device pointer to CSR data values array of size [nnz]
y_	T*	Yes	Device pointer to the label array of length n
nnz_	size_t	Yes	Number of non-zero entries in the sparse matrix
n_	int	Yes	Number of data points (rows)
d_	int	Yes	Number of dimensions (columns)

manifold_precomputed_knn_inputs_t

Name	Type	Required	Description
knn_indices_	value_idx*	Yes	Device pointer to precomputed KNN index array
knn_dists_	value_t*	Yes	Device pointer to precomputed KNN distance array
y_	value_t*	Yes	Device pointer to label array of length n
n_	int	Yes	Number of data points
d_	int	Yes	Number of dimensions
n_neighbors_	int	Yes	Number of nearest neighbors

Outputs

Name	Type	Description
alloc_knn_graph()	bool	Returns true for dense and sparse inputs (KNN graph must be computed), false for precomputed KNN inputs

Usage Examples

#include <cuml/manifold/common.hpp>

// Dense input example
float* d_X;       // device pointer to [n x d] feature matrix
float* d_labels;  // device pointer to [n] labels
int n = 1000;
int d = 50;

ML::manifold_dense_inputs_t<float> dense_input(d_X, d_labels, n, d);
// dense_input.alloc_knn_graph() returns true

// Sparse CSR input example
int* d_indptr;    // device pointer to CSR row offsets [n+1]
int* d_indices;   // device pointer to CSR column indices [nnz]
float* d_data;    // device pointer to CSR values [nnz]
size_t nnz = 50000;

ML::manifold_sparse_inputs_t<int, float> sparse_input(
    d_indptr, d_indices, d_data, d_labels, nnz, n, d);

// Precomputed KNN graph input example
int n_neighbors = 15;
int64_t* d_knn_indices;  // device pointer [n x n_neighbors]
float* d_knn_dists;      // device pointer [n x n_neighbors]

ML::manifold_precomputed_knn_inputs_t<int64_t, float> precomputed_input(
    d_knn_indices, d_knn_dists, d_labels, n, d, n_neighbors);
// precomputed_input.alloc_knn_graph() returns false

Related Pages

• Environment:Rapidsai_Cuml_CUDA_GPU