numkong 7.0.0

package/include/numkong/spatial/sve.h

@@ -0,0 +1,224 @@
+/**
+ *  @brief SIMD-accelerated Spatial Similarity Measures for SVE.
+ *  @file include/numkong/spatial/sve.h
+ *  @author Ash Vardanian
+ *  @date December 27, 2025
+ *
+ *  @sa include/numkong/spatial.h
+ *
+ *  @section spatial_sve_instructions ARM SVE Instructions
+ *
+ *      Intrinsic                   Instruction                     Latency     Throughput
+ *      svld1_f32                   LD1W (Z.S, P/Z, [Xn])           4-6cy       2/cy
+ *      svsub_f32_x                 FSUB (Z.S, P/M, Z.S, Z.S)       3cy         2/cy
+ *      svmla_f32_x                 FMLA (Z.S, P/M, Z.S, Z.S)       4cy         2/cy
+ *      svaddv_f32                  FADDV (S, P, Z.S)               6cy         1/cy
+ *      svdupq_n_f32                DUP (Z.S, #imm)                 1cy         2/cy
+ *      svwhilelt_b32               WHILELT (P.S, Xn, Xm)           2cy         1/cy
+ *      svptrue_b32                 PTRUE (P.S, pattern)            1cy         2/cy
+ *      svcntw                      CNTW (Xd)                       1cy         2/cy
+ *      svld1_f64                   LD1D (Z.D, P/Z, [Xn])           4-6cy       2/cy
+ *      svsub_f64_x                 FSUB (Z.D, P/M, Z.D, Z.D)       3cy         2/cy
+ *      svmla_f64_x                 FMLA (Z.D, P/M, Z.D, Z.D)       4cy         2/cy
+ *      svaddv_f64                  FADDV (D, P, Z.D)               6cy         1/cy
+ *
+ *  SVE vector widths vary across implementations: Graviton3 uses 256-bit, while Graviton4/5
+ *  and Apple M4+ use 128-bit. Code using svcntb() adapts automatically, but wider vectors
+ *  process more elements per iteration with identical latencies.
+ *
+ *  Spatial operations like L2 distance and angular similarity benefit from SVE's fused
+ *  multiply-add instructions. The FADDV reduction dominates the critical path for short vectors.
+ */
+#ifndef NK_SPATIAL_SVE_H
+#define NK_SPATIAL_SVE_H
+
+#if NK_TARGET_ARM_
+#if NK_TARGET_SVE
+
+#include "numkong/types.h"
+#include "numkong/spatial/neon.h" // `nk_f64_sqrt_neon`
+#include "numkong/dot/sve.h"      // `nk_dot_stable_sum_f64_sve_`
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=armv8.2-a+sve"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=armv8.2-a+sve")
+#endif
+
+/** @brief Reciprocal square root of an f32 SVE vector via estimate + 2 Newton-Raphson steps.
+ *
+ *  Computes 1/sqrt(x) for each active lane. The initial estimate from `svrsqrte_f32`
+ *  has ~8 bits of precision; each Newton-Raphson iteration via `svrsqrts_f32` roughly
+ *  doubles the mantissa bits, giving ~23 bits (~full f32 precision) after 2 steps.
+ *
+ *  Marked `__arm_streaming_compatible` so the helper is callable from both streaming
+ *  (SME) and non-streaming (SVE) contexts without mode transitions.
+ *
+ *  @param predicate Active-lane mask
+ *  @param x         Input vector (must be positive for meaningful results)
+ *  @return          Approximate 1/sqrt(x) with ~23-bit mantissa accuracy
+ */
+NK_INTERNAL svfloat32_t nk_rsqrt_f32x_sve_(svbool_t predicate, svfloat32_t x) NK_STREAMING_COMPATIBLE_ {
+    svfloat32_t r = svrsqrte_f32(x);
+    r = svmul_f32_x(predicate, r, svrsqrts_f32(svmul_f32_x(predicate, x, r), r));
+    r = svmul_f32_x(predicate, r, svrsqrts_f32(svmul_f32_x(predicate, x, r), r));
+    return r;
+}
+
+/** @brief Reciprocal square root of an f64 SVE vector via estimate + 3 Newton-Raphson steps.
+ *
+ *  Computes 1/sqrt(x) for each active lane. The initial estimate from `svrsqrte_f64`
+ *  has ~8 bits of precision; three Newton-Raphson iterations via `svrsqrts_f64` yield
+ *  ~52-bit mantissa accuracy (full f64 precision).
+ *
+ *  Marked `__arm_streaming_compatible` so the helper is callable from both streaming
+ *  (SME) and non-streaming (SVE) contexts without mode transitions.
+ *
+ *  @param predicate Active-lane mask
+ *  @param x         Input vector (must be positive for meaningful results)
+ *  @return          Approximate 1/sqrt(x) with ~52-bit mantissa accuracy
+ */
+NK_INTERNAL svfloat64_t nk_rsqrt_f64x_sve_(svbool_t predicate, svfloat64_t x) NK_STREAMING_COMPATIBLE_ {
+    svfloat64_t r = svrsqrte_f64(x);
+    r = svmul_f64_x(predicate, r, svrsqrts_f64(svmul_f64_x(predicate, x, r), r));
+    r = svmul_f64_x(predicate, r, svrsqrts_f64(svmul_f64_x(predicate, x, r), r));
+    r = svmul_f64_x(predicate, r, svrsqrts_f64(svmul_f64_x(predicate, x, r), r));
+    return r;
+}
+
+NK_PUBLIC void nk_sqeuclidean_f32_sve(nk_f32_t const *a, nk_f32_t const *b, nk_size_t n, nk_f64_t *result) {
+    nk_size_t i = 0;
+    nk_size_t const vector_length = svcntd();
+    svfloat64_t dist_sq_f64x = svdupq_n_f64(0.0, 0.0);
+    for (; i < n; i += vector_length) {
+        svbool_t predicate_f32x = svwhilelt_b32_u64(i, n);
+        svbool_t predicate_f64x = svwhilelt_b64_u64(i, n);
+        svfloat64_t a_f64x = svcvt_f64_f32_x(predicate_f64x, svld1_f32(predicate_f32x, a + i));
+        svfloat64_t b_f64x = svcvt_f64_f32_x(predicate_f64x, svld1_f32(predicate_f32x, b + i));
+        svfloat64_t diff_f64x = svsub_f64_x(predicate_f64x, a_f64x, b_f64x);
+        dist_sq_f64x = svmla_f64_x(predicate_f64x, dist_sq_f64x, diff_f64x, diff_f64x);
+    }
+    nk_f64_t dist_sq_f64 = svaddv_f64(svptrue_b64(), dist_sq_f64x);
+    *result = dist_sq_f64;
+}
+
+NK_PUBLIC void nk_euclidean_f32_sve(nk_f32_t const *a, nk_f32_t const *b, nk_size_t n, nk_f64_t *result) {
+    nk_sqeuclidean_f32_sve(a, b, n, result);
+    *result = nk_f64_sqrt_neon(*result);
+}
+
+NK_PUBLIC void nk_angular_f32_sve(nk_f32_t const *a, nk_f32_t const *b, nk_size_t n, nk_f64_t *result) {
+    nk_size_t i = 0;
+    nk_size_t const vector_length = svcntd();
+    svfloat64_t ab_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t a2_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t b2_f64x = svdupq_n_f64(0.0, 0.0);
+    for (; i < n; i += vector_length) {
+        svbool_t predicate_f32x = svwhilelt_b32_u64(i, n);
+        svbool_t predicate_f64x = svwhilelt_b64_u64(i, n);
+        svfloat64_t a_f64x = svcvt_f64_f32_x(predicate_f64x, svld1_f32(predicate_f32x, a + i));
+        svfloat64_t b_f64x = svcvt_f64_f32_x(predicate_f64x, svld1_f32(predicate_f32x, b + i));
+        ab_f64x = svmla_f64_x(predicate_f64x, ab_f64x, a_f64x, b_f64x);
+        a2_f64x = svmla_f64_x(predicate_f64x, a2_f64x, a_f64x, a_f64x);
+        b2_f64x = svmla_f64_x(predicate_f64x, b2_f64x, b_f64x, b_f64x);
+    }
+
+    nk_f64_t ab_f64 = svaddv_f64(svptrue_b64(), ab_f64x);
+    nk_f64_t a2_f64 = svaddv_f64(svptrue_b64(), a2_f64x);
+    nk_f64_t b2_f64 = svaddv_f64(svptrue_b64(), b2_f64x);
+    *result = nk_angular_normalize_f64_neon_(ab_f64, a2_f64, b2_f64);
+}
+
+NK_PUBLIC void nk_sqeuclidean_f64_sve(nk_f64_t const *a, nk_f64_t const *b, nk_size_t n, nk_f64_t *result) {
+    // Neumaier compensated summation for numerical stability
+    nk_size_t i = 0;
+    svfloat64_t sum_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t compensation_f64x = svdupq_n_f64(0.0, 0.0);
+    svbool_t predicate_all_f64x = svptrue_b64();
+    do {
+        svbool_t predicate_f64x = svwhilelt_b64_u64(i, n);
+        svfloat64_t a_f64x = svld1_f64(predicate_f64x, a + i);
+        svfloat64_t b_f64x = svld1_f64(predicate_f64x, b + i);
+        svfloat64_t diff_f64x = svsub_f64_x(predicate_f64x, a_f64x, b_f64x);
+        svfloat64_t diff_sq_f64x = svmul_f64_x(predicate_f64x, diff_f64x, diff_f64x);
+        // Neumaier: t = sum + x
+        svfloat64_t t_f64x = svadd_f64_x(predicate_f64x, sum_f64x, diff_sq_f64x);
+        svfloat64_t abs_sum_f64x = svabs_f64_x(predicate_f64x, sum_f64x);
+        // diff_sq is already non-negative (it's a square), so svabs is unnecessary
+        svbool_t sum_ge_x_f64x = svcmpge_f64(predicate_f64x, abs_sum_f64x, diff_sq_f64x);
+        // When |sum| >= |x|: comp += (sum - t) + x; when |x| > |sum|: comp += (x - t) + sum
+        svfloat64_t comp_sum_large_f64x = svadd_f64_x(predicate_f64x, svsub_f64_x(predicate_f64x, sum_f64x, t_f64x),
+                                                      diff_sq_f64x);
+        svfloat64_t comp_x_large_f64x = svadd_f64_x(predicate_f64x, svsub_f64_x(predicate_f64x, diff_sq_f64x, t_f64x),
+                                                    sum_f64x);
+        svfloat64_t comp_update_f64x = svsel_f64(sum_ge_x_f64x, comp_sum_large_f64x, comp_x_large_f64x);
+        compensation_f64x = svadd_f64_x(predicate_f64x, compensation_f64x, comp_update_f64x);
+        sum_f64x = t_f64x;
+        i += svcntd();
+    } while (i < n);
+    *result = nk_dot_stable_sum_f64_sve_(predicate_all_f64x, sum_f64x, compensation_f64x);
+}
+
+NK_PUBLIC void nk_euclidean_f64_sve(nk_f64_t const *a, nk_f64_t const *b, nk_size_t n, nk_f64_t *result) {
+    nk_sqeuclidean_f64_sve(a, b, n, result);
+    *result = nk_f64_sqrt_neon(*result);
+}
+
+NK_PUBLIC void nk_angular_f64_sve(nk_f64_t const *a, nk_f64_t const *b, nk_size_t n, nk_f64_t *result) {
+    // Dot2 (Ogita-Rump-Oishi) for cross-product ab (may have cancellation),
+    // simple FMA for self-products a2/b2 (all positive, no cancellation)
+    nk_size_t i = 0;
+    svfloat64_t ab_sum_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t ab_compensation_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t a2_f64x = svdupq_n_f64(0.0, 0.0);
+    svfloat64_t b2_f64x = svdupq_n_f64(0.0, 0.0);
+    svbool_t predicate_all_f64x = svptrue_b64();
+    do {
+        svbool_t predicate_f64x = svwhilelt_b64_u64(i, n);
+        svfloat64_t a_f64x = svld1_f64(predicate_f64x, a + i);
+        svfloat64_t b_f64x = svld1_f64(predicate_f64x, b + i);
+        // TwoProd for ab: product = a*b, error = fma(a,b,-product) = -(product - a*b)
+        svfloat64_t product_f64x = svmul_f64_x(predicate_f64x, a_f64x, b_f64x);
+        svfloat64_t product_error_f64x = svneg_f64_x(predicate_f64x,
+                                                     svnmls_f64_x(predicate_f64x, product_f64x, a_f64x, b_f64x));
+        // TwoSum: (tentative_sum, sum_error) = TwoSum(sum, product)
+        svfloat64_t tentative_sum_f64x = svadd_f64_x(predicate_f64x, ab_sum_f64x, product_f64x);
+        svfloat64_t virtual_addend_f64x = svsub_f64_x(predicate_f64x, tentative_sum_f64x, ab_sum_f64x);
+        svfloat64_t sum_error_f64x = svadd_f64_x(
+            predicate_f64x,
+            svsub_f64_x(predicate_f64x, ab_sum_f64x,
+                        svsub_f64_x(predicate_f64x, tentative_sum_f64x, virtual_addend_f64x)),
+            svsub_f64_x(predicate_f64x, product_f64x, virtual_addend_f64x));
+        ab_sum_f64x = tentative_sum_f64x;
+        ab_compensation_f64x = svadd_f64_x(predicate_f64x, ab_compensation_f64x,
+                                           svadd_f64_x(predicate_f64x, sum_error_f64x, product_error_f64x));
+        // Simple FMA for self-products (no cancellation)
+        a2_f64x = svmla_f64_x(predicate_f64x, a2_f64x, a_f64x, a_f64x);
+        b2_f64x = svmla_f64_x(predicate_f64x, b2_f64x, b_f64x, b_f64x);
+        i += svcntd();
+    } while (i < n);
+
+    nk_f64_t ab_f64 = nk_dot_stable_sum_f64_sve_(predicate_all_f64x, ab_sum_f64x, ab_compensation_f64x);
+    nk_f64_t a2_f64 = svaddv_f64(predicate_all_f64x, a2_f64x);
+    nk_f64_t b2_f64 = svaddv_f64(predicate_all_f64x, b2_f64x);
+    *result = nk_angular_normalize_f64_neon_(ab_f64, a2_f64, b2_f64);
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_SVE
+#endif // NK_TARGET_ARM_
+#endif // NK_SPATIAL_SVE_H

package/include/numkong/spatial/svebfdot.h

@@ -0,0 +1,122 @@
+/**
+ *  @brief SIMD-accelerated Spatial Similarity Measures for SVE BF16.
+ *  @file include/numkong/spatial/sve.h
+ *  @author Ash Vardanian
+ *  @date December 27, 2025
+ *
+ *  @sa include/numkong/spatial.h
+ *
+ *  @section spatial_svebfdot_instructions ARM SVE+BF16 Instructions
+ *
+ *      Intrinsic                   Instruction                     Latency     Throughput
+ *      svld1_bf16                  LD1H (Z.H, P/Z, [Xn])           4-6cy       2/cy
+ *      svld1_u16                   LD1H (Z.H, P/Z, [Xn])           4-6cy       2/cy
+ *      svbfdot_f32                 BFDOT (Z.S, Z.H, Z.H)           4cy         2/cy
+ *      svmla_f32_x                 FMLA (Z.S, P/M, Z.S, Z.S)       4cy         2/cy
+ *      svsub_f32_x                 FSUB (Z.S, P/M, Z.S, Z.S)       3cy         2/cy
+ *      svaddv_f32                  FADDV (S, P, Z.S)               6cy         1/cy
+ *      svunpklo_u32                UUNPKLO (Z.S, Z.H)              2cy         2/cy
+ *      svunpkhi_u32                UUNPKHI (Z.S, Z.H)              2cy         2/cy
+ *      svlsl_n_u32_x               LSL (Z.S, P/M, Z.S, #imm)       2cy         2/cy
+ *      svwhilelt_b16               WHILELT (P.H, Xn, Xm)           2cy         1/cy
+ *      svwhilelt_b32               WHILELT (P.S, Xn, Xm)           2cy         1/cy
+ *      svcnth                      CNTH (Xd)                       1cy         2/cy
+ *
+ *  SVE vector widths vary across implementations: Graviton3 uses 256-bit, while Graviton4/5
+ *  and Apple M4+ use 128-bit. Code using svcntb() adapts automatically, but wider vectors
+ *  process more elements per iteration with identical latencies.
+ *
+ *  The BFDOT instruction fuses two BF16 multiplications with FP32 accumulation, providing
+ *  efficient BF16 dot products without explicit conversion overhead.
+ */
+#ifndef NK_SPATIAL_SVEBFDOT_H
+#define NK_SPATIAL_SVEBFDOT_H
+
+#if NK_TARGET_ARM_
+#if NK_TARGET_SVEBFDOT
+
+#include "numkong/types.h"
+#include "numkong/spatial/neon.h" // `nk_f32_sqrt_neon`
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=armv8.2-a+sve+bf16"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=armv8.2-a+sve+bf16")
+#endif
+
+NK_PUBLIC void nk_sqeuclidean_bf16_svebfdot(nk_bf16_t const *a_enum, nk_bf16_t const *b_enum, nk_size_t n,
+                                            nk_f32_t *result) {
+    nk_size_t i = 0;
+    svfloat32_t d2_low_f32x = svdupq_n_f32(0.f, 0.f, 0.f, 0.f);
+    svfloat32_t d2_high_f32x = svdupq_n_f32(0.f, 0.f, 0.f, 0.f);
+    nk_u16_t const *a = (nk_u16_t const *)(a_enum);
+    nk_u16_t const *b = (nk_u16_t const *)(b_enum);
+    do {
+        svbool_t predicate_bf16x = svwhilelt_b16_u64(i, n);
+        svuint16_t a_u16x = svld1_u16(predicate_bf16x, a + i);
+        svuint16_t b_u16x = svld1_u16(predicate_bf16x, b + i);
+
+        // There is no `bf16` subtraction in SVE, so we need to convert to `u32` and shift.
+        svbool_t predicate_low_f32x = svwhilelt_b32_u64(i, n);
+        svbool_t predicate_high_f32x = svwhilelt_b32_u64(i + svcnth() / 2, n);
+        svfloat32_t a_low_f32x = svreinterpret_f32_u32(svlsl_n_u32_x(predicate_low_f32x, svunpklo_u32(a_u16x), 16));
+        svfloat32_t a_high_f32x = svreinterpret_f32_u32(svlsl_n_u32_x(predicate_high_f32x, svunpkhi_u32(a_u16x), 16));
+        svfloat32_t b_low_f32x = svreinterpret_f32_u32(svlsl_n_u32_x(predicate_low_f32x, svunpklo_u32(b_u16x), 16));
+        svfloat32_t b_high_f32x = svreinterpret_f32_u32(svlsl_n_u32_x(predicate_high_f32x, svunpkhi_u32(b_u16x), 16));
+
+        svfloat32_t a_minus_b_low_f32x = svsub_f32_x(predicate_low_f32x, a_low_f32x, b_low_f32x);
+        svfloat32_t a_minus_b_high_f32x = svsub_f32_x(predicate_high_f32x, a_high_f32x, b_high_f32x);
+        d2_low_f32x = svmla_f32_x(predicate_bf16x, d2_low_f32x, a_minus_b_low_f32x, a_minus_b_low_f32x);
+        d2_high_f32x = svmla_f32_x(predicate_bf16x, d2_high_f32x, a_minus_b_high_f32x, a_minus_b_high_f32x);
+        i += svcnth();
+    } while (i < n);
+    nk_f32_t d2 = svaddv_f32(svptrue_b32(), d2_low_f32x) + svaddv_f32(svptrue_b32(), d2_high_f32x);
+    *result = d2;
+}
+NK_PUBLIC void nk_euclidean_bf16_svebfdot(nk_bf16_t const *a, nk_bf16_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_sqeuclidean_bf16_svebfdot(a, b, n, result);
+    *result = nk_f32_sqrt_neon(*result);
+}
+
+NK_PUBLIC void nk_angular_bf16_svebfdot(nk_bf16_t const *a_enum, nk_bf16_t const *b_enum, nk_size_t n,
+                                        nk_f32_t *result) {
+    nk_size_t i = 0;
+    svfloat32_t ab_f32x = svdupq_n_f32(0.f, 0.f, 0.f, 0.f);
+    svfloat32_t a2_f32x = svdupq_n_f32(0.f, 0.f, 0.f, 0.f);
+    svfloat32_t b2_f32x = svdupq_n_f32(0.f, 0.f, 0.f, 0.f);
+    nk_bf16_for_arm_simd_t const *a = (nk_bf16_for_arm_simd_t const *)(a_enum);
+    nk_bf16_for_arm_simd_t const *b = (nk_bf16_for_arm_simd_t const *)(b_enum);
+    do {
+        svbool_t predicate_bf16x = svwhilelt_b16_u64(i, n);
+        svbfloat16_t a_bf16x = svld1_bf16(predicate_bf16x, a + i);
+        svbfloat16_t b_bf16x = svld1_bf16(predicate_bf16x, b + i);
+        ab_f32x = svbfdot_f32(ab_f32x, a_bf16x, b_bf16x);
+        a2_f32x = svbfdot_f32(a2_f32x, a_bf16x, a_bf16x);
+        b2_f32x = svbfdot_f32(b2_f32x, b_bf16x, b_bf16x);
+        i += svcnth();
+    } while (i < n);
+
+    nk_f32_t ab = svaddv_f32(svptrue_b32(), ab_f32x);
+    nk_f32_t a2 = svaddv_f32(svptrue_b32(), a2_f32x);
+    nk_f32_t b2 = svaddv_f32(svptrue_b32(), b2_f32x);
+    *result = nk_angular_normalize_f32_neon_(ab, a2, b2);
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_SVEBFDOT
+#endif // NK_TARGET_ARM_
+#endif // NK_SPATIAL_SVEBFDOT_H

package/include/numkong/spatial/svehalf.h

@@ -0,0 +1,109 @@
+/**
+ *  @brief SIMD-accelerated Spatial Similarity Measures for SVE FP16.
+ *  @file include/numkong/spatial/sve.h
+ *  @author Ash Vardanian
+ *  @date December 27, 2025
+ *
+ *  @sa include/numkong/spatial.h
+ *
+ *  @section spatial_svehalf_instructions ARM SVE+FP16 Instructions
+ *
+ *      Intrinsic                   Instruction                     Latency     Throughput
+ *      svld1_f16                   LD1H (Z.H, P/Z, [Xn])           4-6cy       2/cy
+ *      svsub_f16_x                 FSUB (Z.H, P/M, Z.H, Z.H)       3cy         2/cy
+ *      svmla_f16_x                 FMLA (Z.H, P/M, Z.H, Z.H)       4cy         2/cy
+ *      svaddv_f16                  FADDV (H, P, Z.H)               6cy         1/cy
+ *      svdupq_n_f16                DUP (Z.H, #imm)                 1cy         2/cy
+ *      svwhilelt_b16               WHILELT (P.H, Xn, Xm)           2cy         1/cy
+ *      svptrue_b16                 PTRUE (P.H, pattern)            1cy         2/cy
+ *      svcnth                      CNTH (Xd)                       1cy         2/cy
+ *
+ *  SVE vector widths vary across implementations: Graviton3 uses 256-bit, while Graviton4/5
+ *  and Apple M4+ use 128-bit. Code using svcntb() adapts automatically, but wider vectors
+ *  process more elements per iteration with identical latencies.
+ *
+ *  FP16 spatial operations trade precision for throughput, processing twice as many elements
+ *  per cycle. This is particularly effective for embedding similarity in ML applications.
+ */
+#ifndef NK_SPATIAL_SVEHALF_H
+#define NK_SPATIAL_SVEHALF_H
+
+#if NK_TARGET_ARM_
+#if NK_TARGET_SVEHALF
+
+#include "numkong/types.h"
+#include "numkong/spatial/neon.h" // `nk_f32_sqrt_neon`
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if defined(__clang__)
+#pragma clang attribute push(__attribute__((target("arch=armv8.2-a+sve+fp16"))), apply_to = function)
+#elif defined(__GNUC__)
+#pragma GCC push_options
+#pragma GCC target("arch=armv8.2-a+sve+fp16")
+#endif
+
+NK_PUBLIC void nk_sqeuclidean_f16_svehalf(nk_f16_t const *a_enum, nk_f16_t const *b_enum, nk_size_t n,
+                                          nk_f32_t *result) {
+    nk_size_t i = 0;
+    svfloat32_t d2_f32x = svdup_n_f32(0.0f);
+    nk_f16_for_arm_simd_t const *a = (nk_f16_for_arm_simd_t const *)(a_enum);
+    nk_f16_for_arm_simd_t const *b = (nk_f16_for_arm_simd_t const *)(b_enum);
+    do {
+        svbool_t predicate_f32x = svwhilelt_b32_u64(i, n);
+        svfloat16_t a_f16x = svld1_f16(svwhilelt_b16_u64(i, n), a + i);
+        svfloat16_t b_f16x = svld1_f16(svwhilelt_b16_u64(i, n), b + i);
+        svfloat32_t a_f32x = svcvt_f32_f16_x(predicate_f32x, a_f16x);
+        svfloat32_t b_f32x = svcvt_f32_f16_x(predicate_f32x, b_f16x);
+        svfloat32_t diff_f32x = svsub_f32_x(predicate_f32x, a_f32x, b_f32x);
+        d2_f32x = svmla_f32_x(predicate_f32x, d2_f32x, diff_f32x, diff_f32x);
+        i += svcntw();
+    } while (i < n);
+    *result = svaddv_f32(svptrue_b32(), d2_f32x);
+}
+
+NK_PUBLIC void nk_euclidean_f16_svehalf(nk_f16_t const *a, nk_f16_t const *b, nk_size_t n, nk_f32_t *result) {
+    nk_sqeuclidean_f16_svehalf(a, b, n, result);
+    *result = nk_f32_sqrt_neon(*result);
+}
+
+NK_PUBLIC void nk_angular_f16_svehalf(nk_f16_t const *a_enum, nk_f16_t const *b_enum, nk_size_t n, nk_f32_t *result) {
+    nk_size_t i = 0;
+    svfloat32_t ab_f32x = svdup_n_f32(0.0f);
+    svfloat32_t a2_f32x = svdup_n_f32(0.0f);
+    svfloat32_t b2_f32x = svdup_n_f32(0.0f);
+    nk_f16_for_arm_simd_t const *a = (nk_f16_for_arm_simd_t const *)(a_enum);
+    nk_f16_for_arm_simd_t const *b = (nk_f16_for_arm_simd_t const *)(b_enum);
+    do {
+        svbool_t predicate_f32x = svwhilelt_b32_u64(i, n);
+        svfloat16_t a_f16x = svld1_f16(svwhilelt_b16_u64(i, n), a + i);
+        svfloat16_t b_f16x = svld1_f16(svwhilelt_b16_u64(i, n), b + i);
+        svfloat32_t a_f32x = svcvt_f32_f16_x(predicate_f32x, a_f16x);
+        svfloat32_t b_f32x = svcvt_f32_f16_x(predicate_f32x, b_f16x);
+        ab_f32x = svmla_f32_x(predicate_f32x, ab_f32x, a_f32x, b_f32x);
+        a2_f32x = svmla_f32_x(predicate_f32x, a2_f32x, a_f32x, a_f32x);
+        b2_f32x = svmla_f32_x(predicate_f32x, b2_f32x, b_f32x, b_f32x);
+        i += svcntw();
+    } while (i < n);
+
+    nk_f32_t ab_f32 = svaddv_f32(svptrue_b32(), ab_f32x);
+    nk_f32_t a2_f32 = svaddv_f32(svptrue_b32(), a2_f32x);
+    nk_f32_t b2_f32 = svaddv_f32(svptrue_b32(), b2_f32x);
+    *result = nk_angular_normalize_f32_neon_(ab_f32, a2_f32, b2_f32);
+}
+
+#if defined(__clang__)
+#pragma clang attribute pop
+#elif defined(__GNUC__)
+#pragma GCC pop_options
+#endif
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // NK_TARGET_SVEHALF
+#endif // NK_TARGET_ARM_
+#endif // NK_SPATIAL_SVEHALF_H