usearch 2.26.0 → 2.26.2

package/numkong/c/parallel.c

@@ -0,0 +1,139 @@
+/**
+ *  @brief Tile-parallel execution for NumKong language bindings.
+ *  @file c/parallel.c
+ *  @author Ash Vardanian
+ *  @date August 6, 2026
+ *
+ *  One shared tile counter drives every backend, so dynamic scheduling and the
+ *  thread-count cap behave identically no matter which pool runs the tiles.
+ */
+#include "parallel.h"
+
+#if defined(__APPLE__)
+#include <dispatch/dispatch.h> // `dispatch_apply_f`, part of libSystem
+#include <unistd.h>            // `sysconf`
+#elif defined(_WIN32)
+#include <windows.h> // `CreateThreadpoolWork`, part of kernel32
+#else
+#include <unistd.h> // `sysconf`
+#if defined(_OPENMP)
+#include <omp.h>
+#endif
+#endif
+
+/*  OpenMP schedules tiles itself, so the counter below is for the other pools. */
+#if !defined(__APPLE__) && !defined(_WIN32) && defined(_OPENMP)
+#define NK_PARALLEL_VIA_OPENMP 1
+#else
+#define NK_PARALLEL_VIA_OPENMP 0
+#endif
+
+#if !NK_PARALLEL_VIA_OPENMP
+
+#pragma region Tile Queue
+
+/** @brief Tiles remaining, plus the body that consumes them. */
+typedef struct nk_tile_queue_t {
+    nk_tile_body_t body;
+    void *context;
+    nk_size_t tile_count;
+#if defined(_MSC_VER)
+    volatile long long next_tile;
+#else
+    nk_size_t next_tile;
+#endif
+} nk_tile_queue_t;
+
+/** @brief Claim and run tiles until the queue is empty. Safe to call from every worker at once. */
+static void nk_tile_queue_drain_(nk_tile_queue_t *queue) {
+    for (;;) {
+#if defined(_MSC_VER)
+        nk_size_t const tile_index = (nk_size_t)_InterlockedExchangeAdd64(&queue->next_tile, 1);
+#else
+        nk_size_t const tile_index = __atomic_fetch_add(&queue->next_tile, 1, __ATOMIC_RELAXED);
+#endif
+        if (tile_index >= queue->tile_count) return;
+        queue->body(tile_index, queue->context);
+    }
+}
+
+#pragma endregion Tile Queue
+
+#endif // !NK_PARALLEL_VIA_OPENMP
+
+#pragma region Platform Pools
+
+#if defined(__APPLE__)
+
+/** @brief libdispatch hands each worker its index; the queue decides what it runs. */
+static void nk_tile_worker_dispatch_(void *context, size_t worker_index) {
+    (void)worker_index;
+    nk_tile_queue_drain_((nk_tile_queue_t *)context);
+}
+
+#elif defined(_WIN32)
+
+static void CALLBACK nk_tile_worker_threadpool_(PTP_CALLBACK_INSTANCE instance, PVOID context, PTP_WORK work) {
+    (void)instance;
+    (void)work;
+    nk_tile_queue_drain_((nk_tile_queue_t *)context);
+}
+
+#endif
+
+nk_size_t nk_parallel_concurrency(void) {
+#if defined(_WIN32)
+    DWORD const count = GetActiveProcessorCount(ALL_PROCESSOR_GROUPS);
+    return count ? (nk_size_t)count : 1;
+#elif defined(_SC_NPROCESSORS_ONLN)
+    long const count = sysconf(_SC_NPROCESSORS_ONLN);
+    return count > 0 ? (nk_size_t)count : 1;
+#else
+    return 1;
+#endif
+}
+
+void nk_parallel_for_tiles(nk_size_t tile_count, nk_size_t threads, nk_tile_body_t body, void *context) {
+    if (!tile_count) return;
+    if (threads == 0) threads = nk_parallel_concurrency();
+    if (threads > tile_count) threads = tile_count;
+
+    // A single worker needs no pool, no atomics, and no launch latency.
+    if (threads <= 1) {
+        for (nk_size_t tile_index = 0; tile_index < tile_count; ++tile_index) body(tile_index, context);
+        return;
+    }
+
+#if NK_PARALLEL_VIA_OPENMP
+    // OpenMP's own dynamic queue beats draining a shared counter.
+    long long const tile_limit = (long long)tile_count;
+#pragma omp parallel for schedule(dynamic, 1) num_threads((int)threads)
+    for (long long tile_index = 0; tile_index < tile_limit; ++tile_index) body((nk_size_t)tile_index, context);
+#else
+    nk_tile_queue_t queue;
+    queue.body = body;
+    queue.context = context;
+    queue.tile_count = tile_count;
+    queue.next_tile = 0;
+
+#if defined(__APPLE__)
+    dispatch_apply_f((size_t)threads, dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), &queue,
+                     nk_tile_worker_dispatch_);
+#elif defined(_WIN32)
+    PTP_WORK work = CreateThreadpoolWork(nk_tile_worker_threadpool_, &queue, NULL);
+    if (!work) {
+        nk_tile_queue_drain_(&queue); // Out of pool resources — the caller still needs the result
+        return;
+    }
+    // The calling thread takes a share too, so only the extra workers are submitted.
+    for (nk_size_t worker = 1; worker < threads; ++worker) SubmitThreadpoolWork(work);
+    nk_tile_queue_drain_(&queue);
+    WaitForThreadpoolWorkCallbacks(work, FALSE);
+    CloseThreadpoolWork(work);
+#else
+    nk_tile_queue_drain_(&queue);
+#endif
+#endif // NK_PARALLEL_VIA_OPENMP
+}
+
+#pragma endregion Platform Pools

package/numkong/c/parallel.h

@@ -0,0 +1,47 @@
+/**
+ *  @brief Tile-parallel execution for NumKong language bindings.
+ *  @file c/parallel.h
+ *  @author Ash Vardanian
+ *  @date August 6, 2026
+ *
+ *  Compiled only by `setup.py` and `binding.gyp`, never by CMake or Cargo.
+ *  Each platform's own pool runs the tiles, so no binding ships a `libomp`.
+ */
+#ifndef NUMKONG_PARALLEL_H
+#define NUMKONG_PARALLEL_H
+
+#include <numkong/types.h> // `nk_size_t`
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*  Row-tile sizes: 2 kernel tile blocks per chunk, packed blocking 2×2 rows of 16. */
+#define NK_PARALLEL_PACKED_TILE    64
+#define NK_PARALLEL_SYMMETRIC_TILE 32
+
+/**
+ *  @brief Work for one tile. Must be reentrant and confine writes to its own tile.
+ *  @param tile_index Zero-based index below the `tile_count` passed to the scheduler.
+ *  @param context Caller-owned state, shared unsynchronized across all tiles.
+ */
+typedef void (*nk_tile_body_t)(nk_size_t tile_index, void *context);
+
+/** @brief Logical processors available to this process, or 1 when undetectable. */
+nk_size_t nk_parallel_concurrency(void);
+
+/**
+ *  @brief Run @p tile_count independent tiles, at most @p threads of them at a time.
+ *
+ *  Tiles are claimed from a shared counter, giving the dynamic scheduling uneven
+ *  workloads need. @p threads of 0 means every logical processor, and 1 runs the
+ *  tiles inline on the calling thread with no pool involved. Returns once every
+ *  tile has completed. The caller must release the GIL if the bodies do not need it.
+ */
+void nk_parallel_for_tiles(nk_size_t tile_count, nk_size_t threads, nk_tile_body_t body, void *context);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NUMKONG_PARALLEL_H

package/numkong/cmake/toolchain-wasi.cmake

@@ -38,10 +38,23 @@ set(CMAKE_RANLIB "${WASI_SDK_PATH}/bin/llvm-ranlib${WASI_TOOL_SUFFIX}")
 set(CMAKE_SYSROOT "${WASI_SDK_PATH}/share/wasi-sysroot")
 set(CMAKE_FIND_ROOT_PATH "${WASI_SDK_PATH}")
 
+# Cross-runtime portable mode: build single-threaded with self-contained memory so the SAME `.wasm`
+# runs under node, wasmtime, AND wasmer (used by the cross-runtime kernel validation). Default OFF keeps
+# the threaded, host-imported-memory build that the full nk_test / nk_bench suites rely on.
+if (NK_WASI_PORTABLE)
+    set(NK_WASI_TARGET_ "wasm32-wasip1")
+    set(NK_WASI_THREADS_ "")
+    set(NK_WASI_MEMORY_ "")
+else ()
+    set(NK_WASI_TARGET_ "wasm32-wasip1-threads")
+    set(NK_WASI_THREADS_ "-pthread")
+    set(NK_WASI_MEMORY_ "-Wl,--import-memory -Wl,--export-memory -Wl,--shared-memory -Wl,--max-memory=2147483648")
+endif ()
+
 # WASM SIMD flags (same as Emscripten for consistency).
 set(WASM_SIMD_FLAGS "-msimd128 -mrelaxed-simd")
