Port Panama SIMD kernels to C++ using Google Highway

.github/workflows/run-bench.yml

@@ -90,6 +90,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
@@ -126,6 +129,9 @@ jobs:
           ref: ${{ matrix.branch }}
           fetch-depth: 0
 
+      - name: Initialize Git Submodules
+        run: git submodule update --init
+
       # ==========================================
       # Decode and write the protected dataset catalog
       #
@@ -241,9 +247,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/run-compaction.yml

@@ -56,6 +56,9 @@ jobs:
     steps:
       - 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
@@ -70,6 +73,9 @@ jobs:
           ref: ${{ matrix.branch }}
           fetch-depth: 0
 
+      - name: Initialize Git Submodules
+        run: git submodule update --init
+
       - name: Build branch
         run: mvn -B -Punix-amd64-profile package --file pom.xml
 

.github/workflows/unit-tests.yaml

@@ -14,14 +14,19 @@ on:
 jobs:
   build-avx512:
     concurrency:
-      group: ${{ matrix.isa }}-${{ matrix.jdk }}
+      group: isa-avx512f-${{ matrix.max_isa }}-${{ matrix.jdk }}
       cancel-in-progress: false
     strategy:
       matrix:
         jdk: [ 20, 24 ]
 #        jdk: [ 24 ]
-        isa: [ isa-avx512f ]
-    runs-on: ${{ matrix.isa }}
+        max_isa: [ avx512f, avx2, sse42 ]
+        exclude:
+          - jdk: 20
+            max_isa: avx2
+          - jdk: 20
+            max_isa: sse42
+    runs-on: isa-avx512f
     steps:
       - name: verify-avx512
         run: |
@@ -40,7 +45,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:
@@ -56,27 +66,31 @@ jobs:
           -Dtest=TestVectorizationProvider
           -DTest_RequireSpecificVectorizationProvider=PanamaVectorizationProvider
 
-      - name: Test Panama Support (JDK ${{ matrix.jdk }})
+      - name: Test full suite with Panama (JDK ${{ matrix.jdk }})
         if: matrix.jdk == '20'
         run: >-
-          mvn -B -Pjdk20 -pl jvector-tests test -am test
+          mvn -B -Pjdk20 -pl jvector-tests -am test
           -DTest_RequireSpecificVectorizationProvider=PanamaVectorizationProvider
 
       - name: Verify native-access vector support (JDK ${{ matrix.jdk }})
         if: matrix.jdk == '24'
+        env:
+          JVECTOR_MAX_ISA: ${{ matrix.max_isa }}
         run: >-
           mvn -B -Punix-amd64-profile -pl jvector-tests -am test
           -DTest_RequireSpecificVectorizationProvider=NativeVectorizationProvider
           -Dsurefire.failIfNoSpecifiedTests=false
           -Dtest=TestVectorizationProvider
 
-      - name: Compile, run tests and package (JDK ${{ matrix.jdk }})
+      - name: Test full suite with native vectorization (JDK ${{ matrix.jdk }})
         if: matrix.jdk == '24'
+        env:
+          JVECTOR_MAX_ISA: ${{ matrix.max_isa }}
         run: >-
-          mvn -B -Punix-amd64-profile -pl jvector-tests -am test
+          mvn -B -Punix-amd64-profile test
           -DTest_RequireSpecificVectorizationProvider=NativeVectorizationProvider
 
-      - name: Test Summary for (ISA:${{ matrix.isa}},JDK${{ matrix.jdk }})
+      - name: Test Summary for (ISA:isa-avx512f/max:${{ matrix.max_isa }},JDK${{ matrix.jdk }})
         if: always()
         uses: test-summary/action@v2
         with:
@@ -88,7 +102,7 @@ jobs:
         uses: actions/upload-artifact@v4
         if: always() # ensures upload happens even if tests fail
         with:
-          name: surefire-results--${{ matrix.isa }}-${{ matrix.jdk }}
+          name: surefire-results--isa-avx512f-${{ matrix.max_isa }}-${{ matrix.jdk }}
           path: "**/target/surefire-reports/**"
 
   build:
@@ -102,6 +116,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 +128,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/native/third_party/highway"]
+	path = jvector-native/src/main/native/third_party/highway
+	url = https://github.com/google/highway.git

README.md

@@ -59,6 +59,43 @@ 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/native/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`) is built with [Meson](https://mesonbuild.com/) + [Ninja](https://ninja-build.org/)
+and requires **g++ 11+**. The entry-point script is
+`jvector-native/src/main/native/jextract_vector_simd.sh`. Run it from that directory:
+
+```bash
+cd jvector-native/src/main/native
+bash jextract_vector_simd.sh
+```
+
+On a fresh Ubuntu machine you can install all required dependencies (g++, meson, ninja) and build in one step:
+
+```bash
+cd jvector-native/src/main/native
+bash jextract_vector_simd.sh --auto-install-deps
+```
+
+For other distributions the script will print the install commands needed. See
+[`jvector-native/src/main/native/README.md`](./jvector-native/src/main/native/README.md) for full build options,
+Maven integration, ISA dispatch details, and how to add new kernels.
+
 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

docs/release notes/4.1.0/668.performance.md

@@ -0,0 +1,82 @@
+### Native SIMD Acceleration via Google Highway
+
+**Description**
+
+This PR introduces a comprehensive native SIMD backend to JVector, porting
+**all** Panama Vector API kernels to native code backed by [Google
+Highway](https://github.com/google/highway), a portable, header-only C++
+library for SIMD operations. Previously, only two kernels in `jvector-native`
+were implemented natively; all other SIMD operations relied on the Panama
+Vector API as a fallback. Google Highway is currently enabled on **Linux
+x86-64** only; Windows and macOS are not yet supported. The native shared
+library (`libjvector.so`) is built as a single
+binary containing three ISA-specific variants: AVX-512 (Skylake), AVX2
+(Haswell), and SSE4.2. At JVM startup, the most suitable ISA is automatically
+selected via CPUID detection. SSE4.2 serves as the minimum supported baseline;
+CPUs lacking this capability will trigger a `SIGILL` at runtime.
+
+The ported kernels cover all hot paths:
+
+- **FP32 similarity** — `dot_product`, `cosine`, `euclidean`
+- **Product Quantization (PQ)** — `assemble_and_sum`, `calculate_partial_sums`,
+  `pq_decoded_cosine_similarity`
+- **Non-uniform Vector Quantization (NVQ)** — `nvq_quantize_8bit`, `nvq_loss`,
+  `nvq_square_l2_distance_8bit`, and related helpers
+- **Element-wise arithmetic** — `add_in_place`, `sub_in_place`, `max`,
+  `min_in_place`, and others
+
+A new `calculatePartialSelfSum` kernel was also added. On Linux x86-64, when
+native vectorization is enabled, the Google Highway backend is used
+**exclusively** for all similarity and quantization operations — the Panama
+Vector API path is bypassed almost entirely. On other platforms (Windows,
+macOS) or architectures (ARM, RISC-V, etc.), the Panama Vector API continues
+to provide SIMD acceleration as before; native Highway support for these
+platforms is planned for a future release if required.
+
+**Purpose / Impact**
+
+- Consistent, portable SIMD coverage across AVX-512, AVX2, and SSE4.2
+  without per-target intrinsic duplication
+- Automatic ISA selection at startup based on CPUID — no manual configuration
+  needed
+- Eliminates reliance on Panama Vector API for similarity kernels, removing
+  JDK-version sensitivity for the fast path
+- Runtime ISA can be capped for testing via the `JVECTOR_MAX_ISA` environment
+  variable (`avx3`, `avx2`, or `sse42`)
+- **Minimum requirement:** SSE4.2-capable x86-64 CPU; older CPUs will crash
+  with `SIGILL`
+
+**How to Enable**
+
+Native vectorization is opt-in. Add the following JVM flags to enable it:
+
+```bash
+java --enable-native-access=ALL-UNNAMED \
+     -Djvector.experimental.enable_native_vectorization=true \
+     -jar your-app.jar
+```
+
+Once enabled, `NativeVectorizationProvider` loads `libjvector.so` and the
+Highway-backed kernels are used automatically for all similarity and
+quantization operations.
+
+To additionally cap the ISA for debugging or benchmarking:
+
+```bash
+JVECTOR_MAX_ISA=avx2 java --enable-native-access=ALL-UNNAMED \
+     -Djvector.experimental.enable_native_vectorization=true \
+     -jar your-app.jar
+```
+
+**Notes**
+
+- The build now uses [Meson](https://mesonbuild.com/) + Ninja to compile the
+  three ISA variants; see
+  `jvector-native/src/main/native/jextract_vector_simd.sh` for build and
+  `jextract` binding-regeneration instructions.
+- Google Highway is vendored as a Git submodule under
+  `jvector-native/src/main/native/third_party/highway` at commit
+  [`16f5f5c7`](https://github.com/google/highway/commit/16f5f5c768064d0bb52952888a14236bec75c104)
+  (v1.4.0+15).
+- CI workflows (unit tests and compaction) were updated to install Meson/Ninja
+  and initialise the Highway submodule before building.

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);