numkong 7.0.0

package/include/numkong/set/v128relaxed.h

@@ -0,0 +1,240 @@
+/**
+ *  @brief SIMD-accelerated Set Similarity Measures for WASM.
+ *  @file include/numkong/set/v128relaxed.h
+ *  @author Ash Vardanian
+ *  @date February 1, 2026
+ *
+ *  This file contains windowed implementations of Hamming and Jaccard distance
+ *  for bit-level operations (u1 packed bits). The windowing optimization reduces
+ *  widening overhead by 96.7%, providing 5-10× speedup over naive implementations.
+ *
+ *  Algorithm: Accumulate popcount results in u8 for 31 iterations, then widen
+ *  to u16 → u32 once. Since max(popcount(u8)) = 8, we can safely accumulate
+ *  31 × 8 = 248 < 255 (u8 max) without overflow.
+ */
+
+#ifndef NK_SET_V128RELAXED_H
+#define NK_SET_V128RELAXED_H
+
+#if NK_TARGET_V128RELAXED
+
+#include "numkong/types.h"
+#include "numkong/reduce/v128relaxed.h"
+#include "numkong/set/serial.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("relaxed-simd"))), apply_to = function)
+#endif
+
+#pragma region - Binary Sets
+
+NK_PUBLIC void nk_hamming_u1_v128relaxed(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result) {
+    nk_u8_t const *a_bytes = (nk_u8_t const *)a;
+    nk_u8_t const *b_bytes = (nk_u8_t const *)b;
+    nk_size_t n_bytes = nk_size_divide_round_up_(n, NK_BITS_PER_BYTE);
+
+    nk_u32_t differences = 0;
+    nk_size_t i = 0;
+
+    // Windowed accumulation loop
+    while (i + 16 <= n_bytes) {
+        v128_t popcount_u8x16 = wasm_i8x16_splat(0);
+
+        // Inner loop: accumulate 31 iterations in u8 before widening
+        nk_size_t cycle = 0;
+        for (; cycle < 31 && i + 16 <= n_bytes; ++cycle, i += 16) {
+            v128_t a_u8x16 = wasm_v128_load(a_bytes + i);
+            v128_t b_u8x16 = wasm_v128_load(b_bytes + i);
+
+            // XOR to find differing bits
+            v128_t xor_u8x16 = wasm_v128_xor(a_u8x16, b_u8x16);
+
+            // Popcount each byte
+            v128_t popcnt_u8x16 = wasm_i8x16_popcnt(xor_u8x16);
+
+            // Accumulate in u8 (safe: 31 × 8 = 248 < 255)
+            popcount_u8x16 = wasm_i8x16_add(popcount_u8x16, popcnt_u8x16);
+        }
+
+        // Widen once per window: u8 → u16 → u32
+        differences += nk_reduce_add_u8x16_v128relaxed_(popcount_u8x16);
+    }
+
+    // Handle tail bytes
+    for (; i < n_bytes; i++) {
+        nk_u8_t xor_byte = a_bytes[i] ^ b_bytes[i];
+        differences += nk_u1x8_popcount_(xor_byte);
+    }
+
+    *result = differences;
+}
+
+NK_PUBLIC void nk_jaccard_u1_v128relaxed(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_u8_t const *a_bytes = (nk_u8_t const *)a;
+    nk_u8_t const *b_bytes = (nk_u8_t const *)b;
+    nk_size_t n_bytes = nk_size_divide_round_up_(n, NK_BITS_PER_BYTE);
+
+    nk_u32_t intersection = 0;
+    nk_u32_t union_count = 0;
+    nk_size_t i = 0;
+
+    // Windowed accumulation loop
+    while (i + 16 <= n_bytes) {
+        v128_t popcount_and_u8x16 = wasm_i8x16_splat(0);
+        v128_t popcount_or_u8x16 = wasm_i8x16_splat(0);
+
+        // Inner loop: accumulate 31 iterations in u8 before widening
+        nk_size_t cycle = 0;
+        for (; cycle < 31 && i + 16 <= n_bytes; ++cycle, i += 16) {
+            v128_t a_u8x16 = wasm_v128_load(a_bytes + i);
+            v128_t b_u8x16 = wasm_v128_load(b_bytes + i);
+
+            // Intersection: a AND b
+            v128_t and_u8x16 = wasm_v128_and(a_u8x16, b_u8x16);
+            v128_t popcnt_and_u8x16 = wasm_i8x16_popcnt(and_u8x16);
+            popcount_and_u8x16 = wasm_i8x16_add(popcount_and_u8x16, popcnt_and_u8x16);
+
+            // Union: a OR b
+            v128_t or_u8x16 = wasm_v128_or(a_u8x16, b_u8x16);
+            v128_t popcnt_or_u8x16 = wasm_i8x16_popcnt(or_u8x16);
+            popcount_or_u8x16 = wasm_i8x16_add(popcount_or_u8x16, popcnt_or_u8x16);
+        }
+
+        // Widen once per window
+        intersection += nk_reduce_add_u8x16_v128relaxed_(popcount_and_u8x16);
+        union_count += nk_reduce_add_u8x16_v128relaxed_(popcount_or_u8x16);
+    }
+
+    // Handle tail bytes
+    for (; i < n_bytes; i++) {
+        nk_u8_t a_byte = a_bytes[i];
+        nk_u8_t b_byte = b_bytes[i];
+        intersection += nk_u1x8_popcount_(a_byte & b_byte);
+        union_count += nk_u1x8_popcount_(a_byte | b_byte);
+    }
+
+    // Jaccard distance = 1 - (intersection / union)
+    *result = union_count > 0 ? 1.0f - ((nk_f32_t)intersection / (nk_f32_t)union_count) : 0.0f;
+}
+
+#pragma endregion - Binary Sets
+
+#pragma region - Integer Sets
+
+NK_PUBLIC void nk_hamming_u8_v128relaxed(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result) {
+    nk_u32_t sum_total = 0;
+    nk_size_t i = 0;
+
+    // Windowed accumulation: outer loop for windows, inner loop for iterations within window
+    while (i + 16 <= n) {
+        v128_t sum_u8x16 = wasm_i8x16_splat(0);
+
+        // Inner loop: accumulate up to 31 iterations in u8 (safe: 31 × 1 = 31 < 255)
+        nk_size_t cycle = 0;
+        for (; cycle < 31 && i + 16 <= n; ++cycle, i += 16) {
+            v128_t a_u8x16 = wasm_v128_load(a + i);
+            v128_t b_u8x16 = wasm_v128_load(b + i);
+
+            // Compare for inequality: 0xFF where different, 0x00 where same
+            v128_t neq_mask_u8x16 = wasm_i8x16_ne(a_u8x16, b_u8x16);
+
+            // Convert mask to count: 0xFF → 1, 0x00 → 0
+            v128_t neq_count_u8x16 = wasm_v128_and(neq_mask_u8x16, wasm_i8x16_splat(1));
+
+            // Accumulate counts
+            sum_u8x16 = wasm_i8x16_add(sum_u8x16, neq_count_u8x16);
+        }
+
+        // Widen and reduce once per window
+        sum_total += nk_reduce_add_u8x16_v128relaxed_(sum_u8x16);
+    }
+
+    // Traditional tail loop: handle remaining bytes (0-15) scalar-style
+    for (; i < n; i++) { sum_total += (a[i] != b[i]); }
+
+    *result = sum_total;
+}
+
+NK_PUBLIC void nk_jaccard_u32_v128relaxed(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_u32_t matches = 0;
+    nk_size_t i = 0;
+    v128_t matches_u32x4 = wasm_i32x4_splat(0);
+
+    for (; i + 4 <= n; i += 4) {
+        v128_t a_u32x4 = wasm_v128_load(a + i);
+        v128_t b_u32x4 = wasm_v128_load(b + i);
+        v128_t eq_mask_u32x4 = wasm_i32x4_eq(a_u32x4, b_u32x4);
+        v128_t match_bits_u32x4 = wasm_u32x4_shr(eq_mask_u32x4, 31);
+        matches_u32x4 = wasm_i32x4_add(matches_u32x4, match_bits_u32x4);
+    }
+
+    matches += nk_reduce_add_u32x4_v128relaxed_(matches_u32x4);
+    for (; i < n; ++i) matches += (a[i] == b[i]);
+
+    *result = (n != 0) ? 1.0f - (nk_f32_t)matches / (nk_f32_t)n : 0.0f;
+}
+
+NK_PUBLIC void nk_jaccard_u16_v128relaxed(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_u32_t matches = 0;
+    nk_size_t i = 0;
+    v128_t matches_u32x4 = wasm_i32x4_splat(0);
+
+    for (; i + 8 <= n; i += 8) {
+        v128_t a_u16x8 = wasm_v128_load(a + i);
+        v128_t b_u16x8 = wasm_v128_load(b + i);
+        v128_t eq_mask_u16x8 = wasm_i16x8_eq(a_u16x8, b_u16x8);
+        v128_t match_bits_u16x8 = wasm_u16x8_shr(eq_mask_u16x8, 15);
+        matches_u32x4 = wasm_i32x4_add(matches_u32x4, wasm_u32x4_extadd_pairwise_u16x8(match_bits_u16x8));
+    }
+
+    matches += nk_reduce_add_u32x4_v128relaxed_(matches_u32x4);
+    for (; i < n; ++i) matches += (a[i] == b[i]);
+
+    *result = (n != 0) ? 1.0f - (nk_f32_t)matches / (nk_f32_t)n : 0.0f;
+}
+
+#pragma endregion - Integer Sets
+
+#pragma region - Binary Sets from Dot
+
+NK_INTERNAL void nk_hamming_u32x4_from_dot_v128relaxed_( //
+    nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
+    v128_t dots_u32x4 = dots.v128;
+    v128_t query_u32x4 = wasm_u32x4_splat(query_pop);
+    v128_t target_u32x4 = target_pops.v128;
+    results->v128 = wasm_i32x4_sub(wasm_i32x4_add(query_u32x4, target_u32x4), wasm_i32x4_shl(dots_u32x4, 1));
+}
+
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_v128relaxed_( //
+    nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
+    v128_t dot_f32x4 = wasm_f32x4_convert_u32x4(dots.v128);
+    v128_t query_f32x4 = wasm_f32x4_splat((nk_f32_t)query_pop);
+    v128_t target_f32x4 = wasm_f32x4_convert_u32x4(target_pops.v128);
+    v128_t union_f32x4 = wasm_f32x4_sub(wasm_f32x4_add(query_f32x4, target_f32x4), dot_f32x4);
+
+    v128_t zero_f32x4 = wasm_f32x4_splat(0.0f);
+    v128_t one_f32x4 = wasm_f32x4_splat(1.0f);
+    v128_t zero_mask_u32x4 = wasm_f32x4_eq(union_f32x4, zero_f32x4);
+    v128_t safe_union_f32x4 = wasm_i32x4_relaxed_laneselect(one_f32x4, union_f32x4, zero_mask_u32x4);
+
+    v128_t ratio_f32x4 = wasm_f32x4_div(dot_f32x4, safe_union_f32x4);
+    v128_t jaccard_f32x4 = wasm_f32x4_sub(one_f32x4, ratio_f32x4);
+    results->v128 = wasm_i32x4_relaxed_laneselect(zero_f32x4, jaccard_f32x4, zero_mask_u32x4);
+}
+
+#pragma endregion - Binary Sets from Dot
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_V128RELAXED
+#endif // NK_SET_V128RELAXED_H

package/include/numkong/set.h

@@ -0,0 +1,457 @@
+/**
+ *  @brief SIMD-accelerated Set Similarity Measures.
+ *  @file include/numkong/set.h
+ *  @author Ash Vardanian
+ *  @date July 1, 2023
+ *
+ *  Contains following similarity measures:
+ *
+ *  - Bit-level Hamming distance → `u32` counter
+ *  - Byte-level Hamming distance → `u32` counter
+ *  - Bit-level Jaccard distance (Tanimoto coefficient) → `f32` ratio
+ *  - Word-level Jaccard distance for `u16` and `u32` MinHash vectors from StringZilla → `f32` ratio
+ *
+ *  For hardware architectures:
+ *
+ *  - Arm: NEON, SVE
+ *  - x86: Haswell, Ice Lake
+ *  - RISC-V: RVV, RVV+BB
+ *  - WASM: V128Relaxed
+ *
+ *  @section numerical_stability Numerical Stability
+ *
+ *  Hamming u1: u32 popcount accumulator. Overflows at n_bits > 2^32 (~4.3 billion).
+ *  The streaming u1x512 variant uses u64, safe for any practical dimension.
+ *  Jaccard u1: u32 intersection/union counts, f32 division at finalization.
+ *  Popcount values above 2^24 lose precision in f32 cast (24-bit mantissa).
+ *  Byte-level Hamming/Jaccard u8: u32 mismatch counter. Overflows at n > 2^32.
+ *
+ *  @section popcount_strategies Population Count Strategies
+ *
+ *  Jaccard distances are extremely common and also fairly cheap to compute on binary vectors.
+ *  The hardest part of optimizing binary similarity measures is the population count operation.
+ *  It's natively supported by almost every instruction set, but the throughput and latency can
+ *  be suboptimal. There are several ways to optimize this operation:
+ *
+ *  - Lookup tables, mostly using nibbles (4-bit lookups)
+ *  - Harley-Seal population counts using Carry-Save Adders (CSA)
+ *
+ *  @section x86_instructions Relevant x86 Instructions
+ *
+ *  On binary vectors, when computing Jaccard distance, the CPU often struggles to compute the
+ *  large number of required population counts. There are several instructions we should keep in mind:
+ *
+ *      Intrinsic                   Instruction                     Ice         Genoa
+ *      _mm512_popcnt_epi64         VPOPCNTQ (ZMM, K, ZMM)          3cy @ p5     2cy @ p01
+ *      _mm512_shuffle_epi8         VPSHUFB (ZMM, ZMM, ZMM)         1cy @ p5     2cy @ p12
+ *      _mm512_sad_epu8             VPSADBW (ZMM, ZMM, ZMM)         3cy @ p5     3cy @ p01
+ *      _mm512_ternarylogic_epi64   VPTERNLOGQ (ZMM, ZMM, ZMM, I8)  1cy @ p05    1cy @ p0123
+ *      _mm512_gf2p8mul_epi8        VGF2P8MULB (ZMM, ZMM, ZMM)      5cy @ p0     3cy @ p01
+ *
+ *  On Ice Lake, VPOPCNTQ bottlenecks on port 5. On AMD Genoa/Turin, it dual-issues
+ *  on ports 0-1, making native popcount significantly faster without CSA tricks.
+ *
+ *  @section harley_seal Harley-Seal Carry-Save Adders
+ *
+ *  The Harley-Seal algorithm uses Carry-Save Adders (CSA) to accumulate population counts
+ *  with fewer VPOPCNTQ instructions. A CSA computes (a + b + c) as (sum, carry) using only
+ *  bitwise operations, deferring expensive popcounts to the final reduction.
+ *
+ *  Performance varies significantly by architecture and buffer size (cycles/byte):
+ *
+ *      Method              Buffer      Ice Lake    Sapphire    Genoa
+ *      Native VPOPCNTQ     any         ~0.12       ~0.10       ~0.06
+ *      Harley-Seal CSA     1 KB        0.107       0.095       0.08
+ *      Harley-Seal CSA     4 KB        0.056       0.052       0.05
+ *      VPSHUFB lookup      4 KB        0.063       0.058       0.07
+ *
+ *  For small buffers (<1KB), loop overhead dominates and unrolled native VPOPCNTQ wins.
+ *  Harley-Seal shines on large buffers where CSA chains amortize the setup cost.
+ *  On AMD Genoa, native VPOPCNTQ is competitive even for large buffers.
+ *
+ *  @section jaccard_norms Jaccard Optimization via Norms
+ *
+ *  There is a trivial optimization to halve the number of population counts needed for
+ *  binary Jaccard distance, if one knows the set magnitudes ahead of time:
+ *
+ *      J = |A ∩ B| / |A ∪ B| = |A ∩ B| / (|A| + |B| - |A ∩ B|)
+ *
+ *  At that point the problem reduces to optimizing memory accesses and register usage.
+ *  For such cases, we provide additional function variants designed exclusively for compile-time
+ *  dispatch in heavily inlined code, operating on wider vectors with known sizes:
+ *
+ *  - nk_jaccard_u1x512_state_<isa>_t - Smallest optimal running state
+ *  - nk_jaccard_u1x512_init_<isa> - Initializes the running state
+ *  - nk_jaccard_u1x512_update_<isa> - Updates the running state with 2 new 512-bit vectors
+ *  - nk_jaccard_u1x512_finalize_<isa> - Finalizes the running state and produces the distance
+ *
+ *  @section streaming_api Streaming API
+ *
+ *  The streaming variants aren't always strictly equivalent to their counterparts above
+ *  and their usage also differs quite drastically. For large-scale batch processing where
+ *  vectors won't be reused, consider non-temporal loads (`_mm512_stream_load_si512`) to
+ *  bypass the cache and avoid pollution. This is especially beneficial when computing
+ *  distances across millions of vectors in a single pass.
+ *
+ *  @code{.c}
+ *  // 1024-dimensional binary vectors, one query and four targets
+ *  nk_u1x8_t query[128], target_first[128], target_second[128], target_third[128], target_fourth[128];
+ *  // Precomputed popcount of 'a' as f32
+ *  nk_f32_t query_popcount = ...;
+ *  nk_f32_t target_popcount_first = ..., target_popcount_second = ...;
+ *
+ *  nk_jaccard_u1x512_state_icelake_t state_first, state_second, state_third, state_fourth;
+ *  nk_jaccard_u1x512_init_icelake(&state_first);
+ *  nk_jaccard_u1x512_init_icelake(&state_second);
+ *  nk_jaccard_u1x512_init_icelake(&state_third);
+ *  nk_jaccard_u1x512_init_icelake(&state_fourth);
+ *  nk_jaccard_u1x512_update_icelake(&state_first, &query[0], &target_first[0], 0, 512); // First 512 bits
+ *  nk_jaccard_u1x512_update_icelake(&state_first, &query[64], &target_first[64], 512, 512); // Second 512 bits
+ *  // ... update state_second, state_third, state_fourth similarly ...
+ *
+ *  nk_f32_t results[4];
+ *  nk_jaccard_u1x512_finalize_icelake(&state_first, &state_second, &state_third, &state_fourth,
+ *      query_popcount, target_popcount_first, target_popcount_second,
+ *      target_popcount_third, target_popcount_fourth, total_dimensions, results);
+ *  @endcode
+ *
+ *  @section tail_handling Tail Handling
+ *
+ *  The trickiest part is handling the tails of the vectors when their size isn't divisible
+ *  by our step size. In such cases, it's recommended to use masked loads when supported by
+ *  the ISA, or fall back to scalar code and a local on-stack buffer.
+ *
+ *  @section references References
+ *
+ *  - Intel Intrinsics Guide: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/
+ *  - Arm Intrinsics Reference: https://developer.arm.com/architectures/instruction-sets/intrinsics/
+ *  - Muła et al. "Faster Population Counts": https://arxiv.org/pdf/1611.07612
+ *  - Muła SSE POPCOUNT experiments: https://github.com/WojciechMula/sse-popcount
+ *  - NumKong binary R&D tracker: https://github.com/ashvardanian/NumKong/pull/138
+ *
+ *  @section Finalize Output Types
+ *
+ *  Jaccard similarity finalize outputs to f32:
+ *  - Jaccard = intersection / union, always ∈ [0.0, 1.0]
+ *  - f32 provides ~7 decimal digits, far exceeding practical needs
+ *  - Matches spatial.h convention for non-f64 distance outputs
+ *  - Reduces memory footprint in large-scale binary similarity search
+ *
+ *  The intersection and union counts are u64 internally for correctness,
+ *  but the final ratio fits comfortably in f32.
+ *
+ */
+#ifndef NK_SET_H
+#define NK_SET_H
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/**
+ *  @brief Binary Hamming distance computing the number of differing bits between two binary vectors.
+ *
+ *  @param[in] a The first binary vector.
+ *  @param[in] b The second binary vector.
+ *  @param[in] n The number of bits in the vectors.
+ *  @param[out] result The output distance value.
+ *
+ *  @note The output distance value is non-negative.
+ *  @note The output distance value is zero if and only if the two vectors are identical.
+ */
+NK_DYNAMIC void nk_hamming_u1(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+
+/**
+ *  @brief Binary Jaccard distance computing the ratio of differing bits to the union of bits.
+ *
+ *  @param[in] a The first binary vector.
+ *  @param[in] b The second binary vector.
+ *  @param[in] n The number of bits in the vectors.
+ *  @param[out] result The output distance value.
+ *
+ *  @note The output distance value is non-negative.
+ *  @note The output distance value is zero if and only if the two vectors are identical.
+ */
+NK_DYNAMIC void nk_jaccard_u1(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+
+/**
+ *  @brief Integral Jaccard distance computing the ratio of differing bits to the union of bits.
+ *
+ *  @param[in] a The first binary vector.
+ *  @param[in] b The second binary vector.
+ *  @param[in] n The number of 32-bit scalars in the vectors.
+ *  @param[out] result The output distance value.
+ *
+ *  @note The output distance value is non-negative.
+ *  @note The output distance value is zero if and only if the two vectors are identical.
+ */
+NK_DYNAMIC void nk_jaccard_u32(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+
+/**
+ *  @brief Byte-level Hamming distance computing the number of differing bytes between two vectors.
+ *
+ *  @param[in] a The first byte vector.
+ *  @param[in] b The second byte vector.
+ *  @param[in] n The number of bytes in the vectors.
+ *  @param[out] result The output distance value.
+ *
+ *  @note The output distance value is non-negative.
+ *  @note The output distance value is zero if and only if the two vectors are identical.
+ */
+NK_DYNAMIC void nk_hamming_u8(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+
+/**
+ *  @brief Integral Jaccard distance for 16-bit unsigned integer vectors.
+ *
+ *  @param[in] a The first vector.
+ *  @param[in] b The second vector.
+ *  @param[in] n The number of 16-bit scalars in the vectors.
+ *  @param[out] result The output distance value.
+ *
+ *  @note The output distance value is non-negative.
+ *  @note The output distance value is zero if and only if the two vectors are identical.
+ */
+NK_DYNAMIC void nk_jaccard_u16(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_serial(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_serial(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_serial(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_serial(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_serial(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+
+#if NK_TARGET_NEON
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_neon(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_neon(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_neon(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_neon(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_neon(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+
+#endif // NK_TARGET_NEON
+
+#if NK_TARGET_SVE
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_sve(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_sve(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_sve(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_sve(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_sve(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+#endif // NK_TARGET_SVE
+
+#if NK_TARGET_HASWELL
+/** @copydoc nk_hamming_u1 */
+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);
+/** @copydoc nk_hamming_u8 */
+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);
+/** @copydoc nk_jaccard_u1 */
+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);
+/** @copydoc nk_jaccard_u16 */
+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);
+/** @copydoc nk_jaccard_u32 */
+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);
+#endif // NK_TARGET_HASWELL
+
+#if NK_TARGET_ICELAKE
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_icelake(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_icelake(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_icelake(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_icelake(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_icelake(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+#endif // NK_TARGET_ICELAKE
+
+#if NK_TARGET_RVVBB
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_rvvbb(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_rvvbb(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+#endif // NK_TARGET_RVVBB
+
+#if NK_TARGET_RVV
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_rvv(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_rvv(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_rvv(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_rvv(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_rvv(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+#endif // NK_TARGET_RVV
+
+#if NK_TARGET_V128RELAXED
+/** @copydoc nk_hamming_u1 */
+NK_PUBLIC void nk_hamming_u1_v128relaxed(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_hamming_u8 */
+NK_PUBLIC void nk_hamming_u8_v128relaxed(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result);
+/** @copydoc nk_jaccard_u1 */
+NK_PUBLIC void nk_jaccard_u1_v128relaxed(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u16 */
+NK_PUBLIC void nk_jaccard_u16_v128relaxed(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result);
+/** @copydoc nk_jaccard_u32 */
+NK_PUBLIC void nk_jaccard_u32_v128relaxed(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result);
+#endif // NK_TARGET_V128RELAXED
+
+/**
+ *  @brief  Returns the output dtype for Hamming distance.
+ */
+NK_INTERNAL nk_dtype_t nk_hamming_output_dtype(nk_dtype_t dtype) {
+    switch (dtype) {
+    case nk_u1_k: return nk_u32_k;
+    case nk_u8_k: return nk_u32_k;
+    default: return nk_dtype_unknown_k;
+    }
+}
+
+/**
+ *  @brief  Returns the output dtype for Jaccard distance.
+ */
+NK_INTERNAL nk_dtype_t nk_jaccard_output_dtype(nk_dtype_t dtype) {
+    switch (dtype) {
+    case nk_u1_k: return nk_f32_k;
+    case nk_u16_k: return nk_f32_k;
+    case nk_u32_k: return nk_f32_k;
+    default: return nk_dtype_unknown_k;
+    }
+}
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#include "numkong/set/serial.h"
+#include "numkong/set/neon.h"
+#include "numkong/set/sve.h"
+#include "numkong/set/icelake.h"
+#include "numkong/set/haswell.h"
+#include "numkong/set/v128relaxed.h"
+#include "numkong/set/rvv.h"
+#include "numkong/set/rvvbb.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if !NK_DYNAMIC_DISPATCH
+
+NK_PUBLIC void nk_hamming_u1(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_u32_t *result) {
+#if NK_TARGET_V128RELAXED
+    nk_hamming_u1_v128relaxed(a, b, n, result);
+#elif NK_TARGET_SVE
+    nk_hamming_u1_sve(a, b, n, result);
+#elif NK_TARGET_NEON
+    nk_hamming_u1_neon(a, b, n, result);
+#elif NK_TARGET_ICELAKE
+    nk_hamming_u1_icelake(a, b, n, result);
+#elif NK_TARGET_HASWELL
+    nk_hamming_u1_haswell(a, b, n, result);
+#elif NK_TARGET_RVVBB
+    nk_hamming_u1_rvvbb(a, b, n, result);
+#elif NK_TARGET_RVV
+    nk_hamming_u1_rvv(a, b, n, result);
+#else
+    nk_hamming_u1_serial(a, b, n, result);
+#endif
+}
+
+NK_PUBLIC void nk_jaccard_u1(nk_u1x8_t const *a, nk_u1x8_t const *b, nk_size_t n, nk_f32_t *result) {
+#if NK_TARGET_V128RELAXED
+    nk_jaccard_u1_v128relaxed(a, b, n, result);
+#elif NK_TARGET_SVE
+    nk_jaccard_u1_sve(a, b, n, result);
+#elif NK_TARGET_NEON
+    nk_jaccard_u1_neon(a, b, n, result);
+#elif NK_TARGET_ICELAKE
+    nk_jaccard_u1_icelake(a, b, n, result);
+#elif NK_TARGET_HASWELL
+    nk_jaccard_u1_haswell(a, b, n, result);
+#elif NK_TARGET_RVVBB
+    nk_jaccard_u1_rvvbb(a, b, n, result);
+#elif NK_TARGET_RVV
+    nk_jaccard_u1_rvv(a, b, n, result);
+#else
+    nk_jaccard_u1_serial(a, b, n, result);
+#endif
+}
+
+NK_PUBLIC void nk_jaccard_u32(nk_u32_t const *a, nk_u32_t const *b, nk_size_t n, nk_f32_t *result) {
+#if NK_TARGET_V128RELAXED
+    nk_jaccard_u32_v128relaxed(a, b, n, result);
+#elif NK_TARGET_SVE
+    nk_jaccard_u32_sve(a, b, n, result);
+#elif NK_TARGET_NEON
+    nk_jaccard_u32_neon(a, b, n, result);
+#elif NK_TARGET_ICELAKE
+    nk_jaccard_u32_icelake(a, b, n, result);
+#elif NK_TARGET_HASWELL
+    nk_jaccard_u32_haswell(a, b, n, result);
+#elif NK_TARGET_RVV
+    nk_jaccard_u32_rvv(a, b, n, result);
+#else
+    nk_jaccard_u32_serial(a, b, n, result);
+#endif
+}
+
+NK_PUBLIC void nk_hamming_u8(nk_u8_t const *a, nk_u8_t const *b, nk_size_t n, nk_u32_t *result) {
+#if NK_TARGET_V128RELAXED
+    nk_hamming_u8_v128relaxed(a, b, n, result);
+#elif NK_TARGET_SVE
+    nk_hamming_u8_sve(a, b, n, result);
+#elif NK_TARGET_NEON
+    nk_hamming_u8_neon(a, b, n, result);
+#elif NK_TARGET_ICELAKE
+    nk_hamming_u8_icelake(a, b, n, result);
+#elif NK_TARGET_HASWELL
+    nk_hamming_u8_haswell(a, b, n, result);
+#elif NK_TARGET_RVV
+    nk_hamming_u8_rvv(a, b, n, result);
+#else
+    nk_hamming_u8_serial(a, b, n, result);
+#endif
+}
+
+NK_PUBLIC void nk_jaccard_u16(nk_u16_t const *a, nk_u16_t const *b, nk_size_t n, nk_f32_t *result) {
+#if NK_TARGET_V128RELAXED
+    nk_jaccard_u16_v128relaxed(a, b, n, result);
+#elif NK_TARGET_SVE
+    nk_jaccard_u16_sve(a, b, n, result);
+#elif NK_TARGET_NEON
+    nk_jaccard_u16_neon(a, b, n, result);
+#elif NK_TARGET_ICELAKE
+    nk_jaccard_u16_icelake(a, b, n, result);
+#elif NK_TARGET_HASWELL
+    nk_jaccard_u16_haswell(a, b, n, result);
+#elif NK_TARGET_RVV
+    nk_jaccard_u16_rvv(a, b, n, result);
+#else
+    nk_jaccard_u16_serial(a, b, n, result);
+#endif
+}
+
+#endif // !NK_DYNAMIC_DISPATCH
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif