Approximate Nearest Neighbors - Approximate Nearest Neighbors - 5.3 English - 68552

AOCL API Guide (68552)
Document_ID
68552
Release_Date
2026-05-13
Version
5.3 English
class aoclda.neighbors.approximate_neighbors(n_neighbors=5, algorithm='ivfflat', metric='sqeuclidean', n_list=1, n_probe=1, kmeans_iter=10, train_fraction=1.0, seed=0)#

An Approximate Nearest Neighbors object.

Parameters:

  • n_neighbors (int, optional) – The number of nearest neighbors for kneighbors() queries. Default = 5.

  • algorithm (str, optional) – The algorithm used to compute the approximate nearest neighbors. Available options are ‘auto’ and ‘ivfflat’. Default = ‘ivfflat’.

  • metric (str, optional) – The metric used for the distance computation. Available metrics are ‘euclidean’, ‘sqeuclidean’ (squared Euclidean distances), ‘cosine’, and ‘inner product’. Default = ‘sqeuclidean’.

  • n_list (int, optional) – The number of inverted file lists (centroids) to construct. Default = 1.

  • n_probe (int, optional) – The number of lists to probe at search time. Default = 1.

  • kmeans_iter (int, optional) – Maximum number of k-means iterations to perform during training. Default = 10.

  • train_fraction (float, optional) – Proportion of training data to use for k-means clustering. Default = 1.0.

  • seed (int, optional) – Seed for random number generation. Set to -1 for non-deterministic results. Default = 0.

  • check_data (bool, optional) – Whether to check the data for NaNs. Default = False.

add(X_add)#

Add data points to the index. The model must be trained first.

Parameters:

X_add (array-like) – The data matrix to add to the index. Its shape is (n_samples_add, n_features).

Returns:

Returns the instance itself.

Return type:

self (object)

property cluster_centroids#

The centroid vectors computed during training.

Type:

numpy.ndarray of shape (n_list, n_features)

property kmeans_iter#

The number of k-means iterations performed during training.

Type:

int

kneighbors(X_test, n_neighbors=0, return_distance=True)#

Compute the approximate k nearest neighbors for each query point.

Parameters:

  • X_test (array-like) – The query data matrix. Its shape is (n_queries, n_features).

  • n_neighbors (int, optional) – The number of neighbors to return. If less than or equal to zero, uses the value set during initialization.

  • return_distance (bool, optional) – Whether to return the distances. Default = True.

Returns:

The distances to each neighbor.

Only returned if return_distance=True.

numpy.ndarray of shape (n_queries, n_neighbors): The indices of each neighbor.

Return type:

numpy.ndarray of shape (n_queries, n_neighbors)

property list_sizes#

The number of vectors assigned to each centroid.

Type:

numpy.ndarray of shape (n_list,)

property n_features#

The number of features in the indexed data.

Type:

int

property n_index#

The number of data points added to the index.

Type:

int

property n_list#

The number of inverted file lists (centroids).

Type:

int

property n_probe#

The number of lists to probe at search time.

train(X_train)#

Train the model by computing centroids using k-means clustering. Data is not added to the index; use add() to populate the index after training.

Parameters:

X_train (array-like) – The training data matrix. It has shape (n_samples, n_features).

Returns:

Returns the instance itself.

Return type:

self (object)

train_and_add(X_train)#

Train the model and add the training data to the index.

Parameters:

X_train (array-like) – The training data matrix. It has shape (n_samples, n_features).

Returns:

Returns the instance itself.

Return type:

self (object)

da_status da_approx_nn_set_training_data_s(da_handle handle, da_int n_samples, da_int n_features, const float *X_train, da_int ldx_train)#
da_status da_approx_nn_set_training_data_d(da_handle handle, da_int n_samples, da_int n_features, const double *X_train, da_int ldx_train)#

Pass a data matrix to the da_handle object in preparation for approximate nearest neighbor search.

The data itself is not copied; a pointer to the data matrix is stored instead.

After calling this function you may use the option setting APIs to set options.

Parameters:

  • handle – [inout] a da_handle object, initialized with type da_handle_approx_nn.

  • n_samples – [in] the number of rows in the data matrix, X_train. Constraint: n_samples \(\ge\) 1.

  • n_features – [in] the number of columns in the data matrix, X_train. Constraint: n_features \(\ge\) 1.

  • X_train – [in] array containing n_samples \(\times\) n_features data matrix. By default, it should be stored in column-major order, unless you have set the storage order option to row-major.

  • ldx_train – [in] leading dimension of X_train. Constraint: ldx_train \(\ge\) n_samples if X_train is stored in column-major order, or ldx_train \(\ge\) n_features if X_train is stored in row-major order.

Returns:

da_status. The function returns:

da_status da_approx_nn_train_s(da_handle handle)#
da_status da_approx_nn_train_d(da_handle handle)#

Train the approximate nearest neighbor index.

Trains the approximate nearest neighbor index using the data matrix previously passed into the handle using da_approx_nn_set_training_data_?.

Parameters:

handle – [inout] a da_handle object, initialized with type da_handle_approx_nn and with data passed in via da_approx_nn_set_training_data_?.

Returns:

da_status. The function returns:

Post:

After successful execution, da_handle_get_result_? can be queried with the following enums for floating-point output:

  • da_rinfo - return an array of size 4 containing n_list (the number of lists in the index), n_index (the number of samples currently in the index), n_features (the number of features) and kmeans_iter (the number of k-means iterations performed during training). Note: n_index is zero until da_approx_nn_add_? has been called.

  • da_approx_nn_cluster_centroids - return an array of size n_list \(\times\) n_features containing the coordinates of the cluster centroids, in the same storage format as the input data. In addition da_handle_get_result_int can be queried with the following enum:

  • da_approx_nn_list_sizes - return an array of size n_list containing the number of samples assigned to each list. Note: all entries of the array are zero until da_approx_nn_add_? has been called.

da_status da_approx_nn_add_s(da_handle handle, da_int n_samples_add, da_int n_features, const float *X_add, da_int ldx_add)#
da_status da_approx_nn_add_d(da_handle handle, da_int n_samples_add, da_int n_features, const double *X_add, da_int ldx_add)#

Add data points to the approximate nearest neighbor index.

Adds data points to an already trained approximate nearest neighbor index. The index must have been previously trained using da_approx_nn_train_?.

Parameters:

  • handle – [inout] a da_handle object, with the index previously trained via da_approx_nn_train_?.

  • n_samples_add – [in] the number of rows in the data matrix, X_add. Constraint: n_samples_add \(\ge\) 1.

  • n_features – [in] the number of columns in the data matrix, X_add. Constraint: n_features \(=\) the number of columns in the data matrix originally supplied to da_approx_nn_set_training_data_?.

  • X_add – [in] array containing n_samples_add \(\times\) n_features data matrix, in the same storage format used to set the training data.

  • ldx_add – [in] leading dimension of X_add. Constraint: ldx_add \(\ge\) n_samples_add if X_add is stored in column-major order, or ldx_add \(\ge\) n_features if X_add is stored in row-major order.

Returns:

da_status. The function returns:

da_status da_approx_nn_train_and_add_s(da_handle handle)#
da_status da_approx_nn_train_and_add_d(da_handle handle)#

Train the approximate nearest neighbor index and add the training data.

This is a convenience function that trains the approximate nearest neighbor index and adds the training data to the index in a single step. It is equivalent to calling da_approx_nn_train_? followed by da_approx_nn_add_? with the same training data. The training data must have been previously passed into the handle using da_approx_nn_set_training_data_?.

Parameters:

handle – [inout] a da_handle object, initialized with type da_handle_approx_nn and with data passed in via da_approx_nn_set_training_data_?.

Returns:

da_status. The function returns:

da_status da_approx_nn_kneighbors_s(da_handle handle, da_int n_queries, da_int n_features, const float *X_test, da_int ldx_test, da_int *n_ind, float *n_dist, da_int k, da_int return_distance)#
da_status da_approx_nn_kneighbors_d(da_handle handle, da_int n_queries, da_int n_features, const double *X_test, da_int ldx_test, da_int *n_ind, double *n_dist, da_int k, da_int return_distance)#

Compute approximate k-nearest neighbors.

Computes the approximate k-nearest neighbors of a test data \(X_{test}\) with respect to the data previously added to the index using da_approx_nn_add_? or da_approx_nn_train_and_add_?.

Parameters:

  • handle – [inout] a da_handle object, with data previously added to the index via da_approx_nn_add_? or da_approx_nn_train_and_add_?.

  • n_queries – [in] the number of rows in the data matrix, X_test. Constraint: n_queries \(\ge\) 1.

  • n_features – [in] the number of columns in the data matrix, X_test. Constraint: n_features \(=\) the number of columns in the data matrix originally supplied to da_approx_nn_set_training_data_?.

  • X_test – [in] array containing n_queries \(\times\) n_features data matrix, in the same storage format used to set the training data.

  • ldx_test – [in] leading dimension of X_test. Constraint: ldx_test \(\ge\) n_queries if X_test is stored in column-major order, or ldx_test \(\ge\) n_features if X_test is stored in row-major order.

  • n_ind – [out] array containing the n_queries \(\times\) k matrix, with the indices of the k approximate nearest neighbors for each query point. The indices correspond to the order in which data points were added to the index.

  • n_dist – [out] array containing the corresponding distances to the neighbors whose indices are stored in n_ind, if return_distance is 1.

  • k – [in] number of nearest neighbors requested. If k \(\le\) 0, the number of neighbors set via the options will be used instead. Constraint: k \(\le\) the number of samples added to the index.

  • return_distance – [in] denotes if the distances to the approximate nearest neighbors must be computed. If return_distance is 1, the distances are returned.

Returns:

da_status. The function returns: