Enable native code on AARCH64

.github/workflows/unit-tests-arm64.yaml

@@ -0,0 +1,137 @@
+name: Unit Test CI — ARM64 (NEON / SVE)
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/unit-tests-arm64.yaml
+      - '**.java'
+      - '**/pom.xml'
+
+jobs:
+  build-arm64:
+    concurrency:
+      group: arm64-${{ matrix.max_isa }}-${{ matrix.jdk }}
+      cancel-in-progress: false
+    strategy:
+      matrix:
+        jdk: [ 24 ]
+        # Three ISA tiers in ascending capability order, mirroring avx512f/avx2/sse42.
+        # GitHub-hosted ubuntu-24.04-arm is a Neoverse-N1 (Graviton 2): NEON only, no SVE.
+        # The sve/sve2 matrix entries still exercise the JVECTOR_MAX_ISA cap path and
+        # compile all three ISA variants; the native kernel tests that require actual SVE
+        # hardware are gated on the runtime feature check below.
+        max_isa: [ neon, sve, sve2 ]
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - name: Report ARM64 ISA capabilities
+        id: cpu-features
+        run: |
+          # Parse the "Features" line from /proc/cpuinfo — the kernel only exposes a
+          # token here when the OS has set up context-switch support for it, so this is
+          # the same authority as getauxval(AT_HWCAP / AT_HWCAP2).
+          # "asimd" is the NEON token; "sve"/"sve2"/"sveaes" appear on Graviton 3/4.
+          flags="$(grep '^Features' /proc/cpuinfo | head -1 | cut -d: -f2)"
+          has_neon=false; has_sve=false; has_sve2=false
+          [[ " $flags " == *" asimd "* ]] && has_neon=true
+          [[ " $flags " == *" sve "*   ]] && has_sve=true
+          [[ " $flags " == *" sve2 "*  ]] && has_sve2=true
+          printf "NEON=%s  SVE=%s  SVE2=%s\n" "$has_neon" "$has_sve" "$has_sve2"
+          if [[ "$has_neon" != "true" ]]; then
+            echo "ERROR: NEON (asimd) not found in /proc/cpuinfo — not a valid AArch64 runner"
+            exit 2
+          fi
+          # Expose as step outputs for conditional steps below.
+          echo "has_neon=$has_neon" >> "$GITHUB_OUTPUT"
+          echo "has_sve=$has_sve"   >> "$GITHUB_OUTPUT"
+          echo "has_sve2=$has_sve2" >> "$GITHUB_OUTPUT"
+
+      - name: Set up GCC
+        run: |
+          sudo apt install -y gcc g++
+
+      - name: Install Meson, Ninja, and GTest
+        run: |
+          sudo apt update && sudo apt install -y meson ninja-build pkg-config libgtest-dev
+
+      - uses: actions/checkout@v4
+
+      - name: Initialize Git Submodules
+        run: git submodule update --init
+
+      - name: Build test_simd_kernels (native C++)
+        # Meson detects aarch64 and compiles all three ISA variants (neon/sve/sve2)
+        # regardless of what the host CPU supports at runtime.
+        working-directory: jvector-native/src/main/native
+        run: |
+          meson setup build --wipe
+          ninja -C build test_simd_kernels
+
+      - name: Run test_simd_kernels — no ISA cap (auto-detect, neon job)
+        if: matrix.max_isa == 'neon'
+        working-directory: jvector-native/src/main/native
+        run: ./build/test_simd_kernels
+
+      - name: Run test_simd_kernels — capped at neon (sve job, host may lack SVE)
+        if: matrix.max_isa == 'sve'
+        working-directory: jvector-native/src/main/native
+        env:
+          JVECTOR_MAX_ISA: neon
+        run: ./build/test_simd_kernels
+
+      - name: Run test_simd_kernels — no ISA cap on SVE hardware (sve job)
+        if: matrix.max_isa == 'sve' && steps.cpu-features.outputs.has_sve == 'true'
+        working-directory: jvector-native/src/main/native
+        run: ./build/test_simd_kernels
+
+      - name: Run test_simd_kernels — capped at neon (sve2 job baseline check)
+        if: matrix.max_isa == 'sve2'
+        working-directory: jvector-native/src/main/native
+        env:
+          JVECTOR_MAX_ISA: neon
+        run: ./build/test_simd_kernels
+
+      - name: Run test_simd_kernels — no ISA cap on SVE2 hardware (sve2 job)
+        if: matrix.max_isa == 'sve2' && steps.cpu-features.outputs.has_sve2 == 'true'
+        working-directory: jvector-native/src/main/native
+        run: ./build/test_simd_kernels
+
+      - name: Set up JDK ${{ matrix.jdk }}
+        uses: actions/setup-java@v3
+        with:
+          java-version: ${{ matrix.jdk }}
+          distribution: temurin
+          cache: maven
+
+      - name: Verify native-access vector support (JDK ${{ matrix.jdk }})
+        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: Test full suite with native vectorization (JDK ${{ matrix.jdk }})
+        env:
+          JVECTOR_MAX_ISA: ${{ matrix.max_isa }}
+        run: >-
+          mvn -B -Punix-amd64-profile test
+          -DTest_RequireSpecificVectorizationProvider=NativeVectorizationProvider
+
+      - name: Test Summary for (ARM64/max:${{ matrix.max_isa }},JDK${{ matrix.jdk }})
+        if: always()
+        uses: test-summary/action@v2
+        with:
+          paths: |
+            **/target/surefire-reports/TEST-*.xml
+
+      - name: Upload Surefire Test Results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: surefire-results--arm64-${{ matrix.max_isa }}-${{ matrix.jdk }}
+          path: "**/target/surefire-reports/**"

