[CuVS-Java] Automate panama bindings generation, Include IVF_PQ parameters in CAGRA index parameters and other changes

java/.gitignore

@@ -0,0 +1,19 @@
+# cuvs-java
+/cuvs-java/target/
+/cuvs-java/bin/
+/cuvs-java/src/main/java22/com/nvidia/cuvs/internal/panama/
+/cuvs-java/*.cag
+# internal
+/internal/.ninja_deps
+/internal/.ninja_log
+/internal/CMakeCache.txt
+/internal/CMakeFiles/
+/internal/CPM_modules/
+/internal/_deps/
+/internal/build.ninja
+/internal/cmake/
+/internal/cmake_install.cmake
+/internal/cpm-package-lock.cmake
+/internal/Makefile
+# examples
+/examples/target/

java/README.md

@@ -1,14 +1,26 @@
-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
---------
+## Prerequisites
 
-`./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.
+- [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/build.sh

@@ -6,6 +6,17 @@ if [ -z "$CMAKE_PREFIX_PATH" ]; then
     export CMAKE_PREFIX_PATH=`pwd`/../cpp/build
 fi
 
+# Generate Panama FFM API bindings and update (if any of them changed)
+/bin/bash panama-bindings/generate-bindings.sh
+
+BINDINGS_GENERATION_RETURN_VALUE=$?
+if [ $BINDINGS_GENERATION_RETURN_VALUE != 0 ]
+then
+  echo "Bindings generation did not complete normally (returned value ${BINDINGS_GENERATION_RETURN_VALUE})"
+  echo "Forcing this build process to abort"
+  exit 1
+fi
+
 cd internal && cmake . && cmake --build . \
   && cd .. \
   && mvn install:install-file -DgroupId=$GROUP_ID -DartifactId=cuvs-java-internal -Dversion=$VERSION -Dpackaging=so -Dfile=$SO_FILE_PATH/libcuvs_java.so \

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>
@@ -298,7 +298,4 @@
         </plugin>
         </plugins>
     </build>
-
-
-
 </project>

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,106 @@ 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 {
+
+    CUDA_R_16F(2),
+
+    CUDA_C_16F(6),
+
+    CUDA_R_16BF(14),
+
+    CUDA_C_16BF(15),
+
+    CUDA_R_32F(0),
+
+    CUDA_C_32F(4),
+
+    CUDA_R_64F(1),
+
+    CUDA_C_64F(5),
+
+    CUDA_R_4I(16),
+
+    CUDA_C_4I(17),
+
+    CUDA_R_4U(18),
+
+    CUDA_C_4U(19),
+
+    CUDA_R_8I(3),
+
+    CUDA_C_8I(7),
+
+    CUDA_R_8U(8),
+
+    CUDA_C_8U(9),
+
+    CUDA_R_16I(20),
+
+    CUDA_C_16I(21),
+
+    CUDA_R_16U(22),
+
+    CUDA_C_16U(23),
+
+    CUDA_R_32I(10),
+
+    CUDA_C_32I(11),
+
+    CUDA_R_32U(12),
+
+    CUDA_C_32U(13),
+
+    CUDA_R_64I(24),
+
+    CUDA_C_64I(25),
+
+    CUDA_R_64U(26),
+
+    CUDA_C_64U(27),
+
+    CUDA_R_8F_E4M3(28),
+
+    CUDA_R_8F_E5M2(29);
+
+    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 +308,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 +334,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 +407,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);
     }
   }
 }