usearch 2.21.3 → 2.25.0

package/numkong/include/numkong/scalar/rvv.h

@@ -0,0 +1,211 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for RISC-V.
+ *  @file include/numkong/scalar/rvv.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  RVV scalar helpers use vector instructions with VL=1 for hardware sqrt/rsqrt.
+ *  `vfrsqrt7` provides 7-bit mantissa precision; Newton-Raphson refines to full precision.
+ */
+#ifndef NK_SCALAR_RVV_H
+#define NK_SCALAR_RVV_H
+
+#if NK_TARGET_RISCV64_
+#if NK_TARGET_RVV
+
+#include "numkong/types.h"
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=+v"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=+v")
+#endif
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+NK_PUBLIC nk_f32_t nk_f32_rsqrt_rvv(nk_f32_t number) {
+    vfloat32m1_t x_f32m1 = __riscv_vfmv_s_f_f32m1(number, 1);
+    vfloat32m1_t estimate_f32m1 = __riscv_vfrsqrt7_v_f32m1(x_f32m1, 1);
+    vfloat32m1_t half_f32m1 = __riscv_vfmv_s_f_f32m1(0.5f, 1);
+    vfloat32m1_t three_half_f32m1 = __riscv_vfmv_s_f_f32m1(1.5f, 1);
+    vfloat32m1_t half_x_f32m1 = __riscv_vfmul_vv_f32m1(half_f32m1, x_f32m1, 1);
+    // Iteration 1
+    vfloat32m1_t estimate_sq_f32m1 = __riscv_vfmul_vv_f32m1(estimate_f32m1, estimate_f32m1, 1);
+    vfloat32m1_t correction_f32m1 = __riscv_vfmul_vv_f32m1(half_x_f32m1, estimate_sq_f32m1, 1);
+    vfloat32m1_t factor_f32m1 = __riscv_vfsub_vv_f32m1(three_half_f32m1, correction_f32m1, 1);
+    estimate_f32m1 = __riscv_vfmul_vv_f32m1(estimate_f32m1, factor_f32m1, 1);
+    // Iteration 2
+    estimate_sq_f32m1 = __riscv_vfmul_vv_f32m1(estimate_f32m1, estimate_f32m1, 1);
+    correction_f32m1 = __riscv_vfmul_vv_f32m1(half_x_f32m1, estimate_sq_f32m1, 1);
+    factor_f32m1 = __riscv_vfsub_vv_f32m1(three_half_f32m1, correction_f32m1, 1);
+    estimate_f32m1 = __riscv_vfmul_vv_f32m1(estimate_f32m1, factor_f32m1, 1);
+    return __riscv_vfmv_f_s_f32m1_f32(estimate_f32m1);
+}
+
+NK_PUBLIC nk_f32_t nk_f32_sqrt_rvv(nk_f32_t number) {
+    vfloat32m1_t x_f32m1 = __riscv_vfmv_s_f_f32m1(number, 1);
+    return __riscv_vfmv_f_s_f32m1_f32(__riscv_vfsqrt_v_f32m1(x_f32m1, 1));
+}
+
+NK_PUBLIC nk_f64_t nk_f64_rsqrt_rvv(nk_f64_t number) {
+    vfloat64m1_t x_f64m1 = __riscv_vfmv_s_f_f64m1(number, 1);
+    vfloat64m1_t estimate_f64m1 = __riscv_vfrsqrt7_v_f64m1(x_f64m1, 1);
+    vfloat64m1_t half_f64m1 = __riscv_vfmv_s_f_f64m1(0.5, 1);
+    vfloat64m1_t three_half_f64m1 = __riscv_vfmv_s_f_f64m1(1.5, 1);
+    vfloat64m1_t half_x_f64m1 = __riscv_vfmul_vv_f64m1(half_f64m1, x_f64m1, 1);
+    // Iteration 1
+    vfloat64m1_t estimate_sq_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, estimate_f64m1, 1);
+    vfloat64m1_t correction_f64m1 = __riscv_vfmul_vv_f64m1(half_x_f64m1, estimate_sq_f64m1, 1);
+    vfloat64m1_t factor_f64m1 = __riscv_vfsub_vv_f64m1(three_half_f64m1, correction_f64m1, 1);
+    estimate_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, factor_f64m1, 1);
+    // Iteration 2
+    estimate_sq_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, estimate_f64m1, 1);
+    correction_f64m1 = __riscv_vfmul_vv_f64m1(half_x_f64m1, estimate_sq_f64m1, 1);
+    factor_f64m1 = __riscv_vfsub_vv_f64m1(three_half_f64m1, correction_f64m1, 1);
+    estimate_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, factor_f64m1, 1);
+    // Iteration 3
+    estimate_sq_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, estimate_f64m1, 1);
+    correction_f64m1 = __riscv_vfmul_vv_f64m1(half_x_f64m1, estimate_sq_f64m1, 1);
+    factor_f64m1 = __riscv_vfsub_vv_f64m1(three_half_f64m1, correction_f64m1, 1);
+    estimate_f64m1 = __riscv_vfmul_vv_f64m1(estimate_f64m1, factor_f64m1, 1);
+    return __riscv_vfmv_f_s_f64m1_f64(estimate_f64m1);
+}
+
+NK_PUBLIC nk_f64_t nk_f64_sqrt_rvv(nk_f64_t number) {
+    vfloat64m1_t x_f64m1 = __riscv_vfmv_s_f_f64m1(number, 1);
+    return __riscv_vfmv_f_s_f64m1_f64(__riscv_vfsqrt_v_f64m1(x_f64m1, 1));
+}
+
+NK_PUBLIC nk_f32_t nk_f32_fma_rvv(nk_f32_t a, nk_f32_t b, nk_f32_t c) {
+    vfloat32m1_t a_f32m1 = __riscv_vfmv_s_f_f32m1(a, 1);
+    vfloat32m1_t c_f32m1 = __riscv_vfmv_s_f_f32m1(c, 1);
+    return __riscv_vfmv_f_s_f32m1_f32(__riscv_vfmacc_vf_f32m1(c_f32m1, b, a_f32m1, 1));
+}
+
+NK_PUBLIC nk_f64_t nk_f64_fma_rvv(nk_f64_t a, nk_f64_t b, nk_f64_t c) {
+    vfloat64m1_t a_f64m1 = __riscv_vfmv_s_f_f64m1(a, 1);
+    vfloat64m1_t c_f64m1 = __riscv_vfmv_s_f_f64m1(c, 1);
+    return __riscv_vfmv_f_s_f64m1_f64(__riscv_vfmacc_vf_f64m1(c_f64m1, b, a_f64m1, 1));
+}
+
+NK_PUBLIC nk_u8_t nk_u8_saturating_add_rvv(nk_u8_t a, nk_u8_t b) {
+    vuint8m1_t a_u8m1 = __riscv_vmv_v_x_u8m1(a, 1);
+    vuint8m1_t b_u8m1 = __riscv_vmv_v_x_u8m1(b, 1);
+    return __riscv_vmv_x_s_u8m1_u8(__riscv_vsaddu_vv_u8m1(a_u8m1, b_u8m1, 1));
+}
+
+NK_PUBLIC nk_i8_t nk_i8_saturating_add_rvv(nk_i8_t a, nk_i8_t b) {
+    vint8m1_t a_i8m1 = __riscv_vmv_v_x_i8m1(a, 1);
+    vint8m1_t b_i8m1 = __riscv_vmv_v_x_i8m1(b, 1);
+    return __riscv_vmv_x_s_i8m1_i8(__riscv_vsadd_vv_i8m1(a_i8m1, b_i8m1, 1));
+}
+
+NK_PUBLIC nk_u16_t nk_u16_saturating_add_rvv(nk_u16_t a, nk_u16_t b) {
+    vuint16m1_t a_u16m1 = __riscv_vmv_v_x_u16m1(a, 1);
+    vuint16m1_t b_u16m1 = __riscv_vmv_v_x_u16m1(b, 1);
+    return __riscv_vmv_x_s_u16m1_u16(__riscv_vsaddu_vv_u16m1(a_u16m1, b_u16m1, 1));
+}
+
+NK_PUBLIC nk_i16_t nk_i16_saturating_add_rvv(nk_i16_t a, nk_i16_t b) {
+    vint16m1_t a_i16m1 = __riscv_vmv_v_x_i16m1(a, 1);
+    vint16m1_t b_i16m1 = __riscv_vmv_v_x_i16m1(b, 1);
+    return __riscv_vmv_x_s_i16m1_i16(__riscv_vsadd_vv_i16m1(a_i16m1, b_i16m1, 1));
+}
+
+NK_PUBLIC nk_u32_t nk_u32_saturating_add_rvv(nk_u32_t a, nk_u32_t b) {
+    vuint32m1_t a_u32m1 = __riscv_vmv_v_x_u32m1(a, 1);
+    vuint32m1_t b_u32m1 = __riscv_vmv_v_x_u32m1(b, 1);
+    return __riscv_vmv_x_s_u32m1_u32(__riscv_vsaddu_vv_u32m1(a_u32m1, b_u32m1, 1));
+}
+
+NK_PUBLIC nk_i32_t nk_i32_saturating_add_rvv(nk_i32_t a, nk_i32_t b) {
+    vint32m1_t a_i32m1 = __riscv_vmv_v_x_i32m1(a, 1);
+    vint32m1_t b_i32m1 = __riscv_vmv_v_x_i32m1(b, 1);
+    return __riscv_vmv_x_s_i32m1_i32(__riscv_vsadd_vv_i32m1(a_i32m1, b_i32m1, 1));
+}
+
+NK_PUBLIC nk_u64_t nk_u64_saturating_add_rvv(nk_u64_t a, nk_u64_t b) {
+    vuint64m1_t a_u64m1 = __riscv_vmv_v_x_u64m1(a, 1);
+    vuint64m1_t b_u64m1 = __riscv_vmv_v_x_u64m1(b, 1);
+    return __riscv_vmv_x_s_u64m1_u64(__riscv_vsaddu_vv_u64m1(a_u64m1, b_u64m1, 1));
+}
+
+NK_PUBLIC nk_i64_t nk_i64_saturating_add_rvv(nk_i64_t a, nk_i64_t b) {
+    vint64m1_t a_i64m1 = __riscv_vmv_v_x_i64m1(a, 1);
+    vint64m1_t b_i64m1 = __riscv_vmv_v_x_i64m1(b, 1);
+    return __riscv_vmv_x_s_i64m1_i64(__riscv_vsadd_vv_i64m1(a_i64m1, b_i64m1, 1));
+}
+
+NK_PUBLIC nk_u8_t nk_u8_saturating_mul_rvv(nk_u8_t a, nk_u8_t b) {
+    vuint8m1_t a_u8m1 = __riscv_vmv_v_x_u8m1(a, 1);
+    vuint8m1_t b_u8m1 = __riscv_vmv_v_x_u8m1(b, 1);
+    vuint16m2_t product_u16m2 = __riscv_vwmulu_vv_u16m2(a_u8m1, b_u8m1, 1);
+    return __riscv_vmv_x_s_u8m1_u8(__riscv_vnclipu_wx_u8m1(product_u16m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_i8_t nk_i8_saturating_mul_rvv(nk_i8_t a, nk_i8_t b) {
+    vint8m1_t a_i8m1 = __riscv_vmv_v_x_i8m1(a, 1);
+    vint8m1_t b_i8m1 = __riscv_vmv_v_x_i8m1(b, 1);
+    vint16m2_t product_i16m2 = __riscv_vwmul_vv_i16m2(a_i8m1, b_i8m1, 1);
+    return __riscv_vmv_x_s_i8m1_i8(__riscv_vnclip_wx_i8m1(product_i16m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_u16_t nk_u16_saturating_mul_rvv(nk_u16_t a, nk_u16_t b) {
+    vuint16m1_t a_u16m1 = __riscv_vmv_v_x_u16m1(a, 1);
+    vuint16m1_t b_u16m1 = __riscv_vmv_v_x_u16m1(b, 1);
+    vuint32m2_t product_u32m2 = __riscv_vwmulu_vv_u32m2(a_u16m1, b_u16m1, 1);
+    return __riscv_vmv_x_s_u16m1_u16(__riscv_vnclipu_wx_u16m1(product_u32m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_i16_t nk_i16_saturating_mul_rvv(nk_i16_t a, nk_i16_t b) {
+    vint16m1_t a_i16m1 = __riscv_vmv_v_x_i16m1(a, 1);
+    vint16m1_t b_i16m1 = __riscv_vmv_v_x_i16m1(b, 1);
+    vint32m2_t product_i32m2 = __riscv_vwmul_vv_i32m2(a_i16m1, b_i16m1, 1);
+    return __riscv_vmv_x_s_i16m1_i16(__riscv_vnclip_wx_i16m1(product_i32m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_u32_t nk_u32_saturating_mul_rvv(nk_u32_t a, nk_u32_t b) {
+    vuint32m1_t a_u32m1 = __riscv_vmv_v_x_u32m1(a, 1);
+    vuint32m1_t b_u32m1 = __riscv_vmv_v_x_u32m1(b, 1);
+    vuint64m2_t product_u64m2 = __riscv_vwmulu_vv_u64m2(a_u32m1, b_u32m1, 1);
+    return __riscv_vmv_x_s_u32m1_u32(__riscv_vnclipu_wx_u32m1(product_u64m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_i32_t nk_i32_saturating_mul_rvv(nk_i32_t a, nk_i32_t b) {
+    vint32m1_t a_i32m1 = __riscv_vmv_v_x_i32m1(a, 1);
+    vint32m1_t b_i32m1 = __riscv_vmv_v_x_i32m1(b, 1);
+    vint64m2_t product_i64m2 = __riscv_vwmul_vv_i64m2(a_i32m1, b_i32m1, 1);
+    return __riscv_vmv_x_s_i32m1_i32(__riscv_vnclip_wx_i32m1(product_i64m2, 0, __RISCV_VXRM_RDN, 1));
+}
+NK_PUBLIC nk_u64_t nk_u64_saturating_mul_rvv(nk_u64_t a, nk_u64_t b) {
+    vuint64m1_t a_u64m1 = __riscv_vmv_v_x_u64m1(a, 1);
+    vuint64m1_t b_u64m1 = __riscv_vmv_v_x_u64m1(b, 1);
+    nk_u64_t high = __riscv_vmv_x_s_u64m1_u64(__riscv_vmulhu_vv_u64m1(a_u64m1, b_u64m1, 1));
+    return high ? 18446744073709551615ull : (a * b);
+}
+NK_PUBLIC nk_i64_t nk_i64_saturating_mul_rvv(nk_i64_t a, nk_i64_t b) {
+    int sign = (a < 0) ^ (b < 0);
+    nk_u64_t abs_a = a < 0 ? (0u - (nk_u64_t)a) : (nk_u64_t)a;
+    nk_u64_t abs_b = b < 0 ? (0u - (nk_u64_t)b) : (nk_u64_t)b;
+    vuint64m1_t a_u64m1 = __riscv_vmv_v_x_u64m1(abs_a, 1);
+    vuint64m1_t b_u64m1 = __riscv_vmv_v_x_u64m1(abs_b, 1);
+    nk_u64_t high = __riscv_vmv_x_s_u64m1_u64(__riscv_vmulhu_vv_u64m1(a_u64m1, b_u64m1, 1));
+    nk_u64_t low = abs_a * abs_b;
+    if (high || (sign && low > 9223372036854775808ull) || (!sign && low > 9223372036854775807ull))
+        return sign ? (-9223372036854775807ll - 1ll) : 9223372036854775807ll;
+    return sign ? -(nk_i64_t)low : (nk_i64_t)low;
+}
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#endif // NK_TARGET_RVV
+#endif // NK_TARGET_RISCV64_
+#endif // NK_SCALAR_RVV_H

package/numkong/include/numkong/scalar/sapphire.h

@@ -0,0 +1,74 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for Sapphire Rapids.
+ *  @file include/numkong/scalar/sapphire.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  Provides native AVX-512 FP16 scalar ordering via `VCOMISH`.
+ */
+#ifndef NK_SCALAR_SAPPHIRE_H
+#define NK_SCALAR_SAPPHIRE_H
+
+#if NK_TARGET_X8664_
+#if NK_TARGET_SAPPHIRE
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("avx2,avx512f,avx512vl,avx512bw,avx512fp16,f16c,fma,bmi,bmi2"))), \
+                             apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("avx2", "avx512f", "avx512vl", "avx512bw", "avx512fp16", "f16c", "fma", "bmi", "bmi2")
+#endif
+
+NK_PUBLIC int nk_f16_order_sapphire(nk_f16_t a, nk_f16_t b) {
+    nk_fui16_t a_fui, b_fui;
+    a_fui.f = a, b_fui.f = b;
+    __m128h a_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(a_fui.u));
+    __m128h b_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(b_fui.u));
+    return _mm_comigt_sh(a_f16x8, b_f16x8) - _mm_comilt_sh(a_f16x8, b_f16x8);
+}
+NK_PUBLIC nk_f16_t nk_f16_sqrt_sapphire(nk_f16_t x) {
+    nk_fui16_t x_fui, out_fui;
+    x_fui.f = x;
+    __m128h x_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(x_fui.u));
+    out_fui.u = (nk_u16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_sqrt_sh(x_f16x8, x_f16x8)));
+    return out_fui.f;
+}
+NK_PUBLIC nk_f16_t nk_f16_rsqrt_sapphire(nk_f16_t x) {
+    nk_fui16_t x_fui, out_fui;
+    x_fui.f = x;
+    __m128h x_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(x_fui.u));
+    out_fui.u = (nk_u16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_rsqrt_sh(x_f16x8, x_f16x8)));
+    return out_fui.f;
+}
+NK_PUBLIC nk_f16_t nk_f16_fma_sapphire(nk_f16_t a, nk_f16_t b, nk_f16_t c) {
+    nk_fui16_t a_fui, b_fui, c_fui, out_fui;
+    a_fui.f = a, b_fui.f = b, c_fui.f = c;
+    __m128h a_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(a_fui.u));
+    __m128h b_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(b_fui.u));
+    __m128h c_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(c_fui.u));
+    out_fui.u = (nk_u16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_fmadd_sh(a_f16x8, b_f16x8, c_f16x8)));
+    return out_fui.f;
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_SAPPHIRE
+#endif // NK_TARGET_X8664_
+#endif // NK_SCALAR_SAPPHIRE_H

package/numkong/include/numkong/scalar/serial.h

@@ -0,0 +1,332 @@
+/**
+ *  @brief Software-emulated Scalar Math Helpers for SIMD-free CPUs.
+ *  @file include/numkong/scalar/serial.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  Uses the Quake 3 fast inverse square root trick with Newton-Raphson refinement.
+ *  Three iterations for f32 (~34.9 correct bits), four for f64 (~69.3 correct bits).
+ */
+#ifndef NK_SCALAR_SERIAL_H
+#define NK_SCALAR_SERIAL_H
+
+#include "numkong/types.h"
+#include "numkong/cast/serial.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+NK_PUBLIC nk_f32_t nk_f32_rsqrt_serial(nk_f32_t number) {
+    nk_fui32_t conv;
+    conv.f = number;
+    conv.u = 0x5F375A86 - (conv.u >> 1);
+    nk_f32_t y = conv.f;
+    y = y * (1.5f - 0.5f * number * y * y);
+    y = y * (1.5f - 0.5f * number * y * y);
+    y = y * (1.5f - 0.5f * number * y * y);
+    return y;
+}
+
+NK_PUBLIC nk_f32_t nk_f32_sqrt_serial(nk_f32_t number) { return number > 0 ? number * nk_f32_rsqrt_serial(number) : 0; }
+
+NK_PUBLIC nk_f64_t nk_f64_rsqrt_serial(nk_f64_t number) {
+    nk_fui64_t conv;
+    conv.f = number;
+    conv.u = 0x5FE6EB50C7B537A9ULL - (conv.u >> 1);
+    nk_f64_t y = conv.f;
+    y = y * (1.5 - 0.5 * number * y * y);
+    y = y * (1.5 - 0.5 * number * y * y);
+    y = y * (1.5 - 0.5 * number * y * y);
+    y = y * (1.5 - 0.5 * number * y * y);
+    return y;
+}
+
+NK_PUBLIC nk_f64_t nk_f64_sqrt_serial(nk_f64_t number) { return number > 0 ? number * nk_f64_rsqrt_serial(number) : 0; }
+
+NK_PUBLIC nk_f16_t nk_f16_sqrt_serial(nk_f16_t x) {
+    nk_f32_t x_f32;
+    nk_f16_to_f32_serial(&x, &x_f32);
+    x_f32 = nk_f32_sqrt_serial(x_f32);
+    nk_f16_t result;
+    nk_f32_to_f16_serial(&x_f32, &result);
+    return result;
+}
+
+NK_PUBLIC nk_f16_t nk_f16_rsqrt_serial(nk_f16_t x) {
+    nk_f32_t x_f32;
+    nk_f16_to_f32_serial(&x, &x_f32);
+    x_f32 = nk_f32_rsqrt_serial(x_f32);
+    nk_f16_t result;
+    nk_f32_to_f16_serial(&x_f32, &result);
+    return result;
+}
+
+/**
+ *  @brief Software FMA (Fused Multiply-Add) emulation for f64.
+ *  Computes (multiplicand * multiplier + addend) with improved precision
+ *  using Dekker's error-free multiplication and Knuth's TwoSum.
+ *  @sa std::fma, @sa Rust f64::mul_add
+ */
+NK_PUBLIC nk_f64_t nk_f64_fma_serial(nk_f64_t multiplicand, nk_f64_t multiplier, nk_f64_t addend) {
+    nk_f64_t product = multiplicand * multiplier;
+    // Dekker splitting: break each operand into non-overlapping high and low halves
+    nk_f64_t const dekker_split = 134217729.0; // 2^27 + 1 for double precision
+    nk_f64_t multiplicand_high = dekker_split * multiplicand;
+    nk_f64_t multiplicand_low = multiplicand - (multiplicand_high - (multiplicand_high - multiplicand));
+    multiplicand_high = multiplicand_high - (multiplicand_high - multiplicand);
+    nk_f64_t multiplier_high = dekker_split * multiplier;
+    nk_f64_t multiplier_low = multiplier - (multiplier_high - (multiplier_high - multiplier));
+    multiplier_high = multiplier_high - (multiplier_high - multiplier);
+    // Exact multiplication error from the four cross-products
+    nk_f64_t product_error = ((multiplicand_high * multiplier_high - product) + multiplicand_high * multiplier_low +
+                              multiplicand_low * multiplier_high) +
+                             multiplicand_low * multiplier_low;
+    // Knuth TwoSum: add the addend with error tracking
+    nk_f64_t result = product + addend;
+    nk_f64_t addend_recovered = result - product;
+    nk_f64_t product_recovered = result - addend_recovered;
+    nk_f64_t addition_error = (product - product_recovered) + (addend - addend_recovered);
+    return result + (product_error + addition_error);
+}
+
+/**
+ *  @brief Software FMA (Fused Multiply-Add) emulation for f32.
+ *  Computes (multiplicand * multiplier + addend) with improved precision
+ *  using Dekker's error-free multiplication and Knuth's TwoSum.
+ *  @sa std::fma, @sa Rust f32::mul_add
+ */
+NK_PUBLIC nk_f32_t nk_f32_fma_serial(nk_f32_t multiplicand, nk_f32_t multiplier, nk_f32_t addend) {
+    nk_f32_t product = multiplicand * multiplier;
+    // Dekker splitting: break each operand into non-overlapping high and low halves
+    nk_f32_t const dekker_split = 4097.0f; // 2^12 + 1 for single precision
+    nk_f32_t multiplicand_high = dekker_split * multiplicand;
+    nk_f32_t multiplicand_low = multiplicand - (multiplicand_high - (multiplicand_high - multiplicand));
+    multiplicand_high = multiplicand_high - (multiplicand_high - multiplicand);
+    nk_f32_t multiplier_high = dekker_split * multiplier;
+    nk_f32_t multiplier_low = multiplier - (multiplier_high - (multiplier_high - multiplier));
+    multiplier_high = multiplier_high - (multiplier_high - multiplier);
+    // Exact multiplication error from the four cross-products
+    nk_f32_t product_error = ((multiplicand_high * multiplier_high - product) + multiplicand_high * multiplier_low +
+                              multiplicand_low * multiplier_high) +
+                             multiplicand_low * multiplier_low;
+    // Knuth TwoSum: add the addend with error tracking
+    nk_f32_t result = product + addend;
+    nk_f32_t addend_recovered = result - product;
+    nk_f32_t product_recovered = result - addend_recovered;
+    nk_f32_t addition_error = (product - product_recovered) + (addend - addend_recovered);
+    return result + (product_error + addition_error);
+}
+
+/**
+ *  @brief Scalar Dot2 accumulator: sum += a * b with error compensation.
+ *  Uses TwoProd (via FMA) and TwoSum error-free transformations.
+ *  @see Ogita, T., Rump, S.M., Oishi, S. (2005). "Accurate Sum and Dot Product"
+ */
+NK_INTERNAL void nk_f64_dot2_(nk_f64_t *sum, nk_f64_t *compensation, nk_f64_t a, nk_f64_t b) NK_STREAMING_COMPATIBLE_ {
+    nk_f64_t product = a * b;
+    nk_f64_t product_error = nk_f64_fma_serial(a, b, -product);
+    nk_f64_t running_sum = *sum + product;
+    nk_f64_t recovered_addend = running_sum - *sum;
+    nk_f64_t sum_error = (*sum - (running_sum - recovered_addend)) + (product - recovered_addend);
+    *sum = running_sum;
+    *compensation += sum_error + product_error;
+}
+
+NK_PUBLIC nk_f16_t nk_f16_fma_serial(nk_f16_t a, nk_f16_t b, nk_f16_t c) {
+    nk_f32_t a_f32, b_f32, c_f32;
+    nk_f16_to_f32_serial(&a, &a_f32);
+    nk_f16_to_f32_serial(&b, &b_f32);
+    nk_f16_to_f32_serial(&c, &c_f32);
+    nk_f32_t result_f32 = nk_f32_fma_serial(a_f32, b_f32, c_f32);
+    nk_f16_t result;
+    nk_f32_to_f16_serial(&result_f32, &result);
+    return result;
+}
+
+NK_PUBLIC nk_u8_t nk_u8_saturating_add_serial(nk_u8_t a, nk_u8_t b) {
+    nk_u16_t result = (nk_u16_t)a + (nk_u16_t)b;
+    return (result > 255u) ? (nk_u8_t)255u : (nk_u8_t)result;
+}
+NK_PUBLIC nk_u16_t nk_u16_saturating_add_serial(nk_u16_t a, nk_u16_t b) {
+    nk_u32_t result = (nk_u32_t)a + (nk_u32_t)b;
+    return (result > 65535u) ? (nk_u16_t)65535u : (nk_u16_t)result;
+}
+NK_PUBLIC nk_u32_t nk_u32_saturating_add_serial(nk_u32_t a, nk_u32_t b) {
+    nk_u64_t result = (nk_u64_t)a + (nk_u64_t)b;
+    return (result > 4294967295u) ? (nk_u32_t)4294967295u : (nk_u32_t)result;
+}
+NK_PUBLIC nk_u64_t nk_u64_saturating_add_serial(nk_u64_t a, nk_u64_t b) {
+    return (a + b < a) ? 18446744073709551615ull : (a + b);
+}
+NK_PUBLIC nk_i8_t nk_i8_saturating_add_serial(nk_i8_t a, nk_i8_t b) {
+    nk_i16_t result = (nk_i16_t)a + (nk_i16_t)b;
+    return (result > 127) ? 127 : (result < -128 ? -128 : result);
+}
+NK_PUBLIC nk_i16_t nk_i16_saturating_add_serial(nk_i16_t a, nk_i16_t b) {
+    nk_i32_t result = (nk_i32_t)a + (nk_i32_t)b;
+    return (result > 32767) ? 32767 : (result < -32768 ? -32768 : result);
+}
+NK_PUBLIC nk_i32_t nk_i32_saturating_add_serial(nk_i32_t a, nk_i32_t b) {
+    nk_i64_t result = (nk_i64_t)a + (nk_i64_t)b;
+    return (result > 2147483647ll) ? 2147483647ll : (result < -2147483648ll ? -2147483648ll : (nk_i32_t)result);
+}
+NK_PUBLIC nk_i64_t nk_i64_saturating_add_serial(nk_i64_t a, nk_i64_t b) {
+    //? We can't just write `-9223372036854775808ll`, even though it's the smallest signed 64-bit value.
+    //? The compiler will complain about the number being too large for the type, as it will process the
+    //? constant and the sign separately. So we use the same hint that compilers use to define the `INT64_MIN`.
+    if ((b > 0) && (a > (9223372036854775807ll) - b)) return 9223372036854775807ll;
+    if ((b < 0) && (a < (-9223372036854775807ll - 1ll) - b)) return -9223372036854775807ll - 1ll;
+    return a + b;
+}
+
+NK_PUBLIC nk_u8_t nk_u8_saturating_mul_serial(nk_u8_t a, nk_u8_t b) {
+    nk_u16_t result = (nk_u16_t)a * (nk_u16_t)b;
+    return (result > 255) ? 255 : (nk_u8_t)result;
+}
+
+NK_PUBLIC nk_u16_t nk_u16_saturating_mul_serial(nk_u16_t a, nk_u16_t b) {
+    nk_u32_t result = (nk_u32_t)a * (nk_u32_t)b;
+    return (result > 65535) ? 65535 : (nk_u16_t)result;
+}
+
+NK_PUBLIC nk_u32_t nk_u32_saturating_mul_serial(nk_u32_t a, nk_u32_t b) {
+    nk_u64_t result = (nk_u64_t)a * (nk_u64_t)b;
+    return (result > 4294967295u) ? 4294967295u : (nk_u32_t)result;
+}
+
+NK_PUBLIC nk_u64_t nk_u64_saturating_mul_serial(nk_u64_t a, nk_u64_t b) {
+    // Split the inputs into high and low 32-bit parts
+    nk_u64_t a_high = a >> 32;
+    nk_u64_t a_low = a & 0xFFFFFFFF;
+    nk_u64_t b_high = b >> 32;
+    nk_u64_t b_low = b & 0xFFFFFFFF;
+
+    // Compute partial products
+    nk_u64_t upper_product = a_high * b_high;
+    nk_u64_t cross_ab = a_high * b_low;
+    nk_u64_t cross_ba = a_low * b_high;
+    nk_u64_t lower_product = a_low * b_low;
+
+    // Check if the high part of the result overflows
+    nk_u64_t cross_sum = cross_ab + cross_ba;
+    if (upper_product || (cross_ab >> 32) || (cross_ba >> 32) || (cross_sum < cross_ab) || (cross_sum >> 32))
+        return 18446744073709551615ull;
+    nk_u64_t result = (cross_sum << 32) + lower_product;
+    if (result < lower_product) return 18446744073709551615ull;
+    return result;
+}
+
+NK_PUBLIC nk_i8_t nk_i8_saturating_mul_serial(nk_i8_t a, nk_i8_t b) {
+    nk_i16_t result = (nk_i16_t)a * (nk_i16_t)b;
+    return (result > 127) ? 127 : (result < -128 ? -128 : (nk_i8_t)result);
+}
+
+NK_PUBLIC nk_i16_t nk_i16_saturating_mul_serial(nk_i16_t a, nk_i16_t b) {
+    nk_i32_t result = (nk_i32_t)a * (nk_i32_t)b;
+    return (result > 32767) ? 32767 : (result < -32768 ? -32768 : (nk_i16_t)result);
+}
+
+NK_PUBLIC nk_i32_t nk_i32_saturating_mul_serial(nk_i32_t a, nk_i32_t b) {
+    nk_i64_t result = (nk_i64_t)a * (nk_i64_t)b;
+    return (result > 2147483647ll) ? 2147483647ll : (result < -2147483648ll ? -2147483648ll : (nk_i32_t)result);
+}
+
+NK_PUBLIC nk_i64_t nk_i64_saturating_mul_serial(nk_i64_t a, nk_i64_t b) {
+    int sign = ((a < 0) ^ (b < 0)) ? -1 : 1; // Track the sign of the result
+
+    // Take absolute values for easy multiplication and overflow detection
+    nk_u64_t abs_a = (a < 0) ? (0u - (nk_u64_t)a) : (nk_u64_t)a;
+    nk_u64_t abs_b = (b < 0) ? (0u - (nk_u64_t)b) : (nk_u64_t)b;
+
+    // Split the absolute values into high and low 32-bit parts
+    nk_u64_t a_high = abs_a >> 32;
+    nk_u64_t a_low = abs_a & 0xFFFFFFFF;
+    nk_u64_t b_high = abs_b >> 32;
+    nk_u64_t b_low = abs_b & 0xFFFFFFFF;
+
+    // Compute partial products
+    nk_u64_t upper_product = a_high * b_high;
+    nk_u64_t cross_ab = a_high * b_low;
+    nk_u64_t cross_ba = a_low * b_high;
+    nk_u64_t lower_product = a_low * b_low;
+
+    // Check for overflow and saturate based on sign
+    nk_u64_t cross_sum = cross_ab + cross_ba;
+    if (upper_product || (cross_ab >> 32) || (cross_ba >> 32) || (cross_sum < cross_ab) || (cross_sum >> 32))
+        return (sign > 0) ? 9223372036854775807ll : (-9223372036854775807ll - 1ll);
+    // Combine parts if no overflow, then apply the sign
+    nk_u64_t result = (cross_sum << 32) + lower_product;
+    return (sign < 0) ? -((nk_i64_t)result) : (nk_i64_t)result;
+}
+
+NK_PUBLIC nk_i4x2_t nk_i4x2_saturating_add_serial(nk_i4x2_t a, nk_i4x2_t b) {
+    nk_i8_t low = nk_i4x2_low_(a) + nk_i4x2_low_(b);
+    nk_i8_t high = nk_i4x2_high_(a) + nk_i4x2_high_(b);
+    low = (low > 7) ? 7 : (low < -8 ? -8 : low);
+    high = (high > 7) ? 7 : (high < -8 ? -8 : high);
+    return (nk_i4x2_t)((low & 0x0F) | ((high & 0x0F) << 4));
+}
+NK_PUBLIC nk_u4x2_t nk_u4x2_saturating_add_serial(nk_u4x2_t a, nk_u4x2_t b) {
+    nk_u8_t low = nk_u4x2_low_(a) + nk_u4x2_low_(b);
+    nk_u8_t high = nk_u4x2_high_(a) + nk_u4x2_high_(b);
+    low = (low > 15) ? 15 : low;
+    high = (high > 15) ? 15 : high;
+    return (nk_u4x2_t)((low & 0x0F) | ((high & 0x0F) << 4));
+}
+NK_PUBLIC nk_i4x2_t nk_i4x2_saturating_mul_serial(nk_i4x2_t a, nk_i4x2_t b) {
+    nk_i8_t low = nk_i4x2_low_(a) * nk_i4x2_low_(b);
+    nk_i8_t high = nk_i4x2_high_(a) * nk_i4x2_high_(b);
+    low = (low > 7) ? 7 : (low < -8 ? -8 : low);
+    high = (high > 7) ? 7 : (high < -8 ? -8 : high);
+    return (nk_i4x2_t)((low & 0x0F) | ((high & 0x0F) << 4));
+}
+NK_PUBLIC nk_u4x2_t nk_u4x2_saturating_mul_serial(nk_u4x2_t a, nk_u4x2_t b) {
+    nk_u8_t low = nk_u4x2_low_(a) * nk_u4x2_low_(b);
+    nk_u8_t high = nk_u4x2_high_(a) * nk_u4x2_high_(b);
+    low = (low > 15) ? 15 : low;
+    high = (high > 15) ? 15 : high;
+    return (nk_u4x2_t)((low & 0x0F) | ((high & 0x0F) << 4));
+}
+
+NK_PUBLIC int nk_e4m3_order_serial(nk_e4m3_t a, nk_e4m3_t b) {
+    int sign_a = a >> 7, sign_b = b >> 7;
+    return (a ^ -sign_a) - (b ^ -sign_b);
+}
+NK_PUBLIC int nk_e5m2_order_serial(nk_e5m2_t a, nk_e5m2_t b) {
+    int sign_a = a >> 7, sign_b = b >> 7;
+    return (a ^ -sign_a) - (b ^ -sign_b);
+}
+
+NK_PUBLIC int nk_e2m3_order_serial(nk_e2m3_t a, nk_e2m3_t b) {
+    int value_a = a & 0x3F, value_b = b & 0x3F;
+    int sign_a = value_a >> 5, sign_b = value_b >> 5;
+    return (value_a ^ -sign_a) - (value_b ^ -sign_b);
+}
+NK_PUBLIC int nk_e3m2_order_serial(nk_e3m2_t a, nk_e3m2_t b) {
+    int value_a = a & 0x3F, value_b = b & 0x3F;
+    int sign_a = value_a >> 5, sign_b = value_b >> 5;
+    return (value_a ^ -sign_a) - (value_b ^ -sign_b);
+}
+
+NK_PUBLIC int nk_bf16_order_serial(nk_bf16_t a, nk_bf16_t b) {
+    nk_fui16_t a_fui, b_fui;
+    a_fui.bf = a, b_fui.bf = b;
+    int sign_a = a_fui.u >> 15, sign_b = b_fui.u >> 15;
+    return ((int)a_fui.u ^ -sign_a) - ((int)b_fui.u ^ -sign_b);
+}
+
+NK_PUBLIC int nk_f16_order_serial(nk_f16_t a, nk_f16_t b) {
+    nk_fui16_t a_fui, b_fui;
+    a_fui.f = a, b_fui.f = b;
+    int sign_a = a_fui.u >> 15, sign_b = b_fui.u >> 15;
+    return ((int)a_fui.u ^ -sign_a) - ((int)b_fui.u ^ -sign_b);
+}
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_SCALAR_SERIAL_H

package/numkong/include/numkong/scalar/v128relaxed.h

@@ -0,0 +1,56 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for WASM.
+ *  @file include/numkong/scalar/v128relaxed.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ */
+#ifndef NK_SCALAR_V128RELAXED_H
+#define NK_SCALAR_V128RELAXED_H
+
+#if NK_TARGET_V128RELAXED
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("relaxed-simd"))), apply_to = function)
+#endif
+
+NK_PUBLIC nk_f32_t nk_f32_sqrt_v128relaxed(nk_f32_t x) {
+    return wasm_f32x4_extract_lane(wasm_f32x4_sqrt(wasm_f32x4_splat(x)), 0);
+}
+NK_PUBLIC nk_f64_t nk_f64_sqrt_v128relaxed(nk_f64_t x) {
+    return wasm_f64x2_extract_lane(wasm_f64x2_sqrt(wasm_f64x2_splat(x)), 0);
+}
+NK_PUBLIC nk_f32_t nk_f32_rsqrt_v128relaxed(nk_f32_t x) {
+    v128_t sqrt_f32x4 = wasm_f32x4_sqrt(wasm_f32x4_splat(x));
+    return wasm_f32x4_extract_lane(wasm_f32x4_div(wasm_f32x4_splat(1.0f), sqrt_f32x4), 0);
+}
+NK_PUBLIC nk_f64_t nk_f64_rsqrt_v128relaxed(nk_f64_t x) {
+    v128_t sqrt_f64x2 = wasm_f64x2_sqrt(wasm_f64x2_splat(x));
+    return wasm_f64x2_extract_lane(wasm_f64x2_div(wasm_f64x2_splat(1.0), sqrt_f64x2), 0);
+}
+NK_PUBLIC nk_f32_t nk_f32_fma_v128relaxed(nk_f32_t a, nk_f32_t b, nk_f32_t c) {
+    v128_t result_f32x4 = wasm_f32x4_relaxed_madd(wasm_f32x4_splat(a), wasm_f32x4_splat(b), wasm_f32x4_splat(c));
+    return wasm_f32x4_extract_lane(result_f32x4, 0);
+}
+NK_PUBLIC nk_f64_t nk_f64_fma_v128relaxed(nk_f64_t a, nk_f64_t b, nk_f64_t c) {
+    v128_t result_f64x2 = wasm_f64x2_relaxed_madd(wasm_f64x2_splat(a), wasm_f64x2_splat(b), wasm_f64x2_splat(c));
+    return wasm_f64x2_extract_lane(result_f64x2, 0);
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_V128RELAXED
+#endif // NK_SCALAR_V128RELAXED_H