Skip to content

Add an AArch64 C++ backend with native NEON FastScan - #90

Draft
menghuaban520 wants to merge 1 commit into
VectorDB-NTU:mainfrom
menghuaban520:codex/aarch64-simde-neon
Draft

Add an AArch64 C++ backend with native NEON FastScan#90
menghuaban520 wants to merge 1 commit into
VectorDB-NTU:mainfrom
menghuaban520:codex/aarch64-simde-neon

Conversation

@menghuaban520

Copy link
Copy Markdown

Current C++ source builds require x86 ISA flags and x86-only Hadamard assembly.
This patch allows AArch64 builds through the existing CMake targets: ordinary
FastScan uses a native NEON accumulator, the remaining AVX2 kernels compile
through SIMDe, and Hadamard uses portable butterflies. Consumers still link
rabitq_headers; SIMDe remains a private build dependency.

The public API, persisted index layout and production seed policy are retained.
OpenMP stays enabled by default, with an explicit serial build option. Existing
x86 CPU dispatch is retained. The patch also fixes portability prerequisites:
Linux-only memory advice, libc++ allocator comparison, a SIMD byte-store
alignment issue, and zero-residual normalization leading to a NaN-to-int cast.
Platform-dependent test oracles are replaced with independent scalar/double
references without loosening their tolerances.

Validation on Apple M5 Pro / macOS / AppleClang 21:

  • Fresh application to v0.2.2, library and all six C++ samples build.
  • 52 tests pass in Release, strict ASan/UBSan, and with real LLVM OpenMP.
  • An ordinary IVF consumer passes construction, save/load, both accuracy modes,
    self-query checks, sorted finite results, and exact serial/two-worker equality.
  • Replaying 1,000 held-out 512-D DBpedia queries through the ordinary library
    reproduces all 10,000 IDs and float distance bit patterns from the prior
    same-index experiment; Recall@10 is 90.03%.
  • All x86 AVX2/AVX-512 translation units and test binaries compile/link.
    Native x86 execution is pending: local Rosetta exposes no AVX2.
  • Changed C/C++ files pass the repository's clang-format 15 style.

Historical measurements of the same NEON algorithm showed 1.26–1.37x kernel
speed versus upstream AVX2 compiled through SIMDe. In the earlier isolated
IVF experiment, the median paired speed ratio was 1.090x (range 1.015–1.112x),
with identical IDs/distances across six rounds of 1,000 queries. This final
integration has correctness replay evidence, not a new performance measurement.
These figures apply to one Apple M5 Pro fixture; compression is provided by
RaBitQ itself.

Related to #34.
Acknowledges the earlier SIMDe portability PR #16;
this is not a claim that generic SIMDe portability is new. The intended
contribution is current-tree integration with a measured native ARM hotspot.

SIMDe revision tested: b49b253a24ba1f26c7e619ed88330cae53135950.
Base revision: 290aba274b92f4832b40f0235c8222e998ee9eca.

Keep this PR in draft until native x86 and ARM Linux validation and maintainer
review are available. Python bindings/wheels, full HNSW/SymphonyQG runtime
workloads, universal macOS binaries, RSS/cold-start and concurrency throughput
are outside the demonstrated scope.

@gouyt13

gouyt13 commented Sep 3, 2026

Copy link
Copy Markdown
Member

Thank you for this substantial contribution! AArch64 support is valuable to the project.

However, the current patch changes the build system, portability utilities, numerical edge cases, SIMD dispatch, and the native NEON backend across 28 files.
Before maintainer review, could you split it into a small sequence of focused PRs?
For example:
(1) platform-neutral portability fixes,
(2) portable Hadamard support,
(3) AArch64/SIMDe build support,
and (4) native NEON FastScan?
Please keep the PR in draft until native Linux AArch64 and native x86 AVX2/AVX-512 CI or test results are available.
We would also require cross-platform save/load compatibility tests and separate correctness and performance comparisons between the scalar reference, SIMDe path, and native NEON path.

Moreover, could you please clarify whether this implementation was developed independently or adapted from existing ARM/NEON FastScan implementations, such as the one in Faiss or in this paper https://ieeexplore.ieee.org/abstract/document/9746589? If any existing code was referenced or adapted, please provide the corresponding links and preserve the appropriate attribution and license notices.

Thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants