Neighbors NN Descent

Source header: cuvs/neighbors/nn_descent.h

Types

cuvsNNDescentDistCompDtype

Dtype to use for distance computation

1 typedef enum {
2   NND_DIST_COMP_AUTO = 0,
3   NND_DIST_COMP_FP32 = 1,
4   NND_DIST_COMP_FP16 = 2
5 } cuvsNNDescentDistCompDtype;

Values

Name	Value	Description
`NND_DIST_COMP_AUTO`	`0`	Automatically determine the best dtype for distance computation based on the dataset dimensions.
`NND_DIST_COMP_FP32`	`1`	Use fp32 distance computation for better precision at the cost of performance and memory usage.
`NND_DIST_COMP_FP16`	`2`	Use fp16 distance computation.

The nn-descent algorithm parameters.

cuvsNNDescentIndexParams

Parameters used to build an nn-descent index

1 struct cuvsNNDescentIndexParams {
2   cuvsDistanceType metric;
3   float metric_arg;
4   size_t graph_degree;
5   size_t intermediate_graph_degree;
6   size_t max_iterations;
7   float termination_threshold;
8   bool return_distances;
9   cuvsNNDescentDistCompDtype dist_comp_dtype;
10 };

Fields

Name	Type	Description
`metric`	`cuvsDistanceType`	The distance metric to use
`metric_arg`	`float`	The argument used by distance metrics like Minkowskidistance
`graph_degree`	`size_t`	For an input dataset of dimensions (N, D), determines the final dimensions of the all-neighbors knn graph which turns out to be of dimensions (N, graph_degree)
`intermediate_graph_degree`	`size_t`	Internally, nn-descent builds an all-neighbors knn graph of dimensions (N, intermediate_graph_degree) before selecting the final `graph_degree` neighbors. It’s recommended that `intermediate_graph_degree` >= 1.5 * graph_degree
`max_iterations`	`size_t`	The number of iterations that nn-descent will refine the graph for. More iterations produce a better quality graph at cost of performance
`termination_threshold`	`float`	The delta at which nn-descent will terminate its iterations
`return_distances`	`bool`	Boolean to decide whether to return distances array
`dist_comp_dtype`	`cuvsNNDescentDistCompDtype`	dtype to use for distance computation. Defaults to `NND_DIST_COMP_AUTO` which automatically determines the best dtype for distance computation based on the dataset dimensions. Use `NND_DIST_COMP_FP32` for better precision at the cost of performance and memory usage. This option is only valid when data type is fp32. Use `NND_DIST_COMP_FP16` for better performance and memory usage at the cost of precision.

cuvsNNDescentIndexParamsCreate

Allocate NN-Descent Index params, and populate with default values

1 cuvsError_t cuvsNNDescentIndexParamsCreate(cuvsNNDescentIndexParams_t* index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsNNDescentIndexParams_t*`	cuvsNNDescentIndexParams_t to allocate

Returns

cuvsError_t

cuvsNNDescentIndexParamsDestroy

De-allocate NN-Descent Index params

1 cuvsError_t cuvsNNDescentIndexParamsDestroy(cuvsNNDescentIndexParams_t index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsNNDescentIndexParams_t`

Returns

cuvsError_t

NN-Descent index

cuvsNNDescentIndex

Struct to hold address of cuvs::neighbors::nn_descent::index and its active trained dtype

1 typedef struct {
2   uintptr_t addr;
3   DLDataType dtype;
4 } cuvsNNDescentIndex;

Fields

Name	Type	Description
`addr`	`uintptr_t`
`dtype`	`DLDataType`

cuvsNNDescentIndexCreate

Allocate NN-Descent index

1 cuvsError_t cuvsNNDescentIndexCreate(cuvsNNDescentIndex_t* index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsNNDescentIndex_t*`	cuvsNNDescentIndex_t to allocate

Returns

cuvsError_t

cuvsNNDescentIndexDestroy

De-allocate NN-Descent index

1 cuvsError_t cuvsNNDescentIndexDestroy(cuvsNNDescentIndex_t index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsNNDescentIndex_t`	cuvsNNDescentIndex_t to de-allocate

Returns

cuvsError_t

NN-Descent index build

cuvsNNDescentBuild

Build a NN-Descent index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are:

kDLDataType.code == kDLFloat and kDLDataType.bits = 32
kDLDataType.code == kDLFloat and kDLDataType.bits = 16
kDLDataType.code == kDLInt and kDLDataType.bits = 8
kDLDataType.code == kDLUInt and kDLDataType.bits = 8

1 cuvsError_t cuvsNNDescentBuild(cuvsResources_t res,
2 cuvsNNDescentIndexParams_t index_params,
3 DLManagedTensor* dataset,
4 DLManagedTensor* graph,
5 cuvsNNDescentIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`index_params`	in	`cuvsNNDescentIndexParams_t`	cuvsNNDescentIndexParams_t used to build NN-Descent index
`dataset`	in	`DLManagedTensor*`	DLManagedTensor* training dataset on host or device memory
`graph`	inout	`DLManagedTensor*`	Optional preallocated graph on host memory to store output
`index`	out	`cuvsNNDescentIndex_t`	cuvsNNDescentIndex_t Newly built NN-Descent index

Returns

cuvsError_t