README.md

@@ -77,8 +77,8 @@ 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/build_native_lib.sh`. Run it from that directory:
+and requires **g++ 11+**. Supported platforms: **Linux x86-64** (SSE4.2, AVX2, AVX-512) and **Linux AArch64** (NEON, SVE, SVE2).
+The entry-point script is `jvector-native/src/main/native/build_native_lib.sh`. Run it from that directory.
 
 ```bash
 cd jvector-native/src/main/native

docs/release notes/4.0.2/723.performance.md

@@ -0,0 +1,91 @@
+### Native SIMD Acceleration on AArch64 (NEON, SVE, SVE2)
+
+**Description**
+
+This PR extends JVector's native Highway SIMD backend to **AArch64 (64-bit ARM)**, bringing
+the same native acceleration that x86-64 users already have to ARM-based servers and
+development machines (e.g. AWS Graviton, Apple Silicon under Linux, Ampere Altra).
+
+AArch64 support was previously absent from the native layer — ARM hosts silently fell back to
+the Panama Vector API path. The native binary now ships three AArch64 ISA tiers, all compiled
+as vector-length-agnostic (scalable) code:
+
+| Tier | Highway target | Notes |
+|---|---|---|
+| NEON | `HWY_NEON` | Baseline; all AArch64 CPUs |
+| SVE | `HWY_SVE` | Scalable Vector Extension |
+| SVE2 | `HWY_SVE2` | SVE2 + `i8mm` + `bf16` |
+
+SVE and SVE2 are compiled as VL-agnostic (scalable) code, so the same binary runs correctly
+on any SVE/SVE2-capable CPU regardless of its physical vector length. NEON operates on fixed
+128-bit vectors. At JVM startup, the best available tier is selected automatically via CPU
+feature detection — identical to the existing CPUID-based dispatch on x86-64.
+
+The following changes were made:
+
+- **`NativeVectorizationProvider`** — the hard-coded `x86_64` architecture check is extended
+  to include `aarch64`, so the provider is offered on ARM Linux hosts.
+- **`jvector_arch.h`** — new header introducing `JV_ARCH_X86_64` / `JV_ARCH_AARCH64`
+  preprocessor macros; all arch-specific code is guarded with `#if`/`#elif`/`#endif`.
+- **`jvector_cpu_features.h`** — AArch64 feature probing (NEON, SVE, SVE2 presence and
+  vector-length queries) added alongside the existing x86 CPUID path.
+- **Meson build** — three AArch64 ISA variant targets added; SVE/SVE2 targets skip gracefully
+  on Clang < 22 or non-Linux hosts where SVE is unavailable.
+- **Cross-compilation** — Meson cross-files and updated READMEs provided for building the
+  AArch64 native library from an x86-64 host.
+- **CI** — a dedicated AArch64 GitHub Actions runner added to the matrix so native builds and
+  kernel correctness are verified on real ARM hardware on every PR.
+
+**Purpose / Impact**
+
+Benchmarked on 1M-scale datasets on both AWS Graviton 3 and Graviton 4, Native SIMD (Highway)
+consistently outperforms Panama SIMD on AArch64:
+
+- Up to **40% lower search latency** at the same recall level
+- Up to **29% faster index construction**
+
+- All kernels already ported to Highway for x86-64 (FP32 similarity, PQ, NVQ, element-wise
+  arithmetic) benefit immediately on AArch64 — no separate ARM implementation was required.
+- On AArch64 Linux with native vectorization enabled, the Highway backend is used exclusively
+  for all similarity and quantization operations; the Panama Vector API path is bypassed.
+- On platforms where the native library cannot be loaded, JVector falls back to the Panama or
+  pure-Java provider transparently, as before.
+
+**How to Enable**
+
+Both `libjvector.so` variants — x86-64 and AArch64 — are built and bundled into the release
+JAR. At JVM startup, `NativeVectorizationProvider` detects the current architecture and loads
+the matching native library automatically. The same flags work on both architectures:
+
+```bash
+java --enable-native-access=ALL-UNNAMED \
+     -Djvector.experimental.enable_native_vectorization=true \
+     -jar your-app.jar
+```
+
+To cap the ISA tier for debugging or benchmarking:
+
+```bash
+JVECTOR_MAX_ISA=neon java --enable-native-access=ALL-UNNAMED \
+     -Djvector.experimental.enable_native_vectorization=true \
+     -jar your-app.jar
+```
+
+**Building releases:**
+
+To produce a release JAR with native libraries for all supported
+architectures (x86-64 and AArch64), the build must be run with the `-Dnative.crossarch`
+Maven property. Without this flag, only the native library for the current host architecture
+is built and bundled.
+
+```bash
+mvn package -Dnative.crossarch
+```
+
+
+**Notes**
+
+- SVE/SVE2 compilation requires Clang ≥ 22; older compilers silently skip those targets and
+  fall back to NEON.
+- There is no change to the on-disk index format; AArch64 and x86-64 indexes are fully
+  interchangeable.

