Templatize simdlib types on SIMDLevel (#4866)

Summary:
Pull Request resolved: #4866

Templatize all simd wrapper types (simd16uint16, simd32uint8, simd8float32,
etc.) on SIMDLevel. This is the foundation for PQ4 fast scan Dynamic Dispatch.

Primary templates are declared in simdlib.h. Each platform header provides
explicit specializations:
- simdlib_avx2.h: simd16uint16<AVX2>, simd32uint8<AVX2>, etc.
- simdlib_avx512.h: simd32uint16<AVX512>, simd64uint8<AVX512>, etc.
- simdlib_neon.h: simd16uint16<ARM_NEON>, etc.
- simdlib_emulated.h: simd16uint16<NONE>, etc. (always included)
- simdlib_ppc64.h: simd16uint16<NONE>, etc. (PPC-optimized scalar)

SINGLE_SIMD_LEVEL (inline constexpr in simd_levels.h) resolves to NONE in DD
mode and to the compiled-in level in static mode. SINGLE_SIMD_LEVEL_256 maps
through simd256_level_selector for 256-bit types (AVX512->AVX2, SVE->NEON).
Code without explicit SL context uses these. This is migration scaffolding —
subsequent diffs will replace SINGLE_SIMD_LEVEL usages with proper SL dispatch.

simd_result_handlers.h is no longer %include'd by SWIG (the templatized types
are unparseable by SWIG). make_knn_handler methods are %ignore'd. The Python
API does not use these internal SIMD handler types.

Pre-existing bug fixes bundled with this refactor:
- simdlib_avx512.h: simd512bit::bin() stack buffer overflow (char[257] -> char[513])
- simdlib_avx2.h: simd256bit constructor used aligned _mm256_load_si256 instead
  of unaligned _mm256_loadu_si256
- All platform headers: simd16uint16/simd32uint8 operator+=/operator-= returned
  by value instead of by reference

Static builds: zero performance change. Template specializations produce
identical layout, ABI, and codegen as the old plain structs.

Reviewed By: mdouze

Differential Revision: D95392150

fbshipit-source-id: 435b643f96a7e08d777796390066964d99295f63

Author: algoriddle

faiss/CMakeLists.txt

@@ -296,12 +296,13 @@ set(FAISS_HEADERS
   utils/rabitq_simd.h
   utils/random.h
   utils/sorting.h
-  utils/simdlib.h
-  utils/simdlib_avx2.h
-  utils/simdlib_avx512.h
-  utils/simdlib_emulated.h
-  utils/simdlib_neon.h
-  utils/simdlib_ppc64.h
+  impl/simdlib/simdlib.h
+  impl/simdlib/simdlib_dispatch.h
+  impl/simdlib/simdlib_avx2.h
+  impl/simdlib/simdlib_avx512.h
+  impl/simdlib/simdlib_emulated.h
+  impl/simdlib/simdlib_neon.h
+  impl/simdlib/simdlib_ppc64.h
   utils/utils.h
   utils/simd_levels.h
   utils/distances_fused/avx512.h
@@ -459,6 +460,14 @@ if(FAISS_OPT_LEVEL STREQUAL "dd")
   endif()
 endif()
 
+# NEON is mandatory on ARM64 — ensure COMPILE_SIMD_ARM_NEON is always defined
+# and NEON source files are always compiled into the main faiss target.
+# (On x86, AVX2/AVX512 are optional and only compiled per opt_level above.)
+if(CMAKE_SYSTEM_PROCESSOR MATCHES "(aarch64|arm64|ARM64)")
+  target_compile_definitions(faiss PRIVATE COMPILE_SIMD_ARM_NEON)
+  target_sources(faiss PRIVATE ${FAISS_SIMD_NEON_SRC})
+endif()
+
 if(FAISS_ENABLE_SVS)
   find_package(svs_runtime 0.2.0 REQUIRED)
 

faiss/IndexIVFPQFastScan.cpp

@@ -15,10 +15,10 @@
 
 #include <faiss/impl/AuxIndexStructures.h>
 #include <faiss/impl/FaissAssert.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/Heap.h>
 #include <faiss/utils/distances.h>
 #include <faiss/utils/extra_distances.h>
-#include <faiss/utils/simdlib.h>
 
 #include <faiss/invlists/BlockInvertedLists.h>
 
@@ -349,7 +349,7 @@ struct IVFPQFastScanScanner : InvertedListScanner {
         const float* x = index.by_residual ? residual.data() : this->xi;
         float accu = 0;
         // implemented for all vector distances, although only L2 and IP are
-        // suppored by FastScan
+        // supported by FastScan
         with_VectorDistance(pq.dsub, index.metric_type, 0.0, [&](auto vd) {
             int m;
             for (m = 0; m + 1 < pq.M; m += 2) {

faiss/IndexRaBitQFastScan.h

@@ -16,8 +16,8 @@
 #include <faiss/impl/RaBitQUtils.h>
 #include <faiss/impl/RaBitQuantizer.h>
 #include <faiss/impl/simd_result_handlers.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/Heap.h>
-#include <faiss/utils/simdlib.h>
 
 namespace faiss {
 

faiss/impl/LookupTableScaler.h

@@ -10,7 +10,7 @@
 #include <cstdint>
 #include <cstdlib>
 
-#include <faiss/utils/simdlib.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 
 /*******************************************
  * The Scaler objects are used to specialize the handling of the

faiss/impl/residual_quantizer_encode_steps.cpp

@@ -11,9 +11,9 @@
 #include <faiss/impl/FaissAssert.h>
 #include <faiss/impl/ResidualQuantizer.h>
 #include <faiss/impl/simd_dispatch.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/Heap.h>
 #include <faiss/utils/distances.h>
-#include <faiss/utils/simdlib.h>
 #include <faiss/utils/utils.h>
 
 #include <faiss/utils/approx_topk/approx_topk.h>

faiss/impl/scalar_quantizer/codecs.h

@@ -8,8 +8,8 @@
 #pragma once
 
 #include <faiss/impl/ScalarQuantizer.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/simd_levels.h>
-#include <faiss/utils/simdlib.h>
 
 namespace faiss {
 

faiss/impl/scalar_quantizer/distance_computers.h

@@ -8,8 +8,8 @@
 #pragma once
 
 #include <faiss/impl/ScalarQuantizer.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/simd_levels.h>
-#include <faiss/utils/simdlib.h>
 
 namespace faiss {
 

faiss/impl/scalar_quantizer/quantizers.h

@@ -8,10 +8,10 @@
 #pragma once
 
 #include <faiss/impl/ScalarQuantizer.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/bf16.h>
 #include <faiss/utils/fp16.h>
 #include <faiss/utils/simd_levels.h>
-#include <faiss/utils/simdlib.h>
 
 namespace faiss {
 

faiss/impl/scalar_quantizer/scanners.h

@@ -11,8 +11,8 @@
 #pragma once
 
 #include <faiss/impl/ScalarQuantizer.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/simd_levels.h>
-#include <faiss/utils/simdlib.h>
 
 #include <faiss/impl/simd_dispatch.h>
 

faiss/impl/scalar_quantizer/similarities.h

@@ -8,8 +8,8 @@
 #pragma once
 
 #include <faiss/impl/ScalarQuantizer.h>
+#include <faiss/impl/simdlib/simdlib_dispatch.h>
 #include <faiss/utils/simd_levels.h>
-#include <faiss/utils/simdlib.h>
 
 namespace faiss {