Route Hamming code sizes to the fastest kernel, and accept ragged sizes

Summary:
`faiss::hammings()` had two problems. It threw unless the code size was a whole number of 64-bit words, even though the other Hamming entry points (`hammings_knn_hc`, `hamming_range_search`) have always accepted ragged sizes. And for aligned sizes it always used the bit-level `hammings_impl<nbits>` kernels, never the hand-written `HammingComputer` family, which is substantially faster at some sizes.

Together those forced callers who cared about either case to reach past `hammings()` into `with_simd_level_a0_spr` and `with_HammingComputer` — faiss internals — and hand-roll the sweep plus a routing rule. Laser does exactly this today in `KnnFaissBinaryIndex::measureAllCentroids` (D115840549), and can drop all of it after this.

`hammings_fixSL` now takes the `HammingComputer` path when the size is ragged, or when `prefer_hamming_computer()` says the computer beats the word kernel there. That predicate is `constexpr` over `THE_SIMD_LEVEL`, because which sizes qualify depends on the ISA. Sizes it does not name keep the kernels they use today, so aligned sizes with no dedicated computer (24, 40, 48, 56, 128, ...) are unaffected by design.

## Which sizes, and why

Both kernels measured in one process, interleaved rep by rep, at na=1/nb=65536 and na=256/nb=4096. Negative means the computer wins.

| ncodes | static AVX2 | dynamic dispatch (AVX512) |
| --- | --- | --- |
| 8 | kernel wins 46% | kernel wins 202% |
| 16 | **computer wins 25%** | kernel wins 45% |
| 32 | **computer wins 23%** | kernel wins 27% |
| 64 | **computer wins 42%** | **computer wins 73%** |
| 4, 20 | tie — already routed to the computer | tie |
| 24/40/48/56/128/160 | kernel wins 32-98% | kernel wins 42-144% |

So only 64 qualifies at every level. `hamming<512>` has no SIMD specialization above 256 bits on x86 — it is a plain scalar popcount loop — and compiling it with AVX-512 flags makes it markedly worse rather than better (15.0 ns/pair, versus 6.7 under AVX2). Size 8 never qualifies, which is worth noting because Laser's current rule assumes it does.

## FAISS_NOINLINE removed

An earlier version of this diff put `FAISS_NOINLINE` on the ragged helper, because inlining it doubled `hammings_fixSL` and slowed the sizes sharing the runtime-nwords loop. Re-measuring after the routing change, that no longer reproduces anywhere: with 16/32/64 moved off the switch, inlining is neutral-to-better in both build modes (ncodes 24: -10.1% static, -3.1% DD; ragged sizes -3 to -12%). The attribute and its `platform_macros.h` macro are dropped; nothing else in faiss used it.

## Net effect

Versus the previous state of this diff. Interleaved A/B, one code size per process, 300 samples per cell.

| ncodes | static AVX2 | dynamic dispatch (AVX512) |
| --- | --- | --- |
| 16 | **-25.2%** | -0.5% |
| 32 | **-25.2%** | -0.2% |
| 64 | **-47.3%** | **-83.3%** (15.0 -> 2.50 ns/pair) |
| 12 / 20 / 33 (ragged) | -7.3 / -11.8 / -5.1% | -0.2 / -10.5 / -4.0% |
| 8, 40, 48, 56, 128 | within noise (<=1.6%) | within noise (<=2.6%) |
| **24** | **+19.6%** | -3.5% |

## Caveats

**ncodes 24, static AVX2, +19.6%.** Not explained. Retired instructions per pair are identical (36.86 vs 36.83), both hot loops are 32-byte aligned, and DSB uops, uops issued/retired, resource stalls, memory stalls, 4K aliasing and branch mispredicts are all unchanged; the same instruction sequence simply takes 28% more cycles. This size has swung 30-50% from unrelated code motion three separate times during this work, so the working theory is that its runtime-nwords loop is unusually placement-sensitive on this core and the change landed it badly. Plausible follow-up is to give that path its own out-of-line function so it stops sharing layout with the switch; not attempted here.

**Measured only on Intel Cooper Lake** (Xeon Platinum 8339HC), `mode/opt`. `prefer_hamming_computer()` is a per-ISA table, and AVX-512 behaves quite differently on AMD Zen, so the AVX512 rows should be re-measured before relying on them there. Levels that were not measured (NONE, NEON, SVE, RVV) deliberately keep their current kernels. AVX512_SPR is grouped with AVX512 on the mechanism above rather than on a measurement, since no SPR host was available.

Differential Revision: D115982541

Author: Michael Norris

faiss/utils/hamming.h

@@ -111,7 +111,7 @@ FAISS_API extern size_t hamming_batch_size;
  *
  * @param  a             size na * nbytespercode
  * @param  b             size nb * nbytespercode
- * @param  nbytespercode should be multiple of 8
+ * @param  nbytespercode any size; multiples of 8 take a faster kernel
  * @param  dis           output distances, size na * nb
  */
 void hammings(

faiss/utils/hamming_distance/hamming_impl.h

@@ -298,6 +298,41 @@ void generalized_hammings_knn_hc_impl(
     }
 }
 
+void hammings_with_computer(
+        const uint8_t* __restrict a,
+        const uint8_t* __restrict b,
+        size_t na,
+        size_t nb,
+        size_t ncodes,
+        hamdis_t* __restrict dis) {
+    with_HammingComputer<THE_SIMD_LEVEL>(ncodes, [&]<class HammingComputer>() {
+        for (size_t i = 0; i < na; i++) {
+            HammingComputer hc(a + i * ncodes, ncodes);
+            const uint8_t* bi = b;
+            for (size_t j = 0; j < nb; j++) {
+                dis[i * nb + j] = hc.hamming(bi);
+                bi += ncodes;
+            }
+        }
+    });
+}
+
+// Word-multiple sizes whose HammingComputer beats the kernel below; measured
+// per SIMD level on x86, unmeasured levels keep the kernels. See diff summary.
+constexpr bool prefer_hamming_computer(size_t ncodes) {
+    constexpr bool is_avx512 = THE_SIMD_LEVEL == SIMDLevel::AVX512 ||
+            THE_SIMD_LEVEL == SIMDLevel::AVX512_SPR;
+    constexpr bool is_avx2 = THE_SIMD_LEVEL == SIMDLevel::AVX2;
+
+    if (ncodes == 64) {
+        return is_avx2 || is_avx512;
+    }
+    if (ncodes == 16 || ncodes == 32) {
+        return is_avx2;
+    }
+    return false;
+}
+
 } // anonymous namespace
 
 /******************************************************************
@@ -364,7 +399,10 @@ void hammings_fixSL<THE_SIMD_LEVEL>(
         size_t nb,
         size_t ncodes,
         hamdis_t* dis) {
-    FAISS_THROW_IF_NOT(ncodes % 8 == 0);
+    if (ncodes % 8 != 0 || prefer_hamming_computer(ncodes)) {
+        hammings_with_computer(a, b, na, nb, ncodes, dis);
+        return;
+    }
     switch (ncodes) {
         case 8:
             hammings_impl<64>(C64(a), C64(b), na, nb, dis);

tests/test_hamming.cpp

@@ -316,7 +316,7 @@ TEST(TestHamming, test_hamming_knn) {
         ASSERT_EQ(dist_ham_knn, *true_bit_distances) << assert_str.str();
     }
 
-    for (auto code_size : {8, 16, 24, 32}) {
+    for (auto code_size : {8, 16, 24, 32, 64}) {
         std::stringstream assert_str = get_correct_hamming_example(
                 na,
                 nb,
@@ -333,3 +333,44 @@ TEST(TestHamming, test_hamming_knn) {
         EXPECT_EQ(dist_gen, *true_bit_distances) << assert_str.str();
     }
 }
+
+// Code sizes that are not a whole number of 64-bit words take the byte-tail
+// kernel rather than the word-level one. The knn entry points have always
+// accepted them; hammings() used to throw instead.
+TEST(TestHamming, test_hammings_ragged_code_size) {
+    std::default_random_engine rng(123);
+    std::uniform_int_distribution<int32_t> uniform(0, 255);
+
+    const size_t na = 3;
+    const size_t nb = 7;
+
+    for (auto code_size : {1, 2, 5, 12, 20, 33}) {
+        std::vector<uint8_t> a(na * code_size);
+        std::vector<uint8_t> b(nb * code_size);
+        for (auto& v : a) {
+            v = uniform(rng);
+        }
+        for (auto& v : b) {
+            v = uniform(rng);
+        }
+
+        // Reference: byte-wise popcount of the XOR, independent of faiss.
+        std::vector<hamdis_t> expected(na * nb);
+        for (size_t i = 0; i < na; ++i) {
+            for (size_t j = 0; j < nb; ++j) {
+                int d = 0;
+                for (int c = 0; c < code_size; ++c) {
+                    d += __builtin_popcount(
+                            static_cast<unsigned>(
+                                    a[i * code_size + c] ^
+                                    b[j * code_size + c]));
+                }
+                expected[i * nb + j] = d;
+            }
+        }
+
+        std::vector<hamdis_t> dis(na * nb);
+        faiss::hammings(a.data(), b.data(), na, nb, code_size, dis.data());
+        EXPECT_EQ(dis, expected) << "code_size = " << code_size;
+    }
+}