jvector-native/pom.xml

@@ -14,8 +14,22 @@
     <properties>
         <native.buildtype>release</native.buildtype>
         <native.jextract.skip>true</native.jextract.skip>
+        <!-- Set to true via -Dnative.crossarch to also cross-compile for the other arch -->
+        <native.crossarch>false</native.crossarch>
     </properties>
     <build>
+        <!-- Pick up the .so files from target/meson-build/ so that mvn clean
+             removes stale libraries along with every other build artefact.
+             The build script no longer writes into src/main/resources/. -->
+        <resources>
+            <resource>
+                <directory>${project.build.directory}/meson-build</directory>
+                <includes>
+                    <include>libjvector-x86_64.so</include>
+                    <include>libjvector-aarch64.so</include>
+                </includes>
+            </resource>
+        </resources>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -89,12 +103,24 @@
                 <native.buildtype>release</native.buildtype>
             </properties>
         </profile>
+        <!-- Activate with -Dnative.crossarch to also cross-compile for the other arch -->
+        <profile>
+            <id>native.crossarch</id>
+            <activation>
+                <property>
+                    <name>native.crossarch</name>
+                </property>
+            </activation>
+            <properties>
+                <native.crossarch>true</native.crossarch>
+            </properties>
+        </profile>
+
         <profile>
             <id>unix-amd64-profile</id>
             <activation>
                 <os>
-                    <family>unix</family>
-                    <arch>amd64</arch>
+                    <name>Linux</name>
                 </os>
             </activation>
             <build>
@@ -157,6 +183,7 @@
                                     <arguments>
                                         <argument>build_native_lib.sh</argument>
                                         <argument>${native.buildtype}</argument>
+                                        <argument>${native.crossarch}</argument>
                                     </arguments>
                                     <skip>false</skip>
                                     <workingDirectory>${project.basedir}/src/main/native/src/</workingDirectory>

jvector-native/src/main/java/io/github/jbellis/jvector/vector/NativeVectorizationProvider.java

@@ -31,8 +31,8 @@ public class NativeVectorizationProvider extends VectorizationProvider {
 
     public NativeVectorizationProvider() {
         var arch = System.getProperty("os.arch", "");
-        if (!arch.equals("amd64") && !arch.equals("x86_64")) {
-            throw new UnsupportedOperationException("Native SIMD operations are only supported on x86_64.");
+        if (!arch.equals("amd64") && !arch.equals("x86_64") && !arch.equals("aarch64")) {
+            throw new UnsupportedOperationException("Native SIMD operations are only supported on x86_64 and aarch64.");
         }
         var libraryLoaded = LibraryLoader.loadJvector();
         if (!libraryLoaded) {

jvector-native/src/main/java/io/github/jbellis/jvector/vector/cnative/LibraryLoader.java

@@ -22,9 +22,32 @@
 /**
  * This class is used to load supporting native libraries. First, it tries to load the library from the system path.
  * If that fails, it tries to load the library from the classpath (using the usual copying to a tmp directory route).
+ * <p>
+ * Two resource names are bundled in the jar:
+ * <ul>
+ *   <li>{@code /libjvector-x86_64.so}  — built natively for x86_64</li>
+ *   <li>{@code /libjvector-aarch64.so} — cross-compiled for aarch64</li>
+ * </ul>
+ * At runtime the correct file is chosen based on {@code os.arch}.
  */
 public class LibraryLoader {
     private LibraryLoader() {}
+
+    /**
+     * Returns the classpath resource name for the native library appropriate for the
+     * current CPU architecture, or {@code null} when the architecture is not supported.
+     */
+    static String resourceNameForArch() {
+        String arch = System.getProperty("os.arch", "");
+        if (arch.equals("aarch64") || arch.equals("arm64")) {
+            return "/libjvector-aarch64.so";
+        }
+        if (arch.equals("amd64") || arch.equals("x86_64")) {
+            return "/libjvector-x86_64.so";
+        }
+        return null;
+    }
+
     public static boolean loadJvector() {
         try {
             System.loadLibrary("jvector");
@@ -35,9 +58,14 @@ public static boolean loadJvector() {
         try {
             // reinventing the wheel instead of picking up deps, so we'll just use the classloader to load the library
             // as a resource and then copy it to a tmp directory and load it from there
-            String libName = System.mapLibraryName("jvector");
-            File tmpLibFile = File.createTempFile(libName.substring(0, libName.lastIndexOf('.')), libName.substring(libName.lastIndexOf('.')));
-            try (var in = LibraryLoader.class.getResourceAsStream("/" + libName);
+            String resourceName = resourceNameForArch();
+            if (resourceName == null) {
+                return false; // unsupported architecture
+            }
+            String baseName = resourceName.substring(1, resourceName.lastIndexOf('.'));   // e.g. "libjvector-aarch64"
+            String ext      = resourceName.substring(resourceName.lastIndexOf('.'));      // e.g. ".so"
+            File tmpLibFile = File.createTempFile(baseName, ext);
+            try (var in = LibraryLoader.class.getResourceAsStream(resourceName);
                  var out = Files.newOutputStream(tmpLibFile.toPath())) {
                 if (in != null) {
                     in.transferTo(out);
@@ -54,4 +82,4 @@ public static boolean loadJvector() {
         return false;
     }
 
-}
+}