-set(CMAKE_C_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=wasm32-wasip1-threads -pthread")
-set(CMAKE_CXX_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=wasm32-wasip1-threads -pthread -fno-exceptions")
+set(CMAKE_C_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=${NK_WASI_TARGET_} ${NK_WASI_THREADS_}")
+set(CMAKE_CXX_FLAGS_INIT "${WASM_SIMD_FLAGS} --target=${NK_WASI_TARGET_} ${NK_WASI_THREADS_} -fno-exceptions")
 
 # Optimization flags.
 set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG")
@@ -49,15 +62,18 @@ set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG")
 set(CMAKE_C_FLAGS_DEBUG "-O0 -g")
 set(CMAKE_CXX_FLAGS_DEBUG "-O0 -g")
 
-# Linker flags for WASI.
+# Linker flags for WASI (the imported/shared-memory group is empty in NK_WASI_PORTABLE mode).
 set(CMAKE_EXE_LINKER_FLAGS_INIT
     "-Wl,--allow-undefined \
-     -Wl,--import-memory -Wl,--export-memory \
-     -Wl,--shared-memory -Wl,--max-memory=2147483648 \
+     ${NK_WASI_MEMORY_} \
      -Wl,--export=main \
      -Wl,--export=_start"
 )
 
+# `wasm-ld` resolves `__global_base`, `__data_end`, and `__heap_base` only in a main module, so a `-shared`
+# WASI build cannot link. Seeded rather than forced, so `-D NK_BUILD_SHARED=ON` still overrides.
+set(NK_BUILD_SHARED OFF CACHE BOOL "Compile a dynamic library")
+
 # Do not look for programs in build-host directories.
 set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
 set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
@@ -75,3 +91,21 @@ endif ()
 
 message(STATUS "NumKong WASI: SIMD128 and Relaxed SIMD enabled")
 message(STATUS "NumKong WASI: Toolchain at ${WASI_SDK_PATH}")
+
+# Runtime that CTest invokes on each cross binary, so `ctest` runs the WASI tests cross-engine without a
+# wrapper script. wasmtime and wasmer execute a `.wasm` command directly; node uses the small WASI runner
+# in test/test-wasi.mjs. Relaxed-SIMD lowers differently per engine, so testing more than one matters.
+set(NK_WASM_RUNTIME "wasmtime" CACHE STRING "WASM runtime CTest uses for WASI tests (wasmtime, wasmer, or node)")
+if (NK_WASM_RUNTIME STREQUAL "wasmer")
+    find_program(NK_WASMER_EXE_ wasmer PATHS "$ENV{HOME}/.cargo/bin" "$ENV{HOME}/.wasmer/bin")
+    set(CMAKE_CROSSCOMPILING_EMULATOR "${NK_WASMER_EXE_};run")
+elseif (NK_WASM_RUNTIME STREQUAL "node")
+    find_program(NK_NODE_EXE_ node)
+    set(CMAKE_CROSSCOMPILING_EMULATOR
+        "${NK_NODE_EXE_};--experimental-wasi-unstable-preview1;${CMAKE_CURRENT_LIST_DIR}/../test/test-wasi.mjs"
+    )
+else ()
+    find_program(NK_WASMTIME_EXE_ wasmtime PATHS "$ENV{HOME}/.wasmtime/bin")
+    set(CMAKE_CROSSCOMPILING_EMULATOR "${NK_WASMTIME_EXE_}")
+endif ()
+message(STATUS "NumKong WASI: CTest runtime = ${NK_WASM_RUNTIME}")

package/numkong/include/README.md

@@ -1,7 +1,7 @@
 # NumKong for C and C++
 
 NumKong's native SDK is the reference surface for the project.
-The plain C ABI exposes every kernel family directly: dot products, dense distances, binary metrics, probability divergences, geospatial solvers, curved-space kernels, sparse intersections, mesh alignment, packed matrix multiplication, symmetric self-similarity, and late-interaction scoring.
+The plain C ABI exposes every kernel family directly: dot products, dense distances, binary metrics, probability divergences, geospatial solvers, curved-space kernels, sparse intersections, mesh alignment, packed matrix multiplication, symmetric self-similarity, late-interaction scoring, elementwise arithmetic, reductions, type conversions, scalar math, and trigonometry.
 The ABI is stable, versioned, and callable from any language that can load a shared library.
 There is no runtime overhead: no hidden thread pool, no implicit allocation, no garbage collector interaction.
 The C++ layer stays thin, typed, allocator-aware, and close enough to inline through, adding type-level result promotion and owning containers without hiding the dispatch model or the mixed-precision policy.
@@ -43,7 +43,7 @@ Packing handles internal layout itself and does not require caller-side alignmen
 
 ## Ecosystem Comparison
 
-| Feature                      | NumKong                                                                                                                             | [OpenBLAS](https://github.com/OpenMathLib/OpenBLAS)               | [Eigen](https://gitlab.com/libeigen/eigen)                                              |
+| Feature                      | NumKong                                                                                                                             | [OpenBLAS][openblas]                                              | [Eigen][eigen]                                                                          |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | Operation families           | dots, distances, binary, probability, geospatial, curved, mesh, sparse, MaxSim, elementwise, reductions, cast, trig                 | dense linear algebra only                                         | dense LA, some reductions and elementwise                                               |
 | Precision                    | Sub-byte to Float64 dtypes; automatic widening per scalar type; Kahan-compensated summation; 0 ULP Float32/Float64 where applicable | Float32, Float64 only; same-type in/out; no compensated summation | Float16/BFloat16 partial; no Float8 or sub-byte; manual casts; no compensated summation |
@@ -52,6 +52,8 @@ Packing handles internal layout itself and does not require caller-side alignmen
 | Symmetric kernels, SYRK-like | skips duplicate pairs, up to 2x speedup for self-distance                                                                           | `SSYRK`/`DSYRK` for rank-k updates                                | `.selfadjointView` for rank-k updates                                                   |
 | Memory model                 | Caller-owned buffers; C++ adds `tensor<T,A>` with per-container allocators                                                          | Caller-managed buffers; no container abstraction                  | Lazy expression templates avoid most temporaries; `aligned_allocator` provided          |
 
+[openblas]: https://github.com/OpenMathLib/OpenBLAS
+[eigen]: https://gitlab.com/libeigen/eigen
 
 
 ## Installation
@@ -168,7 +170,7 @@ The higher-level templates use `result_type_ = typename in_type_::dot_result_t`
 The fast typed overloads are constrained so that overriding the result type away from the native policy can disable the specialized path and fall back to the more generic one.
 
 When `__cpp_lib_format >= 202110L` for the C++23 `<format>` header support, all NumKong scalar types provide `std::formatter` specializations with similar format specs to the traditional `float`.
-For the BFloat16 type, the output for `nk::f16_t::from_f32(3.14f)` will look like:
+For the Float16 type, the output for `nk::f16_t::from_f32(3.14f)` will look like:
 
 | Format spec | Output example       | Description                            |
 | ----------- | -------------------- | -------------------------------------- |
@@ -189,10 +191,10 @@ They include real, complex, packed-binary, mini-float, and mixed-precision forms
 ```c
 nk_f32c_t a[384];
 nk_f32c_t b[384];
-nk_f32_t out[2] = {0, 0};
+nk_f64c_t out = {0, 0};         // widened f32c → f64c output
 
-nk_dot_f32c(a, b, 384, out);  // complex inner product
-nk_vdot_f32c(a, b, 384, out); // conjugated variant, like numpy.vdot
+nk_dot_f32c(a, b, 384, &out);   // complex inner product
+nk_vdot_f32c(a, b, 384, &out);  // conjugated variant, like numpy.vdot
 ```
 
 For quantized retrieval pipelines, the storage format often matters more than the nominal math family.
@@ -231,15 +233,18 @@ nk_hamming_u1(a, b, 128 * 8, &hamming);
 nk_jaccard_u1(a, b, 128 * 8, &jaccard);
 ```
 
-Integer set Jaccard works on sorted arrays of integer identifiers.
+`nk_jaccard_u32` is a dense word-wise kernel rather than a sorted-set operation.
+It walks two arrays of `n` 32-bit words position by position and returns `1 - matches / n`.
 
 ```c
-nk_u32_t set_a[] = {1, 3, 5, 7, 9}, set_b[] = {3, 5, 8, 9, 10};
-nk_f32_t jaccard_sets = 0;
-nk_jaccard_u32(set_a, set_b, 5, &jaccard_sets); // |A ∩ B| / |A ∪ B|
-assert(jaccard_sets > 0.0f && jaccard_sets < 1.0f && "|A ∩ B| / |A ∪ B| should be in (0, 1)");
+nk_u32_t a[] = {1, 3, 5, 7, 9}, b[] = {1, 3, 5, 8, 10};
+nk_f32_t jaccard_words = 0;
+nk_jaccard_u32(a, b, 5, &jaccard_words); // 1 - matches / n
+assert(jaccard_words > 0.0f && jaccard_words < 1.0f && "3 of 5 words match");
 ```
 
+Sorted arrays of integer identifiers are handled by the sparse kernels instead, described below.
+
 ## Probability Metrics
 
 Probability kernels target divergences directly instead of making you rebuild them from scalar loops.
@@ -351,8 +356,8 @@ You can also use a more traditional syntax with member functions, also leveragin
 Similar to NumPy, but statically typed:
 
 ```cpp
-auto first_column = t[all, 1, slice];             // strided column view → {2, 5, 8}
-auto minimum_index = nk::argmin(first_column);    // index of the minimum in the second column
+auto second_column = t[all, 1, slice];            // strided column view → {2, 5, 8}
+auto minimum_index = nk::argmin(second_column);   // index of the minimum in the second column
 ```
 
 The view types are conceptually close to `std::mdspan` from C++23.
@@ -498,10 +503,11 @@ The native API covers `rmsd`, `kabsch`, and `umeyama`.
 nk_f32_t source[] = {0, 0, 0, 1, 0, 0, 0, 1, 0};
 nk_f32_t target[] = {0, 0, 0, 2, 0, 0, 0, 2, 0};
 nk_f32_t a_centroid[3], b_centroid[3], rotation[9];
-nk_f32_t scale = 0, rmsd = 0;
+nk_f32_t scale = 0;
+nk_f64_t rmsd = 0; // widened f32 → f64 output
 
 nk_umeyama_f32(source, target, 3, a_centroid, b_centroid, rotation, &scale, &rmsd);
-assert(rmsd < 1e-6f && "umeyama should recover exact alignment");
+assert(rmsd < 1e-6 && "umeyama should recover exact alignment");
 assert(scale > 1.99f && scale < 2.01f && "umeyama should recover 2x scale");
 ```
 
@@ -592,13 +598,14 @@ The main user-facing CMake options are:
 - `NK_BUILD_SHARED` builds a shared library, ON by default for standalone builds and OFF when included as a subdirectory.
 - `NK_BUILD_TEST` and `NK_BUILD_BENCH` enable precision tests and benchmarks respectively, both OFF by default.
 - `NK_DYNAMIC_DISPATCH=1` compiles all backends into one binary and selects at runtime via `nk_capabilities()`, recommended for shipping one binary across CPU generations.
+  It is a preprocessor definition rather than a CMake option, so pass it through the compiler flags.
 - `NK_COMPARE_TO_BLAS` and `NK_COMPARE_TO_MKL` link benchmarks against a system BLAS or Intel MKL, each accepting `AUTO`, `ON`, or `OFF` with `AUTO` as the default.
 
-The build enforces C99 for the C layer and C++23 for the C++ layer.
+The build enforces C99 for the C layer and C++20 for the C++ layer.
 
 ```sh
 cmake -B build -D CMAKE_BUILD_TYPE=Release -D NK_BUILD_TEST=ON
-cmake -B build -D NK_DYNAMIC_DISPATCH=1 -D NK_BUILD_BENCH=ON -D NK_COMPARE_TO_MKL=ON
+cmake -B build -D CMAKE_C_FLAGS="-DNK_DYNAMIC_DISPATCH=1" -D NK_BUILD_BENCH=ON -D NK_COMPARE_TO_MKL=ON
 ```
 
 ## Cross-Compilation

package/numkong/include/numkong/attention/sapphireamx.h

@@ -117,7 +117,7 @@ typedef struct {
  *  2. Polynomial approximation: exp(r) ≈ 1 + r + r²/2 + ... (degree 6)
  *  3. Reconstruction: exp(x) = 2ⁿ × exp(r)
  *
- *  @param x Input vector (16 floats)
+ *  @param x_f32x16 Input vector (16 floats)
  *  @return exp(x) for each element
  */
 NK_INTERNAL __m512 nk_exp_ps_avx512_(__m512 x_f32x16) {
@@ -169,7 +169,7 @@ NK_INTERNAL __m512 nk_exp_ps_avx512_(__m512 x_f32x16) {
  *
  *  Performance: ~12-15 cycles for 16 floats (vs ~18-22 for degree-6)
  *
- *  @param x Input vector (16 floats)
+ *  @param x_f32x16 Input vector (16 floats)
  *  @return exp(x) approximation
  */
 NK_INTERNAL __m512 nk_exp_ps_fast_avx512_(__m512 x_f32x16) {
@@ -475,10 +475,10 @@ NK_INTERNAL void nk_attention_softmax_update_(nk_attention_softmax_row_state_t *
  *  When processing a new KV block with larger scores, previous O accumulator
  *  needs rescaling: O = O × exp(oldₘₐₓ - newₘₐₓ)
  *
- *  @param output       Output accumulator [16][head_dim] in F32
- *  @param head_dim     Head dimension
- *  @param old_max      Previous running max per row (16 values)
- *  @param new_max      New running max per row (16 values)
+ *  @param output          Output accumulator [16][head_dim] in F32
+ *  @param head_dim        Head dimension
+ *  @param old_max_f32x16  Previous running max per row (16 values)
+ *  @param new_max_f32x16  New running max per row (16 values)
  */
 NK_INTERNAL void nk_attention_rescale_output_(nk_f32_t *output, nk_size_t head_dim, __m512 old_max_f32x16,
                                               __m512 new_max_f32x16) {

package/numkong/include/numkong/attention/sme.h

@@ -162,8 +162,8 @@ typedef struct {
  *  Uses Cody-Waite range reduction + Horner polynomial (degree 4).
  *  Accuracy: ~0.1% relative error, acceptable for softmax normalization.
  *
- *  @param pg Active predicate
- *  @param x Input vector
+ *  @param predicate_b32x Active predicate
+ *  @param x_f32x Input vector
  *  @return exp(x) approximation
  */
 NK_INTERNAL svfloat32_t nk_exp_f32_sve_(svbool_t predicate_b32x, svfloat32_t x_f32x) __arm_streaming {

package/numkong/include/numkong/capabilities.h

@@ -95,8 +95,8 @@
 #include "numkong/types.h" // `nk_u64_t`, `NK_DEFINED_LINUX_`
 
 #define NK_VERSION_MAJOR 7
-#define NK_VERSION_MINOR 6
-#define NK_VERSION_PATCH 0
+#define NK_VERSION_MINOR 8
+#define NK_VERSION_PATCH 1
 
 /**
  *  @brief  Removes compile-time dispatching, and replaces it with runtime dispatching.

package/numkong/include/numkong/cast/README.md

@@ -1,7 +1,8 @@
 # Type Conversions in NumKong
 
-NumKong implements bidirectional type conversions between all supported numeric formats through Float32 as a hub type.
-Conversions cover IEEE 754 floats (Float16, Float32, Float64), brain float (BFloat16), Float8 formats (e4m3, e5m2, e2m3, e3m2), and integers (Int8–Int64, UInt8–UInt64, packed i4x2/u4x2).
+NumKong implements bidirectional type conversions between all supported numeric formats through a wider hub type: `u64` when both sides are unsigned integers, `i64` when both sides are integers and at least one is signed, and `f64c` for everything else.
+The SIMD backends use a narrower Float32 hub for the subset of types they cover.
+Conversions cover IEEE 754 floats (Float16, Float32, Float64), brain float (BFloat16), Float8 formats (e4m3, e5m2, e2m3, e3m2), and integers (Int8–Int64, UInt8–UInt64, packed i4x2/u4x2, packed u1x8).
 All conversions use round-to-nearest-even (RNE) for narrowing and exact widening where the target format has sufficient range and precision.
 
 BFloat16 relates to Float32 by truncation with rounding:
@@ -77,16 +78,17 @@ Packed sub-byte conversions:
 
 ### Lookup Tables for Mini-Floats
 
-`nk_e4m3_to_f32_serial`, `nk_e5m2_to_f32_serial`, `nk_e2m3_to_f32_serial`, `nk_e3m2_to_f32_serial` use 256-entry precomputed lookup tables — each 8-bit input indexes directly into a Float32 result array.
-The reverse direction (`nk_f32_to_e4m3_serial`) uses clamping + rounding: clamp to format range, multiply by scale, round-to-nearest, cast to UInt8.
-SIMD backends (`nk_cast_haswell`, `nk_cast_skylake`) use `VPGATHERDD` to perform 8 or 16 simultaneous table lookups from the same 256-entry table.
-AVX-512 gathers on Skylake achieve ~3cy throughput per 16-element lookup vs ~8cy on Haswell for 8-element gathers.
+`nk_e5m2_to_f32_serial` indexes a 128-entry table with the 7-bit magnitude, and `nk_e2m3_to_f32_serial` and `nk_e3m2_to_f32_serial` index 32-entry tables with their 5-bit magnitudes, OR-ing the sign bit back in afterwards.
+`nk_e4m3_to_f32_serial` needs no table: the exponent and mantissa fields map onto Float32 with a bias shift of 120, and only the subnormal and the single NaN encoding are special-cased.
+The reverse direction (`nk_f32_to_e4m3_serial`) is bit manipulation with RNE rounding: NaN and infinity are mapped explicitly, subnormals below 2⁻⁶ are rounded through a `× 512` scale, and normals get their 23-bit mantissa rounded down to 3 bits.
+The SIMD backends do not gather from these tables.
+On x86 the Float8 paths ride the F16C converters described below, and NEON looks up Float16 high bytes with `VQTBL4` over a 128-byte table in `nk_e4m3x16_to_f16x8x2_neon_` and its siblings.
 
 ### BFloat16 as Truncated Float32
 
 `nk_bf16_to_f32_serial` zero-extends by left-shifting 16 bits — exact, no rounding error, single-cycle on all platforms.
 `nk_f32_to_bf16_serial` right-shifts with round-to-nearest-even: adds a rounding bias of `0x7FFF + ((bits >> 16) & 1)` before truncating, matching the IEEE 754 RNE tie-breaking rule.
-NEON backend uses `vreinterpretq_u16_u8` + `vzip` for zero-extension; Haswell uses `VPSLLD` / `VPSRLD` shifts.
+NEON backend uses `vmovl_u16` + `vshlq_n_u32` for zero-extension; Haswell uses `VPSLLD` / `VPSRLD` shifts.
 
 ### F16C Hardware Conversion
 

package/numkong/include/numkong/cast/loongsonasx.h

@@ -139,106 +139,114 @@ NK_INTERNAL __m128 nk_sqrt_f32x4_loongsonasx_(__m128 x_f32x4) {
 }
 
 /** @brief Angular from_dot: computes 1 − dot × rsqrt(query_sumsq × target_sumsq) for 4 pairs (LSX 128-bit f32). */
-NK_INTERNAL void nk_angular_through_f32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_f32_t query_sumsq,
-                                                              nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = dots.xmm_ps;
+NK_INTERNAL void nk_angular_through_f32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_f32_t query_sumsq,
+                                                              nk_b128_vec_t const *target_sumsqs_vec,
+                                                              nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = dots_vec->xmm_ps;
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_(query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot: computes √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs (LSX 128-bit f32). */
-NK_INTERNAL void nk_euclidean_through_f32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_f32_t query_sumsq,
-                                                                nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = dots.xmm_ps;
+NK_INTERNAL void nk_euclidean_through_f32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_f32_t query_sumsq,
+                                                                nk_b128_vec_t const *target_sumsqs_vec,
+                                                                nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = dots_vec->xmm_ps;
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_(query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, target_sumsqs.xmm_ps);
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, target_sumsqs_vec->xmm_ps);
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     // dist_sq = sum_sq − 2 × dots = -(2 × dots − sum_sq)
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for native f64: 1 − dot / √(query_sumsq × target_sumsq) for 4 pairs (LASX 256-bit). */
-NK_INTERNAL void nk_angular_through_f64_from_dot_loongsonasx_(nk_b256_vec_t dots, nk_f64_t query_sumsq,
-                                                              nk_b256_vec_t target_sumsqs, nk_b256_vec_t *results) {
-    __m256d dots_f64x4 = dots.ymm_pd;
+NK_INTERNAL void nk_angular_through_f64_from_dot_loongsonasx_(nk_b256_vec_t const *dots_vec, nk_f64_t query_sumsq,
+                                                              nk_b256_vec_t const *target_sumsqs_vec,
+                                                              nk_b256_vec_t *result_vec) {
+    __m256d dots_f64x4 = dots_vec->ymm_pd;
     __m256d query_sumsq_f64x4 = nk_xvfreplgr2vr_d_(query_sumsq);
-    __m256d products_f64x4 = __lasx_xvfmul_d(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d products_f64x4 = __lasx_xvfmul_d(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d sqrt_products_f64x4 = __lasx_xvfsqrt_d(products_f64x4);
     __m256d normalized_f64x4 = __lasx_xvfdiv_d(dots_f64x4, sqrt_products_f64x4);
     __m256d one_f64x4 = nk_xvfreplgr2vr_d_(1.0);
     __m256d angular_f64x4 = __lasx_xvfsub_d(one_f64x4, normalized_f64x4);
     __m256d zero_f64x4 = (__m256d)__lasx_xvreplgr2vr_d(0);
-    results->ymm_pd = __lasx_xvfmax_d(angular_f64x4, zero_f64x4);
+    result_vec->ymm_pd = __lasx_xvfmax_d(angular_f64x4, zero_f64x4);
 }
 
 /** @brief Euclidean from_dot for native f64: √(query_sumsq + target_sumsq − 2 × dot) for 4 pairs (LASX 256-bit). */
-NK_INTERNAL void nk_euclidean_through_f64_from_dot_loongsonasx_(nk_b256_vec_t dots, nk_f64_t query_sumsq,
-                                                                nk_b256_vec_t target_sumsqs, nk_b256_vec_t *results) {
-    __m256d dots_f64x4 = dots.ymm_pd;
+NK_INTERNAL void nk_euclidean_through_f64_from_dot_loongsonasx_(nk_b256_vec_t const *dots_vec, nk_f64_t query_sumsq,
+                                                                nk_b256_vec_t const *target_sumsqs_vec,
+                                                                nk_b256_vec_t *result_vec) {
+    __m256d dots_f64x4 = dots_vec->ymm_pd;
     __m256d query_sumsq_f64x4 = nk_xvfreplgr2vr_d_(query_sumsq);
-    __m256d sum_sq_f64x4 = __lasx_xvfadd_d(query_sumsq_f64x4, target_sumsqs.ymm_pd);
+    __m256d sum_sq_f64x4 = __lasx_xvfadd_d(query_sumsq_f64x4, target_sumsqs_vec->ymm_pd);
     __m256d two_f64x4 = nk_xvfreplgr2vr_d_(2.0);
     // dist_sq = sum_sq − 2 × dots = -(2 × dots − sum_sq)
     __m256d dist_sq_f64x4 = __lasx_xvfnmsub_d(two_f64x4, dots_f64x4, sum_sq_f64x4);
     __m256d zero_f64x4 = (__m256d)__lasx_xvreplgr2vr_d(0);
-    results->ymm_pd = __lasx_xvfsqrt_d(__lasx_xvfmax_d(dist_sq_f64x4, zero_f64x4));
+    result_vec->ymm_pd = __lasx_xvfsqrt_d(__lasx_xvfmax_d(dist_sq_f64x4, zero_f64x4));
 }
 
 /** @brief Angular from_dot for i32 accumulators: cast i32 → f32, rsqrt+NR, clamp. 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_angular_through_i32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                              nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_angular_through_i32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_i32_t query_sumsq,
+                                                              nk_b128_vec_t const *target_sumsqs_vec,
+                                                              nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot for i32 accumulators: cast i32 → f32, then √(a² + b² − 2ab). 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_euclidean_through_i32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_i32_t query_sumsq,
-                                                                nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_i32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_i32_t query_sumsq,
+                                                                nk_b128_vec_t const *target_sumsqs_vec,
+                                                                nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 /** @brief Angular from_dot for u32 accumulators: cast u32 → f32, rsqrt+NR, clamp. 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_angular_through_u32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                              nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_angular_through_u32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_sumsq,
+                                                              nk_b128_vec_t const *target_sumsqs_vec,
+                                                              nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 products_f32x4 = __lsx_vfmul_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 rsqrt_f32x4 = __lsx_vfrsqrt_s(products_f32x4);
     __m128 normalized_f32x4 = __lsx_vfmul_s(dots_f32x4, rsqrt_f32x4);
     __m128 one_f32x4 = nk_xvreplgr2vr_s_128_(1.0f);
     __m128 angular_f32x4 = __lsx_vfsub_s(one_f32x4, normalized_f32x4);
     __m128 zero_f32x4 = (__m128)__lsx_vreplgr2vr_w(0);
-    results->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
+    result_vec->xmm_ps = __lsx_vfmax_s(angular_f32x4, zero_f32x4);
 }
 
 /** @brief Euclidean from_dot for u32 accumulators: cast u32 → f32, then √(a² + b² − 2ab). 4 pairs (LSX 128-bit). */
-NK_INTERNAL void nk_euclidean_through_u32_from_dot_loongsonasx_(nk_b128_vec_t dots, nk_u32_t query_sumsq,
-                                                                nk_b128_vec_t target_sumsqs, nk_b128_vec_t *results) {
-    __m128 dots_f32x4 = __lsx_vffint_s_w(dots.xmm);
+NK_INTERNAL void nk_euclidean_through_u32_from_dot_loongsonasx_(nk_b128_vec_t const *dots_vec, nk_u32_t query_sumsq,
+                                                                nk_b128_vec_t const *target_sumsqs_vec,
+                                                                nk_b128_vec_t *result_vec) {
+    __m128 dots_f32x4 = __lsx_vffint_s_w(dots_vec->xmm);
     __m128 query_sumsq_f32x4 = nk_xvreplgr2vr_s_128_((nk_f32_t)query_sumsq);
-    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs.xmm));
+    __m128 sum_sq_f32x4 = __lsx_vfadd_s(query_sumsq_f32x4, __lsx_vffint_s_w(target_sumsqs_vec->xmm));
     __m128 two_f32x4 = nk_xvreplgr2vr_s_128_(2.0f);
     __m128 dist_sq_f32x4 = __lsx_vfnmsub_s(two_f32x4, dots_f32x4, sum_sq_f32x4);
-    results->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
+    result_vec->xmm_ps = nk_sqrt_f32x4_loongsonasx_(dist_sq_f32x4);
 }
 
 #pragma endregion Vectorized From Dot Helpers