numkong 7.0.0

package/include/numkong/set/README.md

@@ -0,0 +1,179 @@
+# Set Similarity Measures in NumKong
+
+NumKong implements set similarity functions for binary and integer vectors: Hamming distance measures the number of differing elements, while Jaccard distance measures the complement of the intersection-over-union ratio.
+These are fundamental to locality-sensitive hashing, MinHash sketches, and binary feature matching.
+
+Hamming distance counts the number of positions where elements differ.
+For binary vectors packed as octets, this is the popcount of the XOR.
+For byte-level vectors, it counts the number of mismatched bytes:
+
+```math
+\text{hamming}(a, b) = \sum_{i=0}^{n-1} [a_i \neq b_i]
+```
+
+Jaccard distance measures the dissimilarity of two sets.
+For binary vectors, the intersection and union are computed via bitwise AND and OR with popcount:
+
+```math
+\text{jaccard}(a, b) = 1 - \frac{|A \cap B|}{|A \cup B|} = 1 - \frac{\text{popcount}(a \mathbin{\&} b)}{\text{popcount}(a \mathbin{|} b)}
+```
+
+For word-level vectors (MinHash signatures), Jaccard similarity is the fraction of matching elements:
+
+```math
+\text{jaccard}(a, b) = 1 - \frac{\sum_{i=0}^{n-1} [a_i = b_i]}{n}
+```
+
+Reformulating as Python pseudocode:
+
+```python
+import numpy as np
+
+def hamming_bits(a: np.ndarray, b: np.ndarray) -> int:
+    return np.unpackbits(np.bitwise_xor(a, b)).sum()
+
+def jaccard_bits(a: np.ndarray, b: np.ndarray) -> float:
+    intersection = np.unpackbits(np.bitwise_and(a, b)).sum()
+    union = np.unpackbits(np.bitwise_or(a, b)).sum()
+    return 1 - intersection / union if union else 0
+
+def jaccard_words(a: np.ndarray, b: np.ndarray) -> float:
+    return 1 - np.mean(a == b)
+```
+
+## Input & Output Types
+
+| Input Type | Output Type | Description                                 |
+| ---------- | ----------- | ------------------------------------------- |
+| `u1`       | `u32`       | Binary Hamming distance, packed octets      |
+| `u1`       | `f32`       | Binary Jaccard distance, packed octets      |
+| `u8`       | `u32`       | Byte-level Hamming distance                 |
+| `u16`      | `f32`       | Word-level Jaccard distance, 16-bit MinHash |
+| `u32`      | `f32`       | Word-level Jaccard distance, 32-bit MinHash |
+
+## Optimizations
+
+### Harley-Seal Carry-Save Adders for U1
+
+`nk_hamming_u1_haswell`, `nk_jaccard_u1_haswell` amortize the cost of popcount by using Harley-Seal carry-save adder trees.
+Instead of computing popcount on every XOR/AND/OR result independently, three intermediate values are combined through a full-adder circuit:
+
+```
+ones  = a ^ b ^ c
+twos  = (a & b) | (c & (a ^ b))
+```
+
+This circuit takes three popcount inputs and produces a ones and twos accumulator, where `twos` has double the weight of `ones`.
+By chaining two levels, a fours accumulator is also produced, so the actual `VPSHUFB`-based popcount is called only on the final accumulated ones, twos, and fours values.
+The total number of popcount operations is reduced by roughly a factor of three compared to computing popcount on every vector independently.
+
+### Native VPOPCNTQ on Ice Lake
+
+`nk_hamming_u1_icelake`, `nk_jaccard_u1_icelake` use `VPOPCNTQ` on 512-bit vectors, which directly produces per-quadword population counts for 8 quadwords at once.
+This single instruction replaces the entire nibble-LUT + Harley-Seal pipeline used on Haswell.
+The kernels batch 16 vectors before horizontal reduction to minimize `VPSADBW` overhead, accumulating the per-quadword counts into a running total via `VPADDQ`.
+
+### Jaccard via Precomputed Norms
+
+`nk_jaccard_u1_haswell`, `nk_jaccard_u1_icelake` exploit the identity $|A \cup B| = |A| + |B| - |A \cap B|$ to avoid computing both AND-popcount and OR-popcount in the inner loop.
+When vector norms (popcount of each vector) are precomputed and passed via the streaming API, only the intersection popcount is needed per pair, halving the work in the critical path.
+
+### Byte Hamming via VPSADBW
+
+`nk_hamming_u8_haswell`, `nk_hamming_u8_icelake` compute byte-level Hamming distance using XOR to produce per-byte difference indicators, then `VPSADBW` against zero to horizontally sum the nonzero bytes.
+XOR produces 0 for equal bytes and nonzero for different ones, and `VPSADBW` sums the absolute values of byte differences within each 64-bit lane.
+Since XOR results are either 0 or nonzero (not necessarily 1), the kernel masks XOR output through `VPMIN` with a vector of ones to clamp each byte to 0 or 1 before feeding `VPSADBW`.
+
+## Performance
+
+The following performance tables are produced by manually re-running `nk_test` and `nk_bench` included internal tools to measure both accuracy and throughput at different input shapes.
+The input size is controlled by the `NK_DENSE_DIMENSIONS` environment variable and set to 256, 1024, and 4096 elements.
+The throughput is measured in GB/s as the number of input bytes per second.
+Accuracy is reported where applicable as exact distance in the result representation; floating Jaccard rows are shown as mean ULP (units in last place).
+Each kernel runs for at least 20 seconds per configuration.
+Benchmark threads are pinned to specific cores; on machines with heterogeneous core types (e.g., Apple P/E cores), only the fastest cores are used.
+Workloads that significantly degrade CPU frequencies (Intel AMX, Apple SME) run in separate passes to avoid affecting throughput measurements of other kernels.
+
+### Intel Sapphire Rapids
+
+#### Native
+
+| Kernel                   |                      256 |                     1024 |                     4096 |
+| :----------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u1__                   | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u1_serial`   |                2.30 gb/s |                2.62 gb/s |                2.54 gb/s |
+| `nk_jaccard_u1_serial`   |         1.35 gb/s, 0 ulp |         1.46 gb/s, 0 ulp |         1.50 gb/s, 0 ulp |
+| `nk_hamming_u1_haswell`  |                9.63 gb/s |                25.2 gb/s |                56.2 gb/s |
+| `nk_jaccard_u1_haswell`  |         5.24 gb/s, 0 ulp |         15.5 gb/s, 0 ulp |         27.0 gb/s, 0 ulp |
+| `nk_hamming_u1_icelake`  |                11.2 gb/s |                38.2 gb/s |                56.1 gb/s |
+| `nk_jaccard_u1_icelake`  |         6.46 gb/s, 0 ulp |         22.4 gb/s, 0 ulp |         33.3 gb/s, 0 ulp |
+| __u8__                   | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u8_serial`   |                15.0 gb/s |                14.9 gb/s |                14.8 gb/s |
+| `nk_hamming_u8_haswell`  |                22.4 gb/s |                21.6 gb/s |                17.9 gb/s |
+| `nk_hamming_u8_icelake`  |                55.2 gb/s |                37.7 gb/s |                24.3 gb/s |
+| __u16__                  | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u16_serial`  |         27.8 gb/s, 0 ulp |         23.0 gb/s, 0 ulp |         19.2 gb/s, 0 ulp |
+| `nk_jaccard_u16_haswell` |         22.2 gb/s, 0 ulp |         18.4 gb/s, 0 ulp |         13.7 gb/s, 0 ulp |
+| `nk_jaccard_u16_icelake` |         54.2 gb/s, 0 ulp |         24.3 gb/s, 0 ulp |         20.9 gb/s, 0 ulp |
+| __u32__                  | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u32_serial`  |         33.1 gb/s, 0 ulp |         23.5 gb/s, 0 ulp |         18.3 gb/s, 0 ulp |
+| `nk_jaccard_u32_haswell` |         19.0 gb/s, 0 ulp |         16.9 gb/s, 0 ulp |         11.0 gb/s, 0 ulp |
+| `nk_jaccard_u32_icelake` |         33.0 gb/s, 0 ulp |         24.6 gb/s, 0 ulp |         16.3 gb/s, 0 ulp |
+
+#### WASM
+
+Measured with Wasmtime v42 (Cranelift backend).
+
+| Kernel                       |                      256 |                     1024 |                     4096 |
+| :--------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u1__                       | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u1_v128relaxed`  |               0.138 gb/s |               0.149 gb/s |               0.979 gb/s |
+| `nk_jaccard_u1_v128relaxed`  |        0.153 gb/s, 0 ulp |        0.352 gb/s, 0 ulp |         2.50 gb/s, 0 ulp |
+| __u8__                       | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u8_v128relaxed`  |               0.370 gb/s |               0.400 gb/s |                2.19 gb/s |
+| __u16__                      | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u16_v128relaxed` |         2.30 gb/s, 0 ulp |         2.34 gb/s, 0 ulp |        0.381 gb/s, 0 ulp |
+| __u32__                      | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u32_v128relaxed` |        0.430 gb/s, 0 ulp |         2.46 gb/s, 0 ulp |         1.08 gb/s, 0 ulp |
+
+### Apple M4
+
+#### Native
+
+| Kernel                  |                      256 |                     1024 |                     4096 |
+| :---------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u1__                  | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u1_serial`  |                4.66 gb/s |                5.30 gb/s |                5.04 gb/s |
+| `nk_jaccard_u1_serial`  |         3.03 gb/s, 0 ulp |         3.72 gb/s, 0 ulp |         3.65 gb/s, 0 ulp |
+| `nk_hamming_u1_neon`    |                20.7 gb/s |                41.9 gb/s |                52.2 gb/s |
+| `nk_jaccard_u1_neon`    |         15.8 gb/s, 0 ulp |         29.5 gb/s, 0 ulp |         34.8 gb/s, 0 ulp |
+| __u8__                  | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u8_serial`  |                20.7 gb/s |                21.9 gb/s |                18.1 gb/s |
+| `nk_hamming_u8_neon`    |                49.1 gb/s |                43.9 gb/s |                32.5 gb/s |
+| __u16__                 | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u16_serial` |         42.5 gb/s, 0 ulp |         39.7 gb/s, 0 ulp |         36.1 gb/s, 0 ulp |
+| `nk_jaccard_u16_neon`   |         43.3 gb/s, 0 ulp |         33.0 gb/s, 0 ulp |         29.2 gb/s, 0 ulp |
+| __u32__                 | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u32_serial` |         60.6 gb/s, 0 ulp |         49.0 gb/s, 0 ulp |         51.2 gb/s, 0 ulp |
+| `nk_jaccard_u32_neon`   |         51.0 gb/s, 0 ulp |         39.9 gb/s, 0 ulp |         38.9 gb/s, 0 ulp |
+
+#### WASM
+
+Measured with Wasmtime v42 (Cranelift backend).
+
+| Kernel                       |                      256 |                     1024 |                     4096 |
+| :--------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u1__                       | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u1_serial`       |               0.501 gb/s |             0.00424 gb/s |              0.0443 gb/s |
+| `nk_jaccard_u1_serial`       |        0.315 gb/s, 0 ulp |        0.362 gb/s, 0 ulp |        0.382 gb/s, 0 ulp |
+| `nk_hamming_u1_v128relaxed`  |               0.414 gb/s |              0.0294 gb/s |               0.233 gb/s |
+| `nk_jaccard_u1_v128relaxed`  |       0.0141 gb/s, 0 ulp |        0.317 gb/s, 0 ulp |        0.249 gb/s, 0 ulp |
+| __u8__                       | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_hamming_u8_serial`       |               0.551 gb/s |               0.352 gb/s |               0.154 gb/s |
+| `nk_hamming_u8_v128relaxed`  |               0.702 gb/s |               0.409 gb/s |               0.464 gb/s |
+| __u16__                      | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u16_serial`      |        0.647 gb/s, 0 ulp |        0.362 gb/s, 0 ulp |        0.174 gb/s, 0 ulp |
+| `nk_jaccard_u16_v128relaxed` |        0.409 gb/s, 0 ulp |      0.00109 gb/s, 0 ulp |        0.275 gb/s, 0 ulp |
+| __u32__                      | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_jaccard_u32_serial`      |        0.320 gb/s, 0 ulp |        0.161 gb/s, 0 ulp |        0.607 gb/s, 0 ulp |
+| `nk_jaccard_u32_v128relaxed` |        0.397 gb/s, 0 ulp |        0.364 gb/s, 0 ulp |       0.0807 gb/s, 0 ulp |

package/include/numkong/set/haswell.h

@@ -0,0 +1,334 @@
+/**
+ *  @brief SIMD-accelerated Set Similarity Measures for Haswell.
+ *  @file include/numkong/set/haswell.h
+ *  @author Ash Vardanian
+ *  @date December 27, 2025
+ *
+ *  @sa include/numkong/set.h
+ *
+ *  @section set_haswell_instructions Key POPCNT/AVX2 Set Instructions
+ *
+ *      Intrinsic                   Instruction                     Latency     Throughput  Ports
+ *      _mm_popcnt_u64              POPCNT (R64, R64)               3cy         1/cy        p1
+ *      _mm256_and_si256            VPAND (YMM, YMM, YMM)           1cy         0.33/cy     p015
+ *      _mm256_or_si256             VPOR (YMM, YMM, YMM)            1cy         0.33/cy     p015
+ *      _mm256_xor_si256            VPXOR (YMM, YMM, YMM)           1cy         0.33/cy     p015
+ *      _mm256_extracti128_si256    VEXTRACTI128 (XMM, YMM, I8)     3cy         1/cy        p5
+ *
+ *  Haswell lacks SIMD popcount; we extract 64-bit words and use scalar POPCNT. The p1 port
+ *  bottleneck limits throughput to 1 popcount/cycle. For Hamming distance, XOR + POPCNT;
+ *  for Jaccard, compute AND/OR + POPCNT separately to get intersection and union counts.
+ *
+ *  @section set_haswell_stateful Stateful Streaming Logic
+ *
+ *  To build memory-optimal tiled algorithms, this file defines:
+ *
+ *  - nk_hamming_u1x64_state_haswell_t for streaming Hamming distance
+ *  - nk_jaccard_u1x64_state_haswell_t for streaming Jaccard similarity
+ *
+ *  @code{c}
+ *  nk_jaccard_u1x64_state_haswell_t state_first, state_second, state_third, state_fourth;
+ *  nk_jaccard_u1x64_init_haswell(&state_first);
+ *  // ... stream through packed binary vectors ...
+ *  nk_jaccard_u1x64_finalize_haswell(&state_first, &state_second, &state_third, &state_fourth,
+ *      query_popcount, target_popcount_a, target_popcount_b, target_popcount_c, target_popcount_d,
+ *      total_dimensions, &results);
+ *  @endcode
+ */
+#ifndef NK_SET_HASWELL_H
+#define NK_SET_HASWELL_H
+
+#if NK_TARGET_X86_
+#if NK_TARGET_HASWELL
+
+#include "numkong/types.h"
+#include "numkong/set/serial.h" // `nk_u1x8_popcount_`
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("avx2,sse4.1,popcnt"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("avx2", "sse4.1", "popcnt")
+#endif
+
+#pragma region - Binary Sets
+
+NK_PUBLIC void nk_hamming_u1_haswell(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result) {
+    nk_size_t n_bytes = nk_size_divide_round_up_(n, NK_BITS_PER_BYTE);
+    // x86 supports unaligned loads and works just fine with the scalar version for small vectors.
+    nk_u32_t differences = 0;
+    for (; n_bytes >= 8; n_bytes -= 8, a += 8, b += 8)
+        differences += _mm_popcnt_u64(*(nk_u64_t const *)a ^ *(nk_u64_t const *)b);
+    for (; n_bytes; --n_bytes, ++a, ++b) differences += _mm_popcnt_u32(*a ^ *b);
+    *result = differences;
+}
+
+NK_PUBLIC void nk_jaccard_u1_haswell(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_size_t n_bytes = nk_size_divide_round_up_(n, NK_BITS_PER_BYTE);
+    // x86 supports unaligned loads and works just fine with the scalar version for small vectors.
+    nk_u32_t intersection_count = 0, union_count = 0;
+    for (; n_bytes >= 8; n_bytes -= 8, a += 8, b += 8)
+        intersection_count += (nk_u32_t)_mm_popcnt_u64(*(nk_u64_t const *)a & *(nk_u64_t const *)b),
+            union_count += (nk_u32_t)_mm_popcnt_u64(*(nk_u64_t const *)a | *(nk_u64_t const *)b);
+    for (; n_bytes; --n_bytes, ++a, ++b)
+        intersection_count += nk_u1x8_popcount_(*a & *b), union_count += nk_u1x8_popcount_(*a | *b);
+    *result = (union_count != 0) ? 1.0f - (nk_f32_t)intersection_count / (nk_f32_t)union_count : 0.0f;
+}
+
+#pragma endregion - Binary Sets
+
+#pragma region - Integer Sets
+
+NK_PUBLIC void nk_jaccard_u32_haswell(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_u32_t intersection_count = 0;
+    nk_size_t n_remaining = n;
+    for (; n_remaining >= 4; n_remaining -= 4, a += 4, b += 4) {
+        __m128i a_u32x4 = _mm_loadu_si128((__m128i const *)a);
+        __m128i b_u32x4 = _mm_loadu_si128((__m128i const *)b);
+        __m128i equality_u32x4 = _mm_cmpeq_epi32(a_u32x4, b_u32x4);
+        int equality_mask = _mm_movemask_ps(_mm_castsi128_ps(equality_u32x4));
+        intersection_count += (nk_u32_t)_mm_popcnt_u32((unsigned int)equality_mask);
+    }
+    for (; n_remaining; --n_remaining, ++a, ++b) intersection_count += (*a == *b);
+    *result = (n != 0) ? 1.0f - (nk_f32_t)intersection_count / (nk_f32_t)n : 0.0f;
+}
+
+NK_PUBLIC void nk_hamming_u8_haswell(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result) {
+    // Process 32 bytes at a time using AVX2 (256-bit registers).
+    // Compare bytes for equality, invert to get not-equal mask, then count mismatches.
+    //
+    // Haswell port analysis:
+    // - `_mm256_loadu_si256`:   p23, 1cy latency (load)
+    // - `_mm256_cmpeq_epi8`:    p015, 1cy latency, 0.33cy throughput
+    // - `_mm256_extracti128`:   p5, 3cy latency, 1cy throughput
+    // - `_mm_popcnt_u64`:       p1 ONLY, 3cy latency, 1cy throughput (BOTTLENECK)
+    //
+    // For counting mismatches, we XOR and popcount the resulting bits set to 1.
+    // Alternative: compare -> movemask -> popcount, but movemask only works per-byte MSBs.
+    // XOR approach: each differing byte produces 0xFF (8 bits set), need to count bytes not bits.
+
+    nk_u32_t differences = 0;
+    nk_size_t n_remaining = n;
+
+    // Main loop: process 32 bytes at a time
+    for (; n_remaining >= 32; n_remaining -= 32, a += 32, b += 32) {
+        __m256i a_u8x32 = _mm256_loadu_si256((__m256i const *)a);
+        __m256i b_u8x32 = _mm256_loadu_si256((__m256i const *)b);
+
+        // Compare for equality: 0xFF where equal, 0x00 where different
+        __m256i equality_u8x32 = _mm256_cmpeq_epi8(a_u8x32, b_u8x32);
+
+        // Extract to two 128-bit halves for movemask
+        // movemask extracts the MSB of each byte, giving us 16 bits per 128-bit half
+        __m128i equality_low_u8x16 = _mm256_castsi256_si128(equality_u8x32);
+        __m128i equality_high_u8x16 = _mm256_extracti128_si256(equality_u8x32, 1);
+
+        // Get masks: bit set = equal (0xFF MSB = 1), bit clear = different
+        int mask_low = _mm_movemask_epi8(equality_low_u8x16);   // 16 bits
+        int mask_high = _mm_movemask_epi8(equality_high_u8x16); // 16 bits
+
+        // Invert to count differences (bit set = different)
+        // Then popcount to count mismatches
+        differences += (nk_u32_t)_mm_popcnt_u32((unsigned int)(~mask_low & 0xFFFF));
+        differences += (nk_u32_t)_mm_popcnt_u32((unsigned int)(~mask_high & 0xFFFF));
+    }
+
+    // Handle remaining bytes (0-31) with scalar code
+    for (; n_remaining; --n_remaining, ++a, ++b) differences += (*a != *b);
+
+    *result = differences;
+}
+
+NK_PUBLIC void nk_jaccard_u16_haswell(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result) {
+    // Process 16 u16 values at a time using AVX2 (256-bit registers).
+    // Compare 16-bit integers for equality and count matches.
+    //
+    // Haswell port analysis:
+    // - `_mm256_loadu_si256`:   p23, 1cy latency (load)
+    // - `_mm256_cmpeq_epi16`:   p015, 1cy latency, 0.33cy throughput
+    // - `_mm256_packs_epi16`:   p5, 1cy latency, 1cy throughput (pack 16->8 bit)
+    // - `_mm_movemask_epi8`:    p0, 3cy latency (extracts MSB of each byte)
+    // - `_mm_popcnt_u32`:       p1 ONLY, 3cy latency, 1cy throughput
+
+    nk_u32_t matches = 0;
+    nk_size_t n_remaining = n;
+
+    // Main loop: process 16 u16 values at a time
+    for (; n_remaining >= 16; n_remaining -= 16, a += 16, b += 16) {
+        __m256i a_u16x16 = _mm256_loadu_si256((__m256i const *)a);
+        __m256i b_u16x16 = _mm256_loadu_si256((__m256i const *)b);
+
+        // Compare for equality: 0xFFFF where equal, 0x0000 where different
+        __m256i equality_u16x16 = _mm256_cmpeq_epi16(a_u16x16, b_u16x16);
+
+        // Pack 16-bit results to 8-bit to use movemask efficiently.
+        // _mm256_packs_epi16 saturates signed 16-bit to signed 8-bit:
+        // 0xFFFF (-1) -> 0x80 (-128), 0x0000 (0) -> 0x00 (0)
+        // Note: packs interleaves lanes, so we need to handle the permutation.
+        // For counting, we just need the total popcount, so lane order doesn't matter.
+        __m256i packed_i8x32 = _mm256_packs_epi16(equality_u16x16, equality_u16x16);
+
+        // Extract to 128-bit halves
+        __m128i packed_low_i8x16 = _mm256_castsi256_si128(packed_i8x32);
+        __m128i packed_high_i8x16 = _mm256_extracti128_si256(packed_i8x32, 1);
+
+        // movemask extracts MSB of each byte
+        // After packs: 0x80 (MSB=1) for equal, 0x00 (MSB=0) for different
+        // Each 128-bit half has 8 relevant bytes (lower 8 from each original lane)
+        int mask_low = _mm_movemask_epi8(packed_low_i8x16) & 0xFF;   // Lower 8 bytes
+        int mask_high = _mm_movemask_epi8(packed_high_i8x16) & 0xFF; // Lower 8 bytes from high lane
+
+        matches += (nk_u32_t)_mm_popcnt_u32((unsigned int)mask_low);
+        matches += (nk_u32_t)_mm_popcnt_u32((unsigned int)mask_high);
+    }
+
+    // Handle remaining elements (0-15) with scalar code
+    for (; n_remaining; --n_remaining, ++a, ++b) matches += (*a == *b);
+
+    *result = (n != 0) ? 1.0f - (nk_f32_t)matches / (nk_f32_t)n : 0.0f;
+}
+
+#pragma endregion - Integer Sets
+
+#pragma region - Stateful Streaming
+
+typedef struct nk_hamming_u1x64_state_haswell_t {
+    nk_u32_t intersection_count;
+} nk_hamming_u1x64_state_haswell_t;
+
+NK_INTERNAL void nk_hamming_u1x64_init_haswell(nk_hamming_u1x64_state_haswell_t *state) {
+    state->intersection_count = 0;
+}
+
+NK_INTERNAL void nk_hamming_u1x64_update_haswell(nk_hamming_u1x64_state_haswell_t *state, nk_b64_vec_t a,
+                                                 nk_b64_vec_t b, nk_size_t depth_offset, nk_size_t active_dimensions) {
+    nk_unused_(depth_offset);
+    nk_unused_(active_dimensions);
+    state->intersection_count += (nk_u32_t)_mm_popcnt_u64(a.u64 ^ b.u64);
+}
+
+NK_INTERNAL void nk_hamming_u1x64_finalize_haswell( //
+    nk_hamming_u1x64_state_haswell_t const *state_a, nk_hamming_u1x64_state_haswell_t const *state_b,
+    nk_hamming_u1x64_state_haswell_t const *state_c, nk_hamming_u1x64_state_haswell_t const *state_d,
+    nk_size_t total_dimensions, nk_b128_vec_t *result) {
+    nk_unused_(total_dimensions);
+    result->u32s[0] = state_a->intersection_count;
+    result->u32s[1] = state_b->intersection_count;
+    result->u32s[2] = state_c->intersection_count;
+    result->u32s[3] = state_d->intersection_count;
+}
+
+typedef struct nk_jaccard_u1x64_state_haswell_t {
+    nk_u32_t intersection_count;
+} nk_jaccard_u1x64_state_haswell_t;
+
+NK_INTERNAL void nk_jaccard_u1x64_init_haswell(nk_jaccard_u1x64_state_haswell_t *state) {
+    state->intersection_count = 0;
+}
+
+NK_INTERNAL void nk_jaccard_u1x64_update_haswell(nk_jaccard_u1x64_state_haswell_t *state, nk_b64_vec_t a,
+                                                 nk_b64_vec_t b, nk_size_t depth_offset, nk_size_t active_dimensions) {
+    nk_unused_(depth_offset);
+    nk_unused_(active_dimensions);
+    state->intersection_count += (nk_u32_t)_mm_popcnt_u64(a.u64 & b.u64);
+}
+
+NK_INTERNAL void nk_jaccard_u1x64_finalize_haswell( //
+    nk_jaccard_u1x64_state_haswell_t const *state_a, nk_jaccard_u1x64_state_haswell_t const *state_b,
+    nk_jaccard_u1x64_state_haswell_t const *state_c, nk_jaccard_u1x64_state_haswell_t const *state_d,
+    nk_f32_t query_popcount, nk_f32_t target_popcount_a, nk_f32_t target_popcount_b, nk_f32_t target_popcount_c,
+    nk_f32_t target_popcount_d, nk_size_t total_dimensions, nk_b128_vec_t *result) {
+    nk_unused_(total_dimensions);
+
+    // 4-way SIMD Jaccard computation with fast reciprocal.
+    //
+    // Haswell port analysis:
+    // - `_mm_setr_ps`:     p5, 1cy (INSERTPS chain)
+    // - `_mm_add_ps`:      p01, 3cy latency
+    // - `_mm_sub_ps`:      p01, 3cy latency
+    // - `_mm_rcp_ps`:      p0, 5cy latency, 1cy throughput
+    // - `_mm_mul_ps`:      p01, 5cy latency, 0.5cy throughput
+    // - `_mm_blendv_ps`:   p015, 2cy latency
+
+    // Pack intersection counts and convert to float
+    nk_f32_t intersection_a_f32 = (nk_f32_t)state_a->intersection_count;
+    nk_f32_t intersection_b_f32 = (nk_f32_t)state_b->intersection_count;
+    nk_f32_t intersection_c_f32 = (nk_f32_t)state_c->intersection_count;
+    nk_f32_t intersection_d_f32 = (nk_f32_t)state_d->intersection_count;
+
+    __m128 intersection_f32x4 = _mm_setr_ps(intersection_a_f32, intersection_b_f32, intersection_c_f32,
+                                            intersection_d_f32);
+    __m128 query_f32x4 = _mm_set1_ps(query_popcount);
+    __m128 targets_f32x4 = _mm_setr_ps(target_popcount_a, target_popcount_b, target_popcount_c, target_popcount_d);
+    __m128 union_f32x4 = _mm_sub_ps(_mm_add_ps(query_f32x4, targets_f32x4), intersection_f32x4);
+
+    // Handle zero-union edge case
+    __m128 zero_union_mask = _mm_cmpeq_ps(union_f32x4, _mm_setzero_ps());
+    __m128 one_f32x4 = _mm_set1_ps(1.0f);
+    __m128 two_f32x4 = _mm_set1_ps(2.0f);
+    __m128 safe_union_f32x4 = _mm_blendv_ps(union_f32x4, one_f32x4, zero_union_mask);
+
+    // Fast reciprocal with Newton-Raphson refinement:
+    // - `_mm_rcp_ps`: ~12-bit precision, 5cy latency, 1cy throughput
+    // Newton-Raphson:
+    //      rcp' = rcp × (2 - x × rcp), doubles precision to ~22-24 bits
+    // Total: ~10cy vs `_mm_div_ps` 13cy latency, but NR has better throughput
+    __m128 union_reciprocal_f32x4 = _mm_rcp_ps(safe_union_f32x4);
+    __m128 newton_raphson_correction = _mm_sub_ps(two_f32x4, _mm_mul_ps(safe_union_f32x4, union_reciprocal_f32x4));
+    union_reciprocal_f32x4 = _mm_mul_ps(union_reciprocal_f32x4, newton_raphson_correction);
+
+    __m128 ratio_f32x4 = _mm_mul_ps(intersection_f32x4, union_reciprocal_f32x4);
+    __m128 jaccard_f32x4 = _mm_sub_ps(one_f32x4, ratio_f32x4);
+    result->xmm_ps = _mm_blendv_ps(jaccard_f32x4, _mm_setzero_ps(), zero_union_mask);
+}
+
+/** @brief Hamming from_dot: computes pop_a + pop_b - 2*dot for 4 pairs (Haswell). */
+NK_INTERNAL void nk_hamming_u32x4_from_dot_haswell_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
+                                                    nk_b128_vec_t *results) {
+    __m128i dots_i32x4 = dots.xmm;
+    __m128i query_i32x4 = _mm_set1_epi32((int)query_pop);
+    __m128i target_i32x4 = target_pops.xmm;
+    results->xmm = _mm_sub_epi32(_mm_add_epi32(query_i32x4, target_i32x4), _mm_slli_epi32(dots_i32x4, 1));
+}
+
+/** @brief Jaccard from_dot: computes 1 - dot / (pop_a + pop_b - dot) for 4 pairs (Haswell). */
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_haswell_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
+                                                    nk_b128_vec_t *results) {
+    __m128 dot_f32x4 = _mm_cvtepi32_ps(dots.xmm);
+    __m128 query_f32x4 = _mm_set1_ps((nk_f32_t)query_pop);
+    __m128 target_f32x4 = _mm_cvtepi32_ps(target_pops.xmm);
+    __m128 union_f32x4 = _mm_sub_ps(_mm_add_ps(query_f32x4, target_f32x4), dot_f32x4);
+
+    __m128 zero_union_mask = _mm_cmpeq_ps(union_f32x4, _mm_setzero_ps());
+    __m128 one_f32x4 = _mm_set1_ps(1.0f);
+    __m128 two_f32x4 = _mm_set1_ps(2.0f);
+    __m128 safe_union_f32x4 = _mm_blendv_ps(union_f32x4, one_f32x4, zero_union_mask);
+
+    __m128 union_reciprocal_f32x4 = _mm_rcp_ps(safe_union_f32x4);
+    __m128 nr_correction = _mm_sub_ps(two_f32x4, _mm_mul_ps(safe_union_f32x4, union_reciprocal_f32x4));
+    union_reciprocal_f32x4 = _mm_mul_ps(union_reciprocal_f32x4, nr_correction);
+
+    __m128 ratio_f32x4 = _mm_mul_ps(dot_f32x4, union_reciprocal_f32x4);
+    __m128 jaccard_f32x4 = _mm_sub_ps(one_f32x4, ratio_f32x4);
+    results->xmm_ps = _mm_blendv_ps(jaccard_f32x4, _mm_setzero_ps(), zero_union_mask);
+}
+
+#pragma endregion - Stateful Streaming
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_HASWELL
+#endif // NK_TARGET_X86_
+#endif // NK_SET_HASWELL_H