[CuVS Java] Include IVF_PQ parameters in CAGRA index parameters and other changes

java/README.md

@@ -1,14 +1,27 @@
-Prerequisites
--------------
+# CuVS Java API
 
-* JDK 22
-* Maven 3.9.6 or later
 
-To build this API, please do `./build.sh java` in the top level directory. Since this API is dependent on `libcuvs` it must be noted that `libcuvs` gets built automatically before building this API.
+CuVS Java API provides a Java based simple, efficient, and a robust vector search API.
 
-Alternatively, please build libcuvs (`./build.sh libcuvs` from top level directory) before building the Java API with `./build.sh` from this directory.
+> [!CAUTION]
+> CuVS 25.06 contains an experimental version and updates to this API are expected in the coming release.
 
-Building
---------
 
-`./build.sh` will generate the `libcuvs_java.so` file in the `internal/` directory, and then build the final jar file for the cuVS Java API in the `cuvs-java/` directory.
+## Prerequisites
+
+- [CuVS libraries](https://docs.rapids.ai/api/cuvs/stable/build/#build-from-source)
+- [maven 3.9.6 or above](https://maven.apache.org/download.cgi)
+- [JDK 22](https://openjdk.org/projects/jdk/22/)
+
+
+## Building
+
+The libcuvs C and C++ libraries are needed for this API. If libcuvs libraries have not been built and installed, use `./build.sh libcuvs java` in the top level directory to build this API.
+
+Alternatively, if libcuvs libraries are already built and you just want to build this API, please
+do `./build.sh java` in the top level directory or just do `./build.sh` in this directory.
+
+
+## Examples
+
+A few starter examples of CAGRA, HNSW, and Bruteforce index are provided in the `examples` directory.

java/cuvs-java/.gitignore

@@ -1 +1,2 @@
 /target/
+/bin/

java/cuvs-java/pom.xml

@@ -258,7 +258,7 @@
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-javadoc-plugin</artifactId>
-            <version>2.9.1</version>
+            <version>3.11.2</version>
             <executions>
                 <execution>
                     <id>attach-javadocs</id>

java/cuvs-java/src/main/java/com/nvidia/cuvs/BruteForceIndex.java

@@ -16,13 +16,12 @@
 
 package com.nvidia.cuvs;
 
-import com.nvidia.cuvs.spi.CuVSProvider;
-
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.nio.file.Path;
 import java.util.Objects;
-import java.util.UUID;
+
+import com.nvidia.cuvs.spi.CuVSProvider;
 
 /**
  *

java/cuvs-java/src/main/java/com/nvidia/cuvs/BruteForceQuery.java

@@ -40,7 +40,7 @@ public class BruteForceQuery {
    * @param queryVectors 2D float query vector array
    * @param mapping      an instance of ID mapping
    * @param topK         the top k results to return
-   * @param prefilter    the prefilter data to use while searching the BRUTEFORCE
+   * @param prefilters   the prefilters data to use while searching the BRUTEFORCE
    *                     index
    * @param numDocs      Maximum of bits in each prefilter, representing number of documents in this index.
    *                     Used only when prefilter(s) is/are passed.

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndex.java

@@ -20,7 +20,6 @@
 import java.io.OutputStream;
 import java.nio.file.Path;
 import java.util.Objects;
-import java.util.UUID;
 
 import com.nvidia.cuvs.spi.CuVSProvider;
 

java/cuvs-java/src/main/java/com/nvidia/cuvs/CagraIndexParams.java

@@ -29,6 +29,7 @@ public class CagraIndexParams {
   private final int graphDegree;
   private final int nnDescentNiter;
   private final int numWriterThreads;
+  private final CuVSIvfPqParams cuVSIvfPqParams;
 
   /**
    * Enum that denotes which ANN algorithm is used to build CAGRA graph.
@@ -158,15 +159,119 @@ private CuvsDistanceType(int value) {
 
   }
 
-  private CagraIndexParams(int intermediateGraphDegree, int graphDegree,
-      CagraGraphBuildAlgo CuvsCagraGraphBuildAlgo, int nnDescentNiter, int writerThreads,
-      CuvsDistanceType cuvsDistanceType) {
+  /**
+   * Enum that denotes codebook gen options.
+   */
+  public enum CodebookGen {
+
+    PER_SUBSPACE(0),
+
+    PER_CLUSTER(1);
+
+    /**
+     * The value for the enum choice.
+     */
+    public final int value;
+
+    private CodebookGen(int value) {
+      this.value = value;
+    }
+  }
+
+  /**
+   * Enum that denotes cuda datatypes.
+   */
+  public enum CudaDataType {
+
+    /**
+     * real as a half
+     */
+    CUDA_R_16F(2),
+
+    /**
+     * complex as a pair of half numbers
+     */
+    CUDA_C_16F(6),
+
+    /**
+     * real as a float
+     */
+    CUDA_R_32F(0),
+
+    /**
+     * complex as a pair of float numbers
+     */
+    CUDA_C_32F(4),
+
+    /**
+     * real as a double
+     */
+    CUDA_R_64F(1),
+
+    /**
+     * complex as a pair of double numbers
+     */
+    CUDA_C_64F(5),
+
+    /**
+     * real as a signed char
+     */
+    CUDA_R_8I(3),
+
+    /**
+     * complex as a pair of signed char numbers
+     */
+    CUDA_C_8I(7),
+
+    /**
+     * real as a unsigned char
+     */
+    CUDA_R_8U(8),
+
+    /**
+     * complex as a pair of unsigned char numbers
+     */
+    CUDA_C_8U(9),
+
+    /**
+     * real as a signed int
+     */
+    CUDA_R_32I(10),
+
+    /**
+     * complex as a pair of signed int numbers
+     */
+    CUDA_C_32I(11),
+
+    /**
+     * real as a unsigned int
+     */
+    CUDA_R_32U(12),
+
+    /**
+     * complex as a pair of unsigned int numbers
+     */
+    CUDA_C_32U(13);
+
+    /**
+     * The value for the enum choice.
+     */
+    public final int value;
+
+    private CudaDataType(int value) {
+      this.value = value;
+    }
+  }
+
+  private CagraIndexParams(int intermediateGraphDegree, int graphDegree, CagraGraphBuildAlgo CuvsCagraGraphBuildAlgo,
+      int nnDescentNiter, int writerThreads, CuvsDistanceType cuvsDistanceType, CuVSIvfPqParams cuVSIvfPqParams) {
     this.intermediateGraphDegree = intermediateGraphDegree;
     this.graphDegree = graphDegree;
     this.cuvsCagraGraphBuildAlgo = CuvsCagraGraphBuildAlgo;
     this.nnDescentNiter = nnDescentNiter;
     this.numWriterThreads = writerThreads;
     this.cuvsDistanceType = cuvsDistanceType;
+    this.cuVSIvfPqParams = cuVSIvfPqParams;
   }
 
   /**
@@ -216,11 +321,19 @@ public int getNumWriterThreads() {
     return numWriterThreads;
   }
 
+  /**
+   * Gets the IVF_PQ parameters.
+   */
+  public CuVSIvfPqParams getCuVSIvfPqParams() {
+    return cuVSIvfPqParams;
+  }
+
   @Override
   public String toString() {
     return "CagraIndexParams [cuvsCagraGraphBuildAlgo=" + cuvsCagraGraphBuildAlgo + ", cuvsDistanceType="
         + cuvsDistanceType + ", intermediateGraphDegree=" + intermediateGraphDegree + ", graphDegree=" + graphDegree
-        + ", nnDescentNiter=" + nnDescentNiter + ", numWriterThreads=" + numWriterThreads + "]";
+        + ", nnDescentNiter=" + nnDescentNiter + ", numWriterThreads=" + numWriterThreads + ", cuVSIvfPqParams="
+        + cuVSIvfPqParams + "]";
   }
 
   /**
@@ -234,8 +347,10 @@ public static class Builder {
     private int graphDegree = 64;
     private int nnDescentNumIterations = 20;
     private int numWriterThreads = 2;
+    private CuVSIvfPqParams cuVSIvfPqParams = new CuVSIvfPqParams.Builder().build();
 
-    public Builder() { }
+    public Builder() {
+    }
 
     /**
      * Sets the degree of input graph for pruning.
@@ -305,14 +420,25 @@ public Builder withNumWriterThreads(int numWriterThreads) {
       return this;
     }
 
+    /**
+     * Sets the IVF_PQ index parameters.
+     *
+     * @param cuVSIvfPqParams the IVF_PQ index parameters
+     * @return an instance of Builder
+     */
+    public Builder withCuVSIvfPqParams(CuVSIvfPqParams cuVSIvfPqParams) {
+      this.cuVSIvfPqParams = cuVSIvfPqParams;
+      return this;
+    }
+
     /**
      * Builds an instance of {@link CagraIndexParams}.
      *
      * @return an instance of {@link CagraIndexParams}
      */
     public CagraIndexParams build() {
-      return new CagraIndexParams(intermediateGraphDegree, graphDegree, cuvsCagraGraphBuildAlgo,
-          nnDescentNumIterations, numWriterThreads, cuvsDistanceType);
+      return new CagraIndexParams(intermediateGraphDegree, graphDegree, cuvsCagraGraphBuildAlgo, nnDescentNumIterations,
+          numWriterThreads, cuvsDistanceType, cuVSIvfPqParams);
     }
   }
 }