All-Neighbors#

The all-neighbors method constructs a k-NN graph for all vectors in a dataset. It supports multiple algorithms including brute force, IVF-PQ (approximate), and NN-Descent (approximate) for building local k-NN subgraphs. The API automatically detects whether the dataset is host-resident or device-resident and applies appropriate optimizations.

#include <cuvs/neighbors/all_neighbors.h>

Build#

enum cuvsAllNeighborsAlgo#

Graph build algorithm selection.

Values:

enumerator CUVS_ALL_NEIGHBORS_ALGO_BRUTE_FORCE#: Use Brute Force for local kNN subgraphs.

enumerator CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ#: Use IVF-PQ for local kNN subgraphs (host dataset only)

enumerator CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT#: Use NN-Descent for local kNN subgraphs.

typedef struct cuvsAllNeighborsIndexParams *cuvsAllNeighborsIndexParams_t#

cuvsError_t cuvsAllNeighborsIndexParamsCreate( cuvsAllNeighborsIndexParams_t *index_params )#

Create a default all-neighbors index parameters struct.

Parameters:: index_params – [out] Pointer to allocated index_params struct
Returns:: cuvsError_t

cuvsError_t cuvsAllNeighborsIndexParamsDestroy( cuvsAllNeighborsIndexParams_t index_params )#

Destroy an all-neighbors index parameters struct.

Parameters:: index_params – [in] Index parameters struct to destroy
Returns:: cuvsError_t

cuvsError_t cuvsAllNeighborsBuild( cuvsResources_t res, cuvsAllNeighborsIndexParams_t params, DLManagedTensor *dataset, DLManagedTensor *indices, DLManagedTensor *distances, DLManagedTensor *core_distances, float alpha )#

Build an all-neighbors k-NN graph automatically detecting host vs device dataset.

The function automatically detects whether the dataset is host-resident or device-resident and calls the appropriate implementation. For host datasets, it partitions data into n_clusters clusters and assigns each row to overlap_factor nearest clusters. For device datasets, n_clusters must be 1 (no batching); overlap_factor is ignored. Outputs always reside in device memory.

Parameters:

res – [in] Can be a SNMG multi-GPU resources (cuvsResources_t) or single-GPU resources
params – [in] Build parameters (see cuvsAllNeighborsIndexParams)
dataset – [in] 2D tensor [num_rows x dim] on host or device (auto-detected)
indices – [out] 2D tensor [num_rows x k] on device (int64)
distances – [out] Optional 2D tensor [num_rows x k] on device (float32); can be NULL
core_distances – [out] Optional 1D tensor [num_rows] on device (float32); can be NULL
alpha – [in] Mutual-reachability scaling; used only when core_distances is provided

struct cuvsAllNeighborsIndexParams#

#include <all_neighbors.h>

Parameters controlling SNMG all-neighbors build.

Public Members

cuvsAllNeighborsAlgo algo#: Local kNN graph build algorithm.

size_t overlap_factor#: Number of clusters each point is assigned to (must be < n_clusters)

size_t n_clusters#: Number of clusters/batches to partition the dataset into (> overlap_factor)

cuvsDistanceType metric#: Distance metric used for graph construction.

cuvsIvfPqIndexParams_t ivf_pq_params#: Parameters for IVF-PQ algorithm (when algo == CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ)

cuvsNNDescentIndexParams_t nn_descent_params#: Parameters for NN-Descent algorithm (when algo == CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT)