numkong 7.0.0

package/include/numkong/sets/v128relaxed.h

@@ -0,0 +1,58 @@
+/**
+ *  @brief Batched Set Operations for WASM Relaxed SIMD.
+ *  @file include/numkong/sets/v128relaxed.h
+ *  @author Ash Vardanian
+ *  @date March 10, 2026
+ *
+ *  @sa include/numkong/sets.h
+ */
+#ifndef NK_SETS_V128RELAXED_H
+#define NK_SETS_V128RELAXED_H
+
+#if NK_TARGET_V128RELAXED
+
+#include "numkong/set/v128relaxed.h"
+#include "numkong/dots/v128relaxed.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("relaxed-simd"))), apply_to = function)
+#endif
+
+nk_define_cross_normalized_packed_(hamming, u1, v128relaxed, u1x8, u1x8, u32, /*norm_value_type=*/u32, u32,
+                                   nk_b128_vec_t, nk_dots_packed_u1_v128relaxed, nk_hamming_u32x4_from_dot_v128relaxed_,
+                                   nk_dots_reduce_sum_u1_, nk_load_b128_v128relaxed_, nk_partial_load_b32x4_serial_,
+                                   nk_store_b128_v128relaxed_, nk_partial_store_b32x4_serial_,
+                                   /*dimensions_per_value=*/8)
+
+nk_define_cross_normalized_packed_(jaccard, u1, v128relaxed, u1x8, u1x8, u32, /*norm_value_type=*/u32, f32,
+                                   nk_b128_vec_t, nk_dots_packed_u1_v128relaxed, nk_jaccard_f32x4_from_dot_v128relaxed_,
+                                   nk_dots_reduce_sum_u1_, nk_load_b128_v128relaxed_, nk_partial_load_b32x4_serial_,
+                                   nk_store_b128_v128relaxed_, nk_partial_store_b32x4_serial_,
+                                   /*dimensions_per_value=*/8)
+
+nk_define_cross_normalized_symmetric_(hamming, u1, v128relaxed, u1x8, u32, /*norm_value_type=*/u32, u32, nk_b128_vec_t,
+                                      nk_dots_symmetric_u1_v128relaxed, nk_hamming_u32x4_from_dot_v128relaxed_,
+                                      nk_dots_reduce_sum_u1_, nk_load_b128_v128relaxed_, nk_partial_load_b32x4_serial_,
+                                      nk_store_b128_v128relaxed_, nk_partial_store_b32x4_serial_,
+                                      /*dimensions_per_value=*/8)
+
+nk_define_cross_normalized_symmetric_(jaccard, u1, v128relaxed, u1x8, u32, /*norm_value_type=*/u32, f32, nk_b128_vec_t,
+                                      nk_dots_symmetric_u1_v128relaxed, nk_jaccard_f32x4_from_dot_v128relaxed_,
+                                      nk_dots_reduce_sum_u1_, nk_load_b128_v128relaxed_, nk_partial_load_b32x4_serial_,
+                                      nk_store_b128_v128relaxed_, nk_partial_store_b32x4_serial_,
+                                      /*dimensions_per_value=*/8)
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_V128RELAXED
+#endif // NK_SETS_V128RELAXED_H

package/include/numkong/sets.h

@@ -0,0 +1,339 @@
+/**
+ *  @brief SIMD-accelerated Batched Set Distances.
+ *  @file include/numkong/sets.h
+ *  @author Ash Vardanian
+ *
+ *  This module provides efficient batched computation of Hamming and Jaccard distances
+ *  between large collections of sets. Unlike the single-vector `set.h` module, this module
+ *  is optimized for matrix-style operations where you compute distances between:
+ *
+ *  - All pairs of rows in a query matrix Q against rows in values matrix V
+ *  - All pairs within a single values matrix V (symmetric kernel)
+ *
+ *  For dtypes:
+ *
+ *  - u1: 1-bit binary (packed octets) → u32 Hamming / f32 Jaccard
+ *
+ *  For hardware architectures:
+ *
+ *  - Arm: NEON, SME+BI32
+ *  - x86: Haswell, Ice Lake
+ *
+ *  @section numerical_stability Numerical Stability
+ *
+ *  Hamming u1: u32 popcount accumulator. Overflows at n_bits > 2^32.
+ *  Jaccard u1: u32 intersection count, f32 division. Popcount values above 2^24 lose
+ *  precision in f32 cast. Streaming variants use u64 accumulation internally.
+ *
+ *  @section use_cases Use Cases
+ *
+ *  - Binary similarity search: Find nearest neighbors in Hamming/Jaccard space
+ *  - MinHash/SimHash: Compute Jaccard similarity for document fingerprints
+ *  - Locality-sensitive hashing (LSH): Build similarity graphs
+ *  - Binary neural network inference: Compute distances for BNN outputs
+ *
+ *  @section math Mathematical Background
+ *
+ *  Hamming distance: Number of positions where bits differ
+ *    hamming(a, b) = popcount(a XOR b)
+ *
+ *  Jaccard distance: 1 minus the Jaccard similarity
+ *    jaccard(a, b) = 1 - |a ∩ b| / |a ∪ b|
+ *                  = 1 - popcount(a AND b) / popcount(a OR b)
+ *
+ *  For Jaccard, we use the identity: |a ∪ b| = |a| + |b| - |a ∩ b|
+ *  This allows precomputing |a| and |b| (population counts) during packing.
+ */
+
+#ifndef NK_SETS_H
+#define NK_SETS_H
+
+#include "numkong/types.h"
+#include "numkong/dots.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/**
+ *  @brief Compute Hamming distances between V rows and packed Q rows.
+ *  @param[in] v Input values matrix
+ *  @param[in] q_packed Packed queries matrix
+ *  @param[out] result Row-major results matrix
+ *  @param[in] rows Number of rows in the results matrix
+ *  @param[in] cols Number of columns in the results matrix
+ *  @param[in] d Number of dimensions (depth) per vector
+ *  @param[in] v_stride_in_bytes Byte stride between rows of A
+ *  @param[in] r_stride_in_bytes Byte stride between rows of C
+ */
+NK_DYNAMIC void nk_hammings_packed_u1(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                      nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                      nk_size_t r_stride_in_bytes);
+
+/**
+ *  @brief Computes C = A × Aᵀ symmetric Gram matrix of Hamming distances.
+ *  @param[in] vectors Input matrix of row vectors in row-major order.
+ *  @param[in] n_vectors Number of vectors (rows) in the input matrix.
+ *  @param[in] d Dimension of each vector (columns).
+ *  @param[in] stride Row stride in bytes for the input matrix.
+ *  @param[out] result Output symmetric matrix (n_vectors × n_vectors).
+ *  @param[in] result_stride Row stride in bytes for the result matrix.
+ *  @param[in] row_start Starting row offset of results to compute (needed for parallelism).
+ *  @param[in] row_count Number of rows of results to compute (needed for parallelism).
+ */
+NK_DYNAMIC void nk_hammings_symmetric_u1(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d, nk_size_t stride,
+                                         nk_u32_t *result, nk_size_t result_stride, nk_size_t row_start,
+                                         nk_size_t row_count);
+
+/**
+ *  @brief Compute Jaccard distances between V rows and packed Q rows.
+ *  @param[in] v Input values matrix
+ *  @param[in] q_packed Packed queries matrix (with norms)
+ *  @param[out] result Row-major f32 results matrix
+ *  @param[in] rows Number of rows in the results matrix
+ *  @param[in] cols Number of columns in the results matrix
+ *  @param[in] d Number of dimensions (depth) per vector
+ *  @param[in] v_stride_in_bytes Byte stride between rows of A
+ *  @param[in] r_stride_in_bytes Byte stride between rows of C
+ */
+NK_DYNAMIC void nk_jaccards_packed_u1(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                      nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                      nk_size_t r_stride_in_bytes);
+
+/**
+ *  @brief Computes C = f(A, Aᵀ) symmetric Gram matrix of Jaccard distances.
+ *  @param[in] vectors Input matrix of row vectors in row-major order.
+ *  @param[in] n_vectors Number of vectors (rows).
+ *  @param[in] d Dimension of each vector (columns).
+ *  @param[in] stride Row stride in bytes.
+ *  @param[out] result Output symmetric f32 matrix (n_vectors × n_vectors).
+ *  @param[in] result_stride Row stride in bytes for the result matrix.
+ *  @param[in] row_start Starting row offset (for parallelism).
+ *  @param[in] row_count Number of rows to compute (for parallelism).
+ */
+NK_DYNAMIC void nk_jaccards_symmetric_u1(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d, nk_size_t stride,
+                                         nk_f32_t *result, nk_size_t result_stride, nk_size_t row_start,
+                                         nk_size_t row_count);
+
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_serial(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                            nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                            nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_serial(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                               nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                               nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_serial(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                            nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                            nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_serial(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                               nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                               nk_size_t row_start, nk_size_t row_count);
+
+/*  ARM SME with BI32 (binary integer outer products).
+ *  Uses BMOPA/BMOPS for efficient popcount-based set distances.
+ */
+#if NK_TARGET_SMEBI32
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_smebi32(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_smebi32(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_smebi32(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_smebi32(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+#endif // NK_TARGET_SMEBI32
+
+/*  Haswell backends using AVX2 (Intel Core 4th gen).
+ *  Supports F32/F64 via FMA, F16/BF16/FP8 via software emulation, I8/U8 via VPMADDUBSW+VPADDD.
+ */
+#if NK_TARGET_HASWELL
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_haswell(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_haswell(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_haswell(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_haswell(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+#endif // NK_TARGET_HASWELL
+
+/*  Ice Lake backends using AVX-512 with VNNI (Vector Neural Network Instructions).
+ *  Adds VPDPBUSD for I8/U8, VPDPWSSD for I4/U4 with efficient dot products.
+ */
+#if NK_TARGET_ICELAKE
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_icelake(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_icelake(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_icelake(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                             nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                             nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_icelake(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                                nk_size_t row_start, nk_size_t row_count);
+#endif // NK_TARGET_ICELAKE
+
+/*  ARM NEON backends (base NEON with F32/F64 support).
+ *  Uses FMLA for F32 dots, FMLA (scalar) for F64.
+ */
+#if NK_TARGET_NEON
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_neon(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                          nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                          nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_neon(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                             nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                             nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_neon(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                          nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                          nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_neon(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                             nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                             nk_size_t row_start, nk_size_t row_count);
+#endif // NK_TARGET_NEON
+
+/*  WASM Relaxed SIMD backends using wasm_i8x16_popcnt for popcount-based set distances.
+ */
+#if NK_TARGET_V128RELAXED
+/** @copydoc nk_hammings_packed_u1 */
+NK_PUBLIC void nk_hammings_packed_u1_v128relaxed(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result,
+                                                 nk_size_t rows, nk_size_t cols, nk_size_t d,
+                                                 nk_size_t v_stride_in_bytes, nk_size_t r_stride_in_bytes);
+/** @copydoc nk_hammings_symmetric_u1 */
+NK_PUBLIC void nk_hammings_symmetric_u1_v128relaxed(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                    nk_size_t stride, nk_u32_t *result, nk_size_t result_stride,
+                                                    nk_size_t row_start, nk_size_t row_count);
+/** @copydoc nk_jaccards_packed_u1 */
+NK_PUBLIC void nk_jaccards_packed_u1_v128relaxed(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result,
+                                                 nk_size_t rows, nk_size_t cols, nk_size_t d,
+                                                 nk_size_t v_stride_in_bytes, nk_size_t r_stride_in_bytes);
+/** @copydoc nk_jaccards_symmetric_u1 */
+NK_PUBLIC void nk_jaccards_symmetric_u1_v128relaxed(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d,
+                                                    nk_size_t stride, nk_f32_t *result, nk_size_t result_stride,
+                                                    nk_size_t row_start, nk_size_t row_count);
+#endif // NK_TARGET_V128RELAXED
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#include "numkong/sets/serial.h"
+#include "numkong/sets/neon.h"
+#include "numkong/sets/icelake.h"
+#include "numkong/sets/haswell.h"
+#include "numkong/sets/smebi32.h"
+#include "numkong/sets/v128relaxed.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if !NK_DYNAMIC_DISPATCH
+
+NK_PUBLIC void nk_hammings_packed_u1(nk_u1x8_t const *v, void const *q_packed, nk_u32_t *result, nk_size_t rows,
+                                     nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                     nk_size_t r_stride_in_bytes) {
+#if NK_TARGET_SMEBI32
+    nk_hammings_packed_u1_smebi32(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_NEON
+    nk_hammings_packed_u1_neon(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_ICELAKE
+    nk_hammings_packed_u1_icelake(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_HASWELL
+    nk_hammings_packed_u1_haswell(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_V128RELAXED
+    nk_hammings_packed_u1_v128relaxed(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#else
+    nk_hammings_packed_u1_serial(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#endif
+}
+
+NK_PUBLIC void nk_hammings_symmetric_u1(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d, nk_size_t stride,
+                                        nk_u32_t *result, nk_size_t result_stride, nk_size_t row_start,
+                                        nk_size_t row_count) {
+#if NK_TARGET_SMEBI32
+    nk_hammings_symmetric_u1_smebi32(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_NEON
+    nk_hammings_symmetric_u1_neon(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_ICELAKE
+    nk_hammings_symmetric_u1_icelake(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_HASWELL
+    nk_hammings_symmetric_u1_haswell(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_V128RELAXED
+    nk_hammings_symmetric_u1_v128relaxed(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#else
+    nk_hammings_symmetric_u1_serial(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#endif
+}
+
+NK_PUBLIC void nk_jaccards_packed_u1(nk_u1x8_t const *v, void const *q_packed, nk_f32_t *result, nk_size_t rows,
+                                     nk_size_t cols, nk_size_t d, nk_size_t v_stride_in_bytes,
+                                     nk_size_t r_stride_in_bytes) {
+#if NK_TARGET_SMEBI32
+    nk_jaccards_packed_u1_smebi32(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_NEON
+    nk_jaccards_packed_u1_neon(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_ICELAKE
+    nk_jaccards_packed_u1_icelake(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_HASWELL
+    nk_jaccards_packed_u1_haswell(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#elif NK_TARGET_V128RELAXED
+    nk_jaccards_packed_u1_v128relaxed(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#else
+    nk_jaccards_packed_u1_serial(v, q_packed, result, rows, cols, d, v_stride_in_bytes, r_stride_in_bytes);
+#endif
+}
+
+NK_PUBLIC void nk_jaccards_symmetric_u1(nk_u1x8_t const *vectors, nk_size_t n_vectors, nk_size_t d, nk_size_t stride,
+                                        nk_f32_t *result, nk_size_t result_stride, nk_size_t row_start,
+                                        nk_size_t row_count) {
+#if NK_TARGET_SMEBI32
+    nk_jaccards_symmetric_u1_smebi32(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_NEON
+    nk_jaccards_symmetric_u1_neon(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_ICELAKE
+    nk_jaccards_symmetric_u1_icelake(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_HASWELL
+    nk_jaccards_symmetric_u1_haswell(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#elif NK_TARGET_V128RELAXED
+    nk_jaccards_symmetric_u1_v128relaxed(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#else
+    nk_jaccards_symmetric_u1_serial(vectors, n_vectors, d, stride, result, result_stride, row_start, row_count);
+#endif
+}
+
+#endif // !NK_DYNAMIC_DISPATCH
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_SETS_H

package/include/numkong/sparse/README.md

@@ -0,0 +1,156 @@
+# Sparse Vector Operations in NumKong
+
+NumKong implements set intersection and weighted dot products for sparse vectors stored as sorted arrays of unique indices with optional associated weights.
+Set intersection counts common elements between two sorted index arrays; sparse dot product sums the products of weights at matching indices.
+Used in inverted-index search, sparse feature matching, and graph intersection queries.
+The separate index/weight stream design makes these primitives composable into batched sparse operations and future sparse GEMM workloads.
+
+Set intersection:
+
+```math
+|A \cap B| = |\{i : i \in A \land i \in B\}|
+```
+
+Sparse dot product:
+
+```math
+\text{dot}(a, b) = \sum_{i \in A \cap B} w_a(i) \cdot w_b(i)
+```
+
+Reformulating as Python pseudocode:
+
+```python
+import numpy as np
+
+def intersect(a_indices: np.ndarray, b_indices: np.ndarray) -> int:
+    return len(np.intersect1d(a_indices, b_indices))
+
+def sparse_dot(a_indices: np.ndarray, a_weights: np.ndarray,
+               b_indices: np.ndarray, b_weights: np.ndarray) -> float:
+    common = np.intersect1d(a_indices, b_indices, return_indices=True)
+    return np.dot(a_weights[common[1]], b_weights[common[2]])
+```
+
+## Input & Output Types
+
+| Input Type | Output Type | Description                                  |
+| ---------- | ----------- | -------------------------------------------- |
+| `u16`      | `u64`       | 16-bit index intersection count              |
+| `u32`      | `u64`       | 32-bit index intersection count              |
+| `u64`      | `u64`       | 64-bit index intersection count              |
+| `u32+f32`  | `f32`       | Sparse dot with 32-bit indices, f32 weights  |
+| `u16+bf16` | `f32`       | Sparse dot with 16-bit indices, bf16 weights |
+
+## Optimizations
+
+### Adaptive Merge vs Galloping Search
+
+`nk_sparse_intersect_u32_serial` selects between linear merge and galloping (exponential) search based on length ratio: when `longer_length > 64 * shorter_length`, galloping search over the longer array is used.
+Linear merge advances two pointers in lockstep at $O(|A| + |B|)$ using branch-free conditional increments: `i += ai < bj; j += ai >= bj` — no branch misprediction penalty.
+Galloping binary-searches the longer array for each element of the shorter at $O(|A| \cdot \log |B|)$: an exponential probe doubles the search range until the target is bracketed, then binary search narrows within.
+The crossover at 64x length ratio balances the per-element cost of binary search ($\log_2 |B|$ comparisons) against linear scan's single comparison per advance — the threshold was chosen empirically, as cache locality favors linear merge at moderate ratios.
+
+### Broadcast-Compare SIMD Intersection on x86
+
+`nk_sparse_intersect_u32_icelake` loads 16 indices from each array into ZMM registers, then rotates one register through multiple positions, comparing each rotation against the other with `VPCMPEQD` to test all 16x16 = 256 pairs.
+The rotation approach uses `_mm512_shuffle_epi32` with permutation constants (`_MM_PERM_ADCB`, etc.) to cycle elements through comparison positions — contending for port 5 (~1cy per shuffle, ~3cy for `_mm512_alignr_epi32`).
+Match counts are extracted via `_mm_popcnt_u32` on the comparison masks, accumulating intersection size without materializing matched elements.
+Before each 16x16 comparison block, a fast overlap check (`a_max < b_min || b_max < a_min`) skips non-overlapping register loads entirely — critical for sparse workloads where most pairs have disjoint index ranges.
+No native `_mm512_2intersect_epi16` instruction exists in any x86 ISA — UInt16 intersection must convert indices to UInt32 before comparison, halving effective throughput.
+
+### VP2INTERSECT on AMD Turin
+
+`nk_sparse_intersect_u32_turin` uses the `VP2INTERSECT` instruction (Zen5), which produces _two_ 16-bit masks in a single operation — one indicating which elements of A matched any element of B, and vice versa.
+This replaces the entire shuffle-rotate-compare sequence from Ice Lake with a single instruction, eliminating port-5 contention entirely.
+Even on Turin, UInt16 intersection requires zero-extending to UInt32 first — no `VP2INTERSECT` variant operates on 16-bit elements.
+For UInt64, `_mm512_2intersect_epi64` processes 8x8 = 64 pairs per instruction — half the throughput of UInt32 but still far faster than the Ice Lake shuffle approach.
+
+### SVE2 Set Membership via svmatch and svhistcnt
+
+`nk_sparse_intersect_u16_sve2` uses the `svmatch_u16` instruction — true hardware set membership testing that matches each element against a 128-bit lane of candidates.
+However, `svmatch` only operates on UInt8 and UInt16 — no UInt32 or UInt64 variant exists in SVE2.
+For UInt32/UInt64, `nk_sparse_intersect_u32_sve2` uses `svhistcnt_u32_z` (histogram count): this computes a prefix-match count for each element against preceding elements in the combined register, and a reverse pass captures the upper triangle — ORing both halves yields the full intersection mask.
+NEON (`nk_sparse_intersect_u32_neon`) lacks compress-store entirely — when intersection results must be materialized (not just counted), the kernel falls back to serial extraction, using `vclz_u32` (count leading zeros) to compute pointer advance steps from comparison masks.
+
+### BFloat16 Weights in Sparse Dot Products
+
+`nk_sparse_dot_u16bf16_sve2` loads BFloat16 weights alongside UInt16 indices, selecting matching weights via `svsel_s16` after intersection detection, then accumulating with `svbfdot_f32` — a single instruction that multiplies BFloat16 pairs and adds to a Float32 accumulator.
+`nk_sparse_dot_u16bf16_turin` zero-extends UInt16 indices to UInt32 for `VP2INTERSECT`, then compresses matching BFloat16 weights with `VPCOMPRESSW` and accumulates via `_mm256_dpbf16_ps` (6cy latency on Genoa).
+BFloat16 weights halve memory traffic compared to Float32 (16-bit vs 32-bit per weight) while preserving sufficient precision for learned sparse attention weights and embedding lookups.
+The index/weight stream separation enables type-independent intersection (UInt16/UInt32/UInt64 indices) with type-specific accumulation (BFloat16 or Float32 weights) — the same intersection code path serves both weight types.
+
+### Implications for Sparse GEMM
+
+Current sparse operations handle inner-product dot products — one pair of sparse vectors at a time.
+Extending to batched sparse GEMM (SpMM, SpGEMM) would require simultaneous intersection of multiple sparse vectors — the broadcast-compare pattern scales naturally, since one document vector's indices can be broadcast against multiple query vectors' indices in the same ZMM/SVE registers.
+The 64x galloping threshold is tuned for individual vector pairs; batched workloads with different sparsity patterns per row would benefit from adaptive per-pair threshold selection.
+Hardware support remains the bottleneck: no ISA provides native sparse outer-product instructions, and `VP2INTERSECT` exists only on AMD Zen5+ — Intel Tiger Lake's implementation had 36-41cy latency, making it slower than the manual shuffle approach on Ice Lake.
+
+## 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 `NK_SPARSE_FIRST_LENGTH`, `NK_SPARSE_SECOND_LENGTH`, and `NK_SPARSE_INTERSECTION` environment variables.
+Columns show throughput at 1%, 50%, and 95% intersection ratio with both set lengths fixed at 4096.
+The throughput is measured in GB/s as the number of input bytes per second.
+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.
+Accuracy is reported as mean ULP (units in last place) averaged over all test pairs — the average number of representable floating-point values between the computed result and the exact answer.
+
+### Intel Sapphire Rapids
+
+#### Native
+
+| Kernel                            |                       1% |                      50% |                      95% |
+| :-------------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u64__                           | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u64_serial`  |                2.96 gb/s |                3.06 gb/s |                3.27 gb/s |
+| `nk_sparse_intersect_u64_icelake` |                3.64 gb/s |                3.83 gb/s |                3.74 gb/s |
+| __u32__                           | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u32_serial`  |                1.51 gb/s |                1.55 gb/s |                1.69 gb/s |
+| `nk_sparse_intersect_u32_icelake` |                4.15 gb/s |                4.29 gb/s |                4.25 gb/s |
+| __u16__                           | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u16_serial`  |               0.747 gb/s |               0.793 gb/s |               0.824 gb/s |
+| `nk_sparse_intersect_u16_icelake` |                3.06 gb/s |                3.09 gb/s |                3.10 gb/s |
+| __f32__                           | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u32f32_serial`     |       2.78 gb/s, 6.6 ulp |       2.78 gb/s, 5.9 ulp |       2.79 gb/s, 6.4 ulp |
+| `nk_sparse_dot_u32f32_icelake`    |       7.80 gb/s, 3.8 ulp |         6.46 gb/s, 4 ulp |       5.86 gb/s, 3.8 ulp |
+| __bf16__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u16bf16_serial`    |        0.366 gb/s, 0 ulp |        0.364 gb/s, 0 ulp |        0.366 gb/s, 0 ulp |
+
+#### WASM
+
+Measured with Wasmtime v42 (Cranelift backend).
+
+| Kernel                           |                       1% |                      50% |                      95% |
+| :------------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u64__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u64_serial` |                1.74 gb/s |                1.74 gb/s |                1.74 gb/s |
+| __u32__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u32_serial` |               0.492 gb/s |               0.492 gb/s |               0.492 gb/s |
+| __u16__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u16_serial` |               0.309 gb/s |               0.309 gb/s |               0.309 gb/s |
+| __f32__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u32f32_serial`    |       1.87 gb/s, 9.1 ulp |       1.87 gb/s, 9.1 ulp |       1.87 gb/s, 9.1 ulp |
+| __bf16__                         | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u16bf16_serial`   |        0.927 gb/s, 0 ulp |        0.927 gb/s, 0 ulp |        0.927 gb/s, 0 ulp |
+
+### Apple M4
+
+#### Native
+
+| Kernel                           |                       1% |                      50% |                      95% |
+| :------------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __u64__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u64_serial` |                3.74 gb/s |                3.96 gb/s |                4.17 gb/s |
+| `nk_sparse_intersect_u64_neon`   |                4.91 gb/s |                4.61 gb/s |                4.46 gb/s |
+| __u32__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u32_serial` |                1.88 gb/s |                1.98 gb/s |                2.09 gb/s |
+| `nk_sparse_intersect_u32_neon`   |                2.81 gb/s |                2.60 gb/s |                2.46 gb/s |
+| __u16__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_intersect_u16_serial` |               0.951 gb/s |               0.995 gb/s |                1.05 gb/s |
+| `nk_sparse_intersect_u16_neon`   |                1.86 gb/s |                1.85 gb/s |                1.85 gb/s |
+| __f32__                          | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u32f32_serial`    |       3.73 gb/s, 7.1 ulp |       3.74 gb/s, 7.1 ulp |       3.79 gb/s, 7.0 ulp |
+| __bf16__                         | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_sparse_dot_u16bf16_serial`   |         1.73 gb/s, 0 ulp |         1.72 gb/s, 0 ulp |         1.72 gb/s, 0 ulp |