usearch 2.26.1 → 2.26.3

package/numkong/include/numkong/reduce/skylake.h

@@ -953,7 +953,7 @@ NK_PUBLIC void nk_reduce_moments_f64_skylake(                          //
 NK_INTERNAL void nk_reduce_moments_i8_skylake_contiguous_( //
     nk_i8_t const *data_ptr, nk_size_t count,              //
     nk_i64_t *sum_ptr, nk_u64_t *sumsq_ptr) {
-    // Sum: VPSADBW with XOR bias (same as nk_reduce_add_i8_skylake_contiguous_).
+    // Sum: VPSADBW with XOR bias.
     // Sumsq: widen i8→i16, VPMADDWD(x,x) → i32 (pairs of squares), accumulate i32.
     // i32 overflow safe: max per lane = (128² + 128²) * 65536 iters ≈ 2.1B = safe limit.
     // The dispatch recurses at (NK_U16_MAX+1)*64 elements → at most 65536 iterations here.
@@ -1147,7 +1147,7 @@ NK_PUBLIC void nk_reduce_minmax_i8_skylake(                           //
 NK_INTERNAL void nk_reduce_moments_u8_skylake_contiguous_( //
     nk_u8_t const *data_ptr, nk_size_t count,              //
     nk_u64_t *sum_ptr, nk_u64_t *sumsq_ptr) {
-    // Sum: VPSADBW directly (same as nk_reduce_add_u8_skylake_contiguous_).
+    // Sum: VPSADBW directly.
     // Sumsq: widen u8→i16, VPMADDWD(x,x) → i32 (pairs of squares), accumulate i32.
     // i32 overflow safe: max per lane = (255² + 255²) * 1024 iters ≈ 133M < 2.1B.
     __m512i zero_u8x64 = _mm512_setzero_si512();
@@ -1697,7 +1697,7 @@ NK_PUBLIC void nk_reduce_minmax_u16_skylake(                           //
                                     max_index_ptr);
 }
 
-/** @brief Unsigned saturating add of two i64x8 vectors (3 uops). */
+/** @brief Unsigned saturating add of two u64x8 vectors (3 uops). */
 NK_INTERNAL __m512i nk_u64_sadd_epi64_skylake_(__m512i a, __m512i b) {
     __m512i result_u64x8 = _mm512_add_epi64(a, b);
     __mmask8 ovf = _mm512_cmp_epu64_mask(result_u64x8, a, _MM_CMPINT_LT);
@@ -3371,7 +3371,7 @@ NK_PUBLIC void nk_reduce_moments_u4_skylake(                            //
 NK_INTERNAL void nk_reduce_moments_u1_skylake_contiguous_( //
     nk_u1x8_t const *data_ptr, nk_size_t count,            //
     nk_u64_t *sum_ptr, nk_u64_t *sumsq_ptr) {
-    // Sum = popcount via 4-bit LUT (same as nk_reduce_add_u1_skylake). Sumsq = sum for bits.
+    // Sum = popcount via 4-bit LUT. Sumsq = sum for bits.
     __m512i lut_i8x64 = _mm512_set_epi8(                //
         4, 3, 3, 2, 3, 2, 2, 1, 3, 2, 2, 1, 2, 1, 1, 0, //
         4, 3, 3, 2, 3, 2, 2, 1, 3, 2, 2, 1, 2, 1, 1, 0, //

package/numkong/include/numkong/reduce.hpp

@@ -629,6 +629,44 @@ std::size_t argmax(vector_view<value_type_> input) noexcept {
     return minmax(input).max_index;
 }
 
+/** @brief Population count of a packed bit tensor — number of set bits.
+ *  Wraps `nk_reduce_moments_u1` via `sum`; returns 0 for empty inputs. */
+template <std::size_t max_rank_ = 8>
+u64_t popcount(tensor_view<u1x8_t, max_rank_> input) noexcept {
+    return sum<u1x8_t, max_rank_>(input);
+}
+
+/** @brief True if any bit of the packed bit tensor is set. Suffixed `_set` to
+ *  avoid colliding with the `all_t`/`all` slice marker in `vector.hpp`. */
+template <std::size_t max_rank_ = 8>
+bool any_set(tensor_view<u1x8_t, max_rank_> input) noexcept {
+    return popcount<max_rank_>(input).raw_ != 0;
+}
+
+/** @brief True if no bit of the packed bit tensor is set. */
+template <std::size_t max_rank_ = 8>
+bool none_set(tensor_view<u1x8_t, max_rank_> input) noexcept {
+    return !any_set<max_rank_>(input);
+}
+
+/** @brief True if every bit of the packed bit tensor is set. */
+template <std::size_t max_rank_ = 8>
+bool all_set(tensor_view<u1x8_t, max_rank_> input) noexcept {
+    return popcount<max_rank_>(input).raw_ == input.numel();
+}
+
+/** @brief Population count over a 1D bit-vector view. */
+inline u64_t popcount(vector_view<u1x8_t> input) noexcept { return sum<u1x8_t>(input); }
+
+/** @brief True if any bit of the 1D bit-vector view is set. */
+inline bool any_set(vector_view<u1x8_t> input) noexcept { return popcount(input).raw_ != 0; }
+
+/** @brief True if no bit of the 1D bit-vector view is set. */
+inline bool none_set(vector_view<u1x8_t> input) noexcept { return !any_set(input); }
+
+/** @brief True if every bit of the 1D bit-vector view is set. */
+inline bool all_set(vector_view<u1x8_t> input) noexcept { return popcount(input).raw_ == input.size(); }
+
 #pragma endregion Scalar Reductions
 
 #pragma region Axis Reductions

package/numkong/include/numkong/scalar/README.md

@@ -2,7 +2,7 @@
 
 NumKong provides single-element math operations — square root, reciprocal square root, fused multiply-add, and saturating integer arithmetic — with per-ISA implementations.
 These primitives serve as building blocks for vectorized kernels: distance finalizers call `nk_f32_rsqrt` for angular normalization, packing routines call `nk_f32_sqrt` for norm computation.
-Ordering functions (`nk_f16_order`, `nk_bf16_order`, `nk_e4m3_order`) convert floating-point bit patterns to integers that sort in the same order as the original floats.
+Ordering functions (`nk_f16_order`, `nk_bf16_order`, `nk_e4m3_order`) compare two values through their bit patterns, returning a negative, zero, or positive `int` like `strcmp`.
 
 Reciprocal square root:
 
@@ -40,27 +40,27 @@ def saturating_add(a: int, b: int, bits: int, signed: bool) -> int:
 
 ## Input & Output Types
 
-| Input Type | Output Type | Description                                     |
-| ---------- | ----------- | ----------------------------------------------- |
-| `f64`      | `f64`       | sqrt, rsqrt, fma for 64-bit doubles             |
-| `f32`      | `f32`       | sqrt, rsqrt, fma for 32-bit floats              |
-| `f16`      | `f16`       | sqrt, rsqrt, fma for 16-bit halfs               |
-| `i8`       | `i8`        | Saturating add and multiply                     |
-| `u8`       | `u8`        | Saturating add and multiply                     |
-| `i16`      | `i16`       | Saturating add and multiply                     |
-| `u16`      | `u16`       | Saturating add and multiply                     |
-| `i32`      | `i32`       | Saturating add and multiply                     |
-| `u32`      | `u32`       | Saturating add and multiply                     |
-| `i64`      | `i64`       | Saturating add and multiply                     |
-| `u64`      | `u64`       | Saturating add and multiply                     |
-| `i4x2`     | `i4x2`      | Saturating add for packed signed nibble pairs   |
-| `u4x2`     | `u4x2`      | Saturating add for packed unsigned nibble pairs |
-| `f16`      | `u16`       | Ordering: bit pattern to sortable integer       |
-| `bf16`     | `u16`       | Ordering: bit pattern to sortable integer       |
-| `e4m3`     | `u8`        | Ordering: bit pattern to sortable integer       |
-| `e5m2`     | `u8`        | Ordering: bit pattern to sortable integer       |
-| `e2m3`     | `u8`        | Ordering: bit pattern to sortable integer       |
-| `e3m2`     | `u8`        | Ordering: bit pattern to sortable integer       |
+| Input Type | Output Type | Description                                                  |
+| ---------- | ----------- | ------------------------------------------------------------ |
+| `f64`      | `f64`       | sqrt, rsqrt, fma for 64-bit doubles                          |
+| `f32`      | `f32`       | sqrt, rsqrt, fma for 32-bit floats                           |
+| `f16`      | `f16`       | sqrt, rsqrt, fma for 16-bit halfs                            |
+| `i8`       | `i8`        | Saturating add and multiply                                  |
+| `u8`       | `u8`        | Saturating add and multiply                                  |
+| `i16`      | `i16`       | Saturating add and multiply                                  |
+| `u16`      | `u16`       | Saturating add and multiply                                  |
+| `i32`      | `i32`       | Saturating add and multiply                                  |
+| `u32`      | `u32`       | Saturating add and multiply                                  |
+| `i64`      | `i64`       | Saturating add and multiply                                  |
+| `u64`      | `u64`       | Saturating add and multiply                                  |
+| `i4x2`     | `i4x2`      | Saturating add and multiply for packed signed nibble pairs   |
+| `u4x2`     | `u4x2`      | Saturating add and multiply for packed unsigned nibble pairs |
+| `f16`      | `int`       | Ordering: three-way comparison of two values                 |
+| `bf16`     | `int`       | Ordering: three-way comparison of two values                 |
+| `e4m3`     | `int`       | Ordering: three-way comparison of two values                 |
+| `e5m2`     | `int`       | Ordering: three-way comparison of two values                 |
+| `e2m3`     | `int`       | Ordering: three-way comparison of two values                 |
+| `e3m2`     | `int`       | Ordering: three-way comparison of two values                 |
 
 ## Optimizations
 
@@ -68,20 +68,21 @@ def saturating_add(a: int, b: int, bits: int, signed: bool) -> int:
 
 `nk_f32_rsqrt_serial` uses the classic bit-manipulation trick: reinterpret Float32 bits as Int32, compute `0x5F375A86 - (bits >> 1)`, reinterpret back to Float32, then refine with 3 Newton-Raphson iterations reaching ~34.9 correct bits.
 Each Newton-Raphson iteration: `y = y * (1.5f - 0.5f * x * y * y)` — 2 multiplies and 1 subtract, ~4cy per iteration.
-`nk_f32_rsqrt_haswell` replaces this with hardware `VRSQRT14PS` ($2^{-14}$ relative error, ~4cy latency) plus one Newton-Raphson refinement (~22-24 correct bits).
+`nk_f32_rsqrt_haswell` replaces this with hardware `RSQRTSS` ($2^{-14}$ relative error, ~4cy latency) plus one Newton-Raphson refinement (~22-24 correct bits).
 `nk_f64_rsqrt_serial` uses the Float64 magic constant `0x5FE6EB50C7B537A9` with 4 iterations for 52-bit mantissa coverage.
 
 ### Dekker Error-Free Multiplication for FMA
 
-`nk_f32_fma_serial` emulates fused multiply-add on platforms without hardware FMA using Dekker's algorithm: splits each operand into high and low halves via `a_hi = (a * 134217729.0f) - ((a * 134217729.0f) - a)`, then computes the exact product error term.
-The magic constant $134217729 = 2^{27} + 1$ splits a 24-bit mantissa into two 12-bit halves that multiply without rounding.
+`nk_f32_fma_serial` emulates fused multiply-add on platforms without hardware FMA using Dekker's algorithm: splits each operand into high and low halves via `a_high = (a * 4097.0f) - ((a * 4097.0f) - a)`, then computes the exact product error term.
+The magic constant $4097 = 2^{12} + 1$ splits a 24-bit mantissa into two 12-bit halves that multiply without rounding; `nk_f64_fma_serial` uses $134217729 = 2^{27} + 1$ for the 53-bit mantissa.
 `nk_f32_fma_haswell` uses hardware `VFMADD231SS` — single instruction, single cycle, exact to the last bit.
 
 ### Float-to-Integer Ordering
 
-`nk_f16_order_serial`, `nk_bf16_order_serial`, `nk_e4m3_order_serial` convert floating-point bit patterns to unsigned integers that preserve the total order.
-Positive floats are already ordered by their bit patterns; negative floats need bit inversion: `if (bits & sign_bit) bits = ~bits; else bits ^= sign_bit`.
-This enables integer comparison instructions (`VPCMPUD`) for floating-point sorting without branching — used by `nk_reduce_minmax_*` for Float8 and sub-32-bit types that lack native SIMD comparison.
+`nk_f16_order_serial`, `nk_bf16_order_serial`, `nk_e4m3_order_serial` map floating-point bit patterns onto signed integers that preserve the total order, then return the difference of the two keys.
+Positive floats are already ordered by their bit patterns; negative floats need bit inversion, applied branchlessly as `bits ^ -sign`.
+This keeps floating-point ordering on the integer pipeline — used by `nk_reduce_minmax_*` for Float8 and sub-32-bit types that lack native SIMD comparison.
+`nk_f16_order_sapphire` instead uses the native `VCOMISH` half-precision comparisons.
 
 ## Performance
 

package/numkong/include/numkong/set/README.md

@@ -53,36 +53,39 @@ def jaccard_words(a: np.ndarray, b: np.ndarray) -> float:
 
 ## Optimizations
 
-### Harley-Seal Carry-Save Adders for U1
+### Popcount Without Harley-Seal Carry-Save Adders
 
-`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:
+The textbook way to amortize population counts is a Harley-Seal carry-save adder tree, which folds three inputs through a full-adder circuit before any popcount is issued:
 
 ```
 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.
+Chaining levels yields `fours` and `eights` accumulators, each weighted by a power of two, so popcount runs on the accumulators instead of on every input vector — roughly a third of the calls.
+NumKong does not do this.
+The cycles-per-byte measurements in `set.h` put the crossover above 1 KB per vector: below it, loop and reduction overhead outweighs the saved popcounts, and the largest binary input benchmarked here is 4096 bits, or 512 bytes.
+Ice Lake and later expose `VPOPCNTQ` outright, and on Genoa it dual-issues on ports 0-1, so the popcount pressure that CSA trees relieve is largely absent on the hardware that could run them.
+
+AVX2 has no vector population count at all, so `nk_hamming_u1_haswell` and `nk_jaccard_u1_haswell` walk the packed octets 8 bytes at a time and call the scalar `POPCNT` through `_mm_popcnt_u64`.
+`nk_hamming_u1_neon` and `nk_jaccard_u1_neon` use the NEON `CNT` instruction instead, accumulating per-byte counts in a `uint8x16_t` for at most 31 iterations before widening, since 31 x 8 still fits in a byte.
 
 ### 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`.
+Inputs of up to 256 bytes are fully unrolled into one, two, three, or four masked register pairs with no loop at all, since binary metrics are hard to speed up at tiny lengths.
+Longer inputs enter a loop that accumulates the per-quadword counts via `VPADDQ` and reduces once at the end.
 
 ### 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.
+The streaming helpers `nk_jaccard_u1x64_finalize_haswell` and `nk_jaccard_u1x512_finalize_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.
+The matching `update` step accumulates only the intersection popcount; `finalize` takes the query popcount and a vector of four target popcounts and recovers the union from them, halving the work in the critical path.
+Both finalizers replace the division by a reciprocal estimate — `RCPPS` on Haswell, `VRCP14PS` on Ice Lake — refined with one Newton-Raphson step.
 
-### Byte Hamming via VPSADBW
+### Byte Hamming via Compare Masks
 
-`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`.
+`nk_hamming_u8_haswell` compares 32 bytes at a time with `VPCMPEQB`, extracts the per-byte sign bits of the two 128-bit halves with `VPMOVMSKB`, inverts the masks, and counts the set bits with scalar `POPCNT`.
+`nk_hamming_u8_icelake` does the same over 64 bytes with `VPCMPNEQB`, which writes the mismatch mask straight into a `__mmask64`, so no extract step is needed.
 
 ## Performance
 

package/numkong/include/numkong/set/haswell.h

@@ -31,8 +31,7 @@
  *  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);
+ *      query_popcount, &target_popcounts_vec, total_dimensions, &result_vec);
  *  @endcode
  */
 #ifndef NK_SET_HASWELL_H
@@ -240,8 +239,8 @@ NK_INTERNAL void nk_jaccard_u1x64_update_haswell(nk_jaccard_u1x64_state_haswell_
 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_f32_t query_popcount, nk_b128_vec_t const *target_popcounts_vec, nk_size_t total_dimensions,
+    nk_b128_vec_t *result_vec) {
     nk_unused_(total_dimensions);
 
     // 4-way SIMD Jaccard computation with fast reciprocal.
@@ -263,7 +262,7 @@ NK_INTERNAL void nk_jaccard_u1x64_finalize_haswell( //
     __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 targets_f32x4 = target_popcounts_vec->xmm_ps;
     __m128 union_f32x4 = _mm_sub_ps(_mm_add_ps(query_f32x4, targets_f32x4), intersection_f32x4);
 
     // Handle zero-union edge case
@@ -283,24 +282,24 @@ NK_INTERNAL void nk_jaccard_u1x64_finalize_haswell( //
 
     __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);
+    result_vec->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;
+NK_INTERNAL void nk_hamming_u32x4_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                    nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    __m128i dots_i32x4 = dots_vec->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));
+    __m128i target_i32x4 = target_pops_vec->xmm;
+    result_vec->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);
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_haswell_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                    nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    __m128 dot_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_f32x4 = _mm_set1_ps((nk_f32_t)query_pop);
-    __m128 target_f32x4 = _mm_cvtepi32_ps(target_pops.xmm);
+    __m128 target_f32x4 = _mm_cvtepi32_ps(target_pops_vec->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());
@@ -314,7 +313,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_haswell_(nk_b128_vec_t dots, nk_u32_t
 
     __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);
+    result_vec->xmm_ps = _mm_blendv_ps(jaccard_f32x4, _mm_setzero_ps(), zero_union_mask);
 }
 
 #pragma endregion Stateful Streaming

package/numkong/include/numkong/set/icelake.h

@@ -30,8 +30,7 @@
  *  nk_jaccard_u1x512_init_icelake(&state_first);
  *  // ... stream through packed binary vectors ...
  *  nk_jaccard_u1x512_finalize_icelake(&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);
+ *      query_popcount, &target_popcounts_vec, total_dimensions, &result_vec);
  *  @endcode
  */
 #ifndef NK_SET_ICELAKE_H
@@ -370,8 +369,8 @@ NK_INTERNAL void nk_jaccard_u1x512_update_icelake(nk_jaccard_u1x512_state_icelak
 NK_INTERNAL void nk_jaccard_u1x512_finalize_icelake( //
     nk_jaccard_u1x512_state_icelake_t const *state_a, nk_jaccard_u1x512_state_icelake_t const *state_b,
     nk_jaccard_u1x512_state_icelake_t const *state_c, nk_jaccard_u1x512_state_icelake_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_f32_t query_popcount, nk_b128_vec_t const *target_popcounts_vec, nk_size_t total_dimensions,
+    nk_b128_vec_t *result_vec) {
     nk_unused_(total_dimensions);
 
     // Port-optimized 4-way horizontal reduction using early i64 → i32 truncation.
@@ -415,7 +414,7 @@ NK_INTERNAL void nk_jaccard_u1x512_finalize_icelake( //
     // Compute Jaccard distance: 1 - intersection ÷ union
     // where union = query_popcount + target_popcount - intersection
     __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 targets_f32x4 = target_popcounts_vec->xmm_ps;
     __m128 union_f32x4 = _mm_sub_ps(_mm_add_ps(query_f32x4, targets_f32x4), intersection_f32x4);
 
     // Handle zero-union edge case: if union == 0, result = 0.0
@@ -435,24 +434,24 @@ NK_INTERNAL void nk_jaccard_u1x512_finalize_icelake( //
 
     __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);
+    result_vec->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 (Icelake). */
-NK_INTERNAL void nk_hamming_u32x4_from_dot_icelake_(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;
+NK_INTERNAL void nk_hamming_u32x4_from_dot_icelake_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                    nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    __m128i dots_i32x4 = dots_vec->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));
+    __m128i target_i32x4 = target_pops_vec->xmm;
+    result_vec->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 (Icelake). */
-NK_INTERNAL void nk_jaccard_f32x4_from_dot_icelake_(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);
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_icelake_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                    nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    __m128 dot_f32x4 = _mm_cvtepi32_ps(dots_vec->xmm);
     __m128 query_f32x4 = _mm_set1_ps((nk_f32_t)query_pop);
-    __m128 target_f32x4 = _mm_cvtepi32_ps(target_pops.xmm);
+    __m128 target_f32x4 = _mm_cvtepi32_ps(target_pops_vec->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());
@@ -465,7 +464,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_icelake_(nk_b128_vec_t dots, nk_u32_t
 
     __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);
+    result_vec->xmm_ps = _mm_blendv_ps(jaccard_f32x4, _mm_setzero_ps(), zero_union_mask);
 }
 
 #pragma endregion Stateful Streaming

package/numkong/include/numkong/set/loongsonasx.h

@@ -144,20 +144,22 @@ NK_PUBLIC void nk_hamming_u8_loongsonasx(nk_u8_t const *a, nk_u8_t const *b, nk_
 #pragma region Batched Finalizers
 
 /** @brief Hamming from_dot: computes pop_a + pop_b − 2 × dot for 4 pairs (LSX). */
-NK_INTERNAL void nk_hamming_u32x4_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_pop,
-                                                        nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
-    __m128i dots_u32x4 = dots.xmm;
+NK_INTERNAL void nk_hamming_u32x4_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                        nk_b128_vec_t const *target_pops_vec,
+                                                        nk_b128_vec_t *result_vec) {
+    __m128i dots_u32x4 = dots_vec->xmm;
     __m128i query_u32x4 = __lsx_vreplgr2vr_w((int)query_pop);
-    __m128i target_u32x4 = target_pops.xmm;
-    results->xmm = __lsx_vsub_w(__lsx_vadd_w(query_u32x4, target_u32x4), __lsx_vslli_w(dots_u32x4, 1));
+    __m128i target_u32x4 = target_pops_vec->xmm;
+    result_vec->xmm = __lsx_vsub_w(__lsx_vadd_w(query_u32x4, target_u32x4), __lsx_vslli_w(dots_u32x4, 1));
 }
 
 /** @brief Jaccard from_dot: computes 1 − dot / (pop_a + pop_b − dot) for 4 pairs (LSX). */
-NK_INTERNAL void nk_jaccard_f32x4_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_pop,
-                                                        nk_b128_vec_t target_pops, nk_b128_vec_t *results) {
-    __m128 dot_f32x4 = __lsx_vffint_s_wu(dots.xmm);
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                        nk_b128_vec_t const *target_pops_vec,
+                                                        nk_b128_vec_t *result_vec) {
+    __m128 dot_f32x4 = __lsx_vffint_s_wu(dots_vec->xmm);
     __m128 query_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_pop);
-    __m128 target_f32x4 = __lsx_vffint_s_wu(target_pops.xmm);
+    __m128 target_f32x4 = __lsx_vffint_s_wu(target_pops_vec->xmm);
     __m128 union_f32x4 = __lsx_vfsub_s(__lsx_vfadd_s(query_f32x4, target_f32x4), dot_f32x4);
 
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
@@ -167,7 +169,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u
 
     __m128 ratio_f32x4 = __lsx_vfdiv_s(dot_f32x4, safe_union_f32x4);
     __m128 jaccard_f32x4 = __lsx_vfsub_s(one_f32x4, ratio_f32x4);
-    results->xmm_ps = (__m128)__lsx_vbitsel_v((__m128i)jaccard_f32x4, (__m128i)zero_f32x4, zero_union_mask_u32x4);
+    result_vec->xmm_ps = (__m128)__lsx_vbitsel_v((__m128i)jaccard_f32x4, (__m128i)zero_f32x4, zero_union_mask_u32x4);
 }
 
 #pragma endregion Batched Finalizers

package/numkong/include/numkong/set/neon.h

@@ -34,8 +34,7 @@
  *  nk_jaccard_u1x128_init_neon(&state_first);
  *  // ... stream through packed binary vectors ...
  *  nk_jaccard_u1x128_finalize_neon(&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);
+ *      query_popcount, &target_popcounts_vec, total_dimensions, &result_vec);
  *  @endcode
  */
 #ifndef NK_SET_NEON_H
@@ -274,8 +273,8 @@ NK_INTERNAL void nk_jaccard_u1x128_update_neon(nk_jaccard_u1x128_state_neon_t *s
 NK_INTERNAL void nk_jaccard_u1x128_finalize_neon( //
     nk_jaccard_u1x128_state_neon_t const *state_a, nk_jaccard_u1x128_state_neon_t const *state_b,
     nk_jaccard_u1x128_state_neon_t const *state_c, nk_jaccard_u1x128_state_neon_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_f32_t query_popcount, nk_b128_vec_t const *target_popcounts_vec, nk_size_t total_dimensions,
+    nk_b128_vec_t *result_vec) {
     nk_unused_(total_dimensions);
 
     // Horizontal sum using pairwise adds instead of `vaddvq_u32` (ADDV).
@@ -290,11 +289,8 @@ NK_INTERNAL void nk_jaccard_u1x128_finalize_neon( //
     float32x4_t intersection_f32x4 = vcvtq_f32_u32(intersection_u32x4);
 
     // Compute union using |A ∪ B| = |A| + |B| - |A ∩ B|
-    // Build target popcounts vector from two independent halves (avoids serial lane insertion chain).
     float32x4_t query_f32x4 = vdupq_n_f32(query_popcount);
-    float32x2_t targets_ab_f32x2 = vset_lane_f32(target_popcount_b, vdup_n_f32(target_popcount_a), 1);
-    float32x2_t targets_cd_f32x2 = vset_lane_f32(target_popcount_d, vdup_n_f32(target_popcount_c), 1);
-    float32x4_t targets_f32x4 = vcombine_f32(targets_ab_f32x2, targets_cd_f32x2);
+    float32x4_t targets_f32x4 = target_popcounts_vec->f32x4;
     float32x4_t union_f32x4 = vsubq_f32(vaddq_f32(query_f32x4, targets_f32x4), intersection_f32x4);
 
     // Handle zero-union edge case (empty vectors → distance = 0.0, matching scipy convention)
@@ -314,24 +310,24 @@ NK_INTERNAL void nk_jaccard_u1x128_finalize_neon( //
     // Compute Jaccard distance = 1 - intersection ÷ union
     float32x4_t ratio_f32x4 = vmulq_f32(intersection_f32x4, union_reciprocal_f32x4);
     float32x4_t jaccard_f32x4 = vsubq_f32(one_f32x4, ratio_f32x4);
-    result->f32x4 = vbslq_f32(zero_union_mask, vdupq_n_f32(0.0f), jaccard_f32x4);
+    result_vec->f32x4 = vbslq_f32(zero_union_mask, vdupq_n_f32(0.0f), jaccard_f32x4);
 }
 
 /** @brief Hamming from_dot: computes pop_a + pop_b - 2*dot for 4 pairs (NEON). */
-NK_INTERNAL void nk_hamming_u32x4_from_dot_neon_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                 nk_b128_vec_t *results) {
-    uint32x4_t dots_u32x4 = dots.u32x4;
+NK_INTERNAL void nk_hamming_u32x4_from_dot_neon_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                 nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    uint32x4_t dots_u32x4 = dots_vec->u32x4;
     uint32x4_t query_u32x4 = vdupq_n_u32(query_pop);
-    uint32x4_t target_u32x4 = target_pops.u32x4;
-    results->u32x4 = vsubq_u32(vaddq_u32(query_u32x4, target_u32x4), vshlq_n_u32(dots_u32x4, 1));
+    uint32x4_t target_u32x4 = target_pops_vec->u32x4;
+    result_vec->u32x4 = vsubq_u32(vaddq_u32(query_u32x4, target_u32x4), vshlq_n_u32(dots_u32x4, 1));
 }
 
 /** @brief Jaccard from_dot: computes 1 - dot / (pop_a + pop_b - dot) for 4 pairs (NEON). */
-NK_INTERNAL void nk_jaccard_f32x4_from_dot_neon_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                 nk_b128_vec_t *results) {
-    float32x4_t dot_f32x4 = vcvtq_f32_u32(dots.u32x4);
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_neon_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                 nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    float32x4_t dot_f32x4 = vcvtq_f32_u32(dots_vec->u32x4);
     float32x4_t query_f32x4 = vdupq_n_f32((nk_f32_t)query_pop);
-    float32x4_t target_f32x4 = vcvtq_f32_u32(target_pops.u32x4);
+    float32x4_t target_f32x4 = vcvtq_f32_u32(target_pops_vec->u32x4);
     float32x4_t union_f32x4 = vsubq_f32(vaddq_f32(query_f32x4, target_f32x4), dot_f32x4);
 
     float32x4_t one_f32x4 = vdupq_n_f32(1.0f);
@@ -343,7 +339,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_neon_(nk_b128_vec_t dots, nk_u32_t qu
 
     float32x4_t ratio_f32x4 = vmulq_f32(dot_f32x4, union_reciprocal_f32x4);
     float32x4_t jaccard_f32x4 = vsubq_f32(one_f32x4, ratio_f32x4);
-    results->f32x4 = vbslq_f32(zero_union_mask, vdupq_n_f32(0.0f), jaccard_f32x4);
+    result_vec->f32x4 = vbslq_f32(zero_union_mask, vdupq_n_f32(0.0f), jaccard_f32x4);
 }
 
 #pragma endregion Stateful Streaming

package/numkong/include/numkong/set/powervsx.h

@@ -33,8 +33,7 @@
  *  nk_jaccard_u1x128_init_powervsx(&state_first);
  *  // ... stream through packed binary vectors ...
  *  nk_jaccard_u1x128_finalize_powervsx(&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);
+ *      query_popcount, &target_popcounts_vec, total_dimensions, &result_vec);
  *  @endcode
  */
 #ifndef NK_SET_POWERVSX_H
@@ -224,8 +223,8 @@ NK_INTERNAL void nk_jaccard_u1x128_update_powervsx(nk_jaccard_u1x128_state_power
 NK_INTERNAL void nk_jaccard_u1x128_finalize_powervsx( //
     nk_jaccard_u1x128_state_powervsx_t const *state_a, nk_jaccard_u1x128_state_powervsx_t const *state_b,
     nk_jaccard_u1x128_state_powervsx_t const *state_c, nk_jaccard_u1x128_state_powervsx_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_f32_t query_popcount, nk_b128_vec_t const *target_popcounts_vec, nk_size_t total_dimensions,
+    nk_b128_vec_t *result_vec) {
     nk_unused_(total_dimensions);
 
     // Transpose-based 4-way horizontal sum of u32x4 intersection counts
@@ -247,12 +246,7 @@ NK_INTERNAL void nk_jaccard_u1x128_finalize_powervsx( //
                                              vec_add(sum_lane2_u32x4, sum_lane3_u32x4));
     nk_vf32x4_t intersection_f32x4 = vec_ctf(intersection_u32x4, 0);
 
-    // Build target popcounts vector via vec_insert
-    nk_vf32x4_t targets_f32x4 = vec_splats(0.0f);
-    targets_f32x4 = vec_insert(target_popcount_a, targets_f32x4, 0);
-    targets_f32x4 = vec_insert(target_popcount_b, targets_f32x4, 1);
-    targets_f32x4 = vec_insert(target_popcount_c, targets_f32x4, 2);
-    targets_f32x4 = vec_insert(target_popcount_d, targets_f32x4, 3);
+    nk_vf32x4_t targets_f32x4 = target_popcounts_vec->vf32x4;
     nk_vf32x4_t query_f32x4 = vec_splats(query_popcount);
 
     // Compute union using |A union B| = |A| + |B| - |A intersection B|
@@ -274,25 +268,25 @@ NK_INTERNAL void nk_jaccard_u1x128_finalize_powervsx( //
     // Compute Jaccard distance = 1 - intersection / union
     nk_vf32x4_t ratio_f32x4 = vec_mul(intersection_f32x4, union_reciprocal_f32x4);
     nk_vf32x4_t jaccard_f32x4 = vec_sub(one_f32x4, ratio_f32x4);
-    result->vf32x4 = vec_sel(jaccard_f32x4, zero_f32x4, zero_union_mask_u32x4);
+    result_vec->vf32x4 = vec_sel(jaccard_f32x4, zero_f32x4, zero_union_mask_u32x4);
 }
 
 /** @brief Hamming from_dot: computes pop_a + pop_b - 2 × dot for 4 pairs (Power VSX). */
-NK_INTERNAL void nk_hamming_u32x4_from_dot_powervsx_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                     nk_b128_vec_t *results) {
-    nk_vu32x4_t dots_u32x4 = dots.vu32x4;
+NK_INTERNAL void nk_hamming_u32x4_from_dot_powervsx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                     nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    nk_vu32x4_t dots_u32x4 = dots_vec->vu32x4;
     nk_vu32x4_t query_u32x4 = vec_splats(query_pop);
-    nk_vu32x4_t target_u32x4 = target_pops.vu32x4;
+    nk_vu32x4_t target_u32x4 = target_pops_vec->vu32x4;
     nk_vu32x4_t two_dots_u32x4 = vec_add(dots_u32x4, dots_u32x4);
-    results->vu32x4 = vec_sub(vec_add(query_u32x4, target_u32x4), two_dots_u32x4);
+    result_vec->vu32x4 = vec_sub(vec_add(query_u32x4, target_u32x4), two_dots_u32x4);
 }
 
 /** @brief Jaccard from_dot: computes 1 - dot / (pop_a + pop_b - dot) for 4 pairs (Power VSX). */
-NK_INTERNAL void nk_jaccard_f32x4_from_dot_powervsx_(nk_b128_vec_t dots, nk_u32_t query_pop, nk_b128_vec_t target_pops,
-                                                     nk_b128_vec_t *results) {
-    nk_vf32x4_t dot_f32x4 = vec_ctf(dots.vu32x4, 0);
+NK_INTERNAL void nk_jaccard_f32x4_from_dot_powervsx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_pop,
+                                                     nk_b128_vec_t const *target_pops_vec, nk_b128_vec_t *result_vec) {
+    nk_vf32x4_t dot_f32x4 = vec_ctf(dots_vec->vu32x4, 0);
     nk_vf32x4_t query_f32x4 = vec_splats((nk_f32_t)query_pop);
-    nk_vf32x4_t target_f32x4 = vec_ctf(target_pops.vu32x4, 0);
+    nk_vf32x4_t target_f32x4 = vec_ctf(target_pops_vec->vu32x4, 0);
     nk_vf32x4_t union_f32x4 = vec_sub(vec_add(query_f32x4, target_f32x4), dot_f32x4);
 
     nk_vf32x4_t one_f32x4 = vec_splats(1.0f);
@@ -308,7 +302,7 @@ NK_INTERNAL void nk_jaccard_f32x4_from_dot_powervsx_(nk_b128_vec_t dots, nk_u32_
 
     nk_vf32x4_t ratio_f32x4 = vec_mul(dot_f32x4, union_reciprocal_f32x4);
     nk_vf32x4_t jaccard_f32x4 = vec_sub(one_f32x4, ratio_f32x4);
-    results->vf32x4 = vec_sel(jaccard_f32x4, zero_f32x4, zero_union_mask_u32x4);
+    result_vec->vf32x4 = vec_sel(jaccard_f32x4, zero_f32x4, zero_union_mask_u32x4);
 }
 
 #if defined(__clang__)