diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3e35c05767..328a99e1a4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -51,6 +51,25 @@ repos: args: ["-fallback-style=none", "-style=file", "-i"] - repo: local hooks: + - id: fern-api-reference + name: fern-api-reference + description: 'Regenerate the Fern API reference pages from the sources' + entry: python3 fern/scripts/generate_api_reference.py --quiet + language: system + pass_filenames: false + require_serial: true + files: | + (?x) + ^c/include/.*[.](h|hpp)$| + ^cpp/include/.*[.](h|hpp|cuh)$| + ^python/cuvs/cuvs/.*[.](py|pyx|pxd)$| + ^java/cuvs-java/src/main/.*[.]java$| + ^rust/cuvs/src/.*[.]rs$| + ^go/.*[.]go$| + ^fern/scripts/generate_api_reference[.]py$| + ^fern/pages/(c|cpp|python|java|rust|go)_api/.*[.]md$| + ^fern/pages/api_reference[.]md$| + ^fern/docs[.]yml$ - id: no-deprecationwarning name: no-deprecationwarning description: 'Enforce that DeprecationWarning is not introduced (use FutureWarning instead)' diff --git a/fern/docs.yml b/fern/docs.yml index 2aafaea69e..9e47025b33 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -274,6 +274,8 @@ navigation: path: "./pages/c_api/c-api-cluster-mg-kmeans.md" - page: "Core C API" path: "./pages/c_api/c-api-core-c-api.md" + - page: "Core Dataset" + path: "./pages/c_api/c-api-core-dataset.md" - page: "Distance Distance" path: "./pages/c_api/c-api-distance-distance.md" - page: "Distance Pairwise Distance" @@ -329,6 +331,8 @@ navigation: path: "./pages/cpp_api/cpp-api-cluster-kmeans.md" - page: "Cluster Spectral" path: "./pages/cpp_api/cpp-api-cluster-spectral.md" + - page: "Core Bloom Filter" + path: "./pages/cpp_api/cpp-api-core-bloom-filter.md" - section: "Common Types" path: "./pages/cpp_api/cpp-api-common-types.md" contents: @@ -410,6 +414,8 @@ navigation: path: "./pages/cpp_api/cpp-api-util-cutlass-utils.md" - page: "Util File Io" path: "./pages/cpp_api/cpp-api-util-file-io.md" + - page: "Util Host Memory" + path: "./pages/cpp_api/cpp-api-util-host-memory.md" - section: "Python API Documentation" path: "./pages/python_api/index.md" contents: @@ -462,75 +468,81 @@ navigation: - section: "Java API Documentation" path: "./pages/java_api/index.md" contents: - - page: "Com Nvidia cuVS Cuvsdevicematrix" + - page: "CuVSDeviceMatrix" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsdevicematrix.md" - - page: "Com Nvidia cuVS Cuvshostmatrix" + - page: "CuVSHostMatrix" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvshostmatrix.md" - - page: "Com Nvidia cuVS Cuvsmatrix" + - page: "CuVSMatrix" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsmatrix.md" - - page: "Com Nvidia cuVS Spi Cuvsprovider" + - page: "CuVSProvider" path: "./pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md" - - page: "Com Nvidia cuVS Cuvsresources" + - page: "CuVSResources" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsresources.md" - - page: "Com Nvidia cuVS Cuvsresourcesinfo" + - page: "CuVSResourcesInfo" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsresourcesinfo.md" - - page: "Com Nvidia cuVS Spi Cuvsserviceprovider" + - page: "CuVSServiceProvider" path: "./pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsserviceprovider.md" - - page: "Com Nvidia cuVS Delegatingscopedaccess" + - page: "DelegatingScopedAccess" path: "./pages/java_api/java-api-com-nvidia-cuvs-delegatingscopedaccess.md" - - page: "Com Nvidia cuVS Gpuinfo" + - page: "FilterBitsetHandle" + path: "./pages/java_api/java-api-com-nvidia-cuvs-filterbitsethandle.md" + - page: "GPUInfo" path: "./pages/java_api/java-api-com-nvidia-cuvs-gpuinfo.md" - - page: "Com Nvidia cuVS Gpuinfoprovider" + - page: "GPUInfoProvider" path: "./pages/java_api/java-api-com-nvidia-cuvs-gpuinfoprovider.md" - - page: "Com Nvidia cuVS Libraryexception" + - page: "LibraryException" path: "./pages/java_api/java-api-com-nvidia-cuvs-libraryexception.md" - - page: "Com Nvidia cuVS Rowview" + - page: "RowView" path: "./pages/java_api/java-api-com-nvidia-cuvs-rowview.md" - - page: "Com Nvidia cuVS Synchronizedcuvsresources" + - page: "SynchronizedCuVSResources" path: "./pages/java_api/java-api-com-nvidia-cuvs-synchronizedcuvsresources.md" - - page: "Com Nvidia cuVS Bruteforceindex" + - page: "BruteForceIndex" path: "./pages/java_api/java-api-com-nvidia-cuvs-bruteforceindex.md" - - page: "Com Nvidia cuVS Bruteforceindexparams" + - page: "BruteForceIndexParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-bruteforceindexparams.md" - - page: "Com Nvidia cuVS Bruteforcequery" + - page: "BruteForceQuery" path: "./pages/java_api/java-api-com-nvidia-cuvs-bruteforcequery.md" - - page: "Com Nvidia cuVS Cagracompressionparams" + - page: "CagraCompressionParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagracompressionparams.md" - - page: "Com Nvidia cuVS Cagraindex" + - page: "CagraIndex" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md" - - page: "Com Nvidia cuVS Cagraindexparams" + - page: "CagraIndexParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagraindexparams.md" - - page: "Com Nvidia cuVS Cagramergeparams" + - page: "CagraMergeParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagramergeparams.md" - - page: "Com Nvidia cuVS Cagraquery" + - page: "CagraQuery" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagraquery.md" - - page: "Com Nvidia cuVS Cagrasearchparams" + - page: "CagraSearchParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cagrasearchparams.md" - - page: "Com Nvidia cuVS Cuvsaceparams" + - page: "CuVSAceParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsaceparams.md" - - page: "Com Nvidia cuVS Cuvsivfpqindexparams" + - page: "CuVSIvfPqIndexParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqindexparams.md" - - page: "Com Nvidia cuVS Cuvsivfpqparams" + - page: "CuVSIvfPqParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqparams.md" - - page: "Com Nvidia cuVS Cuvsivfpqsearchparams" + - page: "CuVSIvfPqSearchParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqsearchparams.md" - - page: "Com Nvidia cuVS Hnswaceparams" + - page: "HnswAceParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-hnswaceparams.md" - - page: "Com Nvidia cuVS Hnswindex" + - page: "HnswIndex" path: "./pages/java_api/java-api-com-nvidia-cuvs-hnswindex.md" - - page: "Com Nvidia cuVS Hnswindexparams" + - page: "HnswIndexParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-hnswindexparams.md" - - page: "Com Nvidia cuVS Hnswquery" + - page: "HnswQuery" path: "./pages/java_api/java-api-com-nvidia-cuvs-hnswquery.md" - - page: "Com Nvidia cuVS Hnswsearchparams" + - page: "HnswSearchParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-hnswsearchparams.md" - - page: "Com Nvidia cuVS Searchresults" + - page: "MultiPartitionCagraSearch" + path: "./pages/java_api/java-api-com-nvidia-cuvs-multipartitioncagrasearch.md" + - page: "MultiPartitionSearchResults" + path: "./pages/java_api/java-api-com-nvidia-cuvs-multipartitionsearchresults.md" + - page: "SearchResults" path: "./pages/java_api/java-api-com-nvidia-cuvs-searchresults.md" - - page: "Com Nvidia cuVS Tieredindex" + - page: "TieredIndex" path: "./pages/java_api/java-api-com-nvidia-cuvs-tieredindex.md" - - page: "Com Nvidia cuVS Tieredindexparams" + - page: "TieredIndexParams" path: "./pages/java_api/java-api-com-nvidia-cuvs-tieredindexparams.md" - - page: "Com Nvidia cuVS Tieredindexquery" + - page: "TieredIndexQuery" path: "./pages/java_api/java-api-com-nvidia-cuvs-tieredindexquery.md" - section: "Rust API Documentation" path: "./pages/rust_api/index.md" @@ -543,6 +555,8 @@ navigation: path: "./pages/rust_api/rust-api-cuvs-cluster-kmeans-params.md" - page: "cuVS" path: "./pages/rust_api/rust-api-cuvs.md" + - page: "cuVS Dataset" + path: "./pages/rust_api/rust-api-cuvs-dataset.md" - page: "cuVS Dlpack" path: "./pages/rust_api/rust-api-cuvs-dlpack.md" - page: "cuVS Error" @@ -553,6 +567,8 @@ navigation: path: "./pages/rust_api/rust-api-cuvs-neighbors-filters.md" - page: "cuVS Resources" path: "./pages/rust_api/rust-api-cuvs-resources.md" + - page: "cuVS Version" + path: "./pages/rust_api/rust-api-cuvs-version.md" - page: "cuVS Distance" path: "./pages/rust_api/rust-api-cuvs-distance.md" - page: "cuVS Neighbors Brute Force" diff --git a/fern/pages/c_api/c-api-cluster-kmeans.md b/fern/pages/c_api/c-api-cluster-kmeans.md index d2eb3efbcd..d715413db0 100644 --- a/fern/pages/c_api/c-api-cluster-kmeans.md +++ b/fern/pages/c_api/c-api-cluster-kmeans.md @@ -146,7 +146,7 @@ int* n_iter); Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm. -X may reside on either host (CPU) or device (GPU) memory. When X is on the host the data is streamed to the GPU in batches controlled by params->device_buffer_samples. +X may reside on either host (CPU) or device (GPU) memory. When X is on the host the data is buffered to the GPU in batches controlled by params->device_buffer_samples. **Parameters** diff --git a/fern/pages/c_api/c-api-cluster-mg-kmeans.md b/fern/pages/c_api/c-api-cluster-mg-kmeans.md index cfd3d4dd90..5305541d6f 100644 --- a/fern/pages/c_api/c-api-cluster-mg-kmeans.md +++ b/fern/pages/c_api/c-api-cluster-mg-kmeans.md @@ -14,7 +14,7 @@ _Source header: `cuvs/cluster/mg_kmeans.h`_ Find clusters with single-node multi-GPU k-means using host data. ```c -CUVS_EXPORT cuvsError_t cuvsMultiGpuKMeansFit(cuvsResources_t res, +cuvsError_t cuvsMultiGpuKMeansFit(cuvsResources_t res, cuvsKMeansParams_t params, DLManagedTensor* X, DLManagedTensor* sample_weight, @@ -39,4 +39,4 @@ X, sample_weight, and centroids must be host-accessible, row-major, C-contiguous **Returns** -[`CUVS_EXPORT cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) diff --git a/fern/pages/c_api/c-api-core-c-api.md b/fern/pages/c_api/c-api-core-c-api.md index 14a14ce46b..df84ff2435 100644 --- a/fern/pages/c_api/c-api-core-c-api.md +++ b/fern/pages/c_api/c-api-core-c-api.md @@ -152,6 +152,31 @@ cuvsError_t cuvsResourcesCreate(cuvsResources_t* res); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsResourcesCreateWithMemoryTracking + +Create an opaque C handle for C++ type `raft::resources` whose memory allocations are tracked and written as CSV samples from a background thread. + +```c +cuvsError_t cuvsResourcesCreateWithMemoryTracking(cuvsResources_t* res, +const char* csv_path, +int64_t sample_interval_ms); +``` + +The returned handle wraps all reachable memory resources (host, pinned, managed, device, workspace, large_workspace) with allocation-tracking adaptors and replaces the global host and device memory resources for the lifetime of the handle. It is otherwise indistinguishable from a handle created by ::cuvsResourcesCreate and can be used wherever a :cuvsResources_t is accepted. The CSV reporter is stopped and the global memory resources are restored when the handle is destroyed via :cuvsResourcesDestroy. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | out | [`cuvsResources_t*`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `csv_path` | in | `const char*` | Path to the output CSV file (created/truncated). Must be a non-empty, null-terminated UTF-8 string. | +| `sample_interval_ms` | in | `int64_t` | Minimum time in milliseconds between successive CSV samples. Pass 10 to match the C++ default. | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ### cuvsResourcesDestroy @@ -250,6 +275,27 @@ cuvsError_t cuvsDeviceIdGet(cuvsResources_t res, int* device_id); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsResourcesSetWorkspacePool + +Configure the temporary workspace on this resources object as an uncapped pool, backed by the current device memory resource. After the initial reservation is allocated on first use, subsequent calls to cuvsRMMAlloc / cuvsRMMFree on the same resources handle hit the pool cache rather than calling cudaMallocAsync / cudaFreeAsync, reducing CUDA context lock contention under concurrent query threads. The pool grows without shrinking: freed allocations are returned to the pool rather than to the device, so the pool's high-water mark only increases until the resources object is destroyed. + +```c +cuvsError_t cuvsResourcesSetWorkspacePool(cuvsResources_t res, +size_t initial_size_bytes); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `initial_size_bytes` | in | `size_t` | initial pool reservation in bytes; size to cover the steady-state working set to avoid growth after warmup | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ### cuvsMultiGpuResourcesCreate @@ -396,6 +442,19 @@ bool managed); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsRMMAsyncMemoryResourceEnable + +Switches the working memory resource to use stream-ordered asynchronous allocation (cudaMallocAsync / cudaFreeAsync). Unlike the pool resource, this resource returns memory to the stream immediately without blocking the CPU, eliminating device-wide synchronization on deallocation. This is especially beneficial when multiple CAGRA searches run concurrently on separate CUDA streams, because the internal workspace allocations no longer serialize kernel launches. Be aware that this function will change the memory resource for the whole process and the new memory resource will be used until explicitly changed. + +```c +cuvsError_t cuvsRMMAsyncMemoryResourceEnable(); +``` + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ### cuvsRMMMemoryResourceReset diff --git a/fern/pages/c_api/c-api-core-dataset.md b/fern/pages/c_api/c-api-core-dataset.md new file mode 100644 index 0000000000..1ea26bdaa5 --- /dev/null +++ b/fern/pages/c_api/c-api-core-dataset.md @@ -0,0 +1,74 @@ +--- +slug: api-reference/c-api-core-dataset +--- + +# Dataset + +_Source header: `cuvs/core/dataset.h`_ + +## Types + + +### cuvsDatasetLayout_t + +Generic dataset layout kind for C API dataset handles. + +```c +typedef enum { + CUVS_DATASET_LAYOUT_STANDARD = 0, + CUVS_DATASET_LAYOUT_PADDED = 1 +} cuvsDatasetLayout_t; +``` + +**Values** + +| Name | Value | +| --- | --- | +| `CUVS_DATASET_LAYOUT_STANDARD` | `0` | +| `CUVS_DATASET_LAYOUT_PADDED` | `1` | + + +### cuvsDatasetMemType_t + +Memory space holding a C API dataset handle's data. + +```c +typedef enum { + CUVS_DATASET_MEM_TYPE_HOST = 0, + CUVS_DATASET_MEM_TYPE_DEVICE = 1 +} cuvsDatasetMemType_t; +``` + +**Values** + +| Name | Value | +| --- | --- | +| `CUVS_DATASET_MEM_TYPE_HOST` | `0` | +| `CUVS_DATASET_MEM_TYPE_DEVICE` | `1` | + + +### destroy_addr + +Dataset handle representing owning storage or a non-owning view. + +`addr` points to C++ dataset storage or view metadata managed by the C API. `mem_type` identifies the memory space, `layout` identifies the data layout, and `is_owning` indicates whether the handle owns its backing data. + +```c +typedef struct { + uintptr_t addr; + DLDataType dtype; + cuvsDatasetMemType_t mem_type; + cuvsDatasetLayout_t layout; + bool is_owning; +} cuvsDataset; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `addr` | `uintptr_t` | | +| `dtype` | `DLDataType` | | +| `mem_type` | [`cuvsDatasetMemType_t`](/api-reference/c-api-core-dataset#cuvsdatasetmemtype-t) | | +| `layout` | [`cuvsDatasetLayout_t`](/api-reference/c-api-core-dataset#cuvsdatasetlayout-t) | | +| `is_owning` | `bool` | | diff --git a/fern/pages/c_api/c-api-neighbors-all-neighbors.md b/fern/pages/c_api/c-api-neighbors-all-neighbors.md index 9c15676edf..b7dc390e08 100644 --- a/fern/pages/c_api/c-api-neighbors-all-neighbors.md +++ b/fern/pages/c_api/c-api-neighbors-all-neighbors.md @@ -111,7 +111,9 @@ 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. Outputs always reside in device memory. +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** @@ -120,9 +122,9 @@ The function automatically detects whether the dataset is host-resident or devic | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | Can be a SNMG multi-GPU resources (`cuvsResources_t`) or single-GPU resources | | `params` | in | [`cuvsAllNeighborsIndexParams_t`](/api-reference/c-api-neighbors-all-neighbors#cuvsallneighborsindexparams) | Build parameters (see cuvsAllNeighborsIndexParams) | | `dataset` | in | `DLManagedTensor*` | 2D tensor [num_rows x dim] on host or device (auto-detected) | -| `indices` | out | `DLManagedTensor*` | 2D tensor [num_rows x k] on device (int64) | -| `distances` | out | `DLManagedTensor*` | Optional 2D tensor [num_rows x k] on device (float32); can be NULL | -| `core_distances` | out | `DLManagedTensor*` | Optional 1D tensor [num_rows] on device (float32); can be NULL | +| `indices` | out | `DLManagedTensor*` | 2D tensor [num_rows x k] (int64), host or device | +| `distances` | out | `DLManagedTensor*` | Optional 2D tensor [num_rows x k] (float32), host or device; can be NULL | +| `core_distances` | out | `DLManagedTensor*` | Optional 1D tensor [num_rows] (float32), host or device; can be NULL | | `alpha` | in | `float` | Mutual-reachability scaling; used only when core_distances is provided | **Returns** diff --git a/fern/pages/c_api/c-api-neighbors-cagra.md b/fern/pages/c_api/c-api-neighbors-cagra.md index d77cff2312..7af4269b6d 100644 --- a/fern/pages/c_api/c-api-neighbors-cagra.md +++ b/fern/pages/c_api/c-api-neighbors-cagra.md @@ -93,7 +93,7 @@ struct cuvsAceParams { | --- | --- | --- | | `npartitions` | `size_t` | Number of partitions for ACE (Augmented Core Extraction) partitioned build.

When set to 0 (default), the number of partitions is automatically derived based on available host and GPU memory to maximize partition size while ensuring the build fits in memory.

Small values might improve recall but potentially degrade performance and increase memory usage. Partitions should not be too small to prevent issues in KNN graph construction. The partition size is on average 2 * (n_rows / npartitions) * dim * sizeof(T). 2 is because of the core and augmented vectors. Please account for imbalance in the partition sizes (up to 3x in our tests).

If the specified number of partitions results in partitions that exceed available memory, the value will be automatically increased to fit memory constraints and a warning will be issued. | | `ef_construction` | `size_t` | The index quality for the ACE build.

Bigger values increase the index quality. At some point, increasing this will no longer improve the quality. | -| `build_dir` | `const char*` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph).

Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. | +| `build_dir` | `const char*` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph).

Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. The directory may already exist, but ACE's named artifacts must not already exist. Simultaneous builds must use different directories. On failure, ACE removes only artifacts it created and never deletes unrelated directory contents. | | `use_disk` | `bool` | Whether to use disk-based storage for ACE build.

When true, enables disk-based operations for memory-efficient graph construction. | | `max_host_memory_gb` | `double` | Maximum host memory to use for ACE build in GiB.

When set to 0 (default), uses available host memory. When set to a positive value, limits host memory usage to the specified amount. Useful for testing or when running alongside other memory-intensive processes. | | `max_gpu_memory_gb` | `double` | Maximum GPU memory to use for ACE build in GiB.

When set to 0 (default), uses available GPU memory. When set to a positive value, limits GPU memory usage to the specified amount. Useful for testing or when running alongside other memory-intensive processes. | @@ -110,7 +110,6 @@ struct cuvsCagraIndexParams { size_t graph_degree; enum cuvsCagraGraphBuildAlgo build_algo; size_t nn_descent_niter; - cuvsCagraCompressionParams_t compression; void* graph_build_params; }; ``` @@ -124,9 +123,58 @@ struct cuvsCagraIndexParams { | `graph_degree` | `size_t` | Degree of output graph. | | `build_algo` | [`enum cuvsCagraGraphBuildAlgo`](/api-reference/c-api-neighbors-cagra#cuvscagragraphbuildalgo) | ANN algorithm to build knn graph. | | `nn_descent_niter` | `size_t` | Number of Iterations to run if building with NN_DESCENT | -| `compression` | [`cuvsCagraCompressionParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagracompressionparams) | Optional: specify compression parameters if compression is desired.

NOTE: this is experimental new API, consider it unsafe. | | `graph_build_params` | `void*` | Optional: specify graph build params based on build_algo
- IVF_PQ: cuvsIvfPqParams_t
- ACE: cuvsAceParams_t
- Others: nullptr | + +### cuvsCagraMergeAlgo + +Algorithm used to merge physical CAGRA indices. + +```c +enum cuvsCagraMergeAlgo { + CUVS_CAGRA_MERGE_AUTO = 0, + CUVS_CAGRA_MERGE_FASTENER = 1, + CUVS_CAGRA_MERGE_REBUILD = 2 +}; +``` + +**Values** + +| Name | Value | +| --- | --- | +| `CUVS_CAGRA_MERGE_AUTO` | `0` | +| `CUVS_CAGRA_MERGE_FASTENER` | `1` | +| `CUVS_CAGRA_MERGE_REBUILD` | `2` | + + +### cuvsCagraMergeParams + +Parameters controlling how physical CAGRA indices are merged. + +```c +struct cuvsCagraMergeParams { + uint32_t levels; + uint32_t root_fanout; + uint32_t lower_fanout; + double leader_fraction; + uint32_t max_leaders; + uint32_t leaf_size; + uint32_t leaf_degree; +}; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `levels` | `uint32_t` | | +| `root_fanout` | `uint32_t` | | +| `lower_fanout` | `uint32_t` | | +| `leader_fraction` | `double` | | +| `max_leaders` | `uint32_t` | | +| `leaf_size` | `uint32_t` | | +| `leaf_degree` | `uint32_t` | | + ### cuvsCagraIndexParamsCreate @@ -165,6 +213,44 @@ cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t params); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsCagraMergeParamsCreate + +Allocate CAGRA merge params and populate them with AUTO defaults. + +```c +cuvsError_t cuvsCagraMergeParamsCreate(cuvsCagraMergeParams_t* params); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `params` | | [`cuvsCagraMergeParams_t*`](/api-reference/c-api-neighbors-cagra#cuvscagramergeparams) | | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + + +### cuvsCagraMergeParamsDestroy + +De-allocate CAGRA merge params. + +```c +cuvsError_t cuvsCagraMergeParamsDestroy(cuvsCagraMergeParams_t params); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `params` | | [`cuvsCagraMergeParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagramergeparams) | | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ### cuvsCagraCompressionParamsCreate @@ -274,6 +360,37 @@ This factory function creates CAGRA parameters that yield a graph compatible wit [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsCagraIndexParamsFromDataset + +Create CAGRA index parameters heuristically tuned for a dataset + +```c +cuvsError_t cuvsCagraIndexParamsFromDataset(cuvsCagraIndexParams_t params, +int64_t n_rows, +int64_t dim, +size_t graph_degree, +cuvsDistanceType metric, +size_t build_quality); +``` + +This factory function selects the graph build algorithm and its parameters based on the shape of the dataset. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `params` | out | [`cuvsCagraIndexParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindexparams) | The CAGRA index params to populate | +| `n_rows` | in | `int64_t` | Number of rows in the dataset | +| `dim` | in | `int64_t` | Number of dimensions in the dataset | +| `graph_degree` | in | `size_t` | Degree of the output graph | +| `metric` | in | [`cuvsDistanceType`](/api-reference/c-api-distance-distance#cuvsdistancetype) | Distance metric to use | +| `build_quality` | in | `size_t` | Higher values increase build quality (and cost) up to a point | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ## C API for CUDA ANN Graph-based nearest neighbor search @@ -334,19 +451,7 @@ cuvsError_t cuvsCagraExtendParamsDestroy(cuvsCagraExtendParams_t params); ### cuvsCagraExtend -Extend a CAGRA index using a caller-owned pre-concatenated device-padded -dataset view. The caller must build `extended_dataset` as `old || new` -before calling. Rows `[0, new_start_row)` are the original vectors; rows -`[new_start_row, n_rows)` are the additional vectors. `new_start_row` -must equal the current index size. The library only extends the graph -and rebinds the index to `extended_dataset`. - -Acceptable underlying types are: - -1. `kDLDataType.code == kDLFloat` and `kDLDataType.bits = 32` -2. `kDLDataType.code == kDLFloat` and `kDLDataType.bits = 16` -3. `kDLDataType.code == kDLInt` and `kDLDataType.bits = 8` -4. `kDLDataType.code == kDLUInt` and `kDLDataType.bits = 8` +Extend a CAGRA index with a caller-owned pre-concatenated padded dataset. ```c cuvsError_t cuvsCagraExtend(cuvsResources_t res, @@ -356,14 +461,16 @@ int64_t new_start_row, cuvsCagraIndex_t index); ``` +The caller must build `extended_dataset` as `old \|\| new` (size `n_old + n_new`) before calling. Rows `[0, new_start_row)` are the original vectors; rows `[new_start_row, n_rows)` are the additional vectors. `new_start_row` must equal the current index size. The library only extends the graph and rebinds the index to `extended_dataset`; keep that dataset alive for the index lifetime. + **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsCagraExtendParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraextendparams) | cuvsCagraExtendParams_t used to extend CAGRA index | -| `extended_dataset` | in | `cuvsDataset_t` | Caller-owned device-padded dataset already containing old \|\| new | -| `new_start_row` | in | `int64_t` | Row index where the additional vectors begin | +| `extended_dataset` | in | `cuvsDataset_t` | cuvsDataset_t caller-owned device-padded dataset of old \|\| new | +| `new_start_row` | in | `int64_t` | row index where the additional vectors begin | | `index` | in,out | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | cuvsCagraIndex_t CAGRA index | **Returns** @@ -506,10 +613,12 @@ cuvsError_t cuvsCagraSearchParamsDestroy(cuvsCagraSearchParams_t params); ### cuvsCagraIndex -Struct to hold address of cuvs::neighbors::cagra::index and its active trained dtype +Struct holding the CAGRA index storage address and vector element dtype (DLPack-style) + +Matches the usual cuVS C index pattern (`addr` + `dtype`). `addr` points at implementation-owned storage (not always a bare `cagra::index*`); free only via `cuvsCagraIndexDestroy`. `dtype` describes index vector elements for queries and template dispatch. ```c -typedef struct { +typedef struct cuvsCagraIndex { uintptr_t addr; DLDataType dtype; } cuvsCagraIndex; @@ -668,21 +777,43 @@ Note that the DLManagedTensor graph returned will have an associated 'deleter' f [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsCagraUpdateDataset + +Update a CAGRA index with a device-padded dataset. + +```c +cuvsError_t cuvsCagraUpdateDataset(cuvsResources_t res, +cuvsDataset_t device_padded_dataset, +cuvsCagraIndex_t index); +``` + +This is the centralized dataset update operation for C callers. If `index` is already device-padded, its dataset view is replaced in place. Otherwise, the index is converted and its opaque handle is rebound to a search-ready device-padded index. Caller retains ownership of + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `device_padded_dataset` | in | `cuvsDataset_t` | owning or non-owning device-padded dataset handle | +| `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | CAGRA index handle | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ## C API for CUDA ANN Graph-based nearest neighbor search ### cuvsCagraBuild -Build a CAGRA index from a dataset view handle. Acceptable underlying types are: +Build a CAGRA index from a dataset handle. Acceptable underlying types are: 1. `kDLDataType.code == kDLFloat` and `kDLDataType.bits = 32` 2. `kDLDataType.code == kDLFloat` and `kDLDataType.bits = 16` 3. `kDLDataType.code == kDLInt` and `kDLDataType.bits = 8` 4. `kDLDataType.code == kDLUInt` and `kDLDataType.bits = 8` -The memory space and layout `dataset` was constructed with select the C++ build overload. Build the -handle with the matching type-specific view factory; memory residency is inferred from the tensor. - ```c cuvsError_t cuvsCagraBuild(cuvsResources_t res, cuvsCagraIndexParams_t params, @@ -690,13 +821,17 @@ cuvsDataset_t dataset, cuvsCagraIndex_t index); ``` +The memory space and layout `dataset` was constructed with select the C++ build overload. Build the handle with an owning factory or the matching dataset view factory (`cuvsDatasetMakePaddedView` / `cuvsDatasetMakeStandardView`). + +Note that a dataset residing in host memory produces a host-backed index, which must be made search-ready with `cuvsCagraUpdateDataset` (using a device-padded dataset) before calling `cuvsCagraSearch`. + **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsCagraIndexParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindexparams) | cuvsCagraIndexParams_t used to build CAGRA index | -| `dataset` | in | `cuvsDataset_t` | Training dataset or dataset view | +| `dataset` | in | `cuvsDataset_t` | cuvsDataset_t training dataset or dataset view | | `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | cuvsCagraIndex_t Newly built CAGRA index. This index needs to be already created with cuvsCagraIndexCreate. | **Returns** @@ -740,6 +875,45 @@ cuvsFilter filter); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + +### cuvsCagraSearchMultiPartition + +Search multiple CAGRA index partitions concurrently and return the global top-k per query. + +```c +cuvsError_t cuvsCagraSearchMultiPartition(cuvsResources_t res, +cuvsCagraSearchParams_t params, +uint32_t num_partitions, +cuvsCagraIndex_t* indices, +DLManagedTensor* queries, +DLManagedTensor* partition_ids, +DLManagedTensor* neighbors, +DLManagedTensor* distances, +cuvsFilter* filters); +``` + +For each query row, the function searches all partitions in parallel into an internal intermediate buffer, applies per-partition distance post-processing, runs a batched top-k merge across partitions, and writes the final outputs to the caller-supplied device tensors. All work is submitted to the CUDA stream associated with `res`; use `cuvsStreamSync` to wait for completion. + +The index element type may be float32, float16, int8, or uint8. All partitions must share the same element type, and the queries must use that same type. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `params` | in | [`cuvsCagraSearchParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagrasearchparams) | search parameters (shared across partitions) | +| `num_partitions` | in | `uint32_t` | number of index partitions | +| `indices` | in | [`cuvsCagraIndex_t*`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | array of num_partitions cuvsCagraIndex_t pointers, all of the same element type | +| `queries` | in | `DLManagedTensor*` | DLManagedTensor* (device, same dtype as the indices, [n_queries, dim]); the queries matrix is searched against every partition | +| `partition_ids` | out | `DLManagedTensor*` | DLManagedTensor* (device, uint32, [n_queries, k]); which partition each returned neighbor came from | +| `neighbors` | out | `DLManagedTensor*` | DLManagedTensor* (device, uint32 or int64, [n_queries, k]); ordinal in the corresponding partition's dataset | +| `distances` | out | `DLManagedTensor*` | DLManagedTensor* (device, float32, [n_queries, k]); post-processed distance for each (query, neighbor) | +| `filters` | in | [`cuvsFilter*`](/api-reference/c-api-neighbors-common#cuvsfilter) | array of `num_partitions` filters, one per partition (or NULL for a fully unfiltered search). `filters[i]` applies to partition `i`: use \{.type=NO_FILTER, .addr=0\} for no filter on that partition, or \{.type=BITSET, .addr=ptr\} where ptr is a uintptr_t-cast DLManagedTensor* holding that partition's own bitset (one bit per vector in that partition; standard 32-bit packing). | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ## CAGRA C-API serialize functions @@ -770,7 +944,7 @@ Experimental, both the API and the serialization format are subject to change. ### cuvsCagraSerializeGraphAndDataset -Save the CAGRA graph and its attached host or device dataset to file. Returns an error without modifying the destination file if no dataset is attached. +Save the CAGRA graph and its attached dataset to file. ```c cuvsError_t cuvsCagraSerializeGraphAndDataset(cuvsResources_t res, @@ -778,13 +952,17 @@ const char* filename, cuvsCagraIndex_t index); ``` +The index stores a non-owning dataset view. The caller must keep the dataset backing that view alive while this function runs. Returns CUVS_ERROR without modifying the destination file if the index has no attached dataset. + +Experimental, both the API and the serialization format are subject to change. + **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `filename` | in | `const char*` | the file name for saving the graph and dataset | -| `index` | in | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | CAGRA index with an attached dataset | +| `index` | in | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | CAGRA index with an attached host or device dataset | **Returns** @@ -820,19 +998,25 @@ Experimental, both the API and the serialization format are subject to change. ### cuvsCagraDeserializeGraph -Load the graph from either serialized file form without retaining its dataset. +Load the CAGRA graph from file without retaining a serialized dataset. ```c -cuvsError_t cuvsCagraDeserializeGraph(cuvsResources_t res, const char* filename, cuvsCagraIndex_t index); +cuvsError_t cuvsCagraDeserializeGraph(cuvsResources_t res, +const char* filename, +cuvsCagraIndex_t index); ``` +This succeeds whether or not the file contains a dataset. Use cuvsCagraUpdateDataset to attach a caller-owned device-padded dataset view before searching the graph-only index. + +Experimental, both the API and the serialization format are subject to change. + **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `filename` | in | `const char*` | the name of the file that stores the index | -| `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Pre-created CAGRA index populated on success and unchanged on failure | +| `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | pre-created CAGRA index populated on success and unchanged on failure | **Returns** @@ -841,11 +1025,7 @@ cuvsError_t cuvsCagraDeserializeGraph(cuvsResources_t res, const char* filename, ### cuvsCagraDeserializeGraphAndDataset -Load the graph and dataset. The function allocates an owning dataset that preserves the -serialized host/device memory type and standard/padded layout. The caller must keep it alive while -the index uses its non-owning view and destroy it separately. Only a device-padded result is -immediately searchable through the C API; attach a caller-owned device-padded view with -`cuvsCagraUpdateDataset` for any other kind. +Load the CAGRA graph and dataset from file. ```c cuvsError_t cuvsCagraDeserializeGraphAndDataset(cuvsResources_t res, @@ -854,7 +1034,9 @@ cuvsCagraIndex_t index, cuvsDataset_t* out_dataset); ``` -Returns an error when the file has no dataset or the output pointer does not point to a null handle. The index and output remain unchanged on failure. +The returned owning dataset preserves the serialized host/device memory type and standard/padded layout. The index stores a non-owning view into it, so the caller must keep the dataset alive while the index uses it and destroy it separately with cuvsDatasetDestroy. Only a device-padded result is immediately searchable through the C API; attach a caller-owned device-padded view with cuvsCagraUpdateDataset for any other kind. The output pointer must point to a null handle on entry; deserialization acts as a factory and transfers ownership of the allocated dataset handle on success. Returns CUVS_ERROR when the file has no dataset; the index and output handle are unchanged on failure. + +Experimental, both the API and the serialization format are subject to change. **Parameters** @@ -862,8 +1044,8 @@ Returns an error when the file has no dataset or the output pointer does not poi | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `filename` | in | `const char*` | the name of the file that stores the graph and dataset | -| `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Pre-created CAGRA index populated on success and unchanged on failure | -| `out_dataset` | out | [`cuvsDataset_t`](/api-reference/c-api-core-dataset#cuvsdataset-t) | Receives the allocated owning dataset handle; must point to null on entry | +| `index` | inout | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | pre-created CAGRA index populated on success and unchanged on failure | +| `out_dataset` | out | `cuvsDataset_t*` | receives the allocated owning dataset handle; must point to null on entry | **Returns** @@ -913,7 +1095,7 @@ cuvsDataset_t merged_dataset, cuvsCagraIndex_t output_index); ``` -All input indices must have been built with the same data type (`index.dtype`) and have the same dimensionality (`index.dims`). The merged index uses the output parameters specified in `cuvsCagraIndexParams`. +All input indices must have been built with the same data type (`index.dtype`) and have the same dimensionality (`index.dims`). The merged index uses the output parameters specified in `cuvsCagraIndexParams`. The merge algorithm is selected automatically. Input indices must have: @@ -929,13 +1111,46 @@ Example: | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | -| `params` | in | [`cuvsCagraIndexParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindexparams) | cuvsCagraIndexParams_t parameters controlling merge behavior | +| `params` | in | [`cuvsCagraIndexParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindexparams) | cuvsCagraIndexParams_t parameters for the output index | | `indices` | in | [`cuvsCagraIndex_t*`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Array of input cuvsCagraIndex_t handles to merge | | `num_indices` | in | `size_t` | Number of input indices | | `filter` | in | [`cuvsFilter`](/api-reference/c-api-neighbors-common#cuvsfilter) | Filter that can be used to filter out vectors from the merged index | -| `merged_dataset` | out | `cuvsDataset_t` | Empty owning dataset handle. Merge allocates and populates its device storage using the input index layout. Keep it alive while using the output index. | +| `merged_dataset` | out | `cuvsDataset_t` | Empty owning dataset handle. Merge first attempts to allocate and populate device storage with the same layout as the input indices. For an unfiltered merge, if device allocation fails, it falls back to host storage and returns a host-backed output index. Keep this dataset alive while using `output_index`. A host-backed output index must be updated with `cuvsCagraUpdateDataset` before device search. | | `output_index` | out | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Output handle that will store the merged index. Must be initialized using `cuvsCagraIndexCreate` before use. | **Returns** [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + + +### cuvsCagraMergeWithParams + +Merge multiple CAGRA indices with explicit merge parameters. + +```c +cuvsError_t cuvsCagraMergeWithParams(cuvsResources_t res, +cuvsCagraIndexParams_t params, +cuvsCagraMergeParams_t merge_params, +cuvsCagraIndex_t* indices, +size_t num_indices, +cuvsFilter filter, +cuvsDataset_t merged_dataset, +cuvsCagraIndex_t output_index); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `params` | in | [`cuvsCagraIndexParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindexparams) | cuvsCagraIndexParams_t parameters for the output index | +| `merge_params` | in | [`cuvsCagraMergeParams_t`](/api-reference/c-api-neighbors-cagra#cuvscagramergeparams) | cuvsCagraMergeParams_t parameters controlling the merge algorithm, or NULL to use AUTO defaults | +| `indices` | in | [`cuvsCagraIndex_t*`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Array of input cuvsCagraIndex_t handles to merge | +| `num_indices` | in | `size_t` | Number of input indices | +| `filter` | in | [`cuvsFilter`](/api-reference/c-api-neighbors-common#cuvsfilter) | Filter that can be used to filter out vectors from the merged index | +| `merged_dataset` | out | `cuvsDataset_t` | Empty owning dataset handle. Merge first attempts to allocate and populate device storage with the same layout as the input indices. For an unfiltered merge, AUTO and REBUILD can fall back to host storage if device allocation fails; explicit FASTENER reports the allocation failure instead. Keep this dataset alive while using `output_index`. A host-backed output index must be updated with `cuvsCagraUpdateDataset` before device search. | +| `output_index` | out | [`cuvsCagraIndex_t`](/api-reference/c-api-neighbors-cagra#cuvscagraindex) | Output handle initialized with `cuvsCagraIndexCreate` | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) diff --git a/fern/pages/c_api/c-api-neighbors-common.md b/fern/pages/c_api/c-api-neighbors-common.md index 3c679f6946..53483246ff 100644 --- a/fern/pages/c_api/c-api-neighbors-common.md +++ b/fern/pages/c_api/c-api-neighbors-common.md @@ -34,6 +34,8 @@ enum cuvsFilterType { Struct to hold address of cuvs::neighbors::prefilter and its type +`addr` points to a filter object owned by the caller; the library performs no caching of the underlying bitset across search calls. Allocating and populating the device bitset may be more expensive than a single filtered search, so callers that issue repeated searches against the same filter (e.g. many queries over one index) should build the bitset once and reuse the same cuvsFilter across those calls rather than rebuild it per search. Reusing the bitset is essential for realizing the full throughput of filtered search. + ```c typedef struct { uintptr_t addr; diff --git a/fern/pages/c_api/c-api-neighbors-hnsw.md b/fern/pages/c_api/c-api-neighbors-hnsw.md index 497fe89584..4d46dbfa0e 100644 --- a/fern/pages/c_api/c-api-neighbors-hnsw.md +++ b/fern/pages/c_api/c-api-neighbors-hnsw.md @@ -55,7 +55,7 @@ struct cuvsHnswAceParams { | Name | Type | Description | | --- | --- | --- | | `npartitions` | `size_t` | Number of partitions for ACE partitioned build.

When set to 0 (default), the number of partitions is automatically derived based on available host and GPU memory to maximize partition size while ensuring the build fits in memory.

Small values might improve recall but potentially degrade performance and increase memory usage. The partition size is on average 2 * (n_rows / npartitions) * dim * sizeof(T). 2 is because of the core and augmented vectors. Please account for imbalance in the partition sizes (up to 3x in our tests).

If the specified number of partitions results in partitions that exceed available memory, the value will be automatically increased to fit memory constraints and a warning will be issued. | -| `build_dir` | `const char*` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph). Used when `use_disk` is true or when the graph does not fit in memory. | +| `build_dir` | `const char*` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph). Used when `use_disk` is true or when the graph does not fit in memory. The directory may already exist, but ACE's named artifacts and `hnsw_index.bin` must not already exist. Simultaneous builds must use different directories. On failure, ACE removes only its uncommitted CAGRA artifacts; a completed CAGRA stage is retained if creating the HNSW index fails. | | `use_disk` | `bool` | Whether to use disk-based storage for ACE build. When true, enables disk-based operations for memory-efficient graph construction. | | `max_host_memory_gb` | `double` | Maximum host memory to use for ACE build in GiB. When set to 0 (default), uses available host memory. Useful for testing or when running alongside other memory-intensive processes. | | `max_gpu_memory_gb` | `double` | Maximum GPU memory to use for ACE build in GiB. When set to 0 (default), uses available GPU memory. Useful for testing or when running alongside other memory-intensive processes. | @@ -296,8 +296,7 @@ DLManagedTensor* dataset, cuvsHnswIndex_t index); ``` -The graph is built on the GPU and converted to an HNSW index that can be searched on the CPU. -The graph build algorithm is selected automatically unless explicit ACE parameters are provided. +The graph is built on the GPU and converted to an HNSW index that can be searched on the CPU. The graph build algorithm is selected automatically unless explicit ACE parameters are provided. NOTE: This function requires CUDA to be available at runtime. diff --git a/fern/pages/c_api/c-api-neighbors-mg-cagra.md b/fern/pages/c_api/c-api-neighbors-mg-cagra.md index 4bcb60dee4..1a6d74adcd 100644 --- a/fern/pages/c_api/c-api-neighbors-mg-cagra.md +++ b/fern/pages/c_api/c-api-neighbors-mg-cagra.md @@ -218,6 +218,34 @@ cuvsMultiGpuCagraIndex_t index); [`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) +## Multi-GPU CAGRA index dataset update + + +### cuvsMultiGpuCagraUpdateDataset + +Update a Multi-GPU CAGRA index with a device-padded dataset. + +```c +cuvsError_t cuvsMultiGpuCagraUpdateDataset( +cuvsResources_t res, +cuvsDataset_t device_padded_dataset, +cuvsMultiGpuCagraIndex_t index); +``` + +Standard indexes are converted to device-padded indexes. Existing device-padded indexes are updated in place with the same layout. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | +| `device_padded_dataset` | in | `cuvsDataset_t` | caller-owned device-padded dataset view | +| `index` | in,out | [`cuvsMultiGpuCagraIndex_t`](/api-reference/c-api-neighbors-mg-cagra#cuvsmultigpucagraindex) | Multi-GPU CAGRA index | + +**Returns** + +[`cuvsError_t`](/api-reference/c-api-core-c-api#cuvserror-t) + ## Multi-GPU CAGRA index search diff --git a/fern/pages/c_api/c-api-preprocessing-pca.md b/fern/pages/c_api/c-api-preprocessing-pca.md index 4bfb7d7b51..c95bf324b2 100644 --- a/fern/pages/c_api/c-api-preprocessing-pca.md +++ b/fern/pages/c_api/c-api-preprocessing-pca.md @@ -112,14 +112,16 @@ bool flip_signs_based_on_U); Computes the principal components, explained variances, singular values, and column means from the input data. +The layout of `input` (C-contiguous / row-major or F-contiguous / col-major) is detected from its DLPack strides; `components` must use the same layout as `input`. + **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsPcaParams_t`](/api-reference/c-api-preprocessing-pca#cuvspcaparams) | PCA parameters | -| `input` | inout | `DLManagedTensor*` | input data [n_rows x n_cols] (col-major, float32, device) | -| `components` | out | `DLManagedTensor*` | principal components [n_components x n_cols] (col-major, float32, device) | +| `input` | inout | `DLManagedTensor*` | input data [n_rows x n_cols] (C- or F-contiguous, float32, device) | +| `components` | out | `DLManagedTensor*` | principal components [n_components x n_cols] (same layout as input) | | `explained_var` | out | `DLManagedTensor*` | explained variances [n_components] (float32, device) | | `explained_var_ratio` | out | `DLManagedTensor*` | explained variance ratios [n_components] (float32, device) | | `singular_vals` | out | `DLManagedTensor*` | singular values [n_components] (float32, device) | @@ -150,7 +152,7 @@ DLManagedTensor* noise_vars, bool flip_signs_based_on_U); ``` -Computes the principal components and transforms the input data into the eigenspace. +Computes the principal components and transforms the input data into the eigenspace. The layout of `input` (C- or F-contiguous) is detected from its DLPack strides; all other matrix tensors must use the same layout. **Parameters** @@ -158,9 +160,9 @@ Computes the principal components and transforms the input data into the eigensp | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsPcaParams_t`](/api-reference/c-api-preprocessing-pca#cuvspcaparams) | PCA parameters | -| `input` | inout | `DLManagedTensor*` | input data [n_rows x n_cols] (col-major, float32, device) | -| `trans_input` | out | `DLManagedTensor*` | transformed data [n_rows x n_components] (col-major, float32, device) | -| `components` | out | `DLManagedTensor*` | principal components [n_components x n_cols] (col-major, float32, device) | +| `input` | inout | `DLManagedTensor*` | input data [n_rows x n_cols] (C- or F-contiguous, float32, device) | +| `trans_input` | out | `DLManagedTensor*` | transformed data [n_rows x n_components] (same layout as input) | +| `components` | out | `DLManagedTensor*` | principal components [n_components x n_cols] (same layout as input) | | `explained_var` | out | `DLManagedTensor*` | explained variances [n_components] (float32, device) | | `explained_var_ratio` | out | `DLManagedTensor*` | explained variance ratios [n_components] (float32, device) | | `singular_vals` | out | `DLManagedTensor*` | singular values [n_components] (float32, device) | @@ -187,7 +189,7 @@ DLManagedTensor* mu, DLManagedTensor* trans_input); ``` -Transforms the input data into the eigenspace using previously computed principal components. +Transforms the input data into the eigenspace using previously computed principal components. The layout of `input` (C- or F-contiguous) is detected from its DLPack strides; all other matrix tensors must use the same layout. **Parameters** @@ -195,11 +197,11 @@ Transforms the input data into the eigenspace using previously computed principa | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsPcaParams_t`](/api-reference/c-api-preprocessing-pca#cuvspcaparams) | PCA parameters | -| `input` | inout | `DLManagedTensor*` | data to transform [n_rows x n_cols] (col-major, float32, device) | -| `components` | in | `DLManagedTensor*` | principal components [n_components x n_cols] (col-major, float32, device) | +| `input` | inout | `DLManagedTensor*` | data to transform [n_rows x n_cols] (C- or F-contiguous, float32, device) | +| `components` | in | `DLManagedTensor*` | principal components [n_components x n_cols] (same layout as input) | | `singular_vals` | in | `DLManagedTensor*` | singular values [n_components] (float32, device) | | `mu` | in | `DLManagedTensor*` | column means [n_cols] (float32, device) | -| `trans_input` | out | `DLManagedTensor*` | transformed data [n_rows x n_components] (col-major, float32, device) | +| `trans_input` | out | `DLManagedTensor*` | transformed data [n_rows x n_components] (same layout as input) | **Returns** @@ -220,7 +222,7 @@ DLManagedTensor* mu, DLManagedTensor* output); ``` -Transforms data from the eigenspace back to the original space. +Transforms data from the eigenspace back to the original space. The layout of `trans_input` (C- or F-contiguous) is detected from its DLPack strides; all other matrix tensors must use the same layout. **Parameters** @@ -228,11 +230,11 @@ Transforms data from the eigenspace back to the original space. | --- | --- | --- | --- | | `res` | in | [`cuvsResources_t`](/api-reference/c-api-core-c-api#cuvsresources-t) | cuvsResources_t opaque C handle | | `params` | in | [`cuvsPcaParams_t`](/api-reference/c-api-preprocessing-pca#cuvspcaparams) | PCA parameters | -| `trans_input` | in | `DLManagedTensor*` | transformed data [n_rows x n_components] (col-major, float32, device) | -| `components` | in | `DLManagedTensor*` | principal components [n_components x n_cols] (col-major, float32, device) | +| `trans_input` | in | `DLManagedTensor*` | transformed data [n_rows x n_components] (C- or F-contiguous, float32, device) | +| `components` | in | `DLManagedTensor*` | principal components [n_components x n_cols] (same layout as trans_input) | | `singular_vals` | in | `DLManagedTensor*` | singular values [n_components] (float32, device) | | `mu` | in | `DLManagedTensor*` | column means [n_cols] (float32, device) | -| `output` | out | `DLManagedTensor*` | reconstructed data [n_rows x n_cols] (col-major, float32, device) | +| `output` | out | `DLManagedTensor*` | reconstructed data [n_rows x n_cols] (same layout as trans_input) | **Returns** diff --git a/fern/pages/c_api/index.md b/fern/pages/c_api/index.md index d98f4cebe5..968ef01b0e 100644 --- a/fern/pages/c_api/index.md +++ b/fern/pages/c_api/index.md @@ -10,6 +10,7 @@ These pages are generated from the documented public headers in the cuVS source ## Common - [C API](/api-reference/c-api-core-c-api) +- [Dataset](/api-reference/c-api-core-dataset) ## Distance diff --git a/fern/pages/cpp_api/cpp-api-cluster-gmm.md b/fern/pages/cpp_api/cpp-api-cluster-gmm.md index df5afb1f17..66dff88db2 100644 --- a/fern/pages/cpp_api/cpp-api-cluster-gmm.md +++ b/fern/pages/cpp_api/cpp-api-cluster-gmm.md @@ -59,6 +59,8 @@ enum class init_method { Hyper-parameters for the Gaussian mixture EM solver. +All defaults match scikit-learn's ``GaussianMixture`` so that results are directly comparable out of the box. + ```cpp struct params { int n_components; @@ -136,6 +138,8 @@ When `warm_start` is true the incoming ``weights`` / ``means`` / ``covariances`` **Additional overload:** `cluster::gmm::fit` +Fit a Gaussian mixture with the EM algorithm. + ```cpp void fit(raft::resources const& handle, const params& params, @@ -152,6 +156,8 @@ raft::host_scalar_view converged, bool warm_start = false); ``` +Double-precision overload; see the single-precision overload for details. + **Parameters** | Name | Direction | Type | Description | @@ -207,6 +213,8 @@ raft::device_vector_view labels); **Additional overload:** `cluster::gmm::predict` +Hard component labels (argmax responsibility) for new data. + ```cpp void predict(raft::resources const& handle, const params& params, @@ -217,6 +225,8 @@ raft::device_vector_view precisions_chol, raft::device_vector_view labels); ``` +Double-precision overload; see the single-precision overload for details. + **Parameters** | Name | Direction | Type | Description | @@ -266,6 +276,8 @@ raft::device_matrix_view resp); **Additional overload:** `cluster::gmm::predict_proba` +Posterior responsibilities for new data. + ```cpp void predict_proba(raft::resources const& handle, const params& params, @@ -276,6 +288,8 @@ raft::device_vector_view precisions_chol, raft::device_matrix_view resp); ``` +Double-precision overload; see the single-precision overload for details. + **Parameters** | Name | Direction | Type | Description | @@ -325,6 +339,8 @@ raft::device_vector_view log_prob_norm); **Additional overload:** `cluster::gmm::score_samples` +Per-sample log-likelihood log p(x_i) for new data. + ```cpp void score_samples(raft::resources const& handle, const params& params, @@ -335,6 +351,8 @@ raft::device_vector_view precisions_chol, raft::device_vector_view log_prob_norm); ``` +Double-precision overload; see the single-precision overload for details. + **Parameters** | Name | Direction | Type | Description | diff --git a/fern/pages/cpp_api/cpp-api-cluster-kmeans.md b/fern/pages/cpp_api/cpp-api-cluster-kmeans.md index 4ad724c483..65e8dd62f2 100644 --- a/fern/pages/cpp_api/cpp-api-cluster-kmeans.md +++ b/fern/pages/cpp_api/cpp-api-cluster-kmeans.md @@ -60,35 +60,30 @@ struct params : base_params { | `verbosity` | `rapids_logger::level_enum` | verbosity level. | | `rng_state` | `raft::random::RngState` | Seed to the random number generator. | | `n_init` | `int` | Number of instance k-means algorithm will be run with different seeds. | -| `oversampling_factor` | `double` | Oversampling factor for use in the k-means\|\| algorithm | -| `batch_samples` | `int` | batch_samples and batch_centroids are used to tile 1NN computation which is useful to optimize/control the memory footprint
Default tile is [batch_samples x n_clusters] i.e. when batch_centroids is 0 then don't tile the centroids

NB: These parameters are unrelated to device_buffer_samples, which controls how many samples to transfer from host to device per batch when processing out-of-core data. | +| `oversampling_factor` | `double` | Oversampling factor for use in the k-means\|\| algorithm.

In the single-GPU path the value `0` is overloaded as an algorithm switch that selects the classic sequential k-means++ instead of the scalable variant. Any value `> 0` is used as-is.

In the multi-GPU path (a `fit` call issued with a multi-GPU `handle` and device-resident inputs) any value `< 1.0` (including `0`) is internally clamped to `1.0`. Values `>= 1.0` are passed through unchanged. | +| `batch_samples` | `int` | batch_samples and batch_centroids are used to tile 1NN computation which is useful to optimize/control the memory footprint
Default tile is [batch_samples x n_clusters] i.e. when batch_centroids is 0 then don't tile the centroids

NB: These parameters are unrelated to device_buffer_samples, which specifies the number of training vectors that get buffered on device when the training vectors are passed in on host. | | `batch_centroids` | `int` | if 0 then batch_centroids = n_clusters | | `init_size` | `int64_t` | Number of samples to randomly draw for the KMeansPlusPlus initialization step. A random subset of this size is used for centroid seeding.

Only applies when dataset is on host; for device data the full dataset is always used for seeding and this parameter is ignored.

When set to 0 (default) with host data uses `min(3 * n_clusters, n_samples)` as a default.

In Batched multi-GPU host-data fits, the effective KMeansPlusPlus initialization sample is materialized on device on every rank. Every rank must have enough GPU memory for this sample, and rank 0 must also have enough GPU memory for the seeding workspace.

Default: 0. | -| `device_buffer_samples` | `int64_t` | Number of samples to process per GPU batch when fitting with host data. When set to 0, defaults to n_samples (process all at once). Only used by the batched (host-data) code path and ignored by device-data overloads.

In multi-GPU mode, this is a per-rank batch size. Each rank processes up to this many local samples per batch, clamped to that rank's local sample count.
Default: 0 (process all data at once). | +| `device_buffer_samples` | `int64_t` | Number of samples to process per GPU batch when fitting with host data. When set to 0, defaults to n_samples (process all at once). Only used by the batched (host-data) code path and ignored by device-data overloads.

In multi-GPU mode this is a per-rank batch size: each rank processes up to this many local samples per batch, clamped to that rank's local sample count. This is is ignored by device-data overloads.
Default: 0 (process all data at once). | - -### cluster::kmeans::balanced_params + +### cluster::kmeans::balanced_donor_selection -Simple object to specify hyper-parameters to the balanced k-means algorithm. - -The following metrics are currently supported in k-means balanced: - -- CosineExpanded -- InnerProduct -- L2Expanded -- L2SqrtExpanded +Donor selection strategy used by balanced k-means rebalancing. ```cpp -struct balanced_params : base_params { - uint32_t n_iters; +enum class balanced_donor_selection { + SizeSorted = 0, + Random = 1 }; ``` -**Fields** +**Values** -| Name | Type | Description | -| --- | --- | --- | -| `n_iters` | `uint32_t` | Number of training iterations | +| Name | Value | +| --- | --- | +| `SizeSorted` | `0` | +| `Random` | `1` | ### cluster::kmeans::kmeans_type @@ -126,9 +121,11 @@ raft::host_scalar_view inertia, raft::host_scalar_view n_iter); ``` +Runs on multiple GPUs when `handle` carries an SNMG clique (`raft::resource::is_multi_gpu(handle)`) or initialized RAFT comms (`raft::resource::comms_initialized(handle)`), and on a single GPU otherwise. + TODO: Evaluate replacing the extent type with int64_t. Reference issue: https://github.com/nvidia/cuvs/issues/1961 -This overload supports out-of-core computation where the dataset resides on the host. Data is processed in GPU-sized batches, streaming from host to device. The batch size is controlled by params.device_buffer_samples. In multi-GPU mode, this is a per-rank batch size. +This overload supports out-of-core computation where the dataset resides on the host. Data is processed in batches, streaming from host to device. The batch size is controlled by `params.device_buffer_samples`. Multi-GPU dispatch is selected automatically based on the handle state: @@ -351,7 +348,7 @@ std::optional> inertia = std::nullopt); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | out | `raft::device_matrix_view` | [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `inertia` | out | `std::optional>` | Sum of squared distances of samples to their closest cluster center.
Default: `std::nullopt`. | @@ -377,7 +374,7 @@ std::optional> inertia = std::nullopt); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | inout | `raft::device_matrix_view` | [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `inertia` | out | `std::optional>` | Sum of squared distances of samples to their closest cluster center.
Default: `std::nullopt`. | @@ -403,7 +400,7 @@ std::optional> inertia = std::nullopt); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | inout | `raft::device_matrix_view` | [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `inertia` | out | `std::optional>` | Sum of squared distances of samples to their closest cluster center.
Default: `std::nullopt`. | @@ -429,7 +426,7 @@ std::optional> inertia = std::nullopt); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | inout | `raft::device_matrix_view` | [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `inertia` | out | `std::optional>` | Sum of squared distances of samples to their closest cluster center.
Default: `std::nullopt`. | @@ -584,7 +581,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -610,7 +607,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -636,7 +633,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -662,7 +659,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -688,7 +685,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -714,7 +711,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | New data to predict. [dim = n_samples x n_features] | | `centroids` | in | `raft::device_matrix_view` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -869,7 +866,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | inout | `raft::device_matrix_view` | Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -895,7 +892,7 @@ raft::device_vector_view labels); | Name | Direction | Type | Description | | --- | --- | --- | --- | | `handle` | in | `const raft::resources&` | The raft handle. | -| `params` | in | [`cuvs::cluster::kmeans::balanced_params const&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-balanced-params) | Parameters for KMeans model. | +| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. | | `X` | in | `raft::device_matrix_view` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] | | `centroids` | inout | `raft::device_matrix_view` | Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by 'centroids'. [dim = n_clusters x n_features] | | `labels` | out | `raft::device_vector_view` | Index of the cluster each sample in X belongs to. [len = n_samples] | @@ -1066,6 +1063,201 @@ std::optional> sample_weight = s `void` +## Multi-GPU / out-of-core k-means fit (multiple partitions per rank) + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU k-means fit with one or more local data partitions per rank. + +```cpp +void fit( +raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +Each rank supplies its local training data as a vector of partitions. For host-resident partitions the implementation streams each partition using `params.device_buffer_samples` (per rank). For device-resident partitions `device_buffer_samples` is ignored and each local partition is processed in full. + +The active backend is selected by the resources attached to `handle`: + +- When `raft::resource::is_multi_gpu(handle)` is true (SNMG clique), the call must be issued from inside an OpenMP region with one thread per rank in the clique. +- Otherwise, multi-process NCCL comms must be initialized on the handle (`raft::resource::comms_initialized(handle)`); each process supplies its own local partitions. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | The raft handle. Must have NCCL comms or a SNMG clique initialized. | +| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | K-means parameters. For host-resident partitions the per-rank streaming batch size is read from `params.device_buffer_samples`; it is ignored for device-resident partitions. | +| `X_parts` | in | `const std::vector>&` | Per-partition local data on this rank. Each entry is [n_rows_i x n_features]. | +| `sample_weight_parts` | in | `const std::optional>>&` | Optional per-partition row weights with one vector per data partition. | +| `centroids` | inout | `raft::device_matrix_view` | Device matrix [n_clusters x n_features]. On entry, used as the initial centers when `params.init == InitMethod::Array`. On return, holds the converged centroids. | +| `inertia` | out | `raft::host_scalar_view` | Host scalar receiving the final clustering cost. | +| `n_iter` | out | `raft::host_scalar_view` | Host scalar receiving the iteration count at which the run terminated. | + +**Returns** + +`void` + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU k-means fit. + +```cpp +void fit(raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& +sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | | +| `X_parts` | | `const std::vector>&` | | +| `sample_weight_parts` | | `const std::optional>>&` | | +| `centroids` | | `raft::device_matrix_view` | | +| `inertia` | | `raft::host_scalar_view` | | +| `n_iter` | | `raft::host_scalar_view` | | + +**Returns** + +`void` + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU k-means fit. + +```cpp +void fit(raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& +sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | | +| `X_parts` | | `const std::vector>&` | | +| `sample_weight_parts` | | `const std::optional>>&` | | +| `centroids` | | `raft::device_matrix_view` | | +| `inertia` | | `raft::host_scalar_view` | | +| `n_iter` | | `raft::host_scalar_view` | | + +**Returns** + +`void` + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU k-means fit. + +```cpp +void fit(raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& +sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | | +| `X_parts` | | `const std::vector>&` | | +| `sample_weight_parts` | | `const std::optional>>&` | | +| `centroids` | | `raft::device_matrix_view` | | +| `inertia` | | `raft::host_scalar_view` | | +| `n_iter` | | `raft::host_scalar_view` | | + +**Returns** + +`void` + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU / out-of-core k-means fit. + +```cpp +void fit(raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& +sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | | +| `X_parts` | | `const std::vector>&` | | +| `sample_weight_parts` | | `const std::optional>>&` | | +| `centroids` | | `raft::device_matrix_view` | | +| `inertia` | | `raft::host_scalar_view` | | +| `n_iter` | | `raft::host_scalar_view` | | + +**Returns** + +`void` + +**Additional overload:** `cluster::kmeans::fit` + +Multi-GPU / out-of-core k-means fit. + +```cpp +void fit(raft::resources const& handle, +const cuvs::cluster::kmeans::params& params, +const std::vector>& X_parts, +const std::optional>>& +sample_weight_parts, +raft::device_matrix_view centroids, +raft::host_scalar_view inertia, +raft::host_scalar_view n_iter); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | | +| `X_parts` | | `const std::vector>&` | | +| `sample_weight_parts` | | `const std::optional>>&` | | +| `centroids` | | `raft::device_matrix_view` | | +| `inertia` | | `raft::host_scalar_view` | | +| `n_iter` | | `raft::host_scalar_view` | | + +**Returns** + +`void` + ## k-means API helpers diff --git a/fern/pages/cpp_api/cpp-api-core-bloom-filter.md b/fern/pages/cpp_api/cpp-api-core-bloom-filter.md new file mode 100644 index 0000000000..f94f768042 --- /dev/null +++ b/fern/pages/cpp_api/cpp-api-core-bloom-filter.md @@ -0,0 +1,20 @@ +--- +slug: api-reference/cpp-api-core-bloom-filter +--- + +# Bloom Filter + +_Source header: `cuvs/core/bloom_filter.hpp`_ + +## Types + + +### core::bloom_filter + +cuVS-owned Bloom filter wrapper with opaque implementation. + +This class intentionally hides cuCollections types from the cuVS public API. The wrapper supports the expected bulk host APIs used by ANN workflows. + +```cpp +class bloom_filter; +``` diff --git a/fern/pages/cpp_api/cpp-api-neighbors-all-neighbors.md b/fern/pages/cpp_api/cpp-api-neighbors-all-neighbors.md index 5569e3ffbc..9a908bd2d2 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-all-neighbors.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-all-neighbors.md @@ -69,8 +69,8 @@ Usage example: | `handle` | in | `const raft::resources&` | raft::resources is an object managing resources | | `params` | in | [`const all_neighbors_params&`](/api-reference/cpp-api-neighbors-all-neighbors#neighbors-all-neighbors-all-neighbors-params) | an instance of all_neighbors::all_neighbors_params that are parameters to build all-neighbors knn graph | | `dataset` | in | `raft::host_matrix_view` | raft::host_matrix_view input dataset expected to be located in host memory | -| `indices` | out | `raft::device_matrix_view` | nearest neighbor indices of shape [n_row x k] | -| `distances` | out | `std::optional>` | nearest neighbor distances [n_row x k]
Default: `std::nullopt`. | +| `indices` | out | `raft::device_matrix_view` | nearest neighbor indices of shape [n_row x k] on device memory | +| `distances` | out | `std::optional>` | nearest neighbor distances [n_row x k] on device memory
Default: `std::nullopt`. | | `core_distances` | out | `std::optional>` | array for core distances of size [n_row]. Requires distances matrix to compute core_distances. If core_distances is given, the resulting indices and distances will be mutual reachability space.
Default: `std::nullopt`. | | `alpha` | in | `float` | distance scaling parameter as used in robust single linkage.
Default: `1.0`. | @@ -80,6 +80,39 @@ Usage example: **Additional overload:** `neighbors::all_neighbors::build` +Builds an approximate all-neighbors knn graph (find nearest neighbors for all the training vectors) + +```cpp +void build( +const raft::resources& handle, +const all_neighbors_params& params, +raft::host_matrix_view dataset, +raft::host_matrix_view indices, +std::optional> distances = std::nullopt, +std::optional> core_distances = std::nullopt, +float alpha = 1.0); +``` + +Usage example: + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `const raft::resources&` | raft::resources is an object managing resources | +| `params` | in | [`const all_neighbors_params&`](/api-reference/cpp-api-neighbors-all-neighbors#neighbors-all-neighbors-all-neighbors-params) | an instance of all_neighbors::all_neighbors_params that are parameters to build all-neighbors knn graph | +| `dataset` | in | `raft::host_matrix_view` | raft::host_matrix_view input dataset expected to be located in host memory | +| `indices` | out | `raft::host_matrix_view` | nearest neighbor indices of shape [n_row x k] on host memory | +| `distances` | out | `std::optional>` | nearest neighbor distances [n_row x k] on host memory
Default: `std::nullopt`. | +| `core_distances` | out | `std::optional>` | array for core distances of size [n_row] on host memory. Requires distances matrix to compute core_distances. If core_distances is given, the resulting indices and distances will be mutual reachability space.
Default: `std::nullopt`. | +| `alpha` | in | `float` | distance scaling parameter as used in robust single linkage.
Default: `1.0`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::all_neighbors::build` + Builds an approximate all-neighbors knn graph (find nearest neighbors for all the training vectors) params.n_clusters should be 1 for data on device. To use a larger params.n_clusters for efficient device memory usage, put data on host RAM. ```cpp @@ -102,8 +135,8 @@ Usage example: | `handle` | in | `const raft::resources&` | raft::resources is an object managing resources | | `params` | in | [`const all_neighbors_params&`](/api-reference/cpp-api-neighbors-all-neighbors#neighbors-all-neighbors-all-neighbors-params) | an instance of all_neighbors::all_neighbors_params that are parameters to build all-neighbors knn graph | | `dataset` | in | `raft::device_matrix_view` | raft::device_matrix_view input dataset expected to be located in device memory | -| `indices` | out | `raft::device_matrix_view` | nearest neighbor indices of shape [n_row x k] | -| `distances` | out | `std::optional>` | nearest neighbor distances [n_row x k]
Default: `std::nullopt`. | +| `indices` | out | `raft::device_matrix_view` | nearest neighbor indices of shape [n_row x k] on device memory | +| `distances` | out | `std::optional>` | nearest neighbor distances [n_row x k] on device memory
Default: `std::nullopt`. | | `core_distances` | out | `std::optional>` | array for core distances of size [n_row]. Requires distances matrix to compute core_distances. If core_distances is given, the resulting indices and distances will be mutual reachability space.
Default: `std::nullopt`. | | `alpha` | in | `float` | distance scaling parameter as used in robust single linkage.
Default: `1.0`. | diff --git a/fern/pages/cpp_api/cpp-api-neighbors-brute-force.md b/fern/pages/cpp_api/cpp-api-neighbors-brute-force.md index 1bab0cbd05..b5bdd6cc78 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-brute-force.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-brute-force.md @@ -71,6 +71,32 @@ Constructs a brute force index from a dataset. This lets us precompute norms for **Additional overload:** `neighbors::brute_force::index::index` +Construct a brute force index and take ownership of a row-major device dataset. + +```cpp +index(raft::resources const& res, +raft::device_matrix&& dataset, +std::optional>&& norms, +cuvs::distance::DistanceType metric, +DistT metric_arg = 0.0); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | | `raft::resources const&` | | +| `dataset` | | `raft::device_matrix&&` | | +| `norms` | | `std::optional>&&` | | +| `metric` | | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | | +| `metric_arg` | | `DistT` | Default: `0.0`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::brute_force::index::index` + Construct a brute force index from dataset ```cpp diff --git a/fern/pages/cpp_api/cpp-api-neighbors-cagra.md b/fern/pages/cpp_api/cpp-api-neighbors-cagra.md index 81699949a7..5f1865967d 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-cagra.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-cagra.md @@ -30,7 +30,7 @@ struct ace_params { | --- | --- | --- | | `npartitions` | `size_t` | Number of partitions for ACE (Augmented Core Extraction) partitioned build.

When set to 0 (default), the number of partitions is automatically derived based on available host and GPU memory to maximize partition size while ensuring the build fits in memory.

Small values might improve recall but potentially degrade performance and increase memory usage. Partitions should not be too small to prevent issues in KNN graph construction. The partition size is on average 2 * (n_rows / npartitions) * dim * sizeof(T). 2 is because of the core and augmented vectors. Please account for imbalance in the partition sizes (up to 3x in our tests).

If the specified number of partitions results in partitions that exceed available memory, the value will be automatically increased to fit memory constraints and a warning will be issued. | | `ef_construction` | `size_t` | The index quality for the ACE build.

Bigger values increase the index quality. At some point, increasing this will no longer improve the quality. | -| `build_dir` | `std::string` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph).

Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. | +| `build_dir` | `std::string` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph).

Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. The directory may already exist, but ACE's named artifacts must not already exist. Simultaneous builds must use different directories. On failure, ACE removes only artifacts it created and never deletes unrelated directory contents. | | `use_disk` | `bool` | Whether to use disk-based storage for ACE build.

When true, enables disk-based operations for memory-efficient graph construction. | | `max_host_memory_gb` | `double` | Maximum host memory to use for ACE build in GiB.

When set to 0 (default), uses available host memory. When set to a positive value, limits host memory usage to the specified amount. Useful for testing or when running alongside other memory-intensive processes. | | `max_gpu_memory_gb` | `double` | Maximum GPU memory to use for ACE build in GiB.

When set to 0 (default), uses available GPU memory. When set to a positive value, limits GPU memory usage to the specified amount. Useful for testing or when running alongside other memory-intensive processes. | @@ -70,6 +70,19 @@ struct vpq_params { | `max_train_points_per_pq_code` | `uint32_t` | The max number of data points to use per PQ code during PQ codebook training. Using more data points per PQ code may increase the quality of PQ codebook but may also increase the build time. We will use `pq_n_centers * max_train_points_per_pq_code` training points to train each PQ codebook. | | `max_train_points_per_vq_cluster` | `uint32_t` | The max number of data points to use per VQ cluster during training. | + +### graph_build_params_t + +CAGRA index build parameters + +```cpp +using graph_build_params_t = std::variant; +``` + ### neighbors::cagra::hnsw_heuristic_type @@ -81,6 +94,64 @@ Define how `cagra::index_params::from_hnsw_params` should construct a graph to c enum class hnsw_heuristic_type : uint32_t; ``` + +### neighbors::cagra::index_params::graph_build_heuristic + +Select the graph build algorithm and its parameters for a dataset. + +```cpp +static graph_build_params_t graph_build_heuristic( +raft::matrix_extent dataset, +size_t intermediate_graph_degree, +cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded, +size_t build_quality = 7); +``` + +This is the main CAGRA build heuristic: it chooses between NN-descent and IVF-PQ based on the dataset size and tunes their parameters based on the target intermediate graph degree and the requested build quality. It returns the `graph_build_params` variant only; the caller is responsible for setting `graph_degree` / `intermediate_graph_degree`. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `dataset` | | `raft::matrix_extent` | The shape of the input dataset | +| `intermediate_graph_degree` | | `size_t` | The intermediate (kNN) graph degree the build should target.
Note: the intermediate graph degree must be not smaller than the output graph degree; a good practice is to have it 1.5x to 2x of the desired graph_degree and a multiple of 32. | +| `metric` | | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | The distance metric to search
Default: `cuvs::distance::DistanceType::L2Expanded`. | +| `build_quality` | | `size_t` | Higher values increase the build quality (and cost) up to a point. Any value is valid, but values below 20 are the most practical (default = 7).
Default: `7`. | + +**Returns** + +[`static graph_build_params_t`](/api-reference/cpp-api-neighbors-cagra#graph-build-params-t) + + +### neighbors::cagra::index_params::from_dataset + +Create CAGRA index parameters heuristically tuned for a dataset. + +```cpp +static cagra::index_params from_dataset( +raft::matrix_extent dataset, +size_t graph_degree = 64, +cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded, +size_t build_quality = 7); +``` + +Returns default CAGRA `index_params` with `graph_build_params` selected by `graph_build_heuristic` for the given dataset. + +Usage example: + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `dataset` | | `raft::matrix_extent` | The shape of the input dataset | +| `graph_degree` | | `size_t` | Degree of the output graph.
Default: `64`. | +| `metric` | | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | The distance metric to search
Default: `cuvs::distance::DistanceType::L2Expanded`. | +| `build_quality` | | `size_t` | Higher values increase the build quality (and cost) up to a point. Any value is valid, but values below 20 are the most practical (default = 7).

Default: `7`. | + +**Returns** + +`static cagra::index_params` + ### neighbors::cagra::index_params::from_hnsw_params @@ -169,7 +240,9 @@ CAGRA index. The index stores the dataset and a kNN graph in device memory. ```cpp -template +template > struct index; ``` @@ -225,18 +298,31 @@ Graph degree `uint32_t` - -### neighbors::cagra::index::data + +### neighbors::cagra::index::graph_size + +Number of rows represented by the graph. + +```cpp +[[nodiscard]] constexpr inline auto graph_size() const noexcept -> IdxT; +``` + +**Returns** + +`IdxT` + + +### neighbors::cagra::index::dataset -Dataset [size, dim] +Non-owning dataset binding stored by the index. ```cpp -[[nodiscard]] inline auto data() const noexcept -> const cuvs::neighbors::dataset&; +[[nodiscard]] inline auto dataset() const noexcept -> DatasetViewT const&; ``` **Returns** -[`const cuvs::neighbors::dataset&`](/api-reference/cpp-api-neighbors-common#neighbors-dataset) +`DatasetViewT const&` ### neighbors::cagra::index::graph @@ -341,11 +427,13 @@ index(const index&) = delete; **Additional overload:** `neighbors::cagra::index::index` -Construct an empty index. +Construct a graph-only index with a zero-row dataset view placeholder. ```cpp -index(raft::resources const& res, -cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded); +explicit index(raft::resources const& res, +cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded) +requires(cuvs::neighbors::ann_dataset_view) +: cuvs::neighbors::index(),; ``` **Parameters** @@ -357,34 +445,28 @@ cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded); **Returns** -`void` +`explicit` **Additional overload:** `neighbors::cagra::index::index` -Construct an index from dataset and knn_graph arrays +Construct an index from a `dataset_view` and knn_graph. ```cpp -template +template index(raft::resources const& res, cuvs::distance::DistanceType metric, -raft::mdspan, raft::row_major, data_accessor> dataset, +DatasetViewT const& dataset, raft::mdspan, raft::row_major, graph_accessor> knn_graph); ``` -If the dataset and graph is already in GPU memory, then the index is just a thin wrapper around these that stores a non-owning a reference to the arrays. +Stores a shallow copy of the dataset view. The index stores a **non-owning** view; the caller must keep the underlying host or device storage alive for the index lifetime. -The constructor also accepts host arrays. In that case they are copied to the device, and the device arrays will be owned by the index. +Example — **non-owning** `make_device_padded_dataset_view` (wraps an existing device matrix; that matrix must outlive the index): -In case the dasates rows are not 16 bytes aligned, then we create a padded copy in device memory to ensure alignment for vectorized load. - -Usage examples: - -- Cagra index is normally created by the cagra::build In the above example, we have passed a host dataset to build. The returned index will own a device copy of the dataset and the knn_graph. In contrast, if we pass the dataset as a device_mdspan to build, then it will only store a reference to it. - -- Constructing index using existing knn-graph +Example — **owning** `make_device_padded_dataset` returns owning storage (`std::unique_ptr`). You must **keep that object alive** (e.g. hold the `unique_ptr` in a variable or member) for as long as the index uses the dataset; the index does not take ownership of the buffer. **Parameters** @@ -392,126 +474,52 @@ Usage examples: | --- | --- | --- | --- | | `res` | | `raft::resources const&` | | | `metric` | | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | | -| `dataset` | | `raft::mdspan, raft::row_major, data_accessor>` | | +| `dataset` | | `DatasetViewT const&` | | | `knn_graph` | | `raft::mdspan, raft::row_major, graph_accessor>` | | **Returns** `void` - -### neighbors::cagra::index::update_device_dataset_same_layout - -Replace the dataset with a new dataset. - -```cpp -void update_device_dataset_same_layout(raft::resources const& res, -raft::device_matrix_view dataset); -``` - -If the new dataset rows are aligned on 16 bytes, then only a reference is stored to the dataset. It is the caller's responsibility to ensure that dataset stays alive as long as the index. It is expected that the same set of vectors are used for update_device_dataset_same_layout and index build. - -Note: This will clear any precomputed dataset norms. - -**Parameters** - -| Name | Direction | Type | Description | -| --- | --- | --- | --- | -| `res` | | `raft::resources const&` | | -| `dataset` | | `raft::device_matrix_view` | | - -**Returns** - -`void` - -**Additional overload:** `neighbors::cagra::index::update_device_dataset_same_layout` - -Set the dataset reference explicitly to a device matrix view with padding. - -```cpp -void update_device_dataset_same_layout(raft::resources const& res, -raft::device_matrix_view dataset); -``` - -**Parameters** - -| Name | Direction | Type | Description | -| --- | --- | --- | --- | -| `res` | | `raft::resources const&` | | -| `dataset` | | `raft::device_matrix_view` | | - -**Returns** - -`void` - -**Additional overload:** `neighbors::cagra::index::update_device_dataset_same_layout` + +### neighbors::cagra::index::update_graph -Replace the dataset with a new dataset. +Replace the graph with a new graph. ```cpp -void update_device_dataset_same_layout(raft::resources const& res, -raft::host_matrix_view dataset); +void update_graph( +raft::resources const& res, +raft::device_matrix_view knn_graph); ``` -We create a copy of the dataset on the device. The index manages the lifetime of this copy. It is expected that the same set of vectors are used for update_device_dataset_same_layout and index build. - -Note: This will clear any precomputed dataset norms. +Since the new graph is a device array, we store a reference to that, and it is the caller's responsibility to ensure that knn_graph stays alive as long as the index. **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | | `res` | | `raft::resources const&` | | -| `dataset` | | `raft::host_matrix_view` | | +| `knn_graph` | | `raft::device_matrix_view` | | **Returns** `void` -**Additional overload:** `neighbors::cagra::index::update_device_dataset_same_layout` - -Replace the dataset with a new dataset. It is expected that the same set of vectors are used - -```cpp -template -auto update_device_dataset_same_layout(raft::resources const& res, DatasetT&& dataset) --> std::enable_if_t, DatasetT>>; -``` - -for update_device_dataset_same_layout and index build. - -Note: This will clear any precomputed dataset norms. - -**Parameters** - -| Name | Direction | Type | Description | -| --- | --- | --- | --- | -| `res` | | `raft::resources const&` | | -| `dataset` | | `DatasetT&&` | | - -**Returns** - -[`std::enable_if_t, DatasetT>>`](/api-reference/cpp-api-neighbors-common#neighbors-dataset) - - -### neighbors::cagra::index::update_graph +**Additional overload:** `neighbors::cagra::index::update_graph` -Replace the graph with a new graph. +Replace the graph by taking ownership of an existing device matrix. ```cpp -void update_graph( -raft::resources const& res, -raft::device_matrix_view knn_graph); +void update_graph(raft::resources const&, +raft::device_matrix&& knn_graph); ``` -Since the new graph is a device array, we store a reference to that, and it is the caller's responsibility to ensure that knn_graph stays alive as long as the index. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | | `raft::resources const&` | | -| `knn_graph` | | `raft::device_matrix_view` | | +| `arg1` | | `raft::resources const&` | | +| `knn_graph` | | `raft::device_matrix&&` | | **Returns** @@ -582,7 +590,8 @@ source_indices); `void` -**Additional overload:** `neighbors::cagra::index::update_dataset` + +### neighbors::cagra::index::update_dataset Update the dataset from a disk file using a file descriptor. @@ -651,456 +660,424 @@ This method configures the index to use a disk-based dataset mapping. The mappin ### neighbors::cagra::build -Build the index from the dataset for efficient search. +Build from a device padded dataset view (`float`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::device_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::device_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_padded_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::device_matrix_view` | a matrix view (device) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_padded_dataset_view const&` | device padded dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::device_padded_index` + +built `device_padded_index<float, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a device standard dataset view (`float`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::host_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::device_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_standard_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::host_matrix_view` | a matrix view (host) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_standard_dataset_view const&` | device standard dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::device_standard_index` + +built `device_standard_index<float, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a host padded dataset view (`float`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::device_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::host_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_padded_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::device_matrix_view` | a matrix view (device) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_padded_dataset_view const&` | host padded dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::host_padded_index` + +built `host_padded_index<float, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a host standard dataset view (`float`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::host_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::host_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_standard_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::host_matrix_view` | a matrix view (host) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_standard_dataset_view const&` | host standard dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::host_standard_index` + +built `host_standard_index<float, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a device padded dataset view (`half`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::device_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::device_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_padded_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) -- BitwiseHamming (currently only supported with NN-Descent and Iterative Search as the build algorithm, and only for int8_t and uint8_t data types) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::device_matrix_view` | a matrix view (device) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_padded_dataset_view const&` | device padded dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::device_padded_index` + +built `device_padded_index<half, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a device standard dataset view (`half`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::host_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::device_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_standard_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) -- BitwiseHamming (currently only supported with NN-Descent and Iterative Search as the build algorithm, and only for int8_t and uint8_t data types) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::host_matrix_view` | a matrix view (host) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_standard_dataset_view const&` | device standard dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::device_standard_index` + +built `device_standard_index<half, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a host padded dataset view (`half`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::device_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::host_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_padded_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) -- BitwiseHamming (currently only supported with NN-Descent and Iterative Search as the build algorithm, and only for int8_t and uint8_t data types) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::device_matrix_view` | a matrix view (device) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_padded_dataset_view const&` | host padded dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::host_padded_index` + +built `host_padded_index<half, uint32_t>` **Additional overload:** `neighbors::cagra::build` -Build the index from the dataset for efficient search. +Build from a host standard dataset view (`half`). ```cpp auto build(raft::resources const& res, const cuvs::neighbors::cagra::index_params& params, -raft::host_matrix_view dataset) --> cuvs::neighbors::cagra::index; +cuvs::neighbors::host_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_standard_index; ``` -The build consist of two steps: build an intermediate knn-graph, and optimize it to create the final graph. The index_params struct controls the node degree of these graphs. - -The following distance metrics are supported: - -- L2 -- InnerProduct (currently only supported with IVF-PQ as the build algorithm) -- CosineExpanded (dataset norms are computed as float regardless of input data type) -- L1 (currently only supported with NN-Descent and Iterative Search as the build algorithm) -- BitwiseHamming (currently only supported with NN-Descent and Iterative Search as the build algorithm, and only for int8_t and uint8_t data types) - -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `res` | in | `raft::resources const&` | | -| `params` | in | `const cuvs::neighbors::cagra::index_params&` | parameters for building the index | -| `dataset` | in | `raft::host_matrix_view` | a matrix view (host) to a row-major matrix [n_rows, dim] | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_standard_dataset_view const&` | host standard dataset view [n_rows, dim] | **Returns** -[`cuvs::neighbors::cagra::index`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) +`cuvs::neighbors::cagra::host_standard_index` -## CAGRA extend functions +built `host_standard_index<half, uint32_t>` - -### neighbors::cagra::extend +**Additional overload:** `neighbors::cagra::build` -Add new vectors to a CAGRA index +Build from a device padded dataset view (`int8_t`). ```cpp -void extend( -raft::resources const& handle, -const cagra::extend_params& params, -raft::device_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::device_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_padded_index; ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::device_matrix_view` | additional dataset on device memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_padded_dataset_view const&` | device padded dataset view [n_rows, dim] | **Returns** -`void` +`cuvs::neighbors::cagra::device_padded_index` -**Additional overload:** `neighbors::cagra::extend` +built `device_padded_index<int8_t, uint32_t>` -Add new vectors to a CAGRA index +**Additional overload:** `neighbors::cagra::build` + +Build from a device standard dataset view (`int8_t`). ```cpp -void extend( -raft::resources const& handle, -const cagra::extend_params& params, -raft::host_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::device_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_standard_index; ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::host_matrix_view` | additional dataset on host memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_standard_dataset_view const&` | device standard dataset view [n_rows, dim] | **Returns** -`void` +`cuvs::neighbors::cagra::device_standard_index` -**Additional overload:** `neighbors::cagra::extend` +built `device_standard_index<int8_t, uint32_t>` -Add new vectors to a CAGRA index +**Additional overload:** `neighbors::cagra::build` + +Build from a host padded dataset view (`int8_t`). ```cpp -void extend( -raft::resources const& handle, -const cagra::extend_params& params, -raft::device_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::host_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_padded_index; ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::device_matrix_view` | additional dataset on device memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_padded_dataset_view const&` | host padded dataset view [n_rows, dim] | **Returns** -`void` +`cuvs::neighbors::cagra::host_padded_index` -**Additional overload:** `neighbors::cagra::extend` +built `host_padded_index<int8_t, uint32_t>` -Add new vectors to a CAGRA index +**Additional overload:** `neighbors::cagra::build` + +Build from a host standard dataset view (`int8_t`). ```cpp -void extend( -raft::resources const& handle, -const cagra::extend_params& params, -raft::host_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::host_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_standard_index; ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::host_matrix_view` | additional dataset on host memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_standard_dataset_view const&` | host standard dataset view [n_rows, dim] | **Returns** -`void` +`cuvs::neighbors::cagra::host_standard_index` -**Additional overload:** `neighbors::cagra::extend` +built `host_standard_index<int8_t, uint32_t>` -Add new vectors to a CAGRA index +**Additional overload:** `neighbors::cagra::build` + +Build from a device padded dataset view (`uint8_t`). ```cpp -void extend( -raft::resources const& handle, -const cagra::extend_params& params, -raft::device_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::device_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_padded_index; ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::device_matrix_view` | additional dataset on device memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_padded_dataset_view const&` | device padded dataset view [n_rows, dim] | **Returns** -`void` +`cuvs::neighbors::cagra::device_padded_index` -**Additional overload:** `neighbors::cagra::extend` +built `device_padded_index<uint8_t, uint32_t>` -Add new vectors to a CAGRA index +**Additional overload:** `neighbors::cagra::build` + +Build from a device standard dataset view (`uint8_t`). ```cpp -void extend( -raft::resources const& handle, +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::device_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::device_standard_index; +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::device_standard_dataset_view const&` | device standard dataset view [n_rows, dim] | + +**Returns** + +`cuvs::neighbors::cagra::device_standard_index` + +built `device_standard_index<uint8_t, uint32_t>` + +**Additional overload:** `neighbors::cagra::build` + +Build from a host padded dataset view (`uint8_t`). + +```cpp +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::host_padded_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_padded_index; +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_padded_dataset_view const&` | host padded dataset view [n_rows, dim] | + +**Returns** + +`cuvs::neighbors::cagra::host_padded_index` + +built `host_padded_index<uint8_t, uint32_t>` + +**Additional overload:** `neighbors::cagra::build` + +Build from a host standard dataset view (`uint8_t`). + +```cpp +auto build(raft::resources const& res, +const cuvs::neighbors::cagra::index_params& params, +cuvs::neighbors::host_standard_dataset_view const& dataset) +-> cuvs::neighbors::cagra::host_standard_index; +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | `raft::resources const&` | raft resources | +| `params` | in | `const cuvs::neighbors::cagra::index_params&` | CAGRA index build parameters | +| `dataset` | in | `cuvs::neighbors::host_standard_dataset_view const&` | host standard dataset view [n_rows, dim] | + +**Returns** + +`cuvs::neighbors::cagra::host_standard_index` + +built `host_standard_index<uint8_t, uint32_t>` + +## CAGRA extend functions + + +### neighbors::cagra::extend + +Add new vectors to a CAGRA index + +```cpp +void extend(raft::resources const& handle, const cagra::extend_params& params, -raft::host_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +cuvs::neighbors::device_padded_dataset_view extended_dataset, +int64_t new_start_row, +cuvs::neighbors::cagra::device_padded_index& idx); ``` +Note: `extend` does not concatenate datasets. The caller owns the final dataset and must pre-populate a single padded device matrix of size `(n_old + n_new) x dim` (or overallocation with a view whose logical `n_rows` is `n_old + n_new`): + +- rows `[0, new_start_row)` hold the original vectors attached to `idx` +- rows `[new_start_row, n_rows)` hold the additional vectors `new_start_row` must equal `idx.size()` today. The library only extends the graph and rebinds the index to `extended_dataset`. Keep that view alive for the index lifetime. + Usage example: **Parameters** @@ -1109,10 +1086,9 @@ Usage example: | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | raft resources | | `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::host_matrix_view` | additional dataset on host memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `extended_dataset` | in | `cuvs::neighbors::device_padded_dataset_view` | caller-owned device-padded view already containing old \|\| new rows | +| `new_start_row` | in | `int64_t` | row index where the additional vectors begin (must equal `idx.size()`) | +| `idx` | in,out | `cuvs::neighbors::cagra::device_padded_index&` | CAGRA index; graph is extended and dataset view is rebound | **Returns** @@ -1120,31 +1096,25 @@ Usage example: **Additional overload:** `neighbors::cagra::extend` -Add new vectors to a CAGRA index +Add new vectors to a CAGRA index. See the float overload for the full contract. ```cpp -void extend( -raft::resources const& handle, +void extend(raft::resources const& handle, const cagra::extend_params& params, -raft::device_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +cuvs::neighbors::device_padded_dataset_view extended_dataset, +int64_t new_start_row, +cuvs::neighbors::cagra::device_padded_index& idx); ``` -Usage example: - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::device_matrix_view` | additional dataset on host memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | | +| `extended_dataset` | | `cuvs::neighbors::device_padded_dataset_view` | | +| `new_start_row` | | `int64_t` | | +| `idx` | | `cuvs::neighbors::cagra::device_padded_index&` | | **Returns** @@ -1152,55 +1122,82 @@ Usage example: **Additional overload:** `neighbors::cagra::extend` -Add new vectors to a CAGRA index +Add new vectors to a CAGRA index. See the float overload for the full contract. ```cpp -void extend( -raft::resources const& handle, +void extend(raft::resources const& handle, const cagra::extend_params& params, -raft::host_matrix_view additional_dataset, -cuvs::neighbors::cagra::index& idx, -std::optional> -new_dataset_buffer_view = std::nullopt, -std::optional> new_graph_buffer_view = std::nullopt); +cuvs::neighbors::device_padded_dataset_view extended_dataset, +int64_t new_start_row, +cuvs::neighbors::cagra::device_padded_index& idx); ``` -Usage example: +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | | +| `extended_dataset` | | `cuvs::neighbors::device_padded_dataset_view` | | +| `new_start_row` | | `int64_t` | | +| `idx` | | `cuvs::neighbors::cagra::device_padded_index&` | | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::extend` + +Add new vectors to a CAGRA index. See the float overload for the full contract. + +```cpp +void extend(raft::resources const& handle, +const cagra::extend_params& params, +cuvs::neighbors::device_padded_dataset_view extended_dataset, +int64_t new_start_row, +cuvs::neighbors::cagra::device_padded_index& idx); +``` **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | raft resources | -| `params` | in | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | extend params | -| `additional_dataset` | in | `raft::host_matrix_view` | additional dataset on host memory | -| `idx` | in,out | [`cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `new_dataset_buffer_view` | out | `std::optional>` | memory buffer view for the dataset including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets, cols must be the dimension of the dataset, and the stride must be the same as the original index dataset. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the dataset themselves.
Default: `std::nullopt`. | -| `new_graph_buffer_view` | out | `std::optional>` | memory buffer view for the graph including the additional part. The data will be copied from the current index in this function. The num rows must be the sum of the original and additional datasets and cols must be the graph degree. This view will be stored in the output index. It is the caller's responsibility to ensure that dataset stays alive as long as the index. This option is useful when users want to manage the memory space for the graph themselves.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `params` | | [`const cagra::extend_params&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-extend-params) | | +| `extended_dataset` | | `cuvs::neighbors::device_padded_dataset_view` | | +| `new_start_row` | | `int64_t` | | +| `idx` | | `cuvs::neighbors::cagra::device_padded_index&` | | **Returns** `void` -## CAGRA search functions +## CAGRA serialize functions - -### none_sample_filter + +### neighbors::cagra::serialized_dataset_kind -Search ANN using the constructed index. +Dense dataset storage kind recorded in a serialized CAGRA index. ```cpp -void search(raft::resources const& res, -cuvs::neighbors::cagra::search_params const& params, -const cuvs::neighbors::cagra::index& index, -raft::device_matrix_view queries, -raft::device_matrix_view neighbors, -raft::device_matrix_view distances, -const cuvs::neighbors::filtering::base_filter& sample_filter = -cuvs::neighbors::filtering::none_sample_filter{} +enum class serialized_dataset_kind : std::uint32_t { + none = 0, + device_padded = 1, + device_standard = 2, + host_padded = 3, + host_standard = 4 +}; ``` -## CAGRA serialize functions +**Values** + +| Name | Value | +| --- | --- | +| `none` | `0` | +| `device_padded` | `1` | +| `device_standard` | `2` | +| `host_padded` | `3` | +| `host_standard` | `4` | ### neighbors::cagra::serialize @@ -1210,7 +1207,7 @@ Save the index to file. ```cpp void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1222,7 +1219,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1235,9 +1232,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from file. ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, const std::string& filename, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1248,7 +1247,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the name of the file that stores the index | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the file includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1261,7 +1261,7 @@ Write the index to an output stream ```cpp void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1273,7 +1273,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1285,9 +1285,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from input stream ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, std::istream& is, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1298,7 +1300,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `is` | in | `std::istream&` | input stream | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the stream includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1311,7 +1314,7 @@ Save the index to file. ```cpp void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1323,7 +1326,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1335,9 +1338,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from file. ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, const std::string& filename, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1348,7 +1353,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the name of the file that stores the index | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the file includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1361,7 +1367,7 @@ Write the index to an output stream ```cpp void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1373,7 +1379,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1385,9 +1391,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from input stream ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, std::istream& is, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1398,7 +1406,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `is` | in | `std::istream&` | input stream | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the stream includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1411,7 +1420,7 @@ Save the index to file. ```cpp void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1423,7 +1432,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1435,9 +1444,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from file. ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, const std::string& filename, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1448,7 +1459,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the name of the file that stores the index | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the file includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1461,7 +1473,7 @@ Write the index to an output stream ```cpp void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1473,7 +1485,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1485,9 +1497,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from input stream ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, std::istream& is, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1498,7 +1512,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `is` | in | `std::istream&` | input stream | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the stream includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1511,7 +1526,7 @@ Save the index to file. ```cpp void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1523,7 +1538,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1535,9 +1550,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from file. ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, const std::string& filename, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1548,7 +1565,8 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `filename` | in | `const std::string&` | the name of the file that stores the index | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the file includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** @@ -1561,7 +1579,7 @@ Write the index to an output stream ```cpp void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, +const cuvs::neighbors::cagra::device_padded_index& index, bool include_dataset = true); ``` @@ -1573,7 +1591,7 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | | `include_dataset` | in | `bool` | Whether or not to write out the dataset to the file.
Default: `true`. | **Returns** @@ -1585,9 +1603,11 @@ Experimental, both the API and the serialization format are subject to change. Load index from input stream ```cpp -void deserialize(raft::resources const& handle, +void deserialize( +raft::resources const& handle, std::istream& is, -cuvs::neighbors::cagra::index* index); +cuvs::neighbors::cagra::device_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); ``` Experimental, both the API and the serialization format are subject to change. @@ -1598,249 +1618,894 @@ Experimental, both the API and the serialization format are subject to change. | --- | --- | --- | --- | | `handle` | in | `raft::resources const&` | the raft handle | | `is` | in | `std::istream&` | input stream | -| `index` | out | [`cuvs::neighbors::cagra::index*`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | the cagra index | +| `index` | out | `cuvs::neighbors::cagra::device_padded_index*` | the cagra index | +| `out_dataset` | out | `std::unique_ptr>*` | if non-null, on success may be set to an owned deserialized dataset when the stream includes dataset data; may be left unchanged otherwise. Optional; pass nullptr to ignore.
Default: `nullptr`. | **Returns** `void` - -### neighbors::cagra::serialize_to_hnswlib - -Write the CAGRA built index as a base layer HNSW index to an output stream +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, -std::ostream& os, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +void serialize(raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. +**Parameters** -Experimental, both the API and the serialization format are subject to change. +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); +``` **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Save a CAGRA build index in hnswlib base-layer-only serialized format +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Write the CAGRA built index as a base layer HNSW index to an output stream +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Save a CAGRA build index in hnswlib base-layer-only serialized format +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Write the CAGRA built index as a base layer HNSW index to an output stream +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Save a CAGRA build index in hnswlib base-layer-only serialized format +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Write the CAGRA built index as a base layer HNSW index to an output stream +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, std::ostream& os, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `os` | in | `std::ostream&` | output stream | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` -**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` - -Save a CAGRA build index in hnswlib base-layer-only serialized format +**Additional overload:** `neighbors::cagra::serialize` ```cpp -void serialize_to_hnswlib( -raft::resources const& handle, +void serialize(raft::resources const& handle, const std::string& filename, -const cuvs::neighbors::cagra::index& index, -std::optional> dataset = -std::nullopt); +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); ``` -NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. - -Experimental, both the API and the serialization format are subject to change. - **Parameters** | Name | Direction | Type | Description | | --- | --- | --- | --- | -| `handle` | in | `raft::resources const&` | the raft handle | -| `filename` | in | `const std::string&` | the file name for saving the index | -| `index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | CAGRA index | -| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | **Returns** `void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_padded_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize` + +```cpp +void serialize(raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_standard_index& index, +bool include_dataset = true); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `include_dataset` | | `bool` | Default: `true`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_padded_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_standard_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_standard_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_padded_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_standard_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_standard_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_padded_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_standard_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_standard_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_padded_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_padded_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::deserialize` + +```cpp +void deserialize( +raft::resources const& handle, +const std::string& filename, +cuvs::neighbors::cagra::host_standard_index* index, +std::unique_ptr>* out_dataset = nullptr); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `filename` | | `const std::string&` | | +| `index` | | `cuvs::neighbors::cagra::host_standard_index*` | | +| `out_dataset` | | `std::unique_ptr>*` | Default: `nullptr`. | + +**Returns** + +`void` + + +### neighbors::cagra::serialize_to_hnswlib + +Write the CAGRA built index as a base layer HNSW index to an output stream + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `os` | in | `std::ostream&` | output stream | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Save a CAGRA build index in hnswlib base-layer-only serialized format + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `filename` | in | `const std::string&` | the file name for saving the index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Write the CAGRA built index as a base layer HNSW index to an output stream + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `os` | in | `std::ostream&` | output stream | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Save a CAGRA build index in hnswlib base-layer-only serialized format + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `filename` | in | `const std::string&` | the file name for saving the index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Write the CAGRA built index as a base layer HNSW index to an output stream + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `os` | in | `std::ostream&` | output stream | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Save a CAGRA build index in hnswlib base-layer-only serialized format + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `filename` | in | `const std::string&` | the file name for saving the index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Write the CAGRA built index as a base layer HNSW index to an output stream + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `os` | in | `std::ostream&` | output stream | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Save a CAGRA build index in hnswlib base-layer-only serialized format + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +const std::string& filename, +const cuvs::neighbors::cagra::device_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +NOTE: The saved index can only be read by the hnswlib wrapper in cuVS, as the serialization format is not compatible with the original hnswlib. + +Experimental, both the API and the serialization format are subject to change. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | the raft handle | +| `filename` | in | `const std::string&` | the file name for saving the index | +| `index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | CAGRA index | +| `dataset` | in | `std::optional>` | [optional] host array that stores the dataset, required if the index does not contain the dataset.
Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Write the CAGRA built index as a base layer HNSW index to an output stream. + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_padded_index& index, +std::optional> dataset = +std::nullopt); +``` + +Requires `dataset` — host builds do not store vectors in the index. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `dataset` | | `std::optional>` | Default: `std::nullopt`. | + +**Returns** + +`void` + +**Additional overload:** `neighbors::cagra::serialize_to_hnswlib` + +Write the CAGRA built index as a base layer HNSW index to an output stream. + +```cpp +void serialize_to_hnswlib( +raft::resources const& handle, +std::ostream& os, +const cuvs::neighbors::cagra::host_standard_index& index, +std::optional> dataset = +std::nullopt); +``` + +Requires `dataset` — host builds do not store vectors in the index. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | | `raft::resources const&` | | +| `os` | | `std::ostream&` | | +| `index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `dataset` | | `std::optional>` | Default: `std::nullopt`. | + +**Returns** + +`void` + +## CAGRA index build functions + + +### neighbors::cagra::merge_algo + +CAGRA index build functions + +```cpp +enum class merge_algo { + FASTENER, + REBUILD +}; +``` + +**Values** + +| Name | Value | +| --- | --- | +| `FASTENER` | `` | +| `REBUILD` | `` | + + +### neighbors::cagra::merge_params + +C++ controls for physical CAGRA index merge. + +```cpp +struct merge_params { + merge_algo algo; + uint32_t levels; + uint32_t root_fanout; + uint32_t lower_fanout; + double leader_fraction; + uint32_t max_leaders; + uint32_t leaf_size; + uint32_t leaf_degree; +}; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `algo` | [`merge_algo`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-merge-algo) | | +| `levels` | `uint32_t` | | +| `root_fanout` | `uint32_t` | | +| `lower_fanout` | `uint32_t` | | +| `leader_fraction` | `double` | | +| `max_leaders` | `uint32_t` | | +| `leaf_size` | `uint32_t` | | +| `leaf_degree` | `uint32_t` | | diff --git a/fern/pages/cpp_api/cpp-api-neighbors-common.md b/fern/pages/cpp_api/cpp-api-neighbors-common.md index 73d8b64239..a15c57e2be 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-common.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-common.md @@ -62,29 +62,33 @@ enum class MergeStrategy { ### neighbors::dataset -Two-dimensional dataset; maybe owning, maybe compressed, maybe strided. +Tags selecting dataset representation for `dataset` / `dataset_view`. + +Each container defines nested `owning_storage` then `view_storage` (aliases into `detail::*` storage types shared by device/host). Accessibility (device vs host) is selected by the `Accessor` template parameter on `dataset` / `dataset_view`, not by duplicating containers. Layout kinds: empty, padded, standard, VPQ. `dataset` / `dataset_view` only express ownership vs view. ```cpp -template +template struct dataset; ``` - -### neighbors::device_vpq_dataset + +### math_type + +Floating-point type used for VQ/PQ codebooks (rows are still uint8 codes). -VPQ compressed dataset. +```cpp +using math_type = MathT; +``` -The dataset is compressed using two level quantization + +### neighbors::dataset_view_kind_of -1. Vector Quantization -2. Product Quantization of residuals +Primary template returns `unknown` so traits safely return `false` for non-dataset-view types. ```cpp -template -struct device_vpq_dataset : public dataset { - raft::device_matrix vq_code_book; - raft::device_matrix pq_code_book; - raft::device_matrix data; +template +struct dataset_view_kind_of { + static constexpr dataset_view_kind value; }; ``` @@ -92,9 +96,59 @@ struct device_vpq_dataset : public dataset { | Name | Type | Description | | --- | --- | --- | -| `vq_code_book` | `raft::device_matrix` | Vector Quantization codebook - "coarse cluster centers". | -| `pq_code_book` | `raft::device_matrix` | Product Quantization codebook - "fine cluster centers". | -| `data` | `raft::device_matrix` | Compressed dataset. | +| `value` | `static constexpr dataset_view_kind` | | + + +### neighbors::dataset_view_is_device_accessible + +True when the dataset view accessor is device-accessible. + +```cpp +template +struct dataset_view_is_device_accessible; +``` + + +### neighbors::with_accessor + +Generic accessor retargeting while preserving the dataset tag/layout and value/index types: + +`dataset<Tag, DataT, IdxT, OldAccessor> -> dataset<Tag, DataT, IdxT, NewAccessor>` `dataset_view<Tag, DataT, IdxT, OldAccessor> -> dataset_view<Tag, DataT, IdxT, NewAccessor>` + +```cpp +template +struct with_accessor; +``` + + +### neighbors::to_device_accessor + +Map any host accessor to its device counterpart (same payload policy). + +```cpp +template +struct to_device_accessor; +``` + + +### neighbors::device_counterpart + +Maps a host dataset view type to its device-resident counterpart. + +```cpp +template +struct device_counterpart; +``` + + +### neighbors::cagra_view_element_type + +Element type `T` for `cagra::build(res, params, dataset_view)` (deduced, not a template arg). + +```cpp +template +struct cagra_view_element_type; +``` ### neighbors::ivf::list_base @@ -144,10 +198,12 @@ SizeT> { Filtering for ANN Types ```cpp -enum class FilterType { - None, - Bitmap, - Bitset +enum class FilterType : int { + None = 0, + Bitmap = 1, + Bitset = 2, + Bloom = 3, + UDF = 100 }; ``` @@ -155,9 +211,11 @@ enum class FilterType { | Name | Value | | --- | --- | -| `None` | `` | -| `Bitmap` | `` | -| `Bitset` | `` | +| `None` | `0` | +| `Bitmap` | `1` | +| `Bitset` | `2` | +| `Bloom` | `3` | +| `UDF` | `100` | ### neighbors::filtering::none_sample_filter::operator @@ -277,6 +335,8 @@ FilterType get_filter_type() const override; Filter an index with a bitset +This filter holds a non-owning view of the bitset; it does not allocate or copy the underlying device buffer. The library performs no caching of the bitset across search calls. Allocating and populating the device bitset may be more expensive than a single filtered search, so callers that issue repeated searches against the same filter (e.g. many queries over one index) should build the bitset once and reuse it across those calls rather than rebuild it per search. Reusing the bitset is essential for realizing the full throughput of filtered search. + ```cpp template struct bitset_filter : public base_filter { @@ -318,6 +378,56 @@ FilterType get_filter_type() const override; [`FilterType`](/api-reference/cpp-api-neighbors-common#neighbors-filtering-filtertype) + +### neighbors::filtering::bloom_filter + +Filter CAGRA candidates with a global `cuvs::core::bloom_filter` over the index. + +Build the filter once on the host with bulk `add`() over the allowed dataset row ids and pass the owning `cuvs::core::bloom_filter` to this wrapper. CAGRA internals build/cache the device payload, similar to `bitset_filter`, and the linked JIT-LTO fragment probes the same filter for every query and candidate with probabilistic membership tests. + +Bloom filters have no false negatives: if a row was inserted, `contains` returns `true`. False positives are possible, so highly selective predicates may still need a bitset or UDF for exact filtering. + +This adapter is non-owning. The referenced `cuvs::core::bloom_filter` must outlive the adapter and any searches that use it, and must not be moved or mutated concurrently with a search. + +```cpp +struct bloom_filter : public base_filter { + void* filter_data; +}; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `filter_data` | `void*` | | + + +### neighbors::filtering::udf_filter + +JIT-LTO user-defined filter predicate. + +The source must define a device function named by `function_name` with signature: + +Return `true` to allow a source vector to appear in the results and `false` to reject it. UDF dereferences it. CAGRA currently provides `source_index_t` as `uint32_t` in the generated JIT fragment. + +```cpp +struct udf_filter : public base_filter { + std::string source; + void* filter_data; + float filtering_rate; + std::string function_name; +}; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `source` | `std::string` | CUDA C++ source containing the device predicate. | +| `filter_data` | `void*` | Opaque device-accessible pointer passed to the predicate. | +| `filtering_rate` | `float` | Estimated fraction of rows rejected by the predicate, or negative if unknown. | +| `function_name` | `std::string` | Device function name to call from the generated CAGRA sample filter. | + ## ANN MG index build parameters diff --git a/fern/pages/cpp_api/cpp-api-neighbors-hnsw.md b/fern/pages/cpp_api/cpp-api-neighbors-hnsw.md index e4a29faed5..c7cda26d07 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-hnsw.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-hnsw.md @@ -295,7 +295,7 @@ Construct an hnswlib index from a CAGRA index NOTE: When `hnsw::index_params.hie std::unique_ptr> from_cagra( raft::resources const& res, const index_params& params, -const cuvs::neighbors::cagra::index& cagra_index, +const cuvs::neighbors::cagra::device_padded_index& cagra_index, std::optional> dataset = std::nullopt); ``` @@ -308,7 +308,7 @@ Usage example: | --- | --- | --- | --- | | `res` | in | `raft::resources const&` | raft resources | | `params` | in | `const index_params&` | hnsw index parameters | -| `cagra_index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | cagra index | +| `cagra_index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | cagra index | | `dataset` | in | `std::optional>` | optional dataset to avoid extra memory copy when hierarchy is `CPU`

Default: `std::nullopt`. | **Returns** @@ -326,7 +326,7 @@ Construct an hnswlib index from a CAGRA index NOTE: When `hnsw::index_params.hie std::unique_ptr> from_cagra( raft::resources const& res, const index_params& params, -const cuvs::neighbors::cagra::index& cagra_index, +const cuvs::neighbors::cagra::device_padded_index& cagra_index, std::optional> dataset = std::nullopt); ``` @@ -339,7 +339,7 @@ Usage example: | --- | --- | --- | --- | | `res` | in | `raft::resources const&` | raft resources | | `params` | in | `const index_params&` | hnsw index parameters | -| `cagra_index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | cagra index | +| `cagra_index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | cagra index | | `dataset` | in | `std::optional>` | optional dataset to avoid extra memory copy when hierarchy is `CPU`

Default: `std::nullopt`. | **Returns** @@ -357,7 +357,7 @@ Construct an hnswlib index from a CAGRA index NOTE: When `hnsw::index_params.hie std::unique_ptr> from_cagra( raft::resources const& res, const index_params& params, -const cuvs::neighbors::cagra::index& cagra_index, +const cuvs::neighbors::cagra::device_padded_index& cagra_index, std::optional> dataset = std::nullopt); ``` @@ -370,7 +370,7 @@ Usage example: | --- | --- | --- | --- | | `res` | in | `raft::resources const&` | raft resources | | `params` | in | `const index_params&` | hnsw index parameters | -| `cagra_index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | cagra index | +| `cagra_index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | cagra index | | `dataset` | in | `std::optional>` | optional dataset to avoid extra memory copy when hierarchy is `CPU`

Default: `std::nullopt`. | **Returns** @@ -388,7 +388,7 @@ Construct an hnswlib index from a CAGRA index NOTE: When `hnsw::index_params.hie std::unique_ptr> from_cagra( raft::resources const& res, const index_params& params, -const cuvs::neighbors::cagra::index& cagra_index, +const cuvs::neighbors::cagra::device_padded_index& cagra_index, std::optional> dataset = std::nullopt); ``` @@ -401,13 +401,93 @@ Usage example: | --- | --- | --- | --- | | `res` | in | `raft::resources const&` | raft resources | | `params` | in | `const index_params&` | hnsw index parameters | -| `cagra_index` | in | [`const cuvs::neighbors::cagra::index&`](/api-reference/cpp-api-neighbors-cagra#neighbors-cagra-index) | cagra index | +| `cagra_index` | in | `const cuvs::neighbors::cagra::device_padded_index&` | cagra index | | `dataset` | in | `std::optional>` | optional dataset to avoid extra memory copy when hierarchy is `CPU`

Default: `std::nullopt`. | **Returns** [`std::unique_ptr>`](/api-reference/cpp-api-neighbors-hnsw#neighbors-hnsw-index) +**Additional overload:** `neighbors::hnsw::from_cagra` + +Construct an hnswlib index from a device-standard CAGRA index. + +```cpp +std::unique_ptr> from_cagra( +raft::resources const& res, +const index_params& params, +const cuvs::neighbors::cagra::device_standard_index& cagra_index, +std::optional> dataset = +std::nullopt); +``` + +When the index has an attached device dataset view, `dataset` may be omitted. Otherwise pass a host matrix with the vectors (same contract as `device_padded_index`). + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | | `raft::resources const&` | | +| `params` | | `const index_params&` | | +| `cagra_index` | | `const cuvs::neighbors::cagra::device_standard_index&` | | +| `dataset` | | `std::optional>` | Default: `std::nullopt`. | + +**Returns** + +[`std::unique_ptr>`](/api-reference/cpp-api-neighbors-hnsw#neighbors-hnsw-index) + +**Additional overload:** `neighbors::hnsw::from_cagra` + +Construct an hnswlib index from a host-built CAGRA index. Requires `dataset` for in-memory indices — host builds do not store vectors in the index. + +```cpp +std::unique_ptr> from_cagra( +raft::resources const& res, +const index_params& params, +const cuvs::neighbors::cagra::host_padded_index& cagra_index, +std::optional> dataset = +std::nullopt); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | | `raft::resources const&` | | +| `params` | | `const index_params&` | | +| `cagra_index` | | `const cuvs::neighbors::cagra::host_padded_index&` | | +| `dataset` | | `std::optional>` | Default: `std::nullopt`. | + +**Returns** + +[`std::unique_ptr>`](/api-reference/cpp-api-neighbors-hnsw#neighbors-hnsw-index) + +**Additional overload:** `neighbors::hnsw::from_cagra` + +Construct an hnswlib index from a host-built CAGRA index (standard dataset layout). Requires `dataset` for in-memory indices — host builds do not store vectors in the index. + +```cpp +std::unique_ptr> from_cagra( +raft::resources const& res, +const index_params& params, +const cuvs::neighbors::cagra::host_standard_index& cagra_index, +std::optional> dataset = +std::nullopt); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | | `raft::resources const&` | | +| `params` | | `const index_params&` | | +| `cagra_index` | | `const cuvs::neighbors::cagra::host_standard_index&` | | +| `dataset` | | `std::optional>` | Default: `std::nullopt`. | + +**Returns** + +[`std::unique_ptr>`](/api-reference/cpp-api-neighbors-hnsw#neighbors-hnsw-index) + ## Extend HNSW index with additional vectors diff --git a/fern/pages/cpp_api/cpp-api-neighbors-ivf-pq.md b/fern/pages/cpp_api/cpp-api-neighbors-ivf-pq.md index eea6eab87f..5fd636dfba 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-ivf-pq.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-ivf-pq.md @@ -2519,6 +2519,31 @@ Usage example: `void` + +### neighbors::ivf_pq::helpers::compressed_dataset_size + +Calculate the size of the compressed dataset. + +```cpp +size_t compressed_dataset_size(raft::resources const& res, +raft::matrix_extent dataset, +cuvs::neighbors::ivf_pq::index_params params); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | in | `raft::resources const&` | raft resource | +| `dataset` | in | `raft::matrix_extent` | shape of the dataset | +| `params` | | `cuvs::neighbors::ivf_pq::index_params` | | + +**Returns** + +`size_t` + +compressed dataset size in bytes + ### neighbors::ivf_pq::helpers::resize_list diff --git a/fern/pages/cpp_api/cpp-api-neighbors-ivf-rabitq.md b/fern/pages/cpp_api/cpp-api-neighbors-ivf-rabitq.md index fa39e69e98..85ee32818e 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-ivf-rabitq.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-ivf-rabitq.md @@ -2,7 +2,7 @@ slug: api-reference/cpp-api-neighbors-ivf-rabitq --- -# IVF RaBitQ +# IVF Rabitq _Source header: `cuvs/neighbors/ivf_rabitq.hpp`_ diff --git a/fern/pages/cpp_api/cpp-api-neighbors-vamana.md b/fern/pages/cpp_api/cpp-api-neighbors-vamana.md index f33e889ae2..d731acfb92 100644 --- a/fern/pages/cpp_api/cpp-api-neighbors-vamana.md +++ b/fern/pages/cpp_api/cpp-api-neighbors-vamana.md @@ -134,15 +134,18 @@ Graph degree ### neighbors::vamana::index::data -Dataset [size, dim] +Non-owning dataset view stored by the index (full-precision vectors may live in ```cpp -[[nodiscard]] inline auto data() const noexcept -> const cuvs::neighbors::dataset&; +[[nodiscard]] inline auto data() const noexcept +-> const cuvs::neighbors::device_padded_dataset_view&; ``` +`full_precision_storage_`). + **Returns** -[`const cuvs::neighbors::dataset&`](/api-reference/cpp-api-neighbors-common#neighbors-dataset) +`const cuvs::neighbors::device_padded_dataset_view&` ### neighbors::vamana::index::quantized_data diff --git a/fern/pages/cpp_api/cpp-api-preprocessing-pca.md b/fern/pages/cpp_api/cpp-api-preprocessing-pca.md index b360b3ea42..24953bd585 100644 --- a/fern/pages/cpp_api/cpp-api-preprocessing-pca.md +++ b/fern/pages/cpp_api/cpp-api-preprocessing-pca.md @@ -40,7 +40,7 @@ struct params { ### preprocessing::pca::fit -Perform PCA fit operation. +Perform PCA fit operation (col-major input). ```cpp void fit(raft::resources const& handle, @@ -76,10 +76,48 @@ Computes the principal components, explained variances, singular values, and col `void` +**Additional overload:** `preprocessing::pca::fit` + +Perform PCA fit operation (row-major input). + +```cpp +void fit(raft::resources const& handle, +const params& config, +raft::device_matrix_view input, +raft::device_matrix_view components, +raft::device_vector_view explained_var, +raft::device_vector_view explained_var_ratio, +raft::device_vector_view singular_vals, +raft::device_vector_view mu, +raft::device_scalar_view noise_vars, +bool flip_signs_based_on_U = false); +``` + +Same as the col-major overload, but operates natively on row-major (C-contiguous) data with no internal copy/transpose of the input. The output `components` matrix is also row-major. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | raft resource handle | +| `config` | in | [`const params&`](/api-reference/cpp-api-preprocessing-pca#preprocessing-pca-params) | PCA parameters | +| `input` | inout | `raft::device_matrix_view` | input data [n_rows x n_cols] (row-major). Modified temporarily. | +| `components` | out | `raft::device_matrix_view` | principal components [n_components x n_cols] (row-major) | +| `explained_var` | out | `raft::device_vector_view` | explained variances [n_components] | +| `explained_var_ratio` | out | `raft::device_vector_view` | explained variance ratios [n_components] | +| `singular_vals` | out | `raft::device_vector_view` | singular values [n_components] | +| `mu` | out | `raft::device_vector_view` | column means [n_cols] | +| `noise_vars` | out | `raft::device_scalar_view` | noise variance (scalar) | +| `flip_signs_based_on_U` | in | `bool` | whether to determine signs by U (true) or V.T (false)
Default: `false`. | + +**Returns** + +`void` + ### preprocessing::pca::fit_transform -Perform PCA fit and transform operations. +Perform PCA fit and transform operations (col-major). ```cpp void fit_transform(raft::resources const& handle, @@ -117,10 +155,50 @@ Computes the principal components and transforms the input data into the eigensp `void` +**Additional overload:** `preprocessing::pca::fit_transform` + +Perform PCA fit and transform operations (row-major). + +```cpp +void fit_transform(raft::resources const& handle, +const params& config, +raft::device_matrix_view input, +raft::device_matrix_view trans_input, +raft::device_matrix_view components, +raft::device_vector_view explained_var, +raft::device_vector_view explained_var_ratio, +raft::device_vector_view singular_vals, +raft::device_vector_view mu, +raft::device_scalar_view noise_vars, +bool flip_signs_based_on_U = false); +``` + +Same as the col-major overload but operates natively on row-major data. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | raft resource handle | +| `config` | in | [`const params&`](/api-reference/cpp-api-preprocessing-pca#preprocessing-pca-params) | PCA parameters | +| `input` | inout | `raft::device_matrix_view` | input data [n_rows x n_cols] (row-major). Modified temporarily. | +| `trans_input` | out | `raft::device_matrix_view` | transformed data [n_rows x n_components] (row-major) | +| `components` | out | `raft::device_matrix_view` | principal components [n_components x n_cols] (row-major) | +| `explained_var` | out | `raft::device_vector_view` | explained variances [n_components] | +| `explained_var_ratio` | out | `raft::device_vector_view` | explained variance ratios [n_components] | +| `singular_vals` | out | `raft::device_vector_view` | singular values [n_components] | +| `mu` | out | `raft::device_vector_view` | column means [n_cols] | +| `noise_vars` | out | `raft::device_scalar_view` | noise variance (scalar) | +| `flip_signs_based_on_U` | in | `bool` | whether to determine signs by U (true) or V.T (false)
Default: `false`. | + +**Returns** + +`void` + ### preprocessing::pca::transform -Perform PCA transform operation. +Perform PCA transform operation (col-major). ```cpp void transform(raft::resources const& handle, @@ -150,10 +228,40 @@ Transforms the input data into the eigenspace using previously computed principa `void` +**Additional overload:** `preprocessing::pca::transform` + +Perform PCA transform operation (row-major). + +```cpp +void transform(raft::resources const& handle, +const params& config, +raft::device_matrix_view input, +raft::device_matrix_view components, +raft::device_vector_view singular_vals, +raft::device_vector_view mu, +raft::device_matrix_view trans_input); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | raft resource handle | +| `config` | in | [`const params&`](/api-reference/cpp-api-preprocessing-pca#preprocessing-pca-params) | PCA parameters | +| `input` | inout | `raft::device_matrix_view` | data to transform [n_rows x n_cols] (row-major). Modified temporarily (mean-centered then restored). | +| `components` | in | `raft::device_matrix_view` | principal components [n_components x n_cols] (row-major) | +| `singular_vals` | in | `raft::device_vector_view` | singular values [n_components] | +| `mu` | in | `raft::device_vector_view` | column means [n_cols] | +| `trans_input` | out | `raft::device_matrix_view` | transformed data [n_rows x n_components] (row-major) | + +**Returns** + +`void` + ### preprocessing::pca::inverse_transform -Perform PCA inverse transform operation. +Perform PCA inverse transform operation (col-major). ```cpp void inverse_transform(raft::resources const& handle, @@ -182,3 +290,33 @@ Transforms data from the eigenspace back to the original space. **Returns** `void` + +**Additional overload:** `preprocessing::pca::inverse_transform` + +Perform PCA inverse transform operation (row-major). + +```cpp +void inverse_transform(raft::resources const& handle, +const params& config, +raft::device_matrix_view trans_input, +raft::device_matrix_view components, +raft::device_vector_view singular_vals, +raft::device_vector_view mu, +raft::device_matrix_view output); +``` + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `handle` | in | `raft::resources const&` | raft resource handle | +| `config` | in | [`const params&`](/api-reference/cpp-api-preprocessing-pca#preprocessing-pca-params) | PCA parameters | +| `trans_input` | in | `raft::device_matrix_view` | transformed data [n_rows x n_components] (row-major) | +| `components` | in | `raft::device_matrix_view` | principal components [n_components x n_cols] (row-major) | +| `singular_vals` | in | `raft::device_vector_view` | singular values [n_components] | +| `mu` | in | `raft::device_vector_view` | column means [n_cols] | +| `output` | out | `raft::device_matrix_view` | reconstructed data [n_rows x n_cols] (row-major) | + +**Returns** + +`void` diff --git a/fern/pages/cpp_api/cpp-api-preprocessing-quantize-pq.md b/fern/pages/cpp_api/cpp-api-preprocessing-quantize-pq.md index b70c451b3f..caa67fd80d 100644 --- a/fern/pages/cpp_api/cpp-api-preprocessing-quantize-pq.md +++ b/fern/pages/cpp_api/cpp-api-preprocessing-quantize-pq.md @@ -103,7 +103,7 @@ struct quantizer { | Name | Type | Description | | --- | --- | --- | | `params_quantizer` | [`params`](/api-reference/cpp-api-preprocessing-quantize-pq#preprocessing-quantize-pq-params) | Parameters used to build this quantizer. | -| `vpq_codebooks` | [`cuvs::neighbors::device_vpq_dataset`](/api-reference/cpp-api-neighbors-common#neighbors-vpq-dataset) | VPQ codebooks produced during training. | +| `vpq_codebooks` | `cuvs::neighbors::device_vpq_dataset` | VPQ codebooks produced during training. | ### preprocessing::quantize::pq::build @@ -253,3 +253,32 @@ std::optional> vq_labels = std **Returns** `void` + + +### preprocessing::quantize::pq::make_vpq_dataset + +Train VPQ storage (codebooks + encoded rows) from a row-major mdspan/mdarray/dataset. + +```cpp +template +[[nodiscard]] auto make_vpq_dataset(raft::resources const& res, +cuvs::neighbors::vpq_params const& params, +SrcT const& src) +-> cuvs::neighbors::device_vpq_dataset; +``` + +Accepts either a row-major mdspan with `value_type`, `extent`, `stride`, and `data_handle` (same pattern as `cuvs::neighbors::make_device_padded_dataset`), or any cuVS dense dataset / dataset view exposing `view`, `dim` and `stride`, in which case the logical `dim()` is quantized and the row padding is skipped. The rows may be device-accessible or host-resident. Device-accessible rows (device, managed or pinned) with tight row-major storage (logical stride equals dimension) are passed through to training as they are; a wider row pitch triggers a contiguous dense copy first. Host-resident rows are subsampled for training and encoded in bounded batches, so the dense dataset is never staged on the device in full; they must be tightly packed. Empty sources are rejected. The element type must be `float`, `half`, `int8_t` or `uint8_t`. + +Typical **CAGRA** usage: build the graph on dense vectors, then attach VPQ for search (metric must remain `L2Expanded` for this path). Train VPQ from the same CAGRA-padded device layout you used for graph build, keep the `device_vpq_dataset` alive, and call `cagra::update_dataset` with a non-owning view. + +**Parameters** + +| Name | Direction | Type | Description | +| --- | --- | --- | --- | +| `res` | | `raft::resources const&` | | +| `params` | | [`cuvs::neighbors::vpq_params const&`](/api-reference/cpp-api-neighbors-cagra#neighbors-vpq-params) | | +| `src` | | `SrcT const&` | | + +**Returns** + +`cuvs::neighbors::device_vpq_dataset` diff --git a/fern/pages/cpp_api/cpp-api-util-file-io.md b/fern/pages/cpp_api/cpp-api-util-file-io.md index 09a6ba77b8..c5179c55d3 100644 --- a/fern/pages/cpp_api/cpp-api-util-file-io.md +++ b/fern/pages/cpp_api/cpp-api-util-file-io.md @@ -31,18 +31,40 @@ class fd_istream; RAII wrapper for POSIX file descriptors -Manages file descriptor lifecycle with automatic cleanup. Non-copyable, move-only. +Manages file descriptor lifecycle with automatic cleanup. Used to own the lifetime of disk-backed ACE artifacts and to parse their numpy headers; the bulk data transfers go through kvikio (see :read_large_file / ::write_large_file). Non-copyable, move-only. ```cpp class file_descriptor; ``` + +### util::kvikio_file_reader + +Sequential file reader supporting mixed stream and direct-to-device reads. + +Small metadata can be consumed through stream(), while read_device() transfers the next bytes through KvikIO into device memory. Both operations advance one logical file position. KvikIO uses GPUDirect Storage when available and falls back to its compatible I/O path otherwise. Non-copyable, non-movable. + +```cpp +class kvikio_file_reader; +``` + + +### util::kvikio_ofstream + +Sequential std::ostream backed by kvikio. + +Ordinary stream output is staged into a large host buffer and written to disk through kvikio, which bypasses the page cache via O_DIRECT when supported (and falls back to buffered POSIX writes otherwise). Device buffers passed to write_device() use GPUDirect Storage when available. This can be passed to APIs accepting a std::ostream& for sequential output (e.g. the hnswlib serializer). It supports querying the current output position, but not random-access seeking. std::fstream-specific APIs such as is_open() are not part of its interface. Non-copyable, non-movable. + +```cpp +class kvikio_ofstream; +``` + ### util::buffered_ofstream Buffered output stream wrapper -Wraps an std::ostream with a buffer to improve write performance by reducing the number of system calls. Automatically flushes on destruction. Non-copyable, non-movable. +Wraps an std::ostream with a buffer to improve write performance by reducing the number of system calls. Automatically flushes on destruction. Used by the hnswlib serializer. Non-copyable, non-movable. ```cpp class buffered_ofstream; diff --git a/fern/pages/cpp_api/cpp-api-util-host-memory.md b/fern/pages/cpp_api/cpp-api-util-host-memory.md new file mode 100644 index 0000000000..3648cebb10 --- /dev/null +++ b/fern/pages/cpp_api/cpp-api-util-host-memory.md @@ -0,0 +1,36 @@ +--- +slug: api-reference/cpp-api-util-host-memory +--- + +# Host Memory + +_Source header: `cuvs/util/host_memory.hpp`_ + +## Types + + +### util::host_memory_info + +Snapshot of host and cgroup memory available to the current process. + +```cpp +struct host_memory_info { + size_t system_available; + size_t available; + std::optional cgroup_limit; + std::optional cgroup_current; + std::optional cgroup_reclaimable_file; + std::optional cgroup_working_set; +}; +``` + +**Fields** + +| Name | Type | Description | +| --- | --- | --- | +| `system_available` | `size_t` | Host-wide MemAvailable from /proc/meminfo. | +| `available` | `size_t` | Effective memory available after applying any cgroup limit. | +| `cgroup_limit` | `std::optional` | Hard limit of the most constrained cgroup ancestor, when finite. | +| `cgroup_current` | `std::optional` | Current usage charged to the most constrained cgroup ancestor. | +| `cgroup_reclaimable_file` | `std::optional` | Clean file cache treated as reclaimable for capacity planning. | +| `cgroup_working_set` | `std::optional` | Current cgroup usage after excluding reclaimable file cache. | diff --git a/fern/pages/cpp_api/index.md b/fern/pages/cpp_api/index.md index d5904b5db4..bb4480e8b5 100644 --- a/fern/pages/cpp_api/index.md +++ b/fern/pages/cpp_api/index.md @@ -11,6 +11,7 @@ These pages are generated from the documented public headers in the cuVS source ## Common +- [Bloom Filter](/api-reference/cpp-api-core-bloom-filter) - [Common Types](/api-reference/cpp-api-common-types) ## Distance @@ -31,7 +32,7 @@ These pages are generated from the documented public headers in the cuVS source - [Index](/api-reference/cpp-api-neighbors-composite-index) - [IVF Flat](/api-reference/cpp-api-neighbors-ivf-flat) - [IVF PQ](/api-reference/cpp-api-neighbors-ivf-pq) -- [IVF RaBitQ](/api-reference/cpp-api-neighbors-ivf-rabitq) +- [IVF Rabitq](/api-reference/cpp-api-neighbors-ivf-rabitq) - [IVF SQ](/api-reference/cpp-api-neighbors-ivf-sq) - [NN Descent](/api-reference/cpp-api-neighbors-nn-descent) - [Refine](/api-reference/cpp-api-neighbors-refine) @@ -60,3 +61,4 @@ These pages are generated from the documented public headers in the cuVS source - [Cutlass Utils](/api-reference/cpp-api-util-cutlass-utils) - [File Io](/api-reference/cpp-api-util-file-io) +- [Host Memory](/api-reference/cpp-api-util-host-memory) diff --git a/fern/pages/go_api/go-api-cagra.md b/fern/pages/go_api/go-api-cagra.md index 64f2b70435..3951d14f34 100644 --- a/fern/pages/go_api/go-api-cagra.md +++ b/fern/pages/go_api/go-api-cagra.md @@ -20,7 +20,7 @@ AutoSelect ) ``` -_Source: `go/cagra/index_params.go:23`_ +_Source: `go/cagra/index_params.go:18`_ ### HashmapMode Constants @@ -55,7 +55,7 @@ _Source: `go/cagra/search_params.go:19`_ type BuildAlgo int ``` -_Source: `go/cagra/index_params.go:21`_ +_Source: `go/cagra/index_params.go:16`_ ### CagraIndex @@ -69,18 +69,6 @@ Cagra ANN Index _Source: `go/cagra/cagra.go:14`_ -### CompressionParams - -```go -type CompressionParams struct { - // contains filtered or unexported fields -} -``` - -Supplemental parameters to build CAGRA Index - -_Source: `go/cagra/index_params.go:17`_ - ### ExtendParams ```go @@ -111,6 +99,42 @@ type IndexParams struct { _Source: `go/cagra/index_params.go:12`_ +### PaddedDataset + +```go +type PaddedDataset struct { + // contains filtered or unexported fields +} +``` + +Owning padded dataset handle for explicit CAGRA dataset management. + +_Source: `go/cagra/cagra.go:20`_ + +### PaddedDatasetHandle + +```go +type PaddedDatasetHandle interface { + datasetHandle() C.cuvsDataset_t +} +``` + +PaddedDatasetHandle is an owning padded dataset or non-owning padded dataset view. + +_Source: `go/cagra/cagra.go:25`_ + +### PaddedDatasetView + +```go +type PaddedDatasetView struct { + // contains filtered or unexported fields +} +``` + +Non-owning padded dataset view handle. + +_Source: `go/cagra/cagra.go:30`_ + ### SearchAlgo ```go @@ -131,6 +155,18 @@ Supplemental parameters to search CAGRA Index _Source: `go/cagra/search_params.go:13`_ +### StandardDatasetView + +```go +type StandardDatasetView struct { + // contains filtered or unexported fields +} +``` + +Non-owning standard dataset view handle. + +_Source: `go/cagra/cagra.go:35`_ + ## Functions ### BuildIndex @@ -148,17 +184,7 @@ Builds a new Index from the dataset for efficient search. * `dataset` - A row-major Tensor on either the host or device to index * `index` - CagraIndex to build -_Source: `go/cagra/cagra.go:38`_ - -### CreateCompressionParams - -```go -func CreateCompressionParams() (*CompressionParams, error) -``` - -Creates a new CompressionParams - -_Source: `go/cagra/index_params.go:36`_ +_Source: `go/cagra/cagra.go:226`_ ### CreateExtendParams @@ -178,7 +204,7 @@ func CreateIndex() (*CagraIndex, error) Creates a new empty Cagra Index -_Source: `go/cagra/cagra.go:20`_ +_Source: `go/cagra/cagra.go:208`_ ### CreateIndexParams @@ -188,7 +214,7 @@ func CreateIndexParams() (*IndexParams, error) Creates a new IndexParams -_Source: `go/cagra/index_params.go:99`_ +_Source: `go/cagra/index_params.go:31`_ ### CreateSearchParams @@ -203,115 +229,95 @@ _Source: `go/cagra/search_params.go:35`_ ### ExtendIndex ```go -func ExtendIndex[T any](Resources cuvs.Resource, params *ExtendParams, additional_dataset *cuvs.Tensor[T], index *CagraIndex) error +func ExtendIndex(Resources cuvs.Resource, params *ExtendParams, extended_dataset PaddedDatasetHandle, newStartRow int64, index *CagraIndex) error ``` -Extends the index with additional data +Extends the index with a caller-owned pre-concatenated padded dataset. #### Arguments * `Resources` - Resources to use * `params` - Parameters for extending the index -* `additional_dataset` - A row-major Tensor on the device to extend the index with +* `extended_dataset` - Caller-owned padded dataset already containing old \|\| new rows +* `newStartRow` - Row index where the additional vectors begin (must equal current index size) * `index` - CagraIndex to extend -_Source: `go/cagra/cagra.go:55`_ +_Source: `go/cagra/cagra.go:277`_ -### SearchIndex +### MakePaddedDataset ```go -func SearchIndex[T any](Resources cuvs.Resource, params *SearchParams, index *CagraIndex, queries *cuvs.Tensor[T], neighbors *cuvs.Tensor[uint32], distances *cuvs.Tensor[T], allowList []uint32) error +func MakePaddedDataset[T any](Resources cuvs.Resource, dataset *cuvs.Tensor[T]) (*PaddedDataset, error) ``` -Perform a Approximate Nearest Neighbors search on the Index +MakePaddedDataset creates an owning padded dataset from a tensor. +Memory residency is inferred from the tensor device type. -#### Arguments +_Source: `go/cagra/cagra.go:84`_ -* `Resources` - Resources to use -* `params` - Parameters to use in searching the index -* `queries` - A tensor in device memory to query for -* `neighbors` - Tensor in device memory that receives the indices of the nearest neighbors -* `distances` - Tensor in device memory that receives the distances of the nearest neighbors -* `allowList` - List of indices to allow in the search, if nil, no filtering is applied - -_Source: `go/cagra/cagra.go:85`_ - -## Methods - -### CagraIndex.Close +### MakePaddedDatasetView ```go -func (index *CagraIndex) Close() error +func MakePaddedDatasetView[T any](Resources cuvs.Resource, dataset *cuvs.Tensor[T]) (*PaddedDatasetView, error) ``` -Destroys the Cagra Index +MakePaddedDatasetView creates a non-owning padded dataset view from a tensor. +Memory residency is inferred from the tensor. -_Source: `go/cagra/cagra.go:67`_ +_Source: `go/cagra/cagra.go:109`_ -### CompressionParams.SetKMeansNIters +### MakeStandardDatasetView ```go -func (p *CompressionParams) SetKMeansNIters(kmeans_n_iters uint32) (*CompressionParams, error) +func MakeStandardDatasetView[T any](Resources cuvs.Resource, dataset *cuvs.Tensor[T]) (*StandardDatasetView, error) ``` -The number of iterations searching for kmeans centers (both VQ & PQ -phases). +MakeStandardDatasetView creates a non-owning standard dataset view from a tensor. +Memory residency is inferred from the tensor. -_Source: `go/cagra/index_params.go:76`_ +_Source: `go/cagra/cagra.go:159`_ -### CompressionParams.SetPQBits +### SearchIndex ```go -func (p *CompressionParams) SetPQBits(pq_bits uint32) (*CompressionParams, error) +func SearchIndex[T any](Resources cuvs.Resource, params *SearchParams, index *CagraIndex, queries *cuvs.Tensor[T], neighbors *cuvs.Tensor[uint32], distances *cuvs.Tensor[T], allowList []uint32) error ``` -The bit length of the vector element after compression by PQ. - -_Source: `go/cagra/index_params.go:52`_ - -### CompressionParams.SetPQDim +Perform a Approximate Nearest Neighbors search on the Index -```go -func (p *CompressionParams) SetPQDim(pq_dim uint32) (*CompressionParams, error) -``` +#### Arguments -The dimensionality of the vector after compression by PQ. When zero, -an optimal value is selected using a heuristic. +* `Resources` - Resources to use +* `params` - Parameters to use in searching the index +* `queries` - A tensor in device memory to query for +* `neighbors` - Tensor in device memory that receives the indices of the nearest neighbors +* `distances` - Tensor in device memory that receives the distances of the nearest neighbors +* `allowList` - List of indices to allow in the search, if nil, no filtering is applied -_Source: `go/cagra/index_params.go:60`_ +_Source: `go/cagra/cagra.go:317`_ -### CompressionParams.SetPQKMeansTrainsetFraction +### UpdateDataset ```go -func (p *CompressionParams) SetPQKMeansTrainsetFraction(pq_kmeans_trainset_fraction float64) (*CompressionParams, error) +func UpdateDataset(Resources cuvs.Resource, paddedDataset PaddedDatasetHandle, index *CagraIndex) error ``` -The fraction of data to use during iterative kmeans building (PQ -phase). When zero, an optimal value is selected using a heuristic. - -_Source: `go/cagra/index_params.go:92`_ +UpdateDataset updates any CAGRA index layout with a caller-provided padded +dataset or view and leaves the same handle search-ready. -### CompressionParams.SetVQKMeansTrainsetFraction +_Source: `go/cagra/cagra.go:189`_ -```go -func (p *CompressionParams) SetVQKMeansTrainsetFraction(vq_kmeans_trainset_fraction float64) (*CompressionParams, error) -``` - -The fraction of data to use during iterative kmeans building (VQ -phase). When zero, an optimal value is selected using a heuristic. - -_Source: `go/cagra/index_params.go:84`_ +## Methods -### CompressionParams.SetVQNCenters +### CagraIndex.Close ```go -func (p *CompressionParams) SetVQNCenters(vq_n_centers uint32) (*CompressionParams, error) +func (index *CagraIndex) Close() error ``` -Vector Quantization (VQ) codebook size - number of "coarse cluster -centers". When zero, an optimal value is selected using a heuristic. +Destroys the Cagra Index -_Source: `go/cagra/index_params.go:68`_ +_Source: `go/cagra/cagra.go:299`_ ### ExtendParams.Close @@ -344,7 +350,7 @@ func (p *IndexParams) Close() error Destroys IndexParams -_Source: `go/cagra/index_params.go:152`_ +_Source: `go/cagra/index_params.go:77`_ ### IndexParams.SetBuildAlgo @@ -354,17 +360,7 @@ func (p *IndexParams) SetBuildAlgo(build_algo BuildAlgo) (*IndexParams, error) ANN algorithm to build knn graph -_Source: `go/cagra/index_params.go:126`_ - -### IndexParams.SetCompression - -```go -func (p *IndexParams) SetCompression(compression *CompressionParams) (*IndexParams, error) -``` - -Compression parameters - -_Source: `go/cagra/index_params.go:145`_ +_Source: `go/cagra/index_params.go:58`_ ### IndexParams.SetGraphDegree @@ -374,7 +370,7 @@ func (p *IndexParams) SetGraphDegree(intermediate_graph_degree uintptr) (*IndexP Degree of output graph -_Source: `go/cagra/index_params.go:119`_ +_Source: `go/cagra/index_params.go:51`_ ### IndexParams.SetIntermediateGraphDegree @@ -384,7 +380,7 @@ func (p *IndexParams) SetIntermediateGraphDegree(intermediate_graph_degree uintp Degree of input graph for pruning -_Source: `go/cagra/index_params.go:113`_ +_Source: `go/cagra/index_params.go:45`_ ### IndexParams.SetNNDescentNiter @@ -394,7 +390,27 @@ func (p *IndexParams) SetNNDescentNiter(nn_descent_niter uint32) (*IndexParams, Number of iterations to run if building with NN_DESCENT -_Source: `go/cagra/index_params.go:138`_ +_Source: `go/cagra/index_params.go:70`_ + +### PaddedDataset.Close + +```go +func (dataset *PaddedDataset) Close() error +``` + +Destroys an owning padded dataset handle. + +_Source: `go/cagra/cagra.go:132`_ + +### PaddedDatasetView.Close + +```go +func (view *PaddedDatasetView) Close() error +``` + +Destroys a padded dataset view handle. + +_Source: `go/cagra/cagra.go:145`_ ### SearchParams.Close @@ -537,3 +553,13 @@ func (p *SearchParams) SetThreadBlockSize(thread_block_size uintptr) (*SearchPar Thread block size. 0, 64, 128, 256, 512, 1024. Auto selection when 0. _Source: `go/cagra/search_params.go:107`_ + +### StandardDatasetView.Close + +```go +func (view *StandardDatasetView) Close() error +``` + +Destroys a standard dataset view handle. + +_Source: `go/cagra/cagra.go:175`_ diff --git a/fern/pages/java_api/index.md b/fern/pages/java_api/index.md index eacc465266..d2385b9a1a 100644 --- a/fern/pages/java_api/index.md +++ b/fern/pages/java_api/index.md @@ -12,6 +12,7 @@ These pages are generated from the Java source files in `java/cuvs-java/src/main - [CuVSResourcesInfo](/api-reference/java-api-com-nvidia-cuvs-cuvsresourcesinfo) - [CuVSServiceProvider](/api-reference/java-api-com-nvidia-cuvs-spi-cuvsserviceprovider) - [DelegatingScopedAccess](/api-reference/java-api-com-nvidia-cuvs-delegatingscopedaccess) +- [FilterBitsetHandle](/api-reference/java-api-com-nvidia-cuvs-filterbitsethandle) - [GPUInfo](/api-reference/java-api-com-nvidia-cuvs-gpuinfo) - [GPUInfoProvider](/api-reference/java-api-com-nvidia-cuvs-gpuinfoprovider) - [LibraryException](/api-reference/java-api-com-nvidia-cuvs-libraryexception) @@ -38,6 +39,8 @@ These pages are generated from the Java source files in `java/cuvs-java/src/main - [HnswIndexParams](/api-reference/java-api-com-nvidia-cuvs-hnswindexparams) - [HnswQuery](/api-reference/java-api-com-nvidia-cuvs-hnswquery) - [HnswSearchParams](/api-reference/java-api-com-nvidia-cuvs-hnswsearchparams) +- [MultiPartitionCagraSearch](/api-reference/java-api-com-nvidia-cuvs-multipartitioncagrasearch) +- [MultiPartitionSearchResults](/api-reference/java-api-com-nvidia-cuvs-multipartitionsearchresults) - [SearchResults](/api-reference/java-api-com-nvidia-cuvs-searchresults) - [TieredIndex](/api-reference/java-api-com-nvidia-cuvs-tieredindex) - [TieredIndexParams](/api-reference/java-api-com-nvidia-cuvs-tieredindexparams) diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagracompressionparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagracompressionparams.md index 4aad7e30de..2b0f1624dd 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagracompressionparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagracompressionparams.md @@ -14,28 +14,6 @@ Supplemental compression parameters to build CAGRA Index. ## Public Members -### CagraCompressionParams - -```java -private CagraCompressionParams( int pqBits, int pqDim, int vqNCenters, int kmeansNIters, double vqKmeansTrainsetFraction, double pqKmeansTrainsetFraction) -``` - -Constructs an instance of CagraCompressionParams with passed search -parameters. - -**Parameters** - -| Name | Description | -| --- | --- | -| `pqBits` | the bit length of the vector element after compression by PQ | -| `pqDim` | the dimensionality of the vector after compression by PQ | -| `vqNCenters` | the vector quantization (VQ) codebook size - number of “coarse cluster centers” | -| `kmeansNIters` | the number of iterations searching for kmeans centers (both VQ and PQ phases) | -| `vqKmeansTrainsetFraction` | the fraction of data to use during iterative kmeans building (VQ phase) | -| `pqKmeansTrainsetFraction` | the fraction of data to use during iterative kmeans building (PQ phase) | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraCompressionParams.java:37`_ - ### getPqBits ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md index 5805278f99..8c19be0b1b 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindex.md @@ -21,6 +21,76 @@ here ## Public Members +### setDelegate + +```java +public final void setDelegate(AutoCloseable delegate, long handleAddress) +``` + +Internal wiring hook used by the Java wrapper implementation. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:33`_ + +### isPresent + +```java +public final boolean isPresent() +``` + +Returns true when this view has a native handle. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:41`_ + +### nativeHandleAddress + +```java +public final long nativeHandleAddress() +``` + +Internal accessor for native handle address. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:48`_ + +### setDelegate + +```java +public final void setDelegate(AutoCloseable delegate) +``` + +Internal wiring hook used by the Java wrapper implementation. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:83`_ + +### setDelegate + +```java +public final void setDelegate(AutoCloseable delegate, long handleAddress) +``` + +Internal wiring hook used by the Java wrapper implementation. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:90`_ + +### isPresent + +```java +public final boolean isPresent() +``` + +Returns true when this handle owns native dataset storage. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:98`_ + +### nativeHandleAddress + +```java +public final long nativeHandleAddress() +``` + +Internal accessor for native handle address. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:105`_ + ### close ```java @@ -29,7 +99,7 @@ here Invokes the native destroy_cagra_index to de-allocate the CAGRA index -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:29`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:135`_ ### search @@ -50,7 +120,64 @@ CAGRA index. an instance of `SearchResults` containing the results -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:40`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:146`_ + +### makePaddedDataset + +```java +PaddedDataset makePaddedDataset(CuVSMatrix dataset) throws Throwable +``` + +Create an owning padded dataset by allocating padded storage and copying +`dataset`. Prefer this when the source matrix is not already padded to CAGRA's +required row stride (e.g. unaligned dimensions). + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:153`_ + +### makePaddedDatasetView + +```java +PaddedDatasetView makePaddedDatasetView(CuVSMatrix dataset) throws Throwable +``` + +Create a caller-owned padded dataset view handle from a matrix that is already +padded to CAGRA's required row stride. For unpadded matrices use +`#makePaddedDataset(CuVSMatrix)`. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:160`_ + +### makeStandardDatasetView + +```java +StandardDatasetView makeStandardDatasetView(CuVSMatrix dataset) throws Throwable +``` + +Create a caller-owned standard dataset view handle from a matrix. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:163`_ + +### updateDataset + +```java +void updateDataset(PaddedDatasetView datasetView) throws Throwable +``` + +Update this index with a caller-provided padded device dataset view and leave it +search-ready in padded-device layout. The caller retains ownership of the underlying +padded storage and must keep it alive while this index uses it. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:170`_ + +### updateDataset + +```java +void updateDataset(PaddedDataset dataset) throws Throwable +``` + +Update this index with a caller-owned padded device dataset. The dataset must remain alive +while this index uses it. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:176`_ ### getGraph @@ -64,7 +191,23 @@ Returns the CAGRA graph a `CuVSDeviceMatrix` encapsulating the native int (uint32_t) array used to represent the cagra graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:47`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:183`_ + +### getGraphDegree + +```java +long getGraphDegree() +``` + +Returns the degree of the built CAGRA graph (its number of edges per node), which may be +smaller than the requested `graph_degree` when the dataset is small enough that the +build truncated it. + +**Returns** + +the built graph degree (`graph().extent(1)`) + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:192`_ ### serialize @@ -81,7 +224,7 @@ for writing index bytes. | --- | --- | | `outputStream` | an instance of `OutputStream` to write the index bytes into | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:56`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:201`_ ### serialize @@ -99,7 +242,7 @@ for writing index bytes. | `outputStream` | an instance of `OutputStream` to write the index bytes into | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:67`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:212`_ ### serialize @@ -117,7 +260,7 @@ for writing index bytes. | `outputStream` | an instance of `OutputStream` to write the index bytes into | | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:78`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:223`_ ### serialize @@ -136,7 +279,7 @@ and path to the intermediate temporary file. | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:93`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:238`_ ### serializeToHNSW @@ -153,7 +296,7 @@ of `OutputStream` and path to the intermediate temporary file. | --- | --- | | `outputStream` | an instance of `OutputStream` to write the index bytes to | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:102`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:247`_ ### serializeToHNSW @@ -171,7 +314,7 @@ of `OutputStream` and path to the intermediate temporary file. | `outputStream` | an instance of `OutputStream` to write the index bytes to | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:113`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:258`_ ### serializeToHNSW @@ -189,7 +332,7 @@ of `OutputStream` and path to the intermediate temporary file. | `outputStream` | an instance of `OutputStream` to write the index bytes to | | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:124`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:269`_ ### serializeToHNSW @@ -208,7 +351,7 @@ of `OutputStream` and path to the intermediate temporary file. | `tempFile` | an intermediate `Path` where CAGRA index is written temporarily | | `bufferLength` | the length of buffer to use for writing bytes. Default value is 1024 | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:139`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:284`_ ### getCuVSResources @@ -222,7 +365,7 @@ Gets an instance of `CuVSResources` an instance of `CuVSResources` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:146`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:291`_ ### newBuilder @@ -244,7 +387,7 @@ Creates a new Builder with an instance of `CuVSResources`. | --- | --- | | `UnsupportedOperationException` | if the provider does not cuvs | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:154`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:299`_ ### merge @@ -270,7 +413,7 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:166`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:311`_ ### merge @@ -297,7 +440,33 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:178`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:323`_ + +### isPaddedDataset + +```java +static boolean isPaddedDataset(CuVSMatrix dataset) +``` + +Reports whether the rows of `dataset` already sit at the row stride CAGRA requires, which +is the row length in bytes rounded up to a 16 byte boundary. + +Use it to pick between the two padded dataset factories: a matrix that is already padded has +to go through `#makePaddedDatasetView(CuVSMatrix)`, because cuVS rejects a request to +copy it into padded storage it already occupies, and one that is not has to go through +`#makePaddedDataset(CuVSMatrix)`. + +**Parameters** + +| Name | Description | +| --- | --- | +| `dataset` | the matrix to inspect | + +**Returns** + +true when the rows are already padded the way CAGRA requires + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:350`_ ### from @@ -318,7 +487,30 @@ needed. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:205`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:367`_ + +### from + +```java +Builder from(InputStream inputStream, DeserializeDataset outDataset) +``` + +Sets an input stream and an empty caller-owned output handle for explicit dataset +deserialization. The concrete output type must match the dataset layout stored in the +serialized index. Keep `outDataset` alive while the built index is in use. + +**Parameters** + +| Name | Description | +| --- | --- | +| `inputStream` | an instance of `InputStream` | +| `outDataset` | an empty `PaddedDataset` or `StandardDataset` | + +**Returns** + +an instance of this Builder + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:378`_ ### from @@ -329,7 +521,7 @@ Builder from(CuVSMatrix graph) Sets a CAGRA graph instance to re-create an index from a previously built graph. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:211`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:384`_ ### withDataset @@ -349,7 +541,7 @@ Sets the dataset vectors for building the `CagraIndex`. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:219`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:392`_ ### withDataset @@ -369,7 +561,7 @@ Sets the dataset for building the `CagraIndex`. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:227`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:400`_ ### withIndexParams @@ -390,7 +582,7 @@ Builder. An instance of this Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:236`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:409`_ ### build @@ -404,6 +596,6 @@ Builds and returns an instance of CagraIndex. an instance of CagraIndex -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:243`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:416`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java:25`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindexparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindexparams.md index 81d0c922d1..d1e8bccfc3 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindexparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraindexparams.md @@ -22,7 +22,7 @@ AUTO_SELECT(0), /** * Use IVF-PQ to build all-neighbors knn graph */ IVF_PQ(1), Select build algorithm automatically -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:36`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:35`_ ### IVF_PQ @@ -32,7 +32,7 @@ IVF_PQ(1), /** * Experimental, use NN-Descent to build all-neighbors knn graph * Use IVF-PQ to build all-neighbors knn graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:40`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:39`_ ### NN_DESCENT @@ -42,7 +42,7 @@ NN_DESCENT(2), /** * Experimental, use ACE (Augmented Core Extraction) to build Experimental, use NN-Descent to build all-neighbors knn graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:44`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:43`_ ### ACE @@ -53,7 +53,7 @@ ACE(4) Experimental, use ACE (Augmented Core Extraction) to build graph for large datasets. 4 to be consistent with the other interfaces. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:49`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:48`_ ### SIMILAR_SEARCH_PERFORMANCE @@ -71,7 +71,7 @@ searched by HNSW are close for any search parameter combination. The CAGRA-produ to have a "longer tail" on the low recall side (that is being slightly faster and less precise). -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:85`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:84`_ ### SAME_GRAPH_FOOTPRINT @@ -88,7 +88,7 @@ the same ef, the from-CAGRA index likely has a slightly higher recall and slight However, the Recall-QPS curves should be similar (i.e. the points are just shifted along the curve). -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:96`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:95`_ ### L2Expanded @@ -98,7 +98,7 @@ L2Expanded(0), /** * same as above, but inside the epilogue, perform square root evaluate as dist_ij = sum(x_ik^2) + sum(y_ij)^2 - 2*sum(x_ik * y_jk) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:124`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:123`_ ### L2SqrtExpanded @@ -108,7 +108,7 @@ L2SqrtExpanded(1), /** * cosine distance */ CosineExpanded(2), /** * L1 distance same as above, but inside the epilogue, perform square root operation -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:128`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:127`_ ### CosineExpanded @@ -118,7 +118,7 @@ CosineExpanded(2), /** * L1 distance * */ L1(3), /** * evaluate as dist_ij += (x cosine distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:132`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:131`_ ### L1 @@ -128,7 +128,7 @@ L1(3), /** * evaluate as dist_ij += (x_ik - y-jk)^2 * */ L2Unexpanded(4), /** * L1 distance * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:136`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:135`_ ### L2Unexpanded @@ -138,7 +138,7 @@ L2Unexpanded(4), /** * same as above, but inside the epilogue, perform square ro evaluate as dist_ij += (x_ik - y-jk)^2 * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:140`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:139`_ ### L2SqrtUnexpanded @@ -148,7 +148,7 @@ L2SqrtUnexpanded(5), /** * basic inner product */ InnerProduct(6), /** * Chebysh same as above, but inside the epilogue, perform square root operation -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:144`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:143`_ ### InnerProduct @@ -158,7 +158,7 @@ InnerProduct(6), /** * Chebyshev (Linf) distance */ Linf(7), /** * Canberra dist basic inner product -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:148`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:147`_ ### Linf @@ -168,7 +168,7 @@ Linf(7), /** * Canberra distance */ Canberra(8), /** * Generalized Minkowski dis Chebyshev (Linf) distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:152`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:151`_ ### Canberra @@ -178,7 +178,7 @@ Canberra(8), /** * Generalized Minkowski distance */ LpUnexpanded(9), /** * Corr Canberra distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:156`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:155`_ ### LpUnexpanded @@ -188,7 +188,7 @@ LpUnexpanded(9), /** * Correlation distance */ CorrelationExpanded(10), /** * Ja Generalized Minkowski distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:160`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:159`_ ### CorrelationExpanded @@ -198,7 +198,7 @@ CorrelationExpanded(10), /** * Jaccard distance */ JaccardExpanded(11), /** * He Correlation distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:164`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:163`_ ### JaccardExpanded @@ -208,7 +208,7 @@ JaccardExpanded(11), /** * Hellinger distance */ HellingerExpanded(12), /** * Ha Jaccard distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:168`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:167`_ ### HellingerExpanded @@ -218,7 +218,7 @@ HellingerExpanded(12), /** * Haversine distance */ Haversine(13), /** * Bray-Cur Hellinger distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:172`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:171`_ ### Haversine @@ -228,7 +228,7 @@ Haversine(13), /** * Bray-Curtis distance */ BrayCurtis(14), /** * Jensen-Shanno Haversine distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:176`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:175`_ ### BrayCurtis @@ -238,7 +238,7 @@ BrayCurtis(14), /** * Jensen-Shannon distance */ JensenShannon(15), /** * Hammin Bray-Curtis distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:180`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:179`_ ### JensenShannon @@ -248,7 +248,7 @@ JensenShannon(15), /** * Hamming distance */ HammingUnexpanded(16), /** * KLDive Jensen-Shannon distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:184`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:183`_ ### HammingUnexpanded @@ -258,7 +258,7 @@ HammingUnexpanded(16), /** * KLDivergence */ KLDivergence(17), /** * RusselRao * Hamming distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:188`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:187`_ ### KLDivergence @@ -268,7 +268,7 @@ KLDivergence(17), /** * RusselRao */ RusselRaoExpanded(18), /** * Dice-Sorensen KLDivergence -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:192`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:191`_ ### RusselRaoExpanded @@ -278,7 +278,7 @@ RusselRaoExpanded(18), /** * Dice-Sorensen distance */ DiceExpanded(19), /** * P RusselRao -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:196`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:195`_ ### DiceExpanded @@ -288,7 +288,7 @@ DiceExpanded(19), /** * Precomputed (special value) */ Precomputed(100) Dice-Sorensen distance -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:200`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:199`_ ### Precomputed @@ -298,7 +298,7 @@ Precomputed(100) Precomputed (special value) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:204`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:203`_ ### getIntermediateGraphDegree @@ -312,7 +312,7 @@ Gets the degree of input graph for pruning. the degree of input graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:366`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:369`_ ### getGraphDegree @@ -326,7 +326,7 @@ Gets the degree of output graph. the degree of output graph -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:375`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:378`_ ### getCagraGraphBuildAlgo @@ -336,7 +336,7 @@ public CagraGraphBuildAlgo getCagraGraphBuildAlgo() Gets the `CagraGraphBuildAlgo` used to build the index. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:382`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:385`_ ### getNNDescentNumIterations @@ -347,7 +347,7 @@ public long getNNDescentNumIterations() Gets the number of iterations to run if building with `CagraGraphBuildAlgo#NN_DESCENT` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:390`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:393`_ ### getCuvsDistanceType @@ -357,7 +357,7 @@ public CuvsDistanceType getCuvsDistanceType() Gets the `CuvsDistanceType` used to build the index. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:397`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:400`_ ### getNumWriterThreads @@ -367,7 +367,7 @@ public int getNumWriterThreads() Gets the number of threads used to build the index. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:404`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:407`_ ### getCuVSIvfPqParams @@ -377,7 +377,7 @@ public CuVSIvfPqParams getCuVSIvfPqParams() Gets the IVF_PQ parameters. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:411`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:414`_ ### getCuVSAceParams @@ -387,7 +387,7 @@ public CuVSAceParams getCuVSAceParams() Gets the ACE parameters. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:418`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:421`_ ### getCuvsCagraGraphBuildAlgo @@ -397,17 +397,7 @@ public CagraGraphBuildAlgo getCuvsCagraGraphBuildAlgo() Gets the CAGRA build algorithm. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:425`_ - -### getCagraCompressionParams - -```java -public CagraCompressionParams getCagraCompressionParams() -``` - -Gets the CAGRA compression parameters. - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:432`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:428`_ ### withIntermediateGraphDegree @@ -427,7 +417,7 @@ Sets the degree of input graph for pruning. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:482`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:475`_ ### withGraphDegree @@ -447,7 +437,7 @@ Sets the degree of output graph. an instance to Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:493`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:486`_ ### withCagraGraphBuildAlgo @@ -467,7 +457,7 @@ Sets the CuvsCagraGraphBuildAlgo to use. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:504`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:497`_ ### withMetric @@ -487,7 +477,7 @@ Sets the metric to use. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:515`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:508`_ ### withNNDescentNumIterations @@ -508,7 +498,7 @@ Sets the Number of Iterations to run if building with an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:528`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:521`_ ### withNumWriterThreads @@ -528,7 +518,7 @@ Sets the number of writer threads to use for indexing. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:539`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:532`_ ### withCuVSIvfPqParams @@ -548,7 +538,7 @@ Sets the IVF_PQ index parameters. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:550`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:543`_ ### withCuVSAceParams @@ -568,28 +558,7 @@ Sets the ACE index parameters. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:561`_ - -### withCompressionParams - -```java -public Builder withCompressionParams(CagraCompressionParams cagraCompressionParams) -``` - -Registers an instance of configured `CagraCompressionParams` with this -Builder. - -**Parameters** - -| Name | Description | -| --- | --- | -| `cagraCompressionParams` | An instance of CagraCompressionParams. | - -**Returns** - -An instance of this Builder. - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:573`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:554`_ ### build @@ -603,6 +572,6 @@ Builds an instance of `CagraIndexParams`. an instance of `CagraIndexParams` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:583`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:564`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java:18`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagramergeparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagramergeparams.md index 2fae4815d6..5cbac56994 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagramergeparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagramergeparams.md @@ -12,23 +12,6 @@ public class CagraMergeParams ## Public Members -### CagraMergeParams - -```java -private CagraMergeParams(CagraIndexParams outputIndexParams, MergeStrategy strategy) -``` - -Constructs a CagraMergeParams with the given output index parameters and merge strategy. - -**Parameters** - -| Name | Description | -| --- | --- | -| `outputIndexParams` | Index parameters for the output index | -| `strategy` | Merge strategy to use | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraMergeParams.java:17`_ - ### getOutputIndexParams ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraquery.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraquery.md index ca4b6b0760..c5ae5c4d2c 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraquery.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagraquery.md @@ -19,29 +19,6 @@ between threads can lead to memory allocation errors or JVM crashes. ## Public Members -### CagraQuery - -```java -private CagraQuery( CagraSearchParams cagraSearchParameters, CuVSMatrix queryVectors, LongToIntFunction mapping, int topK, BitSet prefilter, int numDocs, CuVSResources resources) -``` - -Constructs an instance of `CagraQuery` using cagraSearchParameters, -preFilter, queryVectors, mapping, and topK. - -**Parameters** - -| Name | Description | -| --- | --- | -| `cagraSearchParameters` | an instance of `CagraSearchParams` holding the search parameters | -| `queryVectors` | 2D float query vector array | -| `mapping` | a function mapping ordinals (neighbor IDs) to custom user IDs | -| `topK` | the top k results to return | -| `prefilter` | A single BitSet to use as filter while searching the CAGRA index | -| `numDocs` | Total number of dataset vectors; used to align the prefilter correctly | -| `resources` | CuVSResources instance to use for this query | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraQuery.java:43`_ - ### getCagraSearchParameters ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagrasearchparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagrasearchparams.md index 8346f8dba2..59565786a6 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cagrasearchparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cagrasearchparams.md @@ -85,34 +85,6 @@ AUTO_HASH _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraSearchParams.java:74`_ -### CagraSearchParams - -```java -private CagraSearchParams( int maxQueries, int iTopKSize, int maxIterations, SearchAlgo searchAlgo, int teamSize, int searchWidth, int minIterations, int threadBlockSize, HashMapMode hashmapMode, int hashmapMinBitlen, float hashmapMaxFillRate, int numRandomSamplings, long randXORMask) -``` - -Constructs an instance of CagraSearchParams with passed search parameters. - -**Parameters** - -| Name | Description | -| --- | --- | -| `maxQueries` | the maximum number of queries to search at the same time (batch size) | -| `iTopKSize` | the number of intermediate search results retained during the search | -| `maxIterations` | the upper limit of search iterations | -| `searchAlgo` | the search implementation is configured | -| `teamSize` | the number of threads used to calculate a single distance | -| `searchWidth` | the number of graph nodes to select as the starting point for the search in each iteration | -| `minIterations` | the lower limit of search iterations | -| `threadBlockSize` | the thread block size | -| `hashmapMode` | the hash map type configured | -| `hashmapMinBitlen` | the lower limit of hash map bit length | -| `hashmapMaxFillRate` | the upper limit of hash map fill rate | -| `numRandomSamplings` | the number of iterations of initial random seed node selection | -| `randXORMask` | the bit mask used for initial random seed node selection | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraSearchParams.java:109`_ - ### getMaxQueries ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsaceparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsaceparams.md index 90d0f44bf9..a3dccaefab 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsaceparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsaceparams.md @@ -31,7 +31,7 @@ Gets the number of partitions. the number of partitions -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:92`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:97`_ ### getEfConstruction @@ -45,7 +45,7 @@ Gets the `ef_construction` parameter. the `ef_construction` parameter -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:101`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:106`_ ### getBuildDir @@ -59,7 +59,7 @@ Gets the build directory path. the build directory path -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:110`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:115`_ ### isUseDisk @@ -73,7 +73,7 @@ Gets whether disk-based mode is enabled. true if disk-based mode is enabled -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:119`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:124`_ ### getMaxHostMemoryGb @@ -87,7 +87,7 @@ Gets the maximum host memory limit in GiB. the max host memory limit (0 means use available memory) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:128`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:133`_ ### getMaxGpuMemoryGb @@ -101,7 +101,7 @@ Gets the maximum GPU memory limit in GiB. the max GPU memory limit (0 means use available memory) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:137`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:142`_ ### withNpartitions @@ -121,7 +121,7 @@ Sets the number of partitions. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:189`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:194`_ ### withEfConstruction @@ -141,7 +141,7 @@ Sets the ef_construction parameter. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:200`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:205`_ ### withBuildDir @@ -161,7 +161,7 @@ Sets the build directory path. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:211`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:216`_ ### withUseDisk @@ -181,7 +181,7 @@ Sets whether to use disk-based mode. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:222`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:227`_ ### withMaxHostMemoryGb @@ -204,7 +204,7 @@ Useful for testing or when running alongside other memory-intensive processes. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:236`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:241`_ ### withMaxGpuMemoryGb @@ -227,7 +227,7 @@ Useful for testing or when running alongside other memory-intensive processes. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:250`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:255`_ ### build @@ -241,6 +241,6 @@ Builds an instance of `CuVSAceParams`. an instance of `CuVSAceParams` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:260`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:265`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSAceParams.java:17`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqparams.md index 7ac190e2ed..e9dc585c99 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsivfpqparams.md @@ -36,26 +36,6 @@ public float getRefinementRate() _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSIvfPqParams.java:45`_ -### Builder - -```java -private CuVSIvfPqIndexParams cuVSIvfPqIndexParams = new CuVSIvfPqIndexParams.Builder().build() -``` - -CuVS IVF_PQ index parameters - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSIvfPqParams.java:66`_ - -### Builder - -```java -private CuVSIvfPqSearchParams cuVSIvfPqSearchParams = new CuVSIvfPqSearchParams.Builder().build() -``` - -CuVS IVF_PQ search parameters - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSIvfPqParams.java:69`_ - ### withCuVSIvfPqIndexParams ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsmatrix.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsmatrix.md index ae594ff923..29e3e618fd 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsmatrix.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsmatrix.md @@ -26,7 +26,7 @@ static CuVSMatrix ofArray(float[][] vectors) Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:46`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:47`_ ### ofArray @@ -37,7 +37,7 @@ static CuVSMatrix ofArray(int[][] vectors) Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:56`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:57`_ ### ofArray @@ -48,7 +48,7 @@ static CuVSMatrix ofArray(byte[][] vectors) Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:66`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:67`_ ### addVector @@ -64,7 +64,7 @@ Adds a single vector to the matrix. | --- | --- | | `vector` | A float array of as many elements as the dimensions | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:80`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:81`_ ### addVector @@ -80,7 +80,7 @@ Adds a single vector to the matrix. | --- | --- | | `vector` | A byte array of as many elements as the dimensions | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:87`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:88`_ ### addVector @@ -96,7 +96,23 @@ Adds a single vector to the matrix. | --- | --- | | `vector` | An int array of as many elements as the dimensions | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:94`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:95`_ + +### addVector + +```java +void addVector(short[] vector) +``` + +Adds a single vector to the matrix. Each element is a raw float16 bit pattern stored in a short. + +**Parameters** + +| Name | Description | +| --- | --- | +| `vector` | A short array of as many elements as the dimensions | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:102`_ ### hostBuilder @@ -118,7 +134,7 @@ Returns a builder to create a new instance of a host-memory matrix a builder for creating a `CuVSHostMatrix` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:107`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:115`_ ### hostBuilder @@ -142,7 +158,7 @@ Returns a builder to create a new instance of a host-memory matrix a builder for creating a `CuVSDeviceMatrix` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:121`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:129`_ ### deviceBuilder @@ -165,7 +181,7 @@ Returns a builder to create a new instance of a dataset a builder for creating a `CuVSDeviceMatrix` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:136`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:144`_ ### deviceBuilder @@ -190,7 +206,7 @@ Returns a builder to create a new instance of a dataset a builder for creating a `CuVSDeviceMatrix` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:152`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:160`_ ### size @@ -204,7 +220,7 @@ Gets the size of the dataset Size of the dataset -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:168`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:176`_ ### columns @@ -219,7 +235,7 @@ or the graph degree for the graph represented as a list of neighbours Dimensions of the vectors in the dataset -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:176`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:184`_ ### dataType @@ -233,7 +249,7 @@ Gets the element type a `DataType` describing the matrix element type -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:183`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:191`_ ### getRow @@ -249,7 +265,7 @@ Get a view (0-copy) of the row data, as a list of integers (32 bit) | --- | --- | | `row` | the row for which to return the data | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:190`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:198`_ ### toArray @@ -265,7 +281,7 @@ Copies the content of this dataset to an on-heap Java matrix (array of arrays). | --- | --- | | `array` | the destination array. Must be of length `CuVSMatrix#size()` or bigger, and each element must be of length `CuVSMatrix#columns()` or bigger. | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:198`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:206`_ ### toArray @@ -281,7 +297,7 @@ Copies the content of this dataset to an on-heap Java matrix (array of arrays). | --- | --- | | `array` | the destination array. Must be of length `CuVSMatrix#size()` or bigger, and each element must be of length `CuVSMatrix#columns()` or bigger. | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:206`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:214`_ ### toArray @@ -297,7 +313,7 @@ Copies the content of this dataset to an on-heap Java matrix (array of arrays). | --- | --- | | `array` | the destination array. Must be of length `CuVSMatrix#size()` or bigger, and each element must be of length `CuVSMatrix#columns()` or bigger. | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:214`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:222`_ ### toHost @@ -315,7 +331,7 @@ same element type and dimension. | --- | --- | | `hostMatrix` | the host-memory-backed matrix to fill. | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:223`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:231`_ ### toHost @@ -329,7 +345,7 @@ the device matrix. The returned host matrix will need to be managed by the caller, which will be responsible to call `CuVSMatrix#close()` to free its resources when done. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:232`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:240`_ ### toDevice @@ -347,7 +363,7 @@ same element type and dimension. | --- | --- | | `deviceMatrix` | the device-memory-backed matrix to fill. | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:241`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:249`_ ### toDevice @@ -361,6 +377,6 @@ the host matrix. The returned device matrix will need to be managed by the caller, which will be responsible to call `CuVSMatrix#close()` to free its resources when done. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:250`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:258`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:17`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsresources.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsresources.md index f235382555..e9fcdb3a29 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsresources.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-cuvsresources.md @@ -26,7 +26,7 @@ Gets the opaque CuVSResources handle, to be used whenever we need to pass a cuvs the CuVSResources handle -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:25`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:26`_ ### access @@ -40,7 +40,7 @@ concurrently the same native resources. Calling this method from multiple thread returned `ScopedAccess` object must be closed before calling `access()` again from a different thread. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:38`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:39`_ ### deviceId @@ -52,7 +52,7 @@ Get the logical id of the device associated with this resources object. Information about the device id is immutable, so it is safe to expose it without getting `ScopedAccess` to the enclosing resources. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:45`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:46`_ ### close @@ -62,7 +62,7 @@ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:45`_ Closes this CuVSResources object and releases any resources associated with it. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:50`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:51`_ ### tempDirectory @@ -73,7 +73,39 @@ Path tempDirectory() The temporary directory to use for intermediate operations. Defaults to \{@systemProperty java.io.tmpdir\}. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:57`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:58`_ + +### setWorkspacePool + +```java +void setWorkspacePool(long initialSizeBytes) +``` + +Configure the temporary workspace on this resources object as an uncapped pool backed by the +current device memory resource. After the initial reservation is allocated on first use, +subsequent calls to `cuvsRMMAlloc` / `cuvsRMMFree` on this handle hit the pool +cache rather than calling `cudaMallocAsync` / `cudaFreeAsync`, reducing CUDA +context lock contention under concurrent query threads. The pool grows without shrinking: +freed allocations are returned to the pool rather than to the device, so the pool's +high-water mark only increases until the resources object is closed. + +The pool is per-resources-handle (i.e. per query thread when resources are thread-local), +so there is no cross-thread pool mutex contention. Call this once after creating the resources +object; calling it again replaces the pool. + +**Parameters** + +| Name | Description | +| --- | --- | +| `initialSizeBytes` | initial pool reservation in bytes; must be `> 0`. Size `initialSizeBytes` to cover the steady-state working set to avoid growth after warmup | + +**Throws** + +| Type | Description | +| --- | --- | +| `IllegalArgumentException` | if `initialSizeBytes` is not greater than 0 | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:78`_ ### create @@ -87,7 +119,7 @@ Equivalent to create(CuVSProvider.tempDirectory()) \} -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:66`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:87`_ ### create @@ -110,6 +142,40 @@ Creates a new resources. | `UnsupportedOperationException` | if the provider does not cuvs | | `LibraryException` | if the native library cannot be loaded | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:77`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:98`_ + +### create + +```java +static CuVSResources create( Path tempDirectory, Path memoryTrackingCsvPath, Duration memoryTrackingSampleInterval) throws Throwable +``` + +Creates a new resources whose memory allocations are tracked and written as +CSV samples from a background thread. + +The returned handle wraps all reachable memory resources (host, pinned, +managed, device, workspace, large_workspace) with allocation-tracking +adaptors and replaces the global host and device memory resources for the +lifetime of the handle. It is otherwise indistinguishable from a handle +created by `#create(Path)` and can be used wherever a +`CuVSResources` is accepted. The CSV reporter is stopped and the +global memory resources are restored when the handle is closed. + +**Parameters** + +| Name | Description | +| --- | --- | +| `tempDirectory` | the temporary directory to use for intermediate operations | +| `memoryTrackingCsvPath` | path to the output CSV file (created/truncated) | +| `memoryTrackingSampleInterval` | minimum interval between successive CSV samples | + +**Throws** + +| Type | Description | +| --- | --- | +| `UnsupportedOperationException` | if the provider does not support cuvs | +| `LibraryException` | if the native library cannot be loaded | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:123`_ -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:15`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSResources.java:16`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-filterbitsethandle.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-filterbitsethandle.md new file mode 100644 index 0000000000..329f16085a --- /dev/null +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-filterbitsethandle.md @@ -0,0 +1,103 @@ +--- +slug: api-reference/java-api-com-nvidia-cuvs-filterbitsethandle +--- + +# FilterBitsetHandle + +_Java package: `com.nvidia.cuvs`_ + +```java +public interface FilterBitsetHandle extends AutoCloseable +``` + +Holds a precomputed multi-partition filter bitset and manages its device-memory lifecycle. + +The packed `long[]` host arrays are immutable after construction. A single shared device +allocation is uploaded lazily on first use and reused thereafter. + +Device pool configuration + +Filter bitset device allocations use a shared, process-lifetime resources object with a +growable RMM pool initially sized to 4 MiB. Applications can set the +`com.nvidia.cuvs.filterBitsetPoolSize` system property before the first filter bitset upload +to customize it: zero explicitly disables pooling, while a positive value selects the initial +size. An invalid or negative value produces a warning and uses the 4 MiB default. + +The initial size is a reservation, not a memory cap or a host-side cache policy. The pool can +grow as needed. + +Lifecycle + +The handle is reference-counted. Construction grants one initial reference, held by the owner +(typically a host-level cache), which is released by `#close()`. A thread that uses the +handle concurrently — e.g. while it may be evicted and closed by another thread — must guard the +use with `#tryIncRef()` / `#decRef()`. The shared device allocation is released only +when the last reference is dropped, so a concurrent `#close()` cannot free memory that is +still in use. + +## Public Members + +### tryIncRef + +```java +boolean tryIncRef() +``` + +Attempts to acquire a reference to this handle, preventing its device allocation from being +released until a matching `#decRef()`. Callers that pass the handle to a search (or +otherwise touch its device allocation) must hold a reference for the duration of that use. + +**Returns** + +`true` if a reference was acquired; `false` if the handle has already been fully released, in which case no reference is acquired and it must not be used + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/FilterBitsetHandle.java:46`_ + +### decRef + +```java +void decRef() +``` + +Releases a reference previously acquired via `#tryIncRef()`. When the last outstanding +reference is released, the shared device allocation is freed. + +**Throws** + +| Type | Description | +| --- | --- | +| `IllegalStateException` | if called without a matching `#tryIncRef()` | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/FilterBitsetHandle.java:54`_ + +### create + +```java +static FilterBitsetHandle create(long[] combinedLongs) +``` + +Creates a handle from one partition's pre-packed bitset (one bit per vector in that partition). +In a multi-partition search each partition supplies its own handle. + +**Parameters** + +| Name | Description | +| --- | --- | +| `combinedLongs` | packed bitset words for a single partition | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/FilterBitsetHandle.java:62`_ + +### close + +```java +@Override void close() +``` + +Releases the initial reference held since construction. Equivalent to a single `#decRef()` +of the owner's reference; the device allocation is freed once this and every reference acquired +via `#tryIncRef()` has been released. Idempotent — releasing the initial reference more +than once has no effect. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/FilterBitsetHandle.java:72`_ + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/FilterBitsetHandle.java:37`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswaceparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswaceparams.md index 11d71dff1b..a7c002e06d 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswaceparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswaceparams.md @@ -30,7 +30,7 @@ Gets the number of partitions for ACE partitioned build. the number of partitions -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:37`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:41`_ ### getBuildDir @@ -44,7 +44,7 @@ Gets the directory to store ACE build artifacts. the build directory path -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:46`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:50`_ ### isUseDisk @@ -58,7 +58,7 @@ Gets whether disk-based storage is enabled for ACE build. true if disk mode is enabled -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:55`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:59`_ ### getMaxHostMemoryGb @@ -72,7 +72,7 @@ Gets the maximum host memory limit in GiB. the max host memory limit (0 means use available memory) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:64`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:68`_ ### getMaxGpuMemoryGb @@ -86,7 +86,7 @@ Gets the maximum GPU memory limit in GiB. the max GPU memory limit (0 means use available memory) -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:73`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:77`_ ### Builder @@ -96,7 +96,7 @@ public Builder() Constructs this Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:106`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:110`_ ### withNpartitions @@ -129,7 +129,7 @@ constraints and a warning will be issued. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:127`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:131`_ ### withBuildDir @@ -150,7 +150,7 @@ Used when useDisk is true or when the graph does not fit in memory. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:139`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:143`_ ### withUseDisk @@ -171,7 +171,7 @@ When true, enables disk-based operations for memory-efficient graph construction an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:151`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:155`_ ### withMaxHostMemoryGb @@ -194,7 +194,7 @@ Useful for testing or when running alongside other memory-intensive processes. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:165`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:169`_ ### withMaxGpuMemoryGb @@ -217,7 +217,7 @@ Useful for testing or when running alongside other memory-intensive processes. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:179`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:183`_ ### build @@ -231,6 +231,6 @@ Builds an instance of `HnswAceParams`. an instance of `HnswAceParams` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:189`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:193`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswAceParams.java:16`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindex.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindex.md index 36d2623a2e..338dfdb0b3 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindex.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindex.md @@ -123,7 +123,7 @@ A new HNSW index ready for search | --- | --- | | `Throwable` | if an error occurs during building | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:75`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:70`_ ### from @@ -144,7 +144,7 @@ needed. an instance of this Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:96`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:90`_ ### withIndexParams @@ -165,7 +165,7 @@ Builder. An instance of this Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:105`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:99`_ ### build @@ -179,6 +179,6 @@ Builds and returns an instance of CagraIndex. an instance of CagraIndex -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:112`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:106`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndex.java:17`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindexparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindexparams.md index 7b1951fc08..7f0504b010 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindexparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswindexparams.md @@ -89,7 +89,7 @@ used to derive the internal graph build parameters for GPU construction. the M parameter -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:133`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:132`_ ### getMetric @@ -103,7 +103,7 @@ Gets the distance metric type. the metric type -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:142`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:141`_ ### getAceParams @@ -171,7 +171,7 @@ Sets the maximum candidate list size used during index construction. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:215`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:213`_ ### withNumThreads @@ -192,7 +192,7 @@ is `CPU`. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:227`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:225`_ ### withVectorDimension @@ -212,7 +212,7 @@ Sets the vector dimension an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:238`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:236`_ ### withM @@ -220,8 +220,8 @@ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:238` public Builder withM(long m) ``` -Sets the HNSW M parameter: number of bi-directional links per node -used to derive the internal graph build parameters for GPU construction. +Sets the HNSW M parameter: number of bi-directional links per node used to derive the internal +graph build parameters for GPU construction. **Parameters** @@ -233,7 +233,7 @@ used to derive the internal graph build parameters for GPU construction. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:251`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:248`_ ### withMetric @@ -253,7 +253,7 @@ Sets the distance metric type. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:262`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:259`_ ### withAceParams @@ -261,8 +261,8 @@ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:262` public Builder withAceParams(HnswAceParams aceParams) ``` -Sets optional ACE parameters for explicit out-of-core graph construction. When not set, the graph -build algorithm is selected automatically. +Sets optional ACE parameters for explicit out-of-core graph construction. When not set, the +graph build algorithm is selected automatically. **Parameters** @@ -274,7 +274,7 @@ build algorithm is selected automatically. an instance of Builder -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:273`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:271`_ ### build @@ -288,6 +288,6 @@ Builds an instance of `HnswIndexParams`. an instance of `HnswIndexParams` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:283`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:281`_ _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswIndexParams.java:12`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswquery.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswquery.md index c66a6b64e7..dd9f545b26 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswquery.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-hnswquery.md @@ -19,27 +19,6 @@ between threads can lead to memory allocation errors or JVM crashes. ## Public Members -### HnswQuery - -```java -private HnswQuery( HnswSearchParams hnswSearchParams, float[][] queryVectors, LongToIntFunction mapping, int topK, CuVSResources resources) -``` - -Constructs an instance of `HnswQuery` using queryVectors, mapping, and -topK. - -**Parameters** - -| Name | Description | -| --- | --- | -| `hnswSearchParams` | the search parameters to use | -| `queryVectors` | 2D float query vector array | -| `mapping` | a function mapping ordinals (neighbor IDs) to custom user IDs | -| `topK` | the top k results to return | -| `resources` | CuVSResources instance to use for this query | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/HnswQuery.java:38`_ - ### getHnswSearchParams ```java diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitioncagrasearch.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitioncagrasearch.md new file mode 100644 index 0000000000..237103b35a --- /dev/null +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitioncagrasearch.md @@ -0,0 +1,62 @@ +--- +slug: api-reference/java-api-com-nvidia-cuvs-multipartitioncagrasearch +--- + +# MultiPartitionCagraSearch + +_Java package: `com.nvidia.cuvs`_ + +```java +public class MultiPartitionCagraSearch +``` + +Performs an approximate nearest neighbor search across multiple CAGRA index partitions in a +single native call. The caller supplies one `CagraQuery` whose query matrix is searched +against every partition; cuVS performs the per-partition searches, the cross-partition top-k +merge, and the post-processing internally, then returns the merged results. + +As with `CagraIndex#search(CagraQuery)`, the query vectors may be either host- or +device-resident; host-resident query matrices are uploaded to the device internally. + +## Public Members + +### search + +```java +public static MultiPartitionSearchResults search( CuVSResources resources, List indices, CagraQuery query, int k) throws Throwable +``` + +Searches multiple CAGRA index partitions for the global top-k nearest neighbors. + +**Parameters** + +| Name | Description | +| --- | --- | +| `resources` | shared `CuVSResources` handle | +| `indices` | one `CagraIndex` per partition, in partition order | +| `query` | a single `CagraQuery` whose query matrix is searched against every partition; its search parameters are shared across all partitions | +| `k` | number of global nearest neighbors to return per query | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionCagraSearch.java:33`_ + +### search + +```java +public static MultiPartitionSearchResults search( CuVSResources resources, List indices, CagraQuery query, int k, List filters) throws Throwable +``` + +Searches multiple CAGRA index partitions with optional per-partition device-side filters. + +**Parameters** + +| Name | Description | +| --- | --- | +| `resources` | shared `CuVSResources` handle | +| `indices` | one `CagraIndex` per partition, in partition order | +| `query` | a single `CagraQuery` whose query matrix is searched against every partition | +| `k` | number of global nearest neighbors to return per query | +| `filters` | one filter per partition, in the same order as `indices`, or `null`/empty for a fully unfiltered search. When non-null, its size must equal `indices.size()`; a `null` entry means no filter for that partition. Each handle must be obtained from `FilterBitsetHandle#create(long[])` for that partition's packed bitset; handles from other sources are not supported. | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionCagraSearch.java:53`_ + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionCagraSearch.java:21`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitionsearchresults.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitionsearchresults.md new file mode 100644 index 0000000000..5f16df9a02 --- /dev/null +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-multipartitionsearchresults.md @@ -0,0 +1,66 @@ +--- +slug: api-reference/java-api-com-nvidia-cuvs-multipartitionsearchresults +--- + +# MultiPartitionSearchResults + +_Java package: `com.nvidia.cuvs`_ + +```java +public class MultiPartitionSearchResults +``` + +Holds the decoded results of a multi-partition GPU search. + +Each entry `i` in [0, `#count`) identifies: + +which input partition the result came from (`#getPartitionIndex(int)`) +the local vector ordinal within that partition (`#getOrdinal(int)`) +the raw CAGRA distance (`#getDistance(int)`) + + +The caller is responsible for mapping ordinals to its own global identifiers. + +## Public Members + +### count + +```java +public int count() +``` + +Number of valid results (may be less than k if fewer candidates exist). + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionSearchResults.java:36`_ + +### getPartitionIndex + +```java +public int getPartitionIndex(int i) +``` + +Index into the original partition list for result `i`. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionSearchResults.java:41`_ + +### getOrdinal + +```java +public int getOrdinal(int i) +``` + +Local vector ordinal within the partition for result `i`. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionSearchResults.java:46`_ + +### getDistance + +```java +public float getDistance(int i) +``` + +Post-processed distance for result `i` (scaled + metric-transformed). + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionSearchResults.java:51`_ + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/MultiPartitionSearchResults.java:21`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md index 5cc6c3eeb0..3301bfa7ab 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-spi-cuvsprovider.md @@ -23,7 +23,7 @@ static Path tempDirectory() The temporary directory to use for intermediate operations. Defaults to \{@systemProperty java.io.tmpdir\}. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:22`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:24`_ ### nativeLibraryPath @@ -34,7 +34,7 @@ default Path nativeLibraryPath() The directory where to extract and install the native library. Defaults to \{@systemProperty java.io.tmpdir\}. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:30`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:32`_ ### newCuVSResources @@ -44,7 +44,32 @@ CuVSResources newCuVSResources(Path tempDirectory) throws Throwable Creates a new CuVSResources. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:35`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:37`_ + +### newCuVSResources + +```java +default CuVSResources newCuVSResources( Path tempDirectory, Path memoryTrackingCsvPath, Duration memoryTrackingSampleInterval) throws Throwable +``` + +Creates a new CuVSResources whose memory allocations are tracked and +written as CSV samples from a background thread. + +This method is declared as a `default` method so that adding it +does not break binary compatibility with providers compiled against an +earlier version of this interface; the default implementation throws +`UnsupportedOperationException` and providers must override it to +opt in. + +**Parameters** + +| Name | Description | +| --- | --- | +| `tempDirectory` | the temporary directory to use for intermediate operations | +| `memoryTrackingCsvPath` | path to the output CSV file (created/truncated) | +| `memoryTrackingSampleInterval` | minimum interval between successive CSV samples | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:56`_ ### newHostMatrixBuilder @@ -54,7 +79,7 @@ CuVSMatrix.Builder newHostMatrixBuilder( long size, long dimensi Create a `CuVSMatrix.Builder` instance for a host memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:38`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:64`_ ### newHostMatrixBuilder @@ -64,7 +89,7 @@ CuVSMatrix.Builder newHostMatrixBuilder( long size, long columns Create a `CuVSMatrix.Builder` instance for a host memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:42`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:68`_ ### newDeviceMatrixBuilder @@ -74,7 +99,7 @@ CuVSMatrix.Builder newDeviceMatrixBuilder( CuVSResources cuVSR Create a `CuVSMatrix.Builder` instance for a device memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:46`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:72`_ ### newDeviceMatrixBuilder @@ -84,7 +109,7 @@ CuVSMatrix.Builder newDeviceMatrixBuilder( CuVSResources cuVSR Create a `CuVSMatrix.Builder` instance for a device memory matrix * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:50`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:76`_ ### newNativeMatrixBuilder @@ -108,7 +133,7 @@ The caller will need to invoke the factory via the `MethodHandle#invokeExact` me a MethodHandle which can be invoked to build a CuVSMatrix from an external `MemorySegment` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:73`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:99`_ ### newNativeMatrixBuilderWithStrides @@ -134,7 +159,7 @@ The caller will need to invoke the factory via the `MethodHandle#invokeExact` me a MethodHandle which can be invoked to build a CuVSMatrix from an external `MemorySegment` -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:92`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:118`_ ### newMatrixFromArray @@ -144,7 +169,7 @@ CuVSMatrix newMatrixFromArray(float[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:95`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:121`_ ### newMatrixFromArray @@ -154,7 +179,7 @@ CuVSMatrix newMatrixFromArray(int[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:98`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:124`_ ### newMatrixFromArray @@ -164,7 +189,7 @@ CuVSMatrix newMatrixFromArray(byte[][] vectors) Create a `CuVSMatrix` from an on-heap array * -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:101`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:127`_ ### newBruteForceIndexBuilder @@ -174,7 +199,7 @@ BruteForceIndex.Builder newBruteForceIndexBuilder(CuVSResources cuVSResources) t Creates a new BruteForceIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:104`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:130`_ ### newCagraIndexBuilder @@ -184,7 +209,7 @@ CagraIndex.Builder newCagraIndexBuilder(CuVSResources cuVSResources) throws Unsu Creates a new CagraIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:108`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:134`_ ### newHnswIndexBuilder @@ -194,7 +219,7 @@ HnswIndex.Builder newHnswIndexBuilder(CuVSResources cuVSResources) throws Unsupp Creates a new HnswIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:112`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:138`_ ### hnswIndexFromCagra @@ -221,7 +246,7 @@ A new HNSW index | --- | --- | | `Throwable` | if an error occurs during conversion | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:123`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:149`_ ### hnswIndexBuild @@ -249,7 +274,7 @@ A new HNSW index ready for search | --- | --- | | `Throwable` | if an error occurs during building | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:134`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:160`_ ### newTieredIndexBuilder @@ -259,7 +284,7 @@ TieredIndex.Builder newTieredIndexBuilder(CuVSResources cuVSResources) throws Un Creates a new TieredIndex Builder. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:138`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:164`_ ### mergeCagraIndexes @@ -285,7 +310,7 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:148`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:174`_ ### mergeCagraIndexes @@ -312,7 +337,83 @@ A new merged CAGRA index | --- | --- | | `Throwable` | if an error occurs during the merge operation | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:158`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:184`_ + +### isCagraPaddedDataset + +```java +default boolean isCagraPaddedDataset(CuVSMatrix dataset) +``` + +Reports whether the rows of `dataset` already sit at the row stride CAGRA requires, which +is the row length in bytes rounded up to a 16 byte boundary. + +This is the question that decides which of the two padded dataset factories a caller has to +use: `CagraIndex#makePaddedDatasetView(CuVSMatrix)` for a device matrix that is already at +that stride, and `CagraIndex#makePaddedDataset(CuVSMatrix)` for one that is not. Asking +for the wrong one is an error rather than an inefficiency, and the stride of a matrix is not +visible outside this library, so callers cannot answer it for themselves. + +**Parameters** + +| Name | Description | +| --- | --- | +| `dataset` | the matrix to inspect | + +**Returns** + +true when the rows are already padded the way CAGRA requires + +**Throws** + +| Type | Description | +| --- | --- | +| `UnsupportedOperationException` | if this provider cannot answer | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:204`_ + +### newFilterBitsetHandle + +```java +FilterBitsetHandle newFilterBitsetHandle(long[] combinedLongs) +``` + +Creates a device-backed multi-partition filter handle from the pre-packed combined bitset. +Per-partition bit offsets are recomputed inside cuVS from the index sizes. + +**Parameters** + +| Name | Description | +| --- | --- | +| `combinedLongs` | packed bitset words for a single partition | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:215`_ + +### searchCagraMultiPartition + +```java +MultiPartitionSearchResults searchCagraMultiPartition( CuVSResources resources, List indices, CagraQuery query, int k, List filters) throws Throwable +``` + +Searches multiple CAGRA index partitions for the global top-k nearest neighbors per query. + +**Parameters** + +| Name | Description | +| --- | --- | +| `resources` | shared resources handle | +| `indices` | one CAGRA index per partition, in partition order | +| `query` | query whose vectors are searched against every partition | +| `k` | number of global nearest neighbors to return per query | +| `filters` | one filter per partition (same order as `indices`), or `null`/empty for unfiltered search; a `null` entry means no filter for that partition | + +**Throws** + +| Type | Description | +| --- | --- | +| `Throwable` | if an error occurs during the search | + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:228`_ ### gpuInfoProvider @@ -322,7 +423,7 @@ GPUInfoProvider gpuInfoProvider() Returns a `GPUInfoProvider` to query the system for GPU related information -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:165`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:237`_ ### enableRMMPooledMemory @@ -341,7 +442,7 @@ This operation has a global effect, and will affect all resources on the current | `initialPoolSizePercent` | The initial pool size, in percentage of the total GPU memory | | `maxPoolSizePercent` | The maximum pool size, in percentage of the total GPU memory | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:179`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:251`_ ### enableRMMManagedPooledMemory @@ -360,7 +461,22 @@ This operation has a global effect, and will affect all resources on the current | `initialPoolSizePercent` | The initial pool size, in percentage of the total GPU memory | | `maxPoolSizePercent` | The maximum pool size, in percentage of the total GPU memory | -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:189`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:261`_ + +### enableRMMAsyncMemory + +```java +void enableRMMAsyncMemory() +``` + +Switch RMM allocations to use stream-ordered asynchronous allocation +(`cudaMallocAsync` / `cudaFreeAsync`). Unlike the pool resource, this resource +returns memory to the stream without blocking the CPU, eliminating device-wide synchronization +on deallocation. This is especially beneficial when multiple CAGRA searches run concurrently +on separate CUDA streams, because internal workspace allocations no longer serialize kernel +launches. This operation has a global effect and will affect all resources on the current device. + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:271`_ ### resetRMMPooledMemory @@ -370,7 +486,7 @@ void resetRMMPooledMemory() Disables pooled memory on the current device, reverting back to the default setting. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:192`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:274`_ ### provider @@ -380,7 +496,7 @@ static CuVSProvider provider() Retrieves the system-wide provider. -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:195`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:277`_ ### cagraIndexParamsFromHnswParams @@ -410,6 +526,30 @@ may be shifted along the curve right or left. See the heuristics descriptions fo A new CAGRA index parameters object -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:215`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:297`_ + +### cagraIndexParamsFromDataset + +```java +CagraIndexParams cagraIndexParamsFromDataset( long rows, long dim, long graphDegree, CagraIndexParams.CuvsDistanceType metric, long buildQuality) +``` + +Create CAGRA index parameters heuristically tuned for a dataset. + +**Parameters** + +| Name | Description | +| --- | --- | +| `rows` | The number of rows in the input dataset | +| `dim` | The number of dimensions in the input dataset | +| `graphDegree` | Degree of the output graph | +| `metric` | The distance metric to search | +| `buildQuality` | Higher values increase build quality (and cost) up to a point | + +**Returns** + +A new CAGRA index parameters object + +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:315`_ -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:15`_ +_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/spi/CuVSProvider.java:17`_ diff --git a/fern/pages/java_api/java-api-com-nvidia-cuvs-tieredindexparams.md b/fern/pages/java_api/java-api-com-nvidia-cuvs-tieredindexparams.md index 86e0362450..2ac397acc4 100644 --- a/fern/pages/java_api/java-api-com-nvidia-cuvs-tieredindexparams.md +++ b/fern/pages/java_api/java-api-com-nvidia-cuvs-tieredindexparams.md @@ -25,22 +25,6 @@ L2 (Euclidean) distance metric _Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/TieredIndexParams.java:20`_ -### TieredIndexParams - -```java -private TieredIndexParams(Builder builder) -``` - -Private constructor used by the Builder. - -**Parameters** - -| Name | Description | -| --- | --- | -| `builder` | The Builder instance containing the configuration | - -_Source: `java/cuvs-java/src/main/java/com/nvidia/cuvs/TieredIndexParams.java:35`_ - ### getMetric ```java diff --git a/fern/pages/python_api/python-api-common.md b/fern/pages/python_api/python-api-common.md index 996cb250c0..4468e932e8 100644 --- a/fern/pages/python_api/python-api-common.md +++ b/fern/pages/python_api/python-api-common.md @@ -37,6 +37,8 @@ details of this struct. | Name | Type | Description | | --- | --- | --- | | `stream` | `Optional stream to use for ordering CUDA instructions` | | +| `memory_tracking_csv_path` | `Optional path-like` | If provided, the handle wraps all reachable memory resources (host, pinned, managed, device, workspace, large_workspace) with allocation-tracking adaptors and logs CSV samples to the given file from a background thread. The CSV file is created or truncated. The global host and device memory resources are replaced for the lifetime of the handle and restored when the handle is destroyed. | +| `memory_tracking_sample_interval_ms` | `int, default \`\`10\`\`` | Minimum interval between successive CSV samples, in milliseconds. Ignored when ``memory_tracking_csv_path`` is ``None``. | **Examples** @@ -62,6 +64,14 @@ Using a cuPy stream with cuVS Resources: >>> handle = Resources(stream=cupy_stream.ptr) ``` +Tracking memory allocations to a CSV file: + +```python +>>> from cuvs.common import Resources +>>> handle = Resources(memory_tracking_csv_path="/tmp/allocations.csv", +... memory_tracking_sample_interval_ms=10) # doctest: +SKIP +``` + **Members** | Name | Kind | @@ -195,3 +205,87 @@ and call sync on that resources when the function exits. This will also insert the appropriate docstring for the resources parameter + +## Dataset + +```python +cdef class Dataset +``` + +Wrapper around a ``cuvsDataset`` handle. + +**Members** + +| Name | Kind | +| --- | --- | +| `memory_type` | property | +| `layout` | property | +| `is_owning` | property | +| `dtype` | property | + +### memory_type + +```python +def memory_type(self) +``` + +### layout + +```python +def layout(self) +``` + +### is_owning + +```python +def is_owning(self) +``` + +### dtype + +```python +def dtype(self) +``` + +## make_device_padded_dataset + +`@auto_sync_resources` + +```python +def make_device_padded_dataset(dataset, resources=None) +``` + +Create a device-padded ``Dataset`` from a host or device array. + +The input must be a row-major 2-D matrix. Host arrays are always copied into +newly allocated device-padded storage (``is_owning`` is ``True``). Device +arrays are copied when their row stride does not already match the +required padded width; if the stride is already correct, a non-owning +padded view of the input is returned and the caller must keep ``dataset`` +alive for as long as the ``Dataset`` is used. + +**Parameters** + +| Name | Type | Description | +| --- | --- | --- | +| `dataset` | `array interface compliant matrix, shape \`\`(n_samples, dim)\`\`` | Host (e.g. NumPy) or device (e.g. CuPy) array. Supported dtypes are ``float32``, ``float16``, ``int8``, and ``uint8``. | +| `resources` | `cuvs.common.Resources, optional` | | + +**Returns** + +| Name | Type | Description | +| --- | --- | --- | +| `dataset` | `Dataset` | A device-resident padded dataset handle. Check ``is_owning`` to see whether the handle owns its storage or is a view of ``dataset``. | + +**Examples** + +```python +>>> import cupy as cp +>>> from cuvs.common import make_device_padded_dataset +>>> X = cp.random.random_sample((1000, 50), dtype=cp.float32) +>>> ds = make_device_padded_dataset(X) +>>> ds.memory_type +'device' +>>> ds.layout +'padded' +``` diff --git a/fern/pages/python_api/python-api-neighbors-all-neighbors.md b/fern/pages/python_api/python-api-neighbors-all-neighbors.md index 93b2409cc1..281299f708 100644 --- a/fern/pages/python_api/python-api-neighbors-all-neighbors.md +++ b/fern/pages/python_api/python-api-neighbors-all-neighbors.md @@ -100,9 +100,9 @@ vectors in the dataset. | `dataset` | `array_like` | Training dataset to build the k-NN graph for. Can be provided on host (for multi-GPU build) or device (for single-GPU build). Host vs device location is automatically detected. Supported dtype: float32 | | `k` | `int` | Number of nearest neighbors to find for each point | | `params` | `AllNeighborsParams` | Parameters object containing all build settings including algorithm choice and algorithm-specific parameters. | -| `indices` | `array_like, optional` | Optional output buffer for indices [num_rows x k] on device (int64). If not provided, will be allocated automatically. | -| `distances` | `array_like, optional` | Optional output buffer for distances [num_rows x k] on device (float32) | -| `core_distances` | `array_like, optional` | Optional output buffer for core distances [num_rows] on device (float32). Requires distances parameter to be provided. | +| `indices` | `array_like, optional` | Optional output buffer for indices [num_rows x k] (int64), on host or device. If not provided, will be allocated automatically (on device, unless the other provided outputs are on host). A host dataset supports host or device outputs; a device dataset requires device outputs. All provided outputs must share the same memory space. | +| `distances` | `array_like, optional` | Optional output buffer for distances [num_rows x k] (float32), on host or device. | +| `core_distances` | `array_like, optional` | Optional output buffer for core distances [num_rows] (float32), on host or device. Requires distances parameter to be provided. | | `alpha` | `float, default=1.0` | Mutual-reachability scaling; used only when core_distances is provided | | `resources` | `Resources or MultiGpuResources, optional` | CUDA resources to use for the operation. If not provided, a default Resources object will be created. Use MultiGpuResources to enable multi-GPU execution across multiple devices. | @@ -110,6 +110,6 @@ vectors in the dataset. | Name | Type | Description | | --- | --- | --- | -| `indices` | `array_like` | k-NN indices for each point [num_rows x k], always on device. If indices buffer was provided, returns the same array filled with results. | +| `indices` | `array_like` | k-NN indices for each point [num_rows x k], on the same memory space as the outputs (device by default). If an indices buffer was provided, returns the same array filled with results. | | `distances` | `array_like or None` | k-NN distances if distances buffer was provided, None otherwise | | `core_distances` | `array_like or None` | Core distances if core_distances buffer was provided, None otherwise | diff --git a/fern/pages/python_api/python-api-neighbors-cagra.md b/fern/pages/python_api/python-api-neighbors-cagra.md index 4012092b73..c7c74d8d4f 100644 --- a/fern/pages/python_api/python-api-neighbors-cagra.md +++ b/fern/pages/python_api/python-api-neighbors-cagra.md @@ -24,7 +24,7 @@ for each partition independently. | --- | --- | --- | | `npartitions` | `int, default = 0` | Number of partitions for ACE partitioned build. When set to 0 (default), the number of partitions is automatically derived based on available host and GPU memory to maximize partition size while ensuring the build fits in memory.

Small values might improve recall but potentially degrade performance and increase memory usage. Partitions should not be too small to prevent issues in KNN graph construction. The partition size is on average 2 * (n_rows / npartitions) * dim * sizeof(T). 2 is because of the core and augmented vectors. Please account for imbalance in the partition sizes (up to 3x in our tests).

If the specified number of partitions results in partitions that exceed available memory, the value will be automatically increased to fit memory constraints and a warning will be issued. | | `ef_construction` | `int, default = 120` | The index quality for the ACE build. Bigger values increase the index quality. At some point, increasing this will no longer improve the quality. | -| `build_dir` | `str, default = "/tmp/ace_build"` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph). Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. | +| `build_dir` | `str, default = "/tmp/ace_build"` | Directory to store ACE build artifacts (e.g., KNN graph, optimized graph). Used when `use_disk` is true or when the graph does not fit in host and GPU memory. This should be the fastest disk in the system and hold enough space for twice the dataset, final graph, and label mapping. The directory may already exist, but ACE's named artifacts must not already exist. Simultaneous builds must use different directories. On failure, ACE removes only artifacts it created and never deletes unrelated directory contents. | | `use_disk` | `bool, default = False` | Whether to use disk-based storage for ACE build. When true, enables disk-based operations for memory-efficient graph construction. | | `max_host_memory_gb` | `float, default = 0` | Maximum host memory to use for ACE build in GiB. When set to 0 (default), uses available host memory. Useful for testing or when running alongside other memory-intensive processes. | | `max_gpu_memory_gb` | `float, default = 0` | Maximum GPU memory to use for ACE build in GiB. When set to 0 (default), uses available GPU memory. Useful for testing or when running alongside other memory-intensive processes. | @@ -89,85 +89,6 @@ def max_gpu_memory_gb(self) def get_handle(self) ``` -## CompressionParams - -```python -cdef class CompressionParams -``` - -Parameters for VPQ Compression - -**Parameters** - -| Name | Type | Description | -| --- | --- | --- | -| `pq_bits` | `int` | The bit length of the vector element after compression by PQ.
Possible values: [4, 5, 6, 7, 8]. The smaller the 'pq_bits', the smaller the index size and the better the search performance, but the lower the recall. | -| `pq_dim` | `int` | The dimensionality of the vector after compression by PQ. When zero, an optimal value is selected using a heuristic. | -| `vq_n_centers` | `int` | Vector Quantization (VQ) codebook size - number of "coarse cluster centers". When zero, an optimal value is selected using a heuristic. | -| `kmeans_n_iters` | `int` | The number of iterations searching for kmeans centers (both VQ & PQ phases). | -| `vq_kmeans_trainset_fraction` | `float` | The fraction of data to use during iterative kmeans building (VQ phase). When zero, an optimal value is selected using a heuristic. | -| `pq_kmeans_trainset_fraction` | `float` | The fraction of data to use during iterative kmeans building (PQ phase). When zero, an optimal value is selected using a heuristic. | - -**Constructor** - -```python -def __init__(self, *, pq_bits=8, pq_dim=0, vq_n_centers=0, kmeans_n_iters=25, vq_kmeans_trainset_fraction=0.0, pq_kmeans_trainset_fraction=0.0) -``` - -**Members** - -| Name | Kind | -| --- | --- | -| `pq_bits` | property | -| `pq_dim` | property | -| `vq_n_centers` | property | -| `kmeans_n_iters` | property | -| `vq_kmeans_trainset_fraction` | property | -| `pq_kmeans_trainset_fraction` | property | -| `get_handle` | method | - -### pq_bits - -```python -def pq_bits(self) -``` - -### pq_dim - -```python -def pq_dim(self) -``` - -### vq_n_centers - -```python -def vq_n_centers(self) -``` - -### kmeans_n_iters - -```python -def kmeans_n_iters(self) -``` - -### vq_kmeans_trainset_fraction - -```python -def vq_kmeans_trainset_fraction(self) -``` - -### pq_kmeans_trainset_fraction - -```python -def pq_kmeans_trainset_fraction(self) -``` - -### get_handle - -```python -def get_handle(self) -``` - ## ExtendParams ```python @@ -269,7 +190,6 @@ Parameters to build index for CAGRA nearest neighbor search | `intermediate_graph_degree` | `int, default = 128` | | | `graph_degree` | `int, default = 64` | | | `build_algo` | `str, default = "ivf_pq"` | string denoting the graph building algorithm to use.
Valid values for algo: ["ivf_pq", "nn_descent", "iterative_cagra_search", "ace"], where

- ivf_pq will use the IVF-PQ algorithm for building the knn graph
- nn_descent (experimental) will use the NN-Descent algorithm for building the knn graph. It is expected to be generally faster than ivf_pq.
- iterative_cagra_search will iteratively build the knn graph using CAGRA's search() and optimize()
- ace will use ACE (Augmented Core Extraction) for building indices for datasets too large to fit in GPU memory | -| `compression` | `CompressionParams, optional` | If compression is desired should be a CompressionParams object. If None compression will be disabled. | | `ivf_pq_build_params` | `cuvs.neighbors.ivf_pq.IndexParams, optional` | Parameters for IVF-PQ algorithm. If provided, it will be used for building the graph. | | `ivf_pq_search_params` | `cuvs.neighbors.ivf_pq.SearchParams, optional` | Parameters for IVF-PQ search. If provided, it will be used for searching the graph. | | `ace_params` | `AceParams, optional` | Parameters for ACE algorithm. If provided, it will be used for building the graph with ACE partitioning. | @@ -278,7 +198,7 @@ Parameters to build index for CAGRA nearest neighbor search **Constructor** ```python -def __init__(self, *, metric="sqeuclidean", intermediate_graph_degree=128, graph_degree=64, build_algo="ivf_pq", nn_descent_niter=20, compression=None, ivf_pq_build_params: ivf_pq.IndexParams = None, ivf_pq_search_params: ivf_pq.SearchParams = None, ace_params: AceParams = None, refinement_rate: float = 1.0) +def __init__(self, *, metric="sqeuclidean", intermediate_graph_degree=128, graph_degree=64, build_algo="ivf_pq", nn_descent_niter=20, ivf_pq_build_params: ivf_pq.IndexParams = None, ivf_pq_search_params: ivf_pq.SearchParams = None, ace_params: AceParams = None, refinement_rate: float = 1.0) ``` **Members** @@ -504,7 +424,7 @@ The following distance metrics are supported: | Name | Type | Description | | --- | --- | --- | | `index_params` | `IndexParams object` | | -| `dataset` | `CUDA array interface compliant matrix shape (n_samples, dim)` | Supported dtype [float, half, int8, uint8] **Note:** For ACE build algorithm, the dataset MUST be in host memory. Use NumPy arrays or call .get() on CuPy arrays before passing. | +| `dataset` | `CUDA array interface compliant matrix shape (n_samples, dim), or Dataset` | Supported dtype [float, half, int8, uint8] **Note:** For ACE build algorithm, the dataset MUST be in host memory. Use NumPy arrays or call .get() on CuPy arrays before passing. | | `resources` | `cuvs.common.Resources, optional` | | **Returns** @@ -543,14 +463,14 @@ The following distance metrics are supported: def extend(ExtendParams params, Index index, extended_dataset, new_start_row, resources=None) ``` -Extend a CAGRA index with additional vectors. +Extend a CAGRA index with additional vectors The caller owns dataset concatenation. Build a single padded device -dataset of shape `(n_old + n_new, dim)` with the original vectors in -rows `[0, new_start_row)` and the additional vectors in rows -`[new_start_row, n_rows)`. `new_start_row` must equal the current index -size. This function only extends the graph and rebinds the index to -`extended_dataset`; keep that view alive for the index lifetime. +dataset of shape ``(n_old + n_new, dim)`` with the original vectors in +rows ``[0, new_start_row)`` and the additional vectors in rows +``[new_start_row, n_rows)``. ``new_start_row`` must equal the current +index size. This function only extends the graph and rebinds the index +to ``extended_dataset``; keep that dataset alive for the index lifetime. **Parameters** @@ -558,8 +478,8 @@ size. This function only extends the graph and rebinds the index to | --- | --- | --- | | `params` | `ExtendParams object` | | | `index` | `Index` | Existing cagra index to extend | -| `extended_dataset` | `PaddedDatasetView` | Caller-owned padded view already containing old \|\| new | -| `new_start_row` | `int` | Row index where the additional vectors begin | +| `extended_dataset` | `Dataset or array` | Padded dataset already containing old \|\| new rows. | +| `new_start_row` | `int` | Row index where the additional vectors begin (must equal ``index`` size). | | `resources` | `cuvs.common.Resources, optional` | | ## from_graph @@ -592,10 +512,10 @@ Construct a cagra index from an existing graph and dataset `@auto_sync_resources` ```python -def load(filename, resources=None) +def load(index, filename, out_dataset=None, resources=None) ``` -Loads index from file. +Deserialize CAGRA index into an existing index handle. Saving / loading the index is experimental. The serialization format is subject to change, therefore loading an index saved with a previous @@ -605,15 +525,11 @@ version of cuvs is not guaranteed to work. | Name | Type | Description | | --- | --- | --- | +| `index` | `Index` | Pre-created index object to populate. | | `filename` | `string` | Name of the file. | +| `out_dataset` | `Dataset, optional` | Empty dataset populated when the file includes dataset storage. If omitted, only the graph is retained. | | `resources` | `cuvs.common.Resources, optional` | | -**Returns** - -| Name | Type | Description | -| --- | --- | --- | -| `index` | `Index` | | - ## save `@auto_sync_resources` @@ -649,7 +565,9 @@ subject to change. >>> index = cagra.build(cagra.IndexParams(), dataset) >>> # Serialize and deserialize the cagra index built >>> cagra.save("my_index.bin", index) ->>> index_loaded = cagra.load("my_index.bin") +>>> index_loaded = cagra.Index() +>>> out_dataset = cagra.Dataset() +>>> cagra.load(index_loaded, "my_index.bin", out_dataset=out_dataset) ``` ## search @@ -704,3 +622,15 @@ Find the k nearest neighbors for each query. >>> neighbors = cp.asarray(neighbors) >>> distances = cp.asarray(distances) ``` + +## update_dataset + +`@auto_sync_resources` + +```python +def update_dataset(Index index, padded_dataset, resources=None) +``` + +Update any CAGRA index layout with a padded dataset. + +Accepts a ``Dataset`` or array. The index becomes search-ready in padded layout. diff --git a/fern/pages/python_api/python-api-neighbors-mg-cagra.md b/fern/pages/python_api/python-api-neighbors-mg-cagra.md index dda3c00601..668fe21251 100644 --- a/fern/pages/python_api/python-api-neighbors-mg-cagra.md +++ b/fern/pages/python_api/python-api-neighbors-mg-cagra.md @@ -181,6 +181,9 @@ Build the multi-GPU CAGRA index from the dataset for efficient search. ```python >>> import numpy as np +>>> from pylibraft.common import device_ndarray +>>> from cuvs.common import make_device_padded_dataset +>>> from cuvs.neighbors import cagra as sg_cagra >>> from cuvs.neighbors.mg import cagra >>> n_samples = 50000 >>> n_features = 50 @@ -191,6 +194,9 @@ Build the multi-GPU CAGRA index from the dataset for efficient search. ... np.float32) >>> build_params = cagra.IndexParams(metric="sqeuclidean") >>> index = cagra.build(build_params, dataset) +>>> device_dataset = device_ndarray(dataset) +>>> padded_dataset = make_device_padded_dataset(device_dataset) +>>> _ = cagra.update_dataset(index, padded_dataset) >>> distances, neighbors = cagra.search(cagra.SearchParams(), ... index, dataset, k) >>> # Results are already in host memory (NumPy arrays) @@ -286,6 +292,18 @@ Search the multi-GPU CAGRA index for the k-nearest neighbors of each query. >>> # Results are already in host memory (NumPy arrays) ``` +## update_dataset + +`@auto_sync_multi_gpu_resources` + +```python +def update_dataset(Index index, padded_dataset, resources=None) +``` + +Update a multi-GPU CAGRA index with a padded dataset. + +Accepts a ``Dataset`` or array. + ## save `@auto_sync_multi_gpu_resources` diff --git a/fern/pages/python_api/python-api-preprocessing-pca.md b/fern/pages/python_api/python-api-preprocessing-pca.md index a23dc5881a..290b510711 100644 --- a/fern/pages/python_api/python-api-preprocessing-pca.md +++ b/fern/pages/python_api/python-api-preprocessing-pca.md @@ -91,12 +91,16 @@ Compute PCA (fit only). Computes the principal components, explained variances, singular values, and column means from the input data. +The input layout (C-contiguous / row-major or F-contiguous / col-major) +is preserved natively; no internal copy/transpose is performed. Output +arrays use the same layout as the input. + **Parameters** | Name | Type | Description | | --- | --- | --- | | `params` | `Params` | PCA parameters. ``params.copy`` should be True if you intend to reuse *X* after this call. | -| `X` | `device array-like, shape (n_samples, n_features), float32` | Input data (will be converted to col-major device memory). | +| `X` | `device array-like, shape (n_samples, n_features), float32` | Input data. Must be contiguous in either C- or F-order. | | `resources` | `cuvs.common.Resources, optional` | | **Returns** @@ -104,7 +108,7 @@ values, and column means from the input data. FitOutput Named tuple with fields: ``components``, ``explained_var``, ``explained_var_ratio``, ``singular_vals``, ``mu``, -``noise_vars``. +``noise_vars``. ``components`` matches the layout of *X*. **Examples** @@ -128,12 +132,15 @@ def fit_transform(Params params, X, resources=None) Compute PCA and transform the input data in a single operation. +The input layout (C- or F-contiguous) is preserved natively; output +arrays use the same layout. + **Parameters** | Name | Type | Description | | --- | --- | --- | | `params` | `Params` | PCA parameters. | -| `X` | `device array-like, shape (n_samples, n_features), float32` | Input data (will be converted to col-major device memory). | +| `X` | `device array-like, shape (n_samples, n_features), float32` | Input data. Must be contiguous in either C- or F-order. | | `resources` | `cuvs.common.Resources, optional` | | **Returns** @@ -141,7 +148,8 @@ Compute PCA and transform the input data in a single operation. FitTransformOutput Named tuple with fields: ``trans_input``, ``components``, ``explained_var``, ``explained_var_ratio``, ``singular_vals``, -``mu``, ``noise_vars``. +``mu``, ``noise_vars``. ``trans_input`` and ``components`` match +the layout of *X*. **Examples** @@ -166,6 +174,9 @@ def inverse_transform(Params params, trans_input, components, singular_vals, mu, Transform data from the PCA eigenspace back to the original space. +The layout (C- or F-contiguous) of ``trans_input`` is preserved; +``components`` and ``output`` are aligned to that layout. + **Parameters** | Name | Type | Description | @@ -175,7 +186,7 @@ Transform data from the PCA eigenspace back to the original space. | `components` | `device array-like, shape (n_components, n_features)` | Principal components from a prior fit. | | `singular_vals` | `device array-like, shape (n_components,)` | Singular values from a prior fit. | | `mu` | `device array-like, shape (n_features,)` | Column means from a prior fit. | -| `output` | `optional device array, shape (n_samples, n_features)` | Pre-allocated output buffer (col-major, float32). | +| `output` | `optional device array, shape (n_samples, n_features)` | Pre-allocated output buffer (float32). Layout is matched to ``trans_input``. | | `resources` | `cuvs.common.Resources, optional` | | **Returns** @@ -209,7 +220,9 @@ def transform(Params params, X, components, singular_vals, mu, trans_input=None, Transform data into the PCA eigenspace. Uses previously computed principal components from fit or -fit_transform. +fit_transform. The input layout (C- or F-contiguous) of *X* +determines the layout used internally; ``components`` and +``trans_input`` are aligned to that layout. **Parameters** @@ -220,7 +233,7 @@ fit_transform. | `components` | `device array-like, shape (n_components, n_features)` | Principal components from a prior fit. | | `singular_vals` | `device array-like, shape (n_components,)` | Singular values from a prior fit. | | `mu` | `device array-like, shape (n_features,)` | Column means from a prior fit. | -| `trans_input` | `optional device array, shape (n_samples, n_components)` | Pre-allocated output buffer (col-major, float32). | +| `trans_input` | `optional device array, shape (n_samples, n_components)` | Pre-allocated output buffer (float32). Layout is matched to *X*. | | `resources` | `cuvs.common.Resources, optional` | | **Returns** diff --git a/fern/pages/rust_api/index.md b/fern/pages/rust_api/index.md index 1547b3c101..1c73b989df 100644 --- a/fern/pages/rust_api/index.md +++ b/fern/pages/rust_api/index.md @@ -11,11 +11,13 @@ These pages are generated from the Rust crate sources under `rust/cuvs/src`. ## Common - [`cuvs`](/api-reference/rust-api-cuvs) +- [`cuvs::dataset`](/api-reference/rust-api-cuvs-dataset) - [`cuvs::dlpack`](/api-reference/rust-api-cuvs-dlpack) - [`cuvs::error`](/api-reference/rust-api-cuvs-error) - [`cuvs::neighbors`](/api-reference/rust-api-cuvs-neighbors) - [`cuvs::neighbors::filters`](/api-reference/rust-api-cuvs-neighbors-filters) - [`cuvs::resources`](/api-reference/rust-api-cuvs-resources) +- [`cuvs::version`](/api-reference/rust-api-cuvs-version) ## Distance diff --git a/fern/pages/rust_api/rust-api-cuvs-dataset.md b/fern/pages/rust_api/rust-api-cuvs-dataset.md new file mode 100644 index 0000000000..ab9db1810c --- /dev/null +++ b/fern/pages/rust_api/rust-api-cuvs-dataset.md @@ -0,0 +1,135 @@ +--- +slug: api-reference/rust-api-cuvs-dataset +--- + +# Dataset Module + +_Rust module: `cuvs::dataset`_ + +_Source: `rust/cuvs/src/dataset.rs`_ + +## DatasetKind + +```rust +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[non_exhaustive] +pub enum DatasetKind { + /* variants omitted */ +} +``` + +Host/device residency and row layout of a [`DatasetView`]. + +_Source: `rust/cuvs/src/dataset.rs:19`_ + +## Sealed + +```rust +pub trait Sealed { + /* required methods omitted */ +} +``` + +_Source: `rust/cuvs/src/dataset.rs:56`_ + +## CuvsDataset + +```rust +pub trait CuvsDataset: private::Sealed { + /* required methods omitted */ +} +``` + +A Rust wrapper accepted by native cuVS dataset operations. + +This trait is sealed; dataset handles can only be created by this crate. + +_Source: `rust/cuvs/src/dataset.rs:64`_ + +## DatasetView + +```rust +#[derive(Debug)] +pub struct DatasetView<'a> { + /* private fields */ +} +``` + +A non-owning CAGRA dataset view. + +The view records the storage's residency and layout while borrowing its +backing tensor for `'a`. Constructing a view allocates only native metadata; +it never copies vector storage. + +**Methods** + +| Name | Source | +| --- | --- | +| `new` | `rust/cuvs/src/dataset.rs:123` | + +### new + +```rust +pub fn new(res: &Resources, dataset: &'a T) -> Result +where +T: AsDlTensor + ?Sized, +``` + +Borrow a tensor as the host/device and padded/standard view matching its +DLPack shape/strides (CAGRA row-width rule). + +_Source: `rust/cuvs/src/dataset.rs:123`_ + +_Source: `rust/cuvs/src/dataset.rs:115`_ + +## PaddedDataset + +```rust +#[derive(Debug)] +pub struct PaddedDataset { + /* private fields */ +} +``` + +Storage owned by the caller, padded to CAGRA's required row width. + +Construction performs an explicit allocation and copy. Memory residency is +inferred from the source tensor; use [`DatasetView::new`] when its existing +layout is already suitable. + +**Methods** + +| Name | Source | +| --- | --- | +| `new` | `rust/cuvs/src/dataset.rs:172` | + +### new + +```rust +pub fn new(res: &Resources, dataset: &T) -> Result +where +T: AsDlTensor + ?Sized, +``` + +Copy a tensor into freshly allocated, CAGRA-padded storage. + +_Source: `rust/cuvs/src/dataset.rs:172`_ + +_Source: `rust/cuvs/src/dataset.rs:166`_ + +## Dataset + +```rust +#[derive(Debug)] +pub struct Dataset { + /* private fields */ +} +``` + +Owning dataset storage returned by CAGRA deserialization. + +The allocation preserves the serialized host/device residency and +standard/padded row layout. CAGRA keeps only a non-owning view, so this +owner must remain alive while the deserialized index uses it. + +_Source: `rust/cuvs/src/dataset.rs:220`_ diff --git a/fern/pages/rust_api/rust-api-cuvs-dlpack.md b/fern/pages/rust_api/rust-api-cuvs-dlpack.md index 1847adb60a..e1198d2a93 100644 --- a/fern/pages/rust_api/rust-api-cuvs-dlpack.md +++ b/fern/pages/rust_api/rust-api-cuvs-dlpack.md @@ -84,7 +84,7 @@ T::dl_dtype(), } ``` -_Source: `rust/cuvs/src/dlpack.rs:79`_ +_Source: `rust/cuvs/src/dlpack.rs:89`_ ## AsDlTensorMut @@ -100,7 +100,7 @@ In addition to the [`DLTensorView::from_raw_parts`] invariants, writable adapters must guarantee exclusive access to the data region. The `&mut self` receiver makes the compiler enforce that exclusivity for the borrow. -_Source: `rust/cuvs/src/dlpack.rs:88`_ +_Source: `rust/cuvs/src/dlpack.rs:98`_ ## DType @@ -112,7 +112,7 @@ pub trait DType { Maps a Rust element type to a DLPack [`DLDataType`]. -_Source: `rust/cuvs/src/dlpack.rs:93`_ +_Source: `rust/cuvs/src/dlpack.rs:103`_ ## DLPackError @@ -126,7 +126,7 @@ pub enum DLPackError { Error when converting an external tensor to a DLPack view. -_Source: `rust/cuvs/src/dlpack.rs:121`_ +_Source: `rust/cuvs/src/dlpack.rs:131`_ ## DLTensorView @@ -143,12 +143,12 @@ A non-owning, read-only DLPack tensor view. | Name | Source | | --- | --- | -| `from_raw_parts` | `rust/cuvs/src/dlpack.rs:176` | -| `ndim` | `rust/cuvs/src/dlpack.rs:226` | -| `shape` | `rust/cuvs/src/dlpack.rs:231` | -| `strides` | `rust/cuvs/src/dlpack.rs:236` | -| `dtype` | `rust/cuvs/src/dlpack.rs:241` | -| `device` | `rust/cuvs/src/dlpack.rs:246` | +| `from_raw_parts` | `rust/cuvs/src/dlpack.rs:186` | +| `ndim` | `rust/cuvs/src/dlpack.rs:236` | +| `shape` | `rust/cuvs/src/dlpack.rs:241` | +| `strides` | `rust/cuvs/src/dlpack.rs:246` | +| `dtype` | `rust/cuvs/src/dlpack.rs:251` | +| `device` | `rust/cuvs/src/dlpack.rs:256` | ### from_raw_parts @@ -174,7 +174,7 @@ The caller must guarantee that: `shape`/`strides` pointers) only for the duration of the FFI call and does not retain it afterward — cuVS upholds this. -_Source: `rust/cuvs/src/dlpack.rs:176`_ +_Source: `rust/cuvs/src/dlpack.rs:186`_ ### ndim @@ -184,7 +184,7 @@ pub fn ndim(&self) -> usize Number of dimensions. -_Source: `rust/cuvs/src/dlpack.rs:226`_ +_Source: `rust/cuvs/src/dlpack.rs:236`_ ### shape @@ -194,7 +194,7 @@ pub fn shape(&self) -> &[i64] Shape of the tensor. -_Source: `rust/cuvs/src/dlpack.rs:231`_ +_Source: `rust/cuvs/src/dlpack.rs:241`_ ### strides @@ -204,7 +204,7 @@ pub fn strides(&self) -> Option<&[i64]> Strides, if non-contiguous. `None` means row-major contiguous. -_Source: `rust/cuvs/src/dlpack.rs:236`_ +_Source: `rust/cuvs/src/dlpack.rs:246`_ ### dtype @@ -214,7 +214,7 @@ pub fn dtype(&self) -> ffi::DLDataType Element data type. -_Source: `rust/cuvs/src/dlpack.rs:241`_ +_Source: `rust/cuvs/src/dlpack.rs:251`_ ### device @@ -224,9 +224,9 @@ pub fn device(&self) -> ffi::DLDevice Device where the data resides. -_Source: `rust/cuvs/src/dlpack.rs:246`_ +_Source: `rust/cuvs/src/dlpack.rs:256`_ -_Source: `rust/cuvs/src/dlpack.rs:155`_ +_Source: `rust/cuvs/src/dlpack.rs:165`_ ## DLTensorViewMut @@ -243,7 +243,7 @@ A non-owning, writable DLPack tensor view. | Name | Source | | --- | --- | -| `from_raw_parts` | `rust/cuvs/src/dlpack.rs:274` | +| `from_raw_parts` | `rust/cuvs/src/dlpack.rs:284` | ### from_raw_parts @@ -264,6 +264,6 @@ Construct a writable DLPack view from raw tensor metadata. In addition to the [`DLTensorView::from_raw_parts`] invariants, the caller must guarantee the storage is exclusively writable for `'a`. -_Source: `rust/cuvs/src/dlpack.rs:274`_ +_Source: `rust/cuvs/src/dlpack.rs:284`_ -_Source: `rust/cuvs/src/dlpack.rs:262`_ +_Source: `rust/cuvs/src/dlpack.rs:272`_ diff --git a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-index.md b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-index.md index 895be65492..34af5a58c0 100644 --- a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-index.md +++ b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-index.md @@ -17,24 +17,21 @@ pub struct Index<'d> { } ``` -A CAGRA approximate nearest neighbor index. - -The lifetime `'d` ties this index to the underlying dataset, -passed at construction time. The C library may store a non-owning view -of properly aligned device-resident data, so the dataset must outlive -the index. When an index is deserialized from disk, the data is -self-contained and its lifetime is `'static`. +A CAGRA approximate nearest neighbor index borrowing caller-owned dataset storage. **Methods** | Name | Source | | --- | --- | -| `build` | `rust/cuvs/src/neighbors/cagra/index.rs:45` | -| `search` | `rust/cuvs/src/neighbors/cagra/index.rs:77` | -| `search_filtered` | `rust/cuvs/src/neighbors/cagra/index.rs:97` | -| `serialize` | `rust/cuvs/src/neighbors/cagra/index.rs:174` | -| `serialize_to_hnswlib` | `rust/cuvs/src/neighbors/cagra/index.rs:198` | -| `deserialize` | `rust/cuvs/src/neighbors/cagra/index.rs:214` | +| `build` | `rust/cuvs/src/neighbors/cagra/index.rs:70` | +| `build_from_dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:80` | +| `update_dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:105` | +| `search` | `rust/cuvs/src/neighbors/cagra/index.rs:134` | +| `search_filtered` | `rust/cuvs/src/neighbors/cagra/index.rs:154` | +| `serialize` | `rust/cuvs/src/neighbors/cagra/index.rs:195` | +| `serialize_to_hnswlib` | `rust/cuvs/src/neighbors/cagra/index.rs:215` | +| `deserialize_graph` | `rust/cuvs/src/neighbors/cagra/index.rs:220` | +| `deserialize_graph_and_dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:233` | ### build @@ -51,7 +48,35 @@ Builds a CAGRA index over `dataset` for efficient search. view of it, so the returned [`Index`] borrows `dataset` for `'d` and cannot outlive it. -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:45`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:70`_ + +### build_from_dataset + +```rust +pub fn build_from_dataset<'a, D>( +res: &Resources, +params: &IndexParams, +dataset: &'a D, +) -> Result> +where +D: CuvsDataset + ?Sized, +``` + +Build from an owning dataset or non-owning dataset view. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:80`_ + +### update_dataset + +```rust +pub fn update_dataset<'a, D>(self, res: &Resources, dataset: &'a D) -> Result> +where +D: CuvsDataset + ?Sized, +``` + +Attach a device-padded dataset and return a search-ready index borrowing it. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:105`_ ### search @@ -78,7 +103,7 @@ implement [`AsDlTensor`] / `n_queries × k`) receives the neighbor indices and `distances` their distances; both are written in place. -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:77`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:134`_ ### search_filtered @@ -100,7 +125,7 @@ D: AsDlTensorMut + ?Sized, Searches the index with a row-level bitset filter. -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:97`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:154`_ ### serialize @@ -123,30 +148,11 @@ Experimental, both the API and the serialization format are subject to change. * `filename` - The file path for saving the index * `include_dataset` - Whether to write out the dataset to the file -#### Example: -```no_run -use cuvs::Resources; -use cuvs::neighbors::cagra::{Index, IndexParams}; +Deserialize a graph-only file with [`Index::deserialize_graph`], or +recreate the serialized dataset's residency and layout with +[`Index::deserialize_graph_and_dataset`]. -fn serialize_example() -> Result<(), Box> { -let res = Resources::new()?; - -// Build an index (using some dataset) -let build_params = IndexParams::builder().build()?; -// let index = Index::build(&res, &build_params, &dataset)?; - -// Save the index to disk (including the dataset) -// index.serialize(&res, "/path/to/index.bin", true)?; - -// Later, load the index from disk -let loaded_index = Index::deserialize(&res, "/path/to/index.bin")?; - -// The loaded index can be used for search just like the original -Ok(()) -} -``` - -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:174`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:195`_ ### serialize_to_hnswlib @@ -166,23 +172,161 @@ Experimental, both the API and the serialization format are subject to change. * `res` - Resources to use * `filename` - The file path for saving the index -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:198`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:215`_ -### deserialize +### deserialize_graph ```rust -pub fn deserialize>(res: &Resources, filename: P) -> Result> +pub fn deserialize_graph>( +res: &Resources, +filename: P, +) -> Result> ``` -Load a CAGRA index from file. +Load only the graph, ignoring any dataset stored in the file. -Experimental, both the API and the serialization format are subject to change. +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:220`_ -#### Arguments +### deserialize_graph_and_dataset -* `res` - Resources to use -* `filename` - The path of the file that stores the index +```rust +pub fn deserialize_graph_and_dataset>( +res: &Resources, +filename: P, +) -> Result> +``` + +Load the graph and recreate its serialized dataset allocation. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:233`_ + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:47`_ + +## DeserializedIndex + +```rust +#[derive(Debug)] +pub struct DeserializedIndex { + /* private fields */ +} +``` + +A deserialized CAGRA index and the optional dataset storage it views. + +A file serialized without vectors yields `dataset == None` and must have +matching storage attached before search. Field order is significant: the +native index is destroyed before its dataset owner. + +**Methods** + +| Name | Source | +| --- | --- | +| `dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:254` | +| `has_dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:259` | +| `serialize` | `rust/cuvs/src/neighbors/cagra/index.rs:264` | +| `serialize_to_hnswlib` | `rust/cuvs/src/neighbors/cagra/index.rs:274` | +| `update_dataset` | `rust/cuvs/src/neighbors/cagra/index.rs:279` | +| `search` | `rust/cuvs/src/neighbors/cagra/index.rs:304` | +| `search_filtered` | `rust/cuvs/src/neighbors/cagra/index.rs:325` | + +### dataset + +```rust +pub fn dataset(&self) -> Option<&D> +``` + +Borrow the dataset owner when the serialized file included vectors. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:254`_ + +### has_dataset + +```rust +pub fn has_dataset(&self) -> bool +``` + +Whether the serialized file included vector storage. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:259`_ + +### serialize + +```rust +pub fn serialize>( +&self, +res: &Resources, +filename: P, +include_dataset: bool, +) -> Result<()> +``` + +Save this index to file. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:264`_ + +### serialize_to_hnswlib + +```rust +pub fn serialize_to_hnswlib>(&self, res: &Resources, filename: P) -> Result<()> +``` + +Save this index to file in the cuVS hnswlib format. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:274`_ + +### update_dataset + +```rust +pub fn update_dataset<'a, T>(self, res: &Resources, dataset: &'a T) -> Result> +where +T: CuvsDataset + ?Sized, +``` + +Replace the deserialized storage with a caller-owned device-padded view. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:279`_ + +### search + +```rust +pub fn search( +&self, +res: &Resources, +params: &SearchParams, +queries: &Q, +neighbors: &mut N, +distances: &mut D, +) -> Result<()> +where +Q: AsDlTensor + ?Sized, +N: AsDlTensorMut + ?Sized, +D: AsDlTensorMut + ?Sized, +``` + +Search an index whose deserialized owner is device-padded. + +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:304`_ + +### search_filtered + +```rust +pub fn search_filtered( +&self, +res: &Resources, +params: &SearchParams, +queries: &Q, +neighbors: &mut N, +distances: &mut D, +filter: &Filter<'_, Bitset>, +) -> Result<()> +where +Q: AsDlTensor + ?Sized, +N: AsDlTensorMut + ?Sized, +D: AsDlTensorMut + ?Sized, +``` + +Search a padded deserialized index with a row-level bitset filter. -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:214`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:325`_ -_Source: `rust/cuvs/src/neighbors/cagra/index.rs:27`_ +_Source: `rust/cuvs/src/neighbors/cagra/index.rs:58`_ diff --git a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-params.md b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-params.md index 4765a250a2..c6035e2648 100644 --- a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-params.md +++ b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra-params.md @@ -17,42 +17,6 @@ unset values retain the library defaults from the underlying C `*ParamsCreate` functions. Out-of-range values are rejected by `build()` with [`CagraError::Validation`]. -## CompressionParams - -```rust -pub struct CompressionParams { - /* private fields */ -} -``` - -VPQ (Vector-Product Quantization) compression parameters. - -Attach to [`IndexParams`] to enable compressed dataset storage. - -**Methods** - -| Name | Source | -| --- | --- | -| `new` | `rust/cuvs/src/neighbors/cagra/params.rs:39` | - -### new - -```rust -#[builder] -pub fn new( -pq_bits: Option, -pq_dim: Option, -vq_n_centers: Option, -kmeans_n_iters: Option, -vq_kmeans_trainset_fraction: Option, -pq_kmeans_trainset_fraction: Option, -) -> Result -``` - -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:39`_ - -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:32`_ - ## IndexParams ```rust @@ -77,7 +41,7 @@ let params = IndexParams::builder() | Name | Source | | --- | --- | -| `new` | `rust/cuvs/src/neighbors/cagra/params.rs:153` | +| `new` | `rust/cuvs/src/neighbors/cagra/params.rs:59` | ### new @@ -87,16 +51,15 @@ pub fn new( metric: Option, intermediate_graph_degree: Option, graph_degree: Option, -compression: Option, #[builder(setters(vis = "", some_fn = graph_build_internal))] graph_build: Option< RequestedGraphBuild, >, ) -> Result ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:153`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:59`_ -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:142`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:49`_ ## SearchParams @@ -118,7 +81,7 @@ let params = SearchParams::builder().itopk_size(128).build()?; | Name | Source | | --- | --- | -| `new` | `rust/cuvs/src/neighbors/cagra/params.rs:340` | +| `new` | `rust/cuvs/src/neighbors/cagra/params.rs:233` | ### new @@ -131,6 +94,7 @@ itopk_size: Option, max_iterations: Option, algo: Option, team_size: Option, +search_width: Option, min_iterations: Option, thread_block_size: Option, hashmap_mode: Option, @@ -138,12 +102,15 @@ hashmap_min_bitlen: Option, hashmap_max_fill_rate: Option, num_random_samplings: Option, rand_xor_mask: Option, +persistent: Option, +persistent_lifetime: Option, +persistent_device_usage: Option, ) -> Result ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:340`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:233`_ -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:332`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:225`_ ## impl IndexParamsBuilder @@ -155,12 +122,12 @@ impl IndexParamsBuilder | Name | Source | | --- | --- | -| `auto` | `rust/cuvs/src/neighbors/cagra/params.rs:214` | -| `nn_descent` | `rust/cuvs/src/neighbors/cagra/params.rs:221` | -| `nn_descent_with_iterations` | `rust/cuvs/src/neighbors/cagra/params.rs:228` | -| `iterative_cagra_search` | `rust/cuvs/src/neighbors/cagra/params.rs:238` | -| `ace` | `rust/cuvs/src/neighbors/cagra/params.rs:245` | -| `ivf_pq` | `rust/cuvs/src/neighbors/cagra/params.rs:252` | +| `auto` | `rust/cuvs/src/neighbors/cagra/params.rs:107` | +| `nn_descent` | `rust/cuvs/src/neighbors/cagra/params.rs:114` | +| `nn_descent_with_iterations` | `rust/cuvs/src/neighbors/cagra/params.rs:121` | +| `iterative_cagra_search` | `rust/cuvs/src/neighbors/cagra/params.rs:131` | +| `ace` | `rust/cuvs/src/neighbors/cagra/params.rs:138` | +| `ivf_pq` | `rust/cuvs/src/neighbors/cagra/params.rs:145` | ### auto @@ -170,7 +137,7 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:214`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:107`_ ### nn_descent @@ -180,7 +147,7 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:221`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:114`_ ### nn_descent_with_iterations @@ -193,7 +160,7 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:228`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:121`_ ### iterative_cagra_search @@ -203,7 +170,7 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:238`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:131`_ ### ace @@ -213,7 +180,7 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:245`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:138`_ ### ivf_pq @@ -223,6 +190,6 @@ where S::GraphBuild: IsUnset, ``` -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:252`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:145`_ -_Source: `rust/cuvs/src/neighbors/cagra/params.rs:213`_ +_Source: `rust/cuvs/src/neighbors/cagra/params.rs:106`_ diff --git a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra.md b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra.md index d052e661de..11377600ca 100644 --- a/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra.md +++ b/fern/pages/rust_api/rust-api-cuvs-neighbors-cagra.md @@ -22,30 +22,38 @@ builder pattern: every setter is optional and unset values keep the cuVS C library defaults. Values are validated when the builder's `build()` runs, returning [`CagraError::Validation`] for out-of-range inputs. -## crate::neighbors::filters::\{Bitset, Filter\} +## crate::dataset::\{CuvsDataset, Dataset, DatasetKind, DatasetView, PaddedDataset\} ```rust -pub use crate::neighbors::filters::{Bitset, Filter}; +pub use crate::dataset::{CuvsDataset, Dataset, DatasetKind, DatasetView, PaddedDataset}; ``` _Source: `rust/cuvs/src/neighbors/cagra/mod.rs:23`_ -## index::Index +## crate::neighbors::filters::\{Bitset, Filter\} ```rust -pub use index::Index; +pub use crate::neighbors::filters::{Bitset, Filter}; ``` _Source: `rust/cuvs/src/neighbors/cagra/mod.rs:24`_ -## params::\{CompressionParams, IndexParams, SearchParams\} +## index::\{DeserializedIndex, Index\} ```rust -pub use params::{CompressionParams, IndexParams, SearchParams}; +pub use index::{DeserializedIndex, Index}; ``` _Source: `rust/cuvs/src/neighbors/cagra/mod.rs:25`_ +## params::\{IndexParams, SearchParams\} + +```rust +pub use params::{IndexParams, SearchParams}; +``` + +_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:26`_ + ## GraphBuildAlgo ```rust @@ -58,7 +66,7 @@ pub enum GraphBuildAlgo { Algorithm for building the internal k-NN graph. -_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:33`_ +_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:34`_ ## SearchAlgo @@ -72,7 +80,7 @@ pub enum SearchAlgo { Search kernel implementation. -_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:73`_ +_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:74`_ ## HashMode @@ -86,7 +94,7 @@ pub enum HashMode { Hash-table mode used during search. -_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:109`_ +_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:110`_ ## CagraError @@ -100,4 +108,4 @@ pub enum CagraError { Error type for CAGRA operations. -_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:141`_ +_Source: `rust/cuvs/src/neighbors/cagra/mod.rs:142`_ diff --git a/fern/pages/rust_api/rust-api-cuvs-version.md b/fern/pages/rust_api/rust-api-cuvs-version.md new file mode 100644 index 0000000000..d733e73c59 --- /dev/null +++ b/fern/pages/rust_api/rust-api-cuvs-version.md @@ -0,0 +1,21 @@ +--- +slug: api-reference/rust-api-cuvs-version +--- + +# Version Module + +_Rust module: `cuvs::version`_ + +_Source: `rust/cuvs/src/version.rs`_ + +cuVS library version query. + +## version + +```rust +pub fn version() -> Result<(u16, u16, u16), LibraryError> +``` + +Returns the cuVS library version as `(major, minor, patch)`. + +_Source: `rust/cuvs/src/version.rs:12`_ diff --git a/fern/pages/rust_api/rust-api-cuvs.md b/fern/pages/rust_api/rust-api-cuvs.md index 149626eabb..31876592b9 100644 --- a/fern/pages/rust_api/rust-api-cuvs.md +++ b/fern/pages/rust_api/rust-api-cuvs.md @@ -27,7 +27,7 @@ _Source: `rust/cuvs/src/lib.rs:12`_ pub mod distance; ``` -_Source: `rust/cuvs/src/lib.rs:13`_ +_Source: `rust/cuvs/src/lib.rs:14`_ ## dlpack @@ -35,7 +35,7 @@ _Source: `rust/cuvs/src/lib.rs:13`_ pub mod dlpack; ``` -_Source: `rust/cuvs/src/lib.rs:14`_ +_Source: `rust/cuvs/src/lib.rs:15`_ ## error @@ -43,7 +43,7 @@ _Source: `rust/cuvs/src/lib.rs:14`_ pub mod error; ``` -_Source: `rust/cuvs/src/lib.rs:15`_ +_Source: `rust/cuvs/src/lib.rs:16`_ ## neighbors @@ -51,7 +51,7 @@ _Source: `rust/cuvs/src/lib.rs:15`_ pub mod neighbors; ``` -_Source: `rust/cuvs/src/lib.rs:16`_ +_Source: `rust/cuvs/src/lib.rs:18`_ ## resources @@ -59,7 +59,15 @@ _Source: `rust/cuvs/src/lib.rs:16`_ pub mod resources; ``` -_Source: `rust/cuvs/src/lib.rs:17`_ +_Source: `rust/cuvs/src/lib.rs:19`_ + +## version + +```rust +pub mod version; +``` + +_Source: `rust/cuvs/src/lib.rs:20`_ ## dlpack::\{AsDlTensor, AsDlTensorMut, DLPackError, DLTensorView, DLTensorViewMut, DType\} @@ -67,7 +75,7 @@ _Source: `rust/cuvs/src/lib.rs:17`_ pub use dlpack::{AsDlTensor, AsDlTensorMut, DLPackError, DLTensorView, DLTensorViewMut, DType}; ``` -_Source: `rust/cuvs/src/lib.rs:21`_ +_Source: `rust/cuvs/src/lib.rs:25`_ ## error::LibraryError @@ -75,7 +83,7 @@ _Source: `rust/cuvs/src/lib.rs:21`_ pub use error::LibraryError; ``` -_Source: `rust/cuvs/src/lib.rs:22`_ +_Source: `rust/cuvs/src/lib.rs:26`_ ## resources::Resources @@ -83,7 +91,7 @@ _Source: `rust/cuvs/src/lib.rs:22`_ pub use resources::Resources; ``` -_Source: `rust/cuvs/src/lib.rs:23`_ +_Source: `rust/cuvs/src/lib.rs:27`_ ## ReadmeDocTests @@ -95,4 +103,4 @@ pub struct ReadmeDocTests; { } ``` -_Source: `rust/cuvs/src/lib.rs:29`_ +_Source: `rust/cuvs/src/lib.rs:33`_ diff --git a/fern/scripts/generate_api_reference.py b/fern/scripts/generate_api_reference.py index dd7f23442e..6394dd04e5 100755 --- a/fern/scripts/generate_api_reference.py +++ b/fern/scripts/generate_api_reference.py @@ -13,6 +13,7 @@ from collections import Counter, defaultdict from dataclasses import dataclass, field +import argparse import ast import re import shutil @@ -131,6 +132,15 @@ ) API_DECORATOR_RE = re.compile(r"\bCUVS_EXPORT\b\s*") +# Suppressed by ``--quiet`` so the pre-commit hook reports only its verdict. +VERBOSE = True + +# Populated while generating pages, consumed by ``update_api_navigation``. +# A slug cannot round-trip a Java type name (the package prefix and the +# internal capitalization are both lost), so record the real name instead of +# letting ``api_route_title`` title-case the slug. +API_NAV_TITLE_OVERRIDES: dict[tuple[str, str], str] = {} + @dataclass class DoxygenParam: @@ -413,7 +423,17 @@ def _qualify_function(self, entry: DoxygenEntry, prefix: str) -> None: entry.name = "::".join([*qualifiers, entry.name]) -def main() -> int: +def main(argv: list[str] | None = None) -> int: + global VERBOSE + + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--quiet", + action="store_true", + help="only report errors; do not list every generated page", + ) + VERBOSE = not parser.parse_args(argv).quiet + remove_old_api_pages() native_index = DoxygenHeaderIndex.build(NATIVE_HEADER_DIRS) native_pages_by_api = { @@ -2964,6 +2984,7 @@ def generate_java_api_pages() -> None: write_page(out_dir / "index.md", index_lines) for klass in classes: + API_NAV_TITLE_OVERRIDES[("java_api", java_slug(klass))] = klass.name lines = [ *api_frontmatter(api_page_route("java_api", java_slug(klass))), f"# {klass.name}", @@ -3072,6 +3093,11 @@ def parse_java_members(text: str, class_name: str) -> list[JavaMember]: continue if re.search(r"\b(if|for|while|switch|catch)\s*\(", signature): continue + # The pages advertise "Public Members"; drop explicitly private ones. + # Package-private and interface members are left alone because an + # interface method with no modifier is implicitly public. + if re.match(r"\s*private\b", signature): + continue name_match = re.search(r"([A-Za-z_]\w*)\s*\(", signature) if not name_match: continue @@ -5652,6 +5678,7 @@ def update_api_navigation() -> None: lines = [ ' - section: "API Reference"', + ' path: "./pages/api_reference.md"', " contents:", ] for title, directory, _, _, _ in API_NAV_SECTIONS: @@ -5694,7 +5721,8 @@ def update_api_navigation() -> None: docs_yml.write_text( text[:start] + replacement + text[end:], encoding="utf-8" ) - print("Updated fern/docs.yml API Reference navigation") + if VERBOSE: + print("Updated fern/docs.yml API Reference navigation") def read_api_index_slugs(index_path: Path) -> list[str]: @@ -5723,6 +5751,9 @@ def api_frontmatter(route: str) -> list[str]: def api_nav_page_title(directory: str, slug: str) -> str: + override = API_NAV_TITLE_OVERRIDES.get((directory, slug)) + if override is not None: + return override return api_route_title(slug) @@ -5760,6 +5791,7 @@ def api_route_title(slug: str) -> str: "nn": "NN", "pca": "PCA", "pq": "PQ", + "rabitq": "RaBitQ", "sq": "SQ", "vq": "VQ", } @@ -5978,7 +6010,8 @@ def write_page(path: Path, lines: list[str]) -> None: path.write_text( "\n".join(trim_blank_lines(lines)).rstrip() + "\n", encoding="utf-8" ) - print(f"Wrote {path.relative_to(REPO_DIR)}") + if VERBOSE: + print(f"Wrote {path.relative_to(REPO_DIR)}") def validate_generated_api_markdown() -> None: