numkong 7.0.0

package/include/numkong/each.hpp

@@ -0,0 +1,434 @@
+/**
+ *  @brief C++ wrappers for SIMD-accelerated Elementwise Arithmetic.
+ *  @file include/numkong/each.hpp
+ *  @author Ash Vardanian
+ *  @date February 5, 2026
+ */
+#ifndef NK_EACH_HPP
+#define NK_EACH_HPP
+
+#include <cstdint>
+#include <type_traits>
+
+#include "numkong/each.h"
+
+#include "numkong/types.hpp"
+
+namespace ashvardanian::numkong {
+
+/**
+ *  @brief Elementwise sum: cᵢ = aᵢ + bᵢ
+ *  @param[in] a,b Input vectors
+ *  @param[in] d Number of dimensions in input vectors
+ *  @param[out] c Output vector
+ *
+ *  @tparam in_type_ Element type
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ */
+template <numeric_dtype in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void sum(in_type_ const *a, in_type_ const *b, std::size_t d, in_type_ *c) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd) nk_each_sum_f64(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd) nk_each_sum_f32(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f16_t> && simd) nk_each_sum_f16(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, bf16_t> && simd) nk_each_sum_bf16(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i8_t> && simd) nk_each_sum_i8(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u8_t> && simd) nk_each_sum_u8(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i16_t> && simd) nk_each_sum_i16(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u16_t> && simd) nk_each_sum_u16(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i32_t> && simd) nk_each_sum_i32(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u32_t> && simd) nk_each_sum_u32(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i64_t> && simd) nk_each_sum_i64(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u64_t> && simd) nk_each_sum_u64(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32c_t> && simd) nk_each_sum_f32c(&a->raw_, &b->raw_, d, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f64c_t> && simd) nk_each_sum_f64c(&a->raw_, &b->raw_, d, &c->raw_);
+    // Scalar fallback
+    else {
+        for (std::size_t i = 0; i < d; i++) c[i] = saturating_add(a[i], b[i]);
+    }
+}
+
+/**
+ *  @brief Elementwise scale: cᵢ = α × aᵢ + β
+ *  @param[in] a Input vector
+ *  @param[in] d Number of dimensions in input vector
+ *  @param[in] alpha,beta Scale and shift coefficients
+ *  @param[out] c Output vector
+ *
+ *  @tparam in_type_ Element type
+ *  @tparam precision_type_ Precision type for scalar fallback computations, defaults to `in_type_`
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ */
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void scale(in_type_ const *a, std::size_t d, typename in_type_::scale_t const *alpha,
+           typename in_type_::scale_t const *beta, in_type_ *c) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k && std::is_same_v<precision_type_, in_type_>;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd) nk_each_scale_f64(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd) nk_each_scale_f32(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f16_t> && simd) nk_each_scale_f16(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, bf16_t> && simd) nk_each_scale_bf16(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i8_t> && simd) nk_each_scale_i8(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u8_t> && simd) nk_each_scale_u8(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i16_t> && simd) nk_each_scale_i16(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u16_t> && simd) nk_each_scale_u16(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i32_t> && simd) nk_each_scale_i32(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u32_t> && simd) nk_each_scale_u32(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i64_t> && simd) nk_each_scale_i64(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u64_t> && simd) nk_each_scale_u64(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32c_t> && simd) nk_each_scale_f32c(&a->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f64c_t> && simd) nk_each_scale_f64c(&a->raw_, d, alpha, beta, &c->raw_);
+    // Scalar fallback with high-precision intermediates
+    else {
+        for (std::size_t i = 0; i < d; i++)
+            c[i] = (precision_type_(a[i]) * precision_type_(*alpha) + precision_type_(*beta)).template to<in_type_>();
+    }
+}
+
+/**
+ *  @brief Blend: cᵢ = α × aᵢ + β × bᵢ
+ *  @param[in] a,b Input vectors
+ *  @param[in] d Number of dimensions in input vectors
+ *  @param[in] alpha,beta Weight coefficients
+ *  @param[out] c Output vector
+ *
+ *  @tparam in_type_ Element type
+ *  @tparam precision_type_ Precision type for scalar fallback computations, defaults to `in_type_`
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ */
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void blend(in_type_ const *a, in_type_ const *b, std::size_t d, typename in_type_::scale_t const *alpha,
+           typename in_type_::scale_t const *beta, in_type_ *c) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k && std::is_same_v<precision_type_, in_type_>;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd)
+        nk_each_blend_f64(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd)
+        nk_each_blend_f32(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f16_t> && simd)
+        nk_each_blend_f16(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, bf16_t> && simd)
+        nk_each_blend_bf16(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i8_t> && simd)
+        nk_each_blend_i8(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u8_t> && simd)
+        nk_each_blend_u8(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i16_t> && simd)
+        nk_each_blend_i16(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u16_t> && simd)
+        nk_each_blend_u16(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i32_t> && simd)
+        nk_each_blend_i32(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u32_t> && simd)
+        nk_each_blend_u32(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, i64_t> && simd)
+        nk_each_blend_i64(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, u64_t> && simd)
+        nk_each_blend_u64(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32c_t> && simd)
+        nk_each_blend_f32c(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    else if constexpr (std::is_same_v<in_type_, f64c_t> && simd)
+        nk_each_blend_f64c(&a->raw_, &b->raw_, d, alpha, beta, &c->raw_);
+    // Scalar fallback with high-precision intermediates
+    else {
+        for (std::size_t i = 0; i < d; i++) {
+            c[i] = (precision_type_(a[i]) * precision_type_(*alpha) + precision_type_(b[i]) * precision_type_(*beta))
+                       .template to<in_type_>();
+        }
+    }
+}
+
+/**
+ *  @brief Elementwise FMA: outᵢ = α × aᵢ × bᵢ + β × cᵢ
+ *  @param[in] a,b,c Input vectors
+ *  @param[in] d Number of dimensions in input vectors
+ *  @param[in] alpha,beta Coefficients
+ *  @param[out] out Output vector
+ *
+ *  @tparam in_type_ Element type
+ *  @tparam precision_type_ Precision type for scalar fallback computations, defaults to `in_type_`
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ */
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void fma(in_type_ const *a, in_type_ const *b, std::size_t d, in_type_ const *c,
+         typename in_type_::scale_t const *alpha, typename in_type_::scale_t const *beta, in_type_ *out) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k && std::is_same_v<precision_type_, in_type_>;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd)
+        nk_each_fma_f64(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd)
+        nk_each_fma_f32(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, f16_t> && simd)
+        nk_each_fma_f16(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, bf16_t> && simd)
+        nk_each_fma_bf16(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, i8_t> && simd)
+        nk_each_fma_i8(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, u8_t> && simd)
+        nk_each_fma_u8(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, i16_t> && simd)
+        nk_each_fma_i16(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, u16_t> && simd)
+        nk_each_fma_u16(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, i32_t> && simd)
+        nk_each_fma_i32(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, u32_t> && simd)
+        nk_each_fma_u32(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, i64_t> && simd)
+        nk_each_fma_i64(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, u64_t> && simd)
+        nk_each_fma_u64(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32c_t> && simd)
+        nk_each_fma_f32c(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    else if constexpr (std::is_same_v<in_type_, f64c_t> && simd)
+        nk_each_fma_f64c(&a->raw_, &b->raw_, &c->raw_, d, alpha, beta, &out->raw_);
+    // Scalar fallback with high-precision intermediates
+    else {
+        for (std::size_t i = 0; i < d; i++) {
+            out[i] = (precision_type_(a[i]) * precision_type_(b[i]) * precision_type_(*alpha) +
+                      precision_type_(c[i]) * precision_type_(*beta))
+                         .template to<in_type_>();
+        }
+    }
+}
+
+} // namespace ashvardanian::numkong
+
+#include "numkong/tensor.hpp"
+
+namespace ashvardanian::numkong {
+
+#pragma region - Tensor Elementwise
+
+/** @brief Scale: output[i] = α × input[i] + β. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool scale(tensor_view<value_type_, max_rank_> input, typename value_type_::scale_t alpha,
+           typename value_type_::scale_t beta, tensor_span<value_type_, max_rank_> output) noexcept {
+    return elementwise_into_<value_type_, max_rank_>(
+        input, output, [&](tensor_view<value_type_, max_rank_> in, tensor_span<value_type_, max_rank_> out) {
+            numkong::scale<value_type_>(in.data(), in.extent(0), &alpha, &beta, out.data());
+        });
+}
+
+/** @brief Allocating scale: result[i] = α × input[i] + β. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_scale(tensor_view<value_type_, max_rank_> input,
+                                                          typename value_type_::scale_t alpha,
+                                                          typename value_type_::scale_t beta) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (input.empty()) return out_tensor_t {};
+    auto &input_shape = input.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!scale<value_type_, max_rank_>(input, alpha, beta, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Blend: output[i] = α × lhs[i] + β × rhs[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool blend(tensor_view<value_type_, max_rank_> lhs, tensor_view<value_type_, max_rank_> rhs,
+           typename value_type_::scale_t alpha, typename value_type_::scale_t beta,
+           tensor_span<value_type_, max_rank_> output) noexcept {
+    return elementwise_into_<value_type_, max_rank_>(
+        lhs, rhs, output,
+        [&](tensor_view<value_type_, max_rank_> l, tensor_view<value_type_, max_rank_> r,
+            tensor_span<value_type_, max_rank_> out) {
+            numkong::blend<value_type_>(l.data(), r.data(), l.extent(0), &alpha, &beta, out.data());
+        });
+}
+
+/** @brief Allocating blend: result[i] = α × lhs[i] + β × rhs[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_blend(tensor_view<value_type_, max_rank_> lhs,
+                                                          tensor_view<value_type_, max_rank_> rhs,
+                                                          typename value_type_::scale_t alpha,
+                                                          typename value_type_::scale_t beta) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (!shapes_match_(lhs, rhs) || lhs.empty()) return out_tensor_t {};
+    auto &input_shape = lhs.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!blend<value_type_, max_rank_>(lhs, rhs, alpha, beta, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief FMA: output[i] = α × lhs[i] × rhs[i] + β × addend[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool fma(tensor_view<value_type_, max_rank_> lhs, tensor_view<value_type_, max_rank_> rhs,
+         tensor_view<value_type_, max_rank_> addend, typename value_type_::scale_t alpha,
+         typename value_type_::scale_t beta, tensor_span<value_type_, max_rank_> output) noexcept {
+    return elementwise_into_<value_type_, max_rank_>(
+        lhs, rhs, addend, output,
+        [&](tensor_view<value_type_, max_rank_> a, tensor_view<value_type_, max_rank_> b,
+            tensor_view<value_type_, max_rank_> c, tensor_span<value_type_, max_rank_> out) {
+            numkong::fma<value_type_>(a.data(), b.data(), a.extent(0), c.data(), &alpha, &beta, out.data());
+        });
+}
+
+/** @brief Allocating FMA: result[i] = α × lhs[i] × rhs[i] + β × addend[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_fma(tensor_view<value_type_, max_rank_> lhs,
+                                                        tensor_view<value_type_, max_rank_> rhs,
+                                                        tensor_view<value_type_, max_rank_> addend,
+                                                        typename value_type_::scale_t alpha,
+                                                        typename value_type_::scale_t beta) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (!shapes_match_(lhs, rhs) || !shapes_match_(lhs, addend) || lhs.empty()) return out_tensor_t {};
+    auto &input_shape = lhs.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!fma<value_type_, max_rank_>(lhs, rhs, addend, alpha, beta, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise addition: output[i] = lhs[i] + rhs[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool add(tensor_view<value_type_, max_rank_> lhs, tensor_view<value_type_, max_rank_> rhs,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    return elementwise_into_<value_type_, max_rank_>(
+        lhs, rhs, output,
+        [](tensor_view<value_type_, max_rank_> l, tensor_view<value_type_, max_rank_> r,
+           tensor_span<value_type_, max_rank_> out) {
+            numkong::sum<value_type_>(l.data(), r.data(), l.extent(0), out.data());
+        });
+}
+
+/** @brief Allocating elementwise add: result = lhs + rhs. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_add(tensor_view<value_type_, max_rank_> lhs,
+                                                        tensor_view<value_type_, max_rank_> rhs) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (!shapes_match_(lhs, rhs) || lhs.empty()) return out_tensor_t {};
+    auto &input_shape = lhs.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!add<value_type_, max_rank_>(lhs, rhs, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise add scalar: output[i] = input[i] + scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool add(tensor_view<value_type_, max_rank_> input, typename value_type_::scale_t scalar,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    typename value_type_::scale_t one {1};
+    return scale<value_type_, max_rank_>(input, one, scalar, output);
+}
+
+/** @brief Allocating add scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_add(tensor_view<value_type_, max_rank_> input,
+                                                        typename value_type_::scale_t scalar) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (input.empty()) return out_tensor_t {};
+    auto &input_shape = input.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!add<value_type_, max_rank_>(input, scalar, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise subtraction: output[i] = lhs[i] − rhs[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool sub(tensor_view<value_type_, max_rank_> lhs, tensor_view<value_type_, max_rank_> rhs,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    typename value_type_::scale_t alpha {1}, beta {-1};
+    return blend<value_type_, max_rank_>(lhs, rhs, alpha, beta, output);
+}
+
+/** @brief Allocating elementwise sub. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_sub(tensor_view<value_type_, max_rank_> lhs,
+                                                        tensor_view<value_type_, max_rank_> rhs) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (!shapes_match_(lhs, rhs) || lhs.empty()) return out_tensor_t {};
+    auto &input_shape = lhs.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!sub<value_type_, max_rank_>(lhs, rhs, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise sub scalar: output[i] = input[i] − scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool sub(tensor_view<value_type_, max_rank_> input, typename value_type_::scale_t scalar,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    typename value_type_::scale_t one {1};
+    typename value_type_::scale_t neg_scalar = -scalar;
+    return scale<value_type_, max_rank_>(input, one, neg_scalar, output);
+}
+
+/** @brief Allocating sub scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_sub(tensor_view<value_type_, max_rank_> input,
+                                                        typename value_type_::scale_t scalar) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (input.empty()) return out_tensor_t {};
+    auto &input_shape = input.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!sub<value_type_, max_rank_>(input, scalar, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise multiplication: output[i] = lhs[i] × rhs[i]. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool mul(tensor_view<value_type_, max_rank_> lhs, tensor_view<value_type_, max_rank_> rhs,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    return elementwise_into_<value_type_, max_rank_>(
+        lhs, rhs, output,
+        [](tensor_view<value_type_, max_rank_> l, tensor_view<value_type_, max_rank_> r,
+           tensor_span<value_type_, max_rank_> out) {
+            typename value_type_::scale_t alpha {1}, beta {0};
+            numkong::fma<value_type_>(l.data(), r.data(), l.extent(0), out.data(), &alpha, &beta, out.data());
+        });
+}
+
+/** @brief Allocating elementwise multiply. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_mul(tensor_view<value_type_, max_rank_> lhs,
+                                                        tensor_view<value_type_, max_rank_> rhs) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (!shapes_match_(lhs, rhs) || lhs.empty()) return out_tensor_t {};
+    auto &input_shape = lhs.shape();
+    auto result = out_tensor_t::try_zeros(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!mul<value_type_, max_rank_>(lhs, rhs, result.span())) return out_tensor_t {};
+    return result;
+}
+
+/** @brief Elementwise multiply by scalar: output[i] = input[i] × scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8>
+bool mul(tensor_view<value_type_, max_rank_> input, typename value_type_::scale_t scalar,
+         tensor_span<value_type_, max_rank_> output) noexcept {
+    typename value_type_::scale_t zero {0};
+    return scale<value_type_, max_rank_>(input, scalar, zero, output);
+}
+
+/** @brief Allocating multiply by scalar. */
+template <numeric_dtype value_type_, std::size_t max_rank_ = 8,
+          typename allocator_type_ = aligned_allocator<value_type_>>
+tensor<value_type_, allocator_type_, max_rank_> try_mul(tensor_view<value_type_, max_rank_> input,
+                                                        typename value_type_::scale_t scalar) noexcept {
+    using out_tensor_t = tensor<value_type_, allocator_type_, max_rank_>;
+    if (input.empty()) return out_tensor_t {};
+    auto &input_shape = input.shape();
+    auto result = out_tensor_t::try_empty(input_shape.extents, input_shape.rank);
+    if (result.empty()) return result;
+    if (!mul<value_type_, max_rank_>(input, scalar, result.span())) return out_tensor_t {};
+    return result;
+}
+
+#pragma endregion - Tensor Elementwise
+
+} // namespace ashvardanian::numkong
+
+#endif // NK_EACH_HPP

