numkong 7.0.0

package/include/numkong/scalar/README.md

@@ -0,0 +1,89 @@
+# Scalar Math Primitives in NumKong
+
+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.
+
+Reciprocal square root:
+
+```math
+\text{rsqrt}(x) = \frac{1}{\sqrt{x}}
+```
+
+Fused multiply-add:
+
+```math
+\text{fma}(a, b, c) = a \cdot b + c
+```
+
+Saturating addition:
+
+```math
+\text{sat\_add}(a, b) = \text{clamp}(a + b, \text{T\_MIN}, \text{T\_MAX})
+```
+
+Reformulating as Python pseudocode:
+
+```python
+import numpy as np
+
+def rsqrt(x: float) -> float:
+    return 1.0 / np.sqrt(x)
+
+def fma(a: float, b: float, c: float) -> float:
+    return a * b + c
+
+def saturating_add(a: int, b: int, bits: int, signed: bool) -> int:
+    lo, hi = (-(1 << (bits-1)), (1 << (bits-1)) - 1) if signed else (0, (1 << bits) - 1)
+    return max(lo, min(a + b, hi))
+```
+
+## 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       |
+
+## Optimizations
+
+### Quake 3 Fast Inverse Square Root
+
+`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_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_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.
+
+## Performance
+
+Scalar primitives operate on single elements and are not independently benchmarked.
+Their performance is captured within the vector kernels that call them.

package/include/numkong/scalar/haswell.h

@@ -0,0 +1,113 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for Haswell.
+ *  @file include/numkong/scalar/haswell.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  @section scalars_haswell_instructions Key AVX2/FMA Scalar Instructions
+ *
+ *      Intrinsic                   Instruction                     Latency     Throughput  Ports
+ *      _mm_sqrt_ps                 VSQRTPS (XMM, XMM)              11cy        7cy         p0
+ *      _mm_sqrt_pd                 VSQRTPD (XMM, XMM)              16cy        12cy        p0
+ *      _mm_fmadd_ss                VFMADD (XMM, XMM, XMM)          5cy         0.5/cy      p01
+ *      _mm_fmadd_sd                VFMADD (XMM, XMM, XMM)          5cy         0.5/cy      p01
+ *      _mm_cvtps_ph                VCVTPS2PH (XMM, XMM, I8)        4cy         1/cy        p01+p5
+ *      _mm_cvtph_ps                VCVTPH2PS (XMM, XMM)            5cy         1/cy        p01
+ */
+#ifndef NK_SCALAR_HASWELL_H
+#define NK_SCALAR_HASWELL_H
+
+#if NK_TARGET_X86_
+#if NK_TARGET_HASWELL
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("avx2,f16c,fma,bmi,bmi2"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("avx2", "f16c", "fma", "bmi", "bmi2")
+#endif
+
+NK_PUBLIC nk_f32_t nk_f32_sqrt_haswell(nk_f32_t x) { return _mm_cvtss_f32(_mm_sqrt_ps(_mm_set_ss(x))); }
+NK_PUBLIC nk_f64_t nk_f64_sqrt_haswell(nk_f64_t x) { return _mm_cvtsd_f64(_mm_sqrt_pd(_mm_set_sd(x))); }
+NK_PUBLIC nk_f32_t nk_f32_rsqrt_haswell(nk_f32_t x) {
+    __m128 x_f32x4 = _mm_set_ss(x);
+    __m128 estimate_f32x4 = _mm_rsqrt_ss(x_f32x4);
+    __m128 refinement_f32x4 = _mm_mul_ss(_mm_mul_ss(x_f32x4, estimate_f32x4), estimate_f32x4);
+    refinement_f32x4 = _mm_sub_ss(_mm_set_ss(3.0f), refinement_f32x4);
+    return _mm_cvtss_f32(_mm_mul_ss(_mm_mul_ss(_mm_set_ss(0.5f), estimate_f32x4), refinement_f32x4));
+}
+NK_PUBLIC nk_f64_t nk_f64_rsqrt_haswell(nk_f64_t x) { return 1.0 / nk_f64_sqrt_haswell(x); }
+NK_PUBLIC nk_f32_t nk_f32_fma_haswell(nk_f32_t a, nk_f32_t b, nk_f32_t c) {
+    return _mm_cvtss_f32(_mm_fmadd_ss(_mm_set_ss(a), _mm_set_ss(b), _mm_set_ss(c)));
+}
+NK_PUBLIC nk_f64_t nk_f64_fma_haswell(nk_f64_t a, nk_f64_t b, nk_f64_t c) {
+    return _mm_cvtsd_f64(_mm_fmadd_sd(_mm_set_sd(a), _mm_set_sd(b), _mm_set_sd(c)));
+}
+NK_PUBLIC nk_f16_t nk_f16_sqrt_haswell(nk_f16_t x) {
+    __m128 x_f32x4 = _mm_cvtph_ps(_mm_cvtsi32_si128(x));
+    return (nk_f16_t)_mm_cvtsi128_si32(_mm_cvtps_ph(_mm_sqrt_ps(x_f32x4), _MM_FROUND_TO_NEAREST_INT));
+}
+NK_PUBLIC nk_f16_t nk_f16_rsqrt_haswell(nk_f16_t x) {
+    __m128 x_f32x4 = _mm_cvtph_ps(_mm_cvtsi32_si128(x));
+    __m128 estimate_f32x4 = _mm_rsqrt_ss(x_f32x4);
+    __m128 refinement_f32x4 = _mm_mul_ss(_mm_mul_ss(x_f32x4, estimate_f32x4), estimate_f32x4);
+    refinement_f32x4 = _mm_sub_ss(_mm_set_ss(3.0f), refinement_f32x4);
+    estimate_f32x4 = _mm_mul_ss(_mm_mul_ss(_mm_set_ss(0.5f), estimate_f32x4), refinement_f32x4);
+    return (nk_f16_t)_mm_cvtsi128_si32(_mm_cvtps_ph(estimate_f32x4, _MM_FROUND_TO_NEAREST_INT));
+}
+NK_PUBLIC nk_f16_t nk_f16_fma_haswell(nk_f16_t a, nk_f16_t b, nk_f16_t c) {
+    __m128 a_f32x4 = _mm_cvtph_ps(_mm_cvtsi32_si128(a));
+    __m128 b_f32x4 = _mm_cvtph_ps(_mm_cvtsi32_si128(b));
+    __m128 c_f32x4 = _mm_cvtph_ps(_mm_cvtsi32_si128(c));
+    return (nk_f16_t)_mm_cvtsi128_si32(
+        _mm_cvtps_ph(_mm_fmadd_ss(a_f32x4, b_f32x4, c_f32x4), _MM_FROUND_TO_NEAREST_INT));
+}
+NK_PUBLIC nk_u8_t nk_u8_saturating_add_haswell(nk_u8_t a, nk_u8_t b) {
+    return (nk_u8_t)_mm_cvtsi128_si32(_mm_adds_epu8(_mm_cvtsi32_si128(a), _mm_cvtsi32_si128(b)));
+}
+NK_PUBLIC nk_i8_t nk_i8_saturating_add_haswell(nk_i8_t a, nk_i8_t b) {
+    return (nk_i8_t)_mm_cvtsi128_si32(_mm_adds_epi8(_mm_cvtsi32_si128(a), _mm_cvtsi32_si128(b)));
+}
+NK_PUBLIC nk_u16_t nk_u16_saturating_add_haswell(nk_u16_t a, nk_u16_t b) {
+    return (nk_u16_t)_mm_cvtsi128_si32(_mm_adds_epu16(_mm_cvtsi32_si128(a), _mm_cvtsi32_si128(b)));
+}
+NK_PUBLIC nk_i16_t nk_i16_saturating_add_haswell(nk_i16_t a, nk_i16_t b) {
+    return (nk_i16_t)_mm_cvtsi128_si32(_mm_adds_epi16(_mm_cvtsi32_si128(a), _mm_cvtsi32_si128(b)));
+}
+NK_PUBLIC nk_u64_t nk_u64_saturating_mul_haswell(nk_u64_t a, nk_u64_t b) {
+    unsigned long long high;
+    unsigned long long low = _mulx_u64(a, b, &high);
+    return high ? 18446744073709551615ull : low;
+}
+NK_PUBLIC nk_i64_t nk_i64_saturating_mul_haswell(nk_i64_t a, nk_i64_t b) {
+    int sign = (a < 0) ^ (b < 0);
+    nk_u64_t abs_a = a < 0 ? -(nk_u64_t)a : (nk_u64_t)a;
+    nk_u64_t abs_b = b < 0 ? -(nk_u64_t)b : (nk_u64_t)b;
+    unsigned long long high;
+    unsigned long long low = _mulx_u64(abs_a, abs_b, &high);
+    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(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_HASWELL
+#endif // NK_TARGET_X86_
+#endif // NK_SCALAR_HASWELL_H

package/include/numkong/scalar/neon.h

@@ -0,0 +1,122 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for NEON.
+ *  @file include/numkong/scalar/neon.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  @section scalars_neon_instructions Key NEON Scalar Instructions
+ *
+ *      Intrinsic           Instruction                     Latency     Throughput
+ *      vsqrt_f32           FSQRT (S)                       9-12cy      0.25/cy
+ *      vsqrt_f64           FSQRT (D)                       12-18cy     0.25/cy
+ *      vfmas_f32           FMADD (S, S, S, S)              4cy         2/cy
+ *      vfmad_f64           FMADD (D, D, D, D)              4cy         2/cy
+ *      vqaddb_u8           UQADD (B)                       1cy         4/cy
+ *      vqaddb_s8           SQADD (B)                       1cy         4/cy
+ */
+#ifndef NK_SCALAR_NEON_H
+#define NK_SCALAR_NEON_H
+
+#if NK_TARGET_ARM_
+#if NK_TARGET_NEON
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=armv8-a+simd"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=armv8-a+simd")
+#endif
+
+NK_PUBLIC nk_f32_t nk_f32_sqrt_neon(nk_f32_t x) { return vget_lane_f32(vsqrt_f32(vdup_n_f32(x)), 0); }
+NK_PUBLIC nk_f64_t nk_f64_sqrt_neon(nk_f64_t x) { return vget_lane_f64(vsqrt_f64(vdup_n_f64(x)), 0); }
+NK_PUBLIC nk_f32_t nk_f32_rsqrt_neon(nk_f32_t x) {
+    nk_f32_t r = vrsqrtes_f32(x);
+    r *= vrsqrtss_f32(x * r, r);
+    r *= vrsqrtss_f32(x * r, r);
+    return r;
+}
+NK_PUBLIC nk_f64_t nk_f64_rsqrt_neon(nk_f64_t x) {
+    nk_f64_t r = vrsqrted_f64(x);
+    r *= vrsqrtsd_f64(x * r, r);
+    r *= vrsqrtsd_f64(x * r, r);
+    r *= vrsqrtsd_f64(x * r, r);
+    return r;
+}
+NK_PUBLIC nk_f32_t nk_f32_fma_neon(nk_f32_t a, nk_f32_t b, nk_f32_t c) {
+    // MSVC lacks both GCC inline asm and scalar ACLE FMA intrinsics (vfmas_f32/vfmad_f64).
+    // GCC/Clang: use inline asm for scalar FMADD.
+    // MSVC: use vector FMA + lane extract (compiler may optimize to scalar FMADD).
+#if defined(_MSC_VER)
+    return vget_lane_f32(vfma_f32(vdup_n_f32(c), vdup_n_f32(a), vdup_n_f32(b)), 0);
+#else
+    nk_f32_t r;
+    __asm__("fmadd %s0, %s1, %s2, %s3" : "=w"(r) : "w"(a), "w"(b), "w"(c));
+    return r;
+#endif
+}
+NK_PUBLIC nk_f64_t nk_f64_fma_neon(nk_f64_t a, nk_f64_t b, nk_f64_t c) {
+    // MSVC lacks both GCC inline asm and scalar ACLE FMA intrinsics (vfmas_f32/vfmad_f64).
+    // GCC/Clang: use inline asm for scalar FMADD.
+    // MSVC: use vector FMA + lane extract (compiler may optimize to scalar FMADD).
+#if defined(_MSC_VER)
+    return vget_lane_f64(vfma_f64(vdup_n_f64(c), vdup_n_f64(a), vdup_n_f64(b)), 0);
+#else
+    nk_f64_t r;
+    __asm__("fmadd %d0, %d1, %d2, %d3" : "=w"(r) : "w"(a), "w"(b), "w"(c));
+    return r;
+#endif
+}
+
+NK_PUBLIC nk_u8_t nk_u8_saturating_add_neon(nk_u8_t a, nk_u8_t b) { return vqaddb_u8(a, b); }
+NK_PUBLIC nk_i8_t nk_i8_saturating_add_neon(nk_i8_t a, nk_i8_t b) { return vqaddb_s8(a, b); }
+NK_PUBLIC nk_u16_t nk_u16_saturating_add_neon(nk_u16_t a, nk_u16_t b) { return vqaddh_u16(a, b); }
+NK_PUBLIC nk_i16_t nk_i16_saturating_add_neon(nk_i16_t a, nk_i16_t b) { return vqaddh_s16(a, b); }
+NK_PUBLIC nk_u32_t nk_u32_saturating_add_neon(nk_u32_t a, nk_u32_t b) { return vqadds_u32(a, b); }
+NK_PUBLIC nk_i32_t nk_i32_saturating_add_neon(nk_i32_t a, nk_i32_t b) { return vqadds_s32(a, b); }
+NK_PUBLIC nk_u64_t nk_u64_saturating_add_neon(nk_u64_t a, nk_u64_t b) { return vqaddd_u64(a, b); }
+NK_PUBLIC nk_i64_t nk_i64_saturating_add_neon(nk_i64_t a, nk_i64_t b) { return vqaddd_s64(a, b); }
+
+NK_INTERNAL nk_u64_t nk_u64_mulhigh_neon_(nk_u64_t a, nk_u64_t b) {
+#if defined(_MSC_VER)
+    return __umulh(a, b);
+#else
+    nk_u64_t high;
+    __asm__("umulh %0, %1, %2" : "=r"(high) : "r"(a), "r"(b));
+    return high;
+#endif
+}
+NK_PUBLIC nk_u64_t nk_u64_saturating_mul_neon(nk_u64_t a, nk_u64_t b) {
+    return nk_u64_mulhigh_neon_(a, b) ? 18446744073709551615ull : (a * b);
+}
+NK_PUBLIC nk_i64_t nk_i64_saturating_mul_neon(nk_i64_t a, nk_i64_t b) {
+    int sign = (a < 0) ^ (b < 0);
+    nk_u64_t abs_a = a < 0 ? -(nk_u64_t)a : (nk_u64_t)a;
+    nk_u64_t abs_b = b < 0 ? -(nk_u64_t)b : (nk_u64_t)b;
+    nk_u64_t high = nk_u64_mulhigh_neon_(abs_a, abs_b);
+    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(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_NEON
+#endif // NK_TARGET_ARM_
+#endif // NK_SCALAR_NEON_H

package/include/numkong/scalar/neonhalf.h

@@ -0,0 +1,70 @@
+/**
+ *  @brief SIMD-accelerated Scalar Math Helpers for NEON FP16 (FEAT_FP16).
+ *  @file include/numkong/scalar/neonhalf.h
+ *  @author Ash Vardanian
+ *  @date March 1, 2026
+ *
+ *  @sa include/numkong/scalar.h
+ *
+ *  ARMv8.2-A FEAT_FP16 provides native scalar f16 sqrt, rsqrt estimate, and fma.
+ *  `vrsqrte_f16` gives ~4-bit estimate; 2 Newton-Raphson steps refine to ~16 bits,
+ *  exceeding f16's 10-bit mantissa precision.
+ */
+#ifndef NK_SCALAR_NEONHALF_H
+#define NK_SCALAR_NEONHALF_H
+
+#if NK_TARGET_ARM_
+#if NK_TARGET_NEONHALF
+
+#include "numkong/types.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=armv8.2-a+simd+fp16"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=armv8.2-a+simd+fp16")
+#endif
+
+NK_PUBLIC nk_f16_t nk_f16_sqrt_neonhalf(nk_f16_t x) {
+    float16x4_t x_f16x4 = vld1_dup_f16((nk_f16_for_arm_simd_t const *)&x);
+    x_f16x4 = vsqrt_f16(x_f16x4);
+    nk_f16_t result;
+    vst1_lane_f16((nk_f16_for_arm_simd_t *)&result, x_f16x4, 0);
+    return result;
+}
+NK_PUBLIC nk_f16_t nk_f16_rsqrt_neonhalf(nk_f16_t x) {
+    float16x4_t x_f16x4 = vld1_dup_f16((nk_f16_for_arm_simd_t const *)&x);
+    float16x4_t estimate_f16x4 = vrsqrte_f16(x_f16x4);
+    estimate_f16x4 = vmul_f16(estimate_f16x4, vrsqrts_f16(vmul_f16(x_f16x4, estimate_f16x4), estimate_f16x4));
+    estimate_f16x4 = vmul_f16(estimate_f16x4, vrsqrts_f16(vmul_f16(x_f16x4, estimate_f16x4), estimate_f16x4));
+    nk_f16_t result;
+    vst1_lane_f16((nk_f16_for_arm_simd_t *)&result, estimate_f16x4, 0);
+    return result;
+}
+NK_PUBLIC nk_f16_t nk_f16_fma_neonhalf(nk_f16_t a, nk_f16_t b, nk_f16_t c) {
+    float16x4_t a_f16x4 = vld1_dup_f16((nk_f16_for_arm_simd_t const *)&a);
+    float16x4_t b_f16x4 = vld1_dup_f16((nk_f16_for_arm_simd_t const *)&b);
+    float16x4_t c_f16x4 = vld1_dup_f16((nk_f16_for_arm_simd_t const *)&c);
+    c_f16x4 = vfma_f16(c_f16x4, a_f16x4, b_f16x4);
+    nk_f16_t result;
+    vst1_lane_f16((nk_f16_for_arm_simd_t *)&result, c_f16x4, 0);
+    return result;
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_NEONHALF
+#endif // NK_TARGET_ARM_
+#endif // NK_SCALAR_NEONHALF_H

package/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_RISCV_
+#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 ? -(nk_u64_t)a : (nk_u64_t)a;
+    nk_u64_t abs_b = b < 0 ? -(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_RISCV_
+#endif // NK_SCALAR_RVV_H

package/include/numkong/scalar/sapphire.h

@@ -0,0 +1,63 @@
+/**
+ *  @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_X86_
+#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) {
+    __m128h a_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(a));
+    __m128h b_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(b));
+    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) {
+    __m128h x_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(x));
+    return (nk_f16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_sqrt_sh(x_f16x8, x_f16x8)));
+}
+NK_PUBLIC nk_f16_t nk_f16_rsqrt_sapphire(nk_f16_t x) {
+    __m128h x_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(x));
+    return (nk_f16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_rsqrt_sh(x_f16x8, x_f16x8)));
+}
+NK_PUBLIC nk_f16_t nk_f16_fma_sapphire(nk_f16_t a, nk_f16_t b, nk_f16_t c) {
+    __m128h a_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(a));
+    __m128h b_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(b));
+    __m128h c_f16x8 = _mm_castsi128_ph(_mm_cvtsi32_si128(c));
+    return (nk_f16_t)_mm_cvtsi128_si32(_mm_castph_si128(_mm_fmadd_sh(a_f16x8, b_f16x8, c_f16x8)));
+}
+
+#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_X86_
+#endif // NK_SCALAR_SAPPHIRE_H