Skip to navigation

All Neighbors

View as Markdown

Source header: cuvs/neighbors/all_neighbors.h

All-neighbors C-API build parameters

cuvsAllNeighborsAlgo

Graph build algorithm selection.

typedef enum {
CUVS_ALL_NEIGHBORS_ALGO_BRUTE_FORCE = 0,
CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ = 1,
CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT = 2
} cuvsAllNeighborsAlgo;

Values

NameValue
CUVS_ALL_NEIGHBORS_ALGO_BRUTE_FORCE0
CUVS_ALL_NEIGHBORS_ALGO_IVF_PQ1
CUVS_ALL_NEIGHBORS_ALGO_NN_DESCENT2

cuvsAllNeighborsIndexParams

Parameters controlling SNMG all-neighbors build.

struct cuvsAllNeighborsIndexParams {
cuvsAllNeighborsAlgo algo;
size_t overlap_factor;
size_t n_clusters;
cuvsDistanceType metric;
cuvsIvfPqIndexParams_t ivf_pq_params;
cuvsNNDescentIndexParams_t nn_descent_params;
};

Fields

NameTypeDescription
algocuvsAllNeighborsAlgo
overlap_factorsize_t
n_clusterssize_t
metriccuvsDistanceType
ivf_pq_paramscuvsIvfPqIndexParams_t
nn_descent_paramscuvsNNDescentIndexParams_t

cuvsAllNeighborsIndexParamsCreate

Create a default all-neighbors index parameters struct.

cuvsError_t cuvsAllNeighborsIndexParamsCreate(cuvsAllNeighborsIndexParams_t* index_params);

Parameters

NameDirectionTypeDescription
index_paramsoutcuvsAllNeighborsIndexParams_t*Pointer to allocated index_params struct

Returns

cuvsError_t

cuvsAllNeighborsIndexParamsDestroy

Destroy an all-neighbors index parameters struct.

cuvsError_t cuvsAllNeighborsIndexParamsDestroy(cuvsAllNeighborsIndexParams_t index_params);

Parameters

NameDirectionTypeDescription
index_paramsincuvsAllNeighborsIndexParams_tIndex parameters struct to destroy

Returns

cuvsError_t

All-neighbors C-API build

cuvsAllNeighborsBuild

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

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

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.

Output memory space: a host dataset supports host- or device-resident outputs; a device dataset requires device-resident outputs. All provided outputs must share the same memory space.

Parameters

NameDirectionTypeDescription
resincuvsResources_tCan be a SNMG multi-GPU resources (cuvsResources_t) or single-GPU resources
paramsincuvsAllNeighborsIndexParams_tBuild parameters (see cuvsAllNeighborsIndexParams)
datasetinDLManagedTensor*2D tensor [num_rows x dim] on host or device (auto-detected)
indicesoutDLManagedTensor*2D tensor [num_rows x k] (int64), host or device
distancesoutDLManagedTensor*Optional 2D tensor [num_rows x k] (float32), host or device; can be NULL
core_distancesoutDLManagedTensor*Optional 1D tensor [num_rows] (float32), host or device; can be NULL
alphainfloatMutual-reachability scaling; used only when core_distances is provided

Returns

cuvsError_t