package/include/numkong/geospatial/README.md

@@ -0,0 +1,147 @@
+# Geospatial Distances in NumKong
+
+NumKong implements geodesic distance functions for points on Earth's surface: Haversine computes great-circle distance on a perfect sphere, while Vincenty solves the inverse geodesic problem on the WGS-84 oblate spheroid.
+Both operate on arrays of latitude/longitude pairs in radians and produce distances in meters.
+
+The Haversine formula computes the great-circle distance between two points:
+
+```math
+\text{haversine}(\phi_1, \lambda_1, \phi_2, \lambda_2) = 2R \arcsin\sqrt{\sin^2\frac{\phi_2 - \phi_1}{2} + \cos\phi_1 \cos\phi_2 \sin^2\frac{\lambda_2 - \lambda_1}{2}}
+```
+
+where $R$ is Earth's mean radius and $(\phi, \lambda)$ are latitude and longitude in radians.
+
+Vincenty's formula solves the inverse geodesic problem on an oblate spheroid, iteratively refining the reduced latitude difference until convergence:
+
+```math
+\text{vincenty}(\phi_1, \lambda_1, \phi_2, \lambda_2) = b \cdot A \cdot (\sigma - \Delta\sigma)
+```
+
+where $a$ and $b$ are the equatorial and polar semi-axes of the WGS-84 ellipsoid, $\sigma$ is the angular separation, and $\Delta\sigma$ is the correction term computed through iterative convergence.
+
+Reformulating as Python pseudocode:
+
+```python
+import numpy as np
+
+def haversine(lat1, lon1, lat2, lon2, R=6371000):
+    dlat = lat2 - lat1
+    dlon = lon2 - lon1
+    a = np.sin(dlat / 2) ** 2 + np.cos(lat1) * np.cos(lat2) * np.sin(dlon / 2) ** 2
+    return 2 * R * np.arcsin(np.sqrt(a))
+```
+
+Input coordinates are in radians, output distances are in meters.
+
+## Input & Output Types
+
+| Input Type | Output Type | Description             |
+| ---------- | ----------- | ----------------------- |
+| `f64`      | `f64`       | 64-bit double precision |
+| `f32`      | `f32`       | 32-bit single precision |
+
+## Optimizations
+
+### Trigonometric Polynomial Approximations
+
+`nk_haversine_f32_haswell`, `nk_haversine_f32_skylake`, `nk_haversine_f32_neon` replace `libm` sin, cos, atan2, and asin with SIMD polynomial approximations achieving approximately 3.5 ULP accuracy.
+Range reduction maps the input angle to $[-\pi/4, \pi/4]$ using Cody-Waite extended precision constants, then an odd-degree minimax polynomial evaluates sin and an even-degree polynomial evaluates cos.
+The `f32` kernels use 5-term polynomials while `f64` kernels use 11-term polynomials for the extra precision required by double-precision inputs.
+This avoids the latency of scalar `libm` calls — each trigonometric evaluation would otherwise serialize through a single execution port, while the polynomial chains pipeline across multiple FMA units.
+
+### Vincenty Iterative Convergence with Masked Lanes
+
+`nk_vincenty_f64_haswell`, `nk_vincenty_f64_skylake`, `nk_vincenty_f64_neon` implement the full Vincenty inverse formula with up to 100 iterations and a convergence threshold of $10^{-12}$ radians (approximately 6 micrometers on Earth's surface).
+Each SIMD lane may converge at a different iteration count, so the kernel accumulates a `converged_mask` via `_mm256_or_pd(converged_mask, newly_converged)` and selectively freezes converged lanes with `_mm256_blendv_pd(lambda_new, lambda, converged_mask)`.
+Early exit uses `_mm256_movemask_pd` — when all 4 bits (for `f64`) or 8 bits (for `f32`) are set, the loop breaks.
+Coincident points and equatorial edge cases are handled by blending safe values (ones) into the intermediate terms to avoid division by zero, without requiring branches that would diverge across SIMD lanes.
+
+### Haversine Without Final Arc Conversion
+
+`nk_haversine_f32_haswell`, `nk_haversine_f64_haswell` support a similarity mode where the haversine formula involves $2R \cdot \text{asin}(\sqrt{h})$ and the intermediate value $h = \sin^2(\Delta\phi/2) + \cos\phi_1 \cos\phi_2 \cdot \sin^2(\Delta\lambda/2)$ is monotonic with distance.
+For ranking and comparison use cases, comparing $h$ values directly produces the same ordering as comparing full Haversine distances, since both asin and sqrt are monotonically increasing.
+This eliminates the two most expensive operations in the pipeline.
+The kernels compute the full distance by default, but the streaming API can optionally skip the final conversion when only relative ordering is needed.
+
+## Performance
+
+The following performance tables are produced by manually re-running `nk_test` and `nk_bench` included internal tools to measure both accuracy and throughput at different input shapes.
+The input size is controlled by the `NK_MAX_COORD_ANGLE` environment variable and set to ≤1°, ≤30°, and ≤180° maximum angular separation between pairs of coordinates.
+The larger the angular separation between pairs, the longer the algorithm may take to converge and the higher the error.
+The throughput is measured in MP/s as the number of Millions of pairwise point distances computed per second - amortized for a large batch size, with `NK_DENSE_DIMENSIONS=1536` by default.
+Current `nk_test` output reports geospatial accuracy in two forms: mean/max absolute error in meters against Vincenty's formula computed at double-double (f118) precision, and mean/max ULP against the matching high-precision implementation of the same formula. The historical tables below use the meter-based summary where it has been remeasured; older x86 rows still retain their original ULP figures until rerun.
+Each kernel runs for at least 20 seconds per configuration.
+Benchmark threads are pinned to specific cores; on machines with heterogeneous core types (e.g., Apple P/E cores), only the fastest cores are used.
+Workloads that significantly degrade CPU frequencies (Intel AMX, Apple SME) run in separate passes to avoid affecting throughput measurements of other kernels.
+
+### Intel Sapphire Rapids
+
+#### Native
+
+| Kernel                     |                      ≤1° |                     ≤30° |                    ≤180° |
+| :------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __f64__                    | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f64_serial`  |       1.95 mp/s, 0.8 ulp |       2.10 mp/s, 0.8 ulp |       2.02 mp/s, 1.7 ulp |
+| `nk_vincenty_f64_serial`   |       0.565 mp/s, 82 ulp |      0.481 mp/s, 3.9 ulp |      0.514 mp/s, 1.1 ulp |
+| `nk_haversine_f64_haswell` |       73.3 mp/s, 0.6 ulp |       68.3 mp/s, 0.6 ulp |       70.4 mp/s, 1.5 ulp |
+| `nk_vincenty_f64_haswell`  |        12.2 mp/s, 80 ulp |       10.2 mp/s, 3.6 ulp |       7.15 mp/s, 1.1 ulp |
+| `nk_haversine_f64_skylake` |        106 mp/s, 0.6 ulp |        107 mp/s, 0.6 ulp |       99.8 mp/s, 1.5 ulp |
+| `nk_vincenty_f64_skylake`  |      20.4 mp/s, 171K ulp |     17.5 mp/s, 6.57K ulp |     11.2 mp/s, 1.02K ulp |
+| __f32__                    | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f32_serial`  |       56.2 mp/s, 3.4 ulp |       62.3 mp/s, 2.9 ulp |        57.2 mp/s, 55 ulp |
+| `nk_vincenty_f32_serial`   |     3.25 mp/s, 58.3K ulp |       2.39 mp/s, 306 ulp |       1.79 mp/s, 103 ulp |
+| `nk_haversine_f32_haswell` |        247 mp/s, 3.2 ulp |        282 mp/s, 2.7 ulp |         281 mp/s, 54 ulp |
+| `nk_vincenty_f32_haswell`  |     53.6 mp/s, 26.2K ulp |       46.4 mp/s, 289 ulp |        16.5 mp/s, 61 ulp |
+| `nk_haversine_f32_skylake` |        350 mp/s, 3.1 ulp |        328 mp/s, 2.7 ulp |         356 mp/s, 53 ulp |
+| `nk_vincenty_f32_skylake`  |     78.7 mp/s, 7.16K ulp |       73.6 mp/s, 406 ulp |       20.1 mp/s, 105 ulp |
+
+#### WASM
+
+Measured with Wasmtime v42 (Cranelift backend).
+
+| Kernel                         |                      ≤1° |                     ≤30° |                    ≤180° |
+| :----------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __f64__                        | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f64_serial`      |          ? mp/s, 0.9 ulp |          ? mp/s, 0.9 ulp |          ? mp/s, 1.8 ulp |
+| `nk_vincenty_f64_serial`       |          ? mp/s, 102 ulp |          ? mp/s, 3.7 ulp |          ? mp/s, 1.1 ulp |
+| `nk_haversine_f64_v128relaxed` |          ? mp/s, 0.6 ulp |          ? mp/s, 0.6 ulp |          ? mp/s, 1.7 ulp |
+| `nk_vincenty_f64_v128relaxed`  |          ? mp/s, 104 ulp |          ? mp/s, 3.4 ulp |          ? mp/s, 1.1 ulp |
+| __f32__                        | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f32_serial`      |          ? mp/s, 3.5 ulp |          ? mp/s, 2.9 ulp |         ? mp/s, 53.6 ulp |
+| `nk_vincenty_f32_serial`       |        ? mp/s, 70.5K ulp |          ? mp/s, 326 ulp |         ? mp/s, 65.5 ulp |
+| `nk_haversine_f32_v128relaxed` |          ? mp/s, 6.5 ulp |          ? mp/s, 5.6 ulp |         ? mp/s, 53.3 ulp |
+| `nk_vincenty_f32_v128relaxed`  |        ? mp/s, 23.8K ulp |          ? mp/s, 323 ulp |         ? mp/s, 64.0 ulp |
+
+### Apple M4
+
+#### Native
+
+| Kernel                    |                      ≤1° |                     ≤30° |                    ≤180° |
+| :------------------------ | -----------------------: | -----------------------: | -----------------------: |
+| __f64__                   | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f64_serial` |       3.47 mp/s, 1.12 km |       3.47 mp/s, 32.8 km |        3.48 mp/s, 150 km |
+| `nk_vincenty_f64_serial`  |      0.888 mp/s, 2.20 nm |      0.770 mp/s, 2.79 nm |       0.662 mp/s, 622 nm |
+| `nk_haversine_f64_neon`   |       72.8 mp/s, 1.12 km |       72.5 mp/s, 32.8 km |        72.8 mp/s, 150 km |
+| `nk_vincenty_f64_neon`    |       9.34 mp/s, 2.12 nm |       7.61 mp/s, 2.33 nm |        5.99 mp/s, 622 nm |
+| __f32__                   | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f32_serial` |       14.1 mp/s, 1.12 km |       13.8 mp/s, 32.8 km |        14.0 mp/s, 146 km |
+| `nk_vincenty_f32_serial`  |        4.54 mp/s, 12.0 m |        3.25 mp/s, 12.5 m |        2.42 mp/s, 22.0 m |
+| `nk_haversine_f32_neon`   |        247 mp/s, 1.12 km |        235 mp/s, 32.8 km |         252 mp/s, 146 km |
+| `nk_vincenty_f32_neon`    |        45.7 mp/s, 12.2 m |        37.9 mp/s, 12.8 m |        15.7 mp/s, 22.0 m |
+
+#### WASM
+
+Measured with Wasmtime v42 (Cranelift backend).
+
+| Kernel                         |                      ≤1° |                     ≤30° |                    ≤180° |
+| :----------------------------- | -----------------------: | -----------------------: | -----------------------: |
+| __f64__                        | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f64_serial`      |       1.84 mp/s, 1.12 km |       1.83 mp/s, 32.8 km |        1.99 mp/s, 148 km |
+| `nk_vincenty_f64_serial`       |      0.481 mp/s, 1.86 nm |      0.419 mp/s, 2.33 nm |       0.422 mp/s, 594 nm |
+| `nk_haversine_f64_v128relaxed` |       35.7 mp/s, 1.12 km |       35.9 mp/s, 32.8 km |        35.9 mp/s, 148 km |
+| `nk_vincenty_f64_v128relaxed`  |       4.19 mp/s, 1.89 nm |       3.57 mp/s, 2.33 nm |        2.94 mp/s, 594 nm |
+| __f32__                        | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
+| `nk_haversine_f32_serial`      |     6.74 mp/s, 20,000 km |       6.80 mp/s, 32.7 km |        7.34 mp/s, 136 km |
+| `nk_vincenty_f32_serial`       |     2.25 mp/s, 20,000 km |        1.65 mp/s, 12.0 m |        1.35 mp/s, 22.0 m |
+| `nk_haversine_f32_v128relaxed` |      161 mp/s, 20,000 km |        165 mp/s, 32.7 km |         165 mp/s, 153 km |
+| `nk_vincenty_f32_v128relaxed`  |        24.6 mp/s, 12.0 m |        20.5 mp/s, 16.2 m |        9.57 mp/s, 18.0 m |