Port Panama SIMD kernels to C++ using Google Highway

.github/workflows/run-bench.yml

@@ -93,6 +93,9 @@ jobs:
       - name: Set up GCC
         run: |
           sudo apt install -y gcc
+      - name: Install Meson and Ninja
+        run: |
+          sudo apt update && sudo apt install -y meson ninja-build
       - uses: actions/checkout@v4
       - name: Set up JDK ${{ matrix.jdk }}
         uses: actions/setup-java@v3
@@ -129,6 +132,9 @@ jobs:
           ref: ${{ matrix.branch }}
           fetch-depth: 0
 
+      - name: Initialize Git Submodules
+        run: git submodule update --init
+
       # ==========================================
       # Decode and write the protected dataset catalog
       #
@@ -250,9 +256,15 @@ jobs:
     needs: test-avx512
     runs-on: ubuntu-latest
     steps:
+      - name: Install Meson and Ninja
+        run: |
+          sudo apt update && sudo apt install -y meson ninja-build
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Initialize Git Submodules
+        run: git submodule update --init
+
       - name: Download all benchmark results
         uses: actions/download-artifact@v4
         with:

.github/workflows/unit-tests.yaml

@@ -40,7 +40,12 @@ jobs:
       - name: Set up GCC
         run: |
           sudo apt install -y gcc
+      - name: Install Meson and Ninja
+        run: |
+          sudo apt update && sudo apt install -y meson ninja-build
       - uses: actions/checkout@v4
+      - name: Initialize Git Submodules
+        run: git submodule update --init
       - name: Set up JDK ${{ matrix.jdk }}
         uses: actions/setup-java@v3
         with:
@@ -102,6 +107,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+      - name: Initialize Git Submodules
+        run: git submodule update --init
       - name: Set up JDK
         uses: actions/setup-java@v3
         with:
@@ -112,6 +119,10 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: |
           sudo apt install -y gcc
+      - name: Install Meson and Ninja
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt update && sudo apt install -y meson ninja-build
       - name: Compile, run tests, and package (JDK 22)
         run: mvn -B verify
         if: matrix.jdk == '22'

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "jvector-native/src/main/c/third_party/highway"]
+	path = jvector-native/src/main/c/third_party/highway
+	url = https://github.com/google/highway.git

README.md

@@ -59,6 +59,30 @@ a dependency from any Java 11 code. When run on a Java 20+ JVM with the Vector m
 providers will be used. In general, the project is structured to be built with JDK 20+, but when `JAVA_HOME` is set to
 Java 11 -> Java 19, certain build features will still be available.
 
+### Cloning
+
+This repository uses a Git submodule for [Google Highway](https://github.com/google/highway), located at
+`jvector-native/src/main/c/third_party/highway`. After cloning, initialise it with:
+
+```bash
+git submodule update --init
+```
+
+Or clone with submodules in one step:
+
+```bash
+git clone --recurse-submodules <repo-url>
+```
+
+### Building native libraries
+
+The native SIMD library (`libjvector.so`) requires **g++ 11+** and is built by the script
+`jvector-native/src/main/c/jextract_vector_simd.sh`. To build and auto-install `g++` on Ubuntu:
+
+```bash
+./jvector-native/src/main/c/jextract_vector_simd.sh --auto-install-g++
+```
+
 Base code is in [jvector-base](./jvector-base) and will be built for Java 11 releases, restricting language features and APIs
 appropriately. Code in [jvector-twenty](./jvector-twenty) will be compiled for Java 20 language features/APIs and included in the final
 multirelease jar targeting supported JVMs. [jvector-multirelease](./jvector-multirelease) packages [jvector-base](./jvector-base) and [jvector-twenty](./jvector-twenty) as a

jvector-base/src/main/java/io/github/jbellis/jvector/quantization/PQDecoder.java

@@ -99,9 +99,7 @@ public CosineDecoder(PQVectors cv, VectorFloat<?> query) {
                 for (int m = 0; m < pq.getSubspaceCount(); ++m) {
                     int size = pq.subvectorSizesAndOffsets[m][0];
                     var codebook = pq.codebooks[m];
-                    for (int j = 0; j < pq.getClusterCount(); ++j) {
-                        partialMagnitudes.set((m * pq.getClusterCount()) + j, VectorUtil.dotProduct(codebook, j * size, codebook, j * size, size));
-                    }
+                    VectorUtil.calculatePartialSelfMagnitudes(codebook, m, size, pq.getClusterCount(), partialMagnitudes);
                 }
                 return partialMagnitudes;
             });
@@ -117,9 +115,7 @@ public CosineDecoder(PQVectors cv, VectorFloat<?> query) {
                 int offset = pq.subvectorSizesAndOffsets[m][1];
                 int size = pq.subvectorSizesAndOffsets[m][0];
                 var codebook = pq.codebooks[m];
-                for (int j = 0; j < pq.getClusterCount(); ++j) {
-                    partialSums.set((m * pq.getClusterCount()) + j, VectorUtil.dotProduct(codebook, j * size, centeredQuery, offset, size));
-                }
+                VectorUtil.calculatePartialSums(codebook, m, size, pq.getClusterCount(), centeredQuery, offset, VectorSimilarityFunction.DOT_PRODUCT, partialSums);
             }
 
             this.bMagnitude = VectorUtil.dotProduct(centeredQuery, centeredQuery);

jvector-base/src/main/java/io/github/jbellis/jvector/vector/VectorUtil.java

@@ -182,6 +182,10 @@ public static void calculatePartialSums(VectorFloat<?> codebook, int codebookInd
     impl.calculatePartialSums(codebook, codebookIndex, size, clusterCount, query, offset, vsf, partialSums);
   }
 
+  public static void calculatePartialSelfMagnitudes(VectorFloat<?> codebook, int codebookIndex, int size, int clusterCount, VectorFloat<?> partialMagnitudes) {
+    impl.calculatePartialSelfMagnitudes(codebook, codebookIndex, size, clusterCount, partialMagnitudes);
+  }
+
   /**
    * Calculates the maximum value in the vector.
    * @param v vector

jvector-base/src/main/java/io/github/jbellis/jvector/vector/VectorUtilSupport.java

@@ -134,6 +134,13 @@ public interface VectorUtilSupport {
 
   void calculatePartialSums(VectorFloat<?> codebook, int codebookIndex, int size, int clusterCount, VectorFloat<?> query, int offset, VectorSimilarityFunction vsf, VectorFloat<?> partialSums);
 
+  default void calculatePartialSelfMagnitudes(VectorFloat<?> codebook, int codebookIndex, int size, int clusterCount, VectorFloat<?> partialMagnitudes) {
+    int codebookBase = codebookIndex * clusterCount;
+    for (int i = 0; i < clusterCount; i++) {
+      partialMagnitudes.set(codebookBase + i, dotProduct(codebook, i * size, codebook, i * size, size));
+    }
+  }
+
   float max(VectorFloat<?> v);
   float min(VectorFloat<?> v);