usearch 2.26.1 → 2.26.2

package/numkong/include/numkong/trigonometry/serial.h

@@ -21,7 +21,7 @@ extern "C" {
 /**
  *  @brief Computes an approximate sine of the given angle in radians with @b 3-ULP error bound for [-2π, 2π].
  *  @see Based on @b `xfastsinf_u3500` in SLEEF library.
- *  @param[in] angle The input angle in radians.
+ *  @param[in] angle_radians The input angle in radians.
  *  @return The approximate sine of the input angle in [-1, 1] range.
  */
 NK_PUBLIC nk_f32_t nk_f32_sin(nk_f32_t const angle_radians) {
@@ -62,7 +62,7 @@ NK_PUBLIC nk_f32_t nk_f32_sin(nk_f32_t const angle_radians) {
 /**
  *  @brief Computes an approximate cosine of the given angle in radians with @b 3-ULP error bound for [-2π, 2π].
  *  @see Based on @b `xfastcosf_u3500` in SLEEF library.
- *  @param[in] angle The input angle in radians.
+ *  @param[in] angle_radians The input angle in radians.
  *  @return The approximate cosine of the input angle in [-1, 1] range.
  */
 NK_PUBLIC nk_f32_t nk_f32_cos(nk_f32_t const angle_radians) {
@@ -255,8 +255,8 @@ NK_PUBLIC nk_f32_t nk_f32_atan2(nk_f32_t const y_input, nk_f32_t const x_input)
 /**
  *  @brief Computes the sine of the given angle in radians with @b 0-ULP error bound in [-2π, 2π].
  *  @see Based on @b `xsin` in SLEEF library.
- *  @param[in] angle The input angle in radians.
- *  @return The approximate cosine of the input angle.
+ *  @param[in] angle_radians The input angle in radians.
+ *  @return The approximate sine of the input angle.
  */
 NK_PUBLIC nk_f64_t nk_f64_sin(nk_f64_t const angle_radians) {
 
@@ -316,7 +316,7 @@ NK_PUBLIC nk_f64_t nk_f64_sin(nk_f64_t const angle_radians) {
 /**
  *  @brief Computes the cosine of the given angle in radians with @b 0-ULP error bound in [-2π, 2π].
  *  @see Based on @b `xcos` in SLEEF library.
- *  @param[in] angle The input angle in radians.
+ *  @param[in] angle_radians The input angle in radians.
  *  @return The approximate cosine of the input angle in [-1, 1] range.
  */
 NK_PUBLIC nk_f64_t nk_f64_cos(nk_f64_t const angle_radians) {
@@ -439,7 +439,7 @@ NK_PUBLIC nk_f64_t nk_f64_atan(nk_f64_t const input) {
  *  @see Based on @b `xatan2` in SLEEF library.
  *  @param  y_input The input sine value.
  *  @param  x_input The input cosine value.
- *  @return The arc-tangent of (y_input/x_input) in [-π/2, π/2] radians range.
+ *  @return The arc-tangent of (y_input/x_input) in [-π, π] radians range.
  */
 NK_PUBLIC nk_f64_t nk_f64_atan2(nk_f64_t const y_input, nk_f64_t const x_input) {
     // Polynomial coefficients for atan2 approximation

package/numkong/include/numkong/trigonometry/v128relaxed.h

@@ -37,6 +37,7 @@
 #if NK_TARGET_V128RELAXED
 
 #include "numkong/types.h"
+#include "numkong/cast/serial.h" // `nk_partial_load_b32x4_serial_`, `nk_partial_load_b64x2_serial_`, `nk_partial_store_b32x4_serial_`
 
 #if defined(__cplusplus)
 extern "C" {

package/numkong/include/numkong/types.hpp

@@ -481,9 +481,11 @@ struct f32_t {
     inline f32_t clamp(f32_t lo, f32_t hi) const noexcept { return max(lo).min(hi); }
 
     static constexpr f32_t clamped_to_finite_(float x) noexcept {
-        if (x == std::numeric_limits<float>::infinity()) return finite_max();
-        if (x == -std::numeric_limits<float>::infinity()) return finite_min();
-        return f32_t {x};
+        f32_t const value {x};
+        // Classify by bit pattern: arithmetic comparisons against infinity are folded away
+        // under `-ffinite-math-only`, silently disabling the clamp.
+        if (value.is_infinite()) return value.is_sign_negative() ? finite_min() : finite_max();
+        return value;
     }
 
     /** @brief Saturating addition: clamps to finite range on overflow. */
@@ -751,9 +753,11 @@ struct f64_t {
     inline f64_t clamp(f64_t lo, f64_t hi) const noexcept { return max(lo).min(hi); }
 
     static constexpr f64_t clamped_to_finite_(double x) noexcept {
-        if (x == std::numeric_limits<double>::infinity()) return finite_max();
-        if (x == -std::numeric_limits<double>::infinity()) return finite_min();
-        return f64_t {x};
+        f64_t const value {x};
+        // Classify by bit pattern: arithmetic comparisons against infinity are folded away
+        // under `-ffinite-math-only`, silently disabling the clamp.
+        if (value.is_infinite()) return value.is_sign_negative() ? finite_min() : finite_max();
+        return value;
     }
 
     /** @brief Saturating addition: clamps to finite range on overflow. */
@@ -3062,11 +3066,16 @@ struct f118_t {
 
     /** @brief Returns true if the value is positive or negative infinity. */
     constexpr bool is_infinite() const noexcept {
-        return high_ == std::numeric_limits<double>::infinity() || high_ == -std::numeric_limits<double>::infinity();
+        // Classify by bit pattern: arithmetic comparisons against infinity are folded away
+        // under `-ffinite-math-only`.
+        return (std::bit_cast<std::uint64_t>(high_) & 0x7FFFFFFFFFFFFFFFull) == 0x7FF0000000000000ull;
     }
 
     /** @brief Returns true if the value is neither infinite nor NaN. */
-    inline bool is_finite() const noexcept { return std::isfinite(high_); }
+    constexpr bool is_finite() const noexcept {
+        // Classify by bit pattern: `std::isfinite` constant-folds to true under `-ffinite-math-only`.
+        return (std::bit_cast<std::uint64_t>(high_) & 0x7FF0000000000000ull) != 0x7FF0000000000000ull;
+    }
 
     /** @brief Returns true if the sign bit is positive (includes +0). */
     inline bool is_sign_positive() const noexcept { return high_ > 0.0 || (high_ == 0.0 && !std::signbit(high_)); }
@@ -4917,11 +4926,13 @@ struct sub_byte_ref<u1x8_t> {
     constexpr bool get() const noexcept { return (*raw_ptr_ & bit_mask_) != 0; }
     constexpr operator bool() const noexcept { return get(); }
 
-    constexpr sub_byte_ref &operator=(bool value) noexcept {
-        if (value) *raw_ptr_ |= bit_mask_;
+    template <std::integral integral_type_>
+    constexpr sub_byte_ref &operator=(integral_type_ value) noexcept {
+        if (value != integral_type_ {0}) *raw_ptr_ |= bit_mask_;
         else *raw_ptr_ &= static_cast<nk_u1x8_t>(~bit_mask_);
         return *this;
     }
+    constexpr sub_byte_ref &operator=(u8_t value) noexcept { return *this = value.raw(); }
 
     constexpr void flip() noexcept { *raw_ptr_ ^= bit_mask_; }
 };
@@ -4941,11 +4952,21 @@ struct sub_byte_ref<i4x2_t> {
     }
     constexpr operator std::int8_t() const noexcept { return get(); }
 
-    constexpr sub_byte_ref &operator=(std::int8_t value) noexcept {
-        if (high_nibble_) *raw_ptr_ = static_cast<nk_i4x2_t>((*raw_ptr_ & 0x0F) | ((value & 0x0F) << 4));
-        else *raw_ptr_ = static_cast<nk_i4x2_t>((*raw_ptr_ & 0xF0) | (value & 0x0F));
+    template <std::integral integral_type_>
+    constexpr sub_byte_ref &operator=(integral_type_ value) noexcept {
+        std::int8_t clamped;
+        if constexpr (std::is_signed_v<integral_type_>) {
+            clamped = value < integral_type_(-8) ? std::int8_t(-8)
+                      : value > integral_type_(7) ? std::int8_t(7)
+                                                  : static_cast<std::int8_t>(value);
+        }
+        else { clamped = value > integral_type_(7) ? std::int8_t(7) : static_cast<std::int8_t>(value); }
+        auto nibble = static_cast<nk_i4x2_t>(clamped & 0x0F);
+        if (high_nibble_) *raw_ptr_ = static_cast<nk_i4x2_t>((*raw_ptr_ & 0x0F) | (nibble << 4));
+        else *raw_ptr_ = static_cast<nk_i4x2_t>((*raw_ptr_ & 0xF0) | nibble);
         return *this;
     }
+    constexpr sub_byte_ref &operator=(i8_t value) noexcept { return *this = value.raw(); }
 };
 
 /** @brief Unsigned 4-bit access for u4x2_t vectors (2 nibbles packed per byte). */
@@ -4960,11 +4981,20 @@ struct sub_byte_ref<u4x2_t> {
     constexpr std::uint8_t get() const noexcept { return high_nibble_ ? (*raw_ptr_ >> 4) : (*raw_ptr_ & 0x0F); }
     constexpr operator std::uint8_t() const noexcept { return get(); }
 
-    constexpr sub_byte_ref &operator=(std::uint8_t value) noexcept {
-        if (high_nibble_) *raw_ptr_ = static_cast<nk_u4x2_t>((*raw_ptr_ & 0x0F) | ((value & 0x0F) << 4));
-        else *raw_ptr_ = static_cast<nk_u4x2_t>((*raw_ptr_ & 0xF0) | (value & 0x0F));
+    template <std::integral integral_type_>
+    constexpr sub_byte_ref &operator=(integral_type_ value) noexcept {
+        std::uint8_t clamped;
+        if constexpr (std::is_signed_v<integral_type_>) {
+            clamped = value < integral_type_(0) ? std::uint8_t(0)
+                      : value > integral_type_(15) ? std::uint8_t(15)
+                                                   : static_cast<std::uint8_t>(value);
+        }
+        else { clamped = value > integral_type_(15) ? std::uint8_t(15) : static_cast<std::uint8_t>(value); }
+        if (high_nibble_) *raw_ptr_ = static_cast<nk_u4x2_t>((*raw_ptr_ & 0x0F) | (clamped << 4));
+        else *raw_ptr_ = static_cast<nk_u4x2_t>((*raw_ptr_ & 0xF0) | clamped);
         return *this;
     }
+    constexpr sub_byte_ref &operator=(u8_t value) noexcept { return *this = value.raw(); }
 };
 
 /**

package/numkong/include/numkong/vector.hpp

@@ -411,6 +411,9 @@ struct vector_view {
  */
 template <typename value_type_>
 struct vector_span {
+    static_assert(!std::is_const_v<value_type_>,
+                  "vector_span requires a non-const value_type_; use vector_view<value_type_> for read-only access");
+
     using value_type = value_type_;
     using size_type = std::size_t;
     using difference_type = std::ptrdiff_t;
@@ -451,12 +454,10 @@ struct vector_span {
     }
 
     /** @brief Raw byte pointer. */
-    constexpr char *byte_data() noexcept { return data_; }
-    constexpr char const *byte_data() const noexcept { return data_; }
+    constexpr char *byte_data() const noexcept { return data_; }
 
     /** @brief Typed pointer (only valid if contiguous). */
-    constexpr value_type *data() noexcept { return reinterpret_cast<value_type *>(data_); }
-    constexpr value_type const *data() const noexcept { return reinterpret_cast<value_type const *>(data_); }
+    constexpr value_type *data() const noexcept { return reinterpret_cast<value_type *>(data_); }
 
     /** @brief Implicit conversion to const view. */
     constexpr operator vector_view<value_type>() const noexcept {
@@ -465,7 +466,7 @@ struct vector_span {
 
     /** @brief Mutable integral indexing. Signed negatives wrap from end. */
     template <std::integral index_type_>
-    decltype(auto) operator[](index_type_ idx) noexcept {
+    decltype(auto) operator[](index_type_ idx) const noexcept {
         auto i = resolve_index_(idx, dimensions_);
         if constexpr (dimensions_per_value<value_type>() > 1) {
             constexpr auto dims_per_value = dimensions_per_value<value_type>();
@@ -479,37 +480,120 @@ struct vector_span {
         else { return *reinterpret_cast<value_type *>(data_ + static_cast<difference_type>(i) * stride_bytes_); }
     }
 
-    /** @brief Const integral indexing. Signed negatives wrap from end. */
-    template <std::integral index_type_>
-    decltype(auto) operator[](index_type_ idx) const noexcept {
-        return static_cast<vector_view<value_type>>(*this)[idx];
-    }
-
     /** @brief Sub-slice via range. */
-    vector_span operator[](range r) noexcept {
+    vector_span operator[](range r) const noexcept {
         size_type start, stop;
         resolve_range_(r, dimensions_, start, stop);
         auto count = range_extent_(start, stop, r.step);
         return {data_ + static_cast<difference_type>(start) * stride_bytes_, count, stride_bytes_ * r.step};
     }
 
-    /** @brief Const sub-slice via range. */
-    vector_view<value_type> operator[](range r) const noexcept {
-        return static_cast<vector_view<value_type>>(*this)[r];
-    }
-
     /** @brief Select all elements. */
-    vector_span operator[](all_t) noexcept { return *this; }
+    vector_span operator[](all_t) const noexcept { return *this; }
 
-    /** @brief Dimension iterator to beginning. */
-    iterator begin() noexcept { return {*this, 0}; }
-    const_iterator begin() const noexcept { return {*this, 0}; }
+    /** @brief Dimension iterator to beginning. The handle is shallow-const, so iteration yields mutable refs. */
+    iterator begin() const noexcept { return {const_cast<vector_span &>(*this), 0}; }
     const_iterator cbegin() const noexcept { return {*this, 0}; }
 
     /** @brief Dimension iterator to end. */
-    iterator end() noexcept { return {*this, dimensions_}; }
-    const_iterator end() const noexcept { return {*this, dimensions_}; }
+    iterator end() const noexcept { return {const_cast<vector_span &>(*this), dimensions_}; }
     const_iterator cend() const noexcept { return {*this, dimensions_}; }
+
+    /** @brief Zero-fill every element. memset on the contiguous fast path,
+     *  one memset per element on the strided slow path. */
+    bool fill_zeros() noexcept {
+        static_assert(is_memset_zero_safe_v<value_type>,
+                      "fill_zeros requires a dtype whose binary-zero is the value-zero");
+        if (data_ == nullptr || dimensions_ == 0) return true;
+        if constexpr (dimensions_per_value<value_type>() > 1) {
+            if (!is_contiguous()) return false;
+            auto byte_count = divide_round_up(dimensions_, dimensions_per_value<value_type>()) * sizeof(value_type);
+            std::memset(static_cast<void *>(data_), 0, byte_count);
+            return true;
+        }
+        else {
+            if (is_contiguous()) {
+                std::memset(static_cast<void *>(data_), 0, dimensions_ * sizeof(value_type));
+                return true;
+            }
+            for (size_type element_index = 0; element_index < dimensions_; ++element_index)
+                std::memset(static_cast<void *>(data_ + static_cast<difference_type>(element_index) * stride_bytes_),
+                            0, sizeof(value_type));
+            return true;
+        }
+    }
+
+    /** @brief Fill every element with `value`. memset-then-overlay strategy mirroring the
+     *  free `fill` on tensor_span: 1-byte storage uses a single byte_pattern memset, multi-byte
+     *  storage uses a typed scalar broadcast loop. */
+    bool fill(value_type value) noexcept {
+        if (!fill_zeros()) return false;
+        value_type const default_value {};
+        if (std::memcmp(&value, &default_value, sizeof(value_type)) == 0) return true;
+        if constexpr (sizeof(value_type) == 1) {
+            unsigned char byte_pattern;
+            std::memcpy(&byte_pattern, &value, 1);
+            if constexpr (dimensions_per_value<value_type>() > 1) {
+                auto byte_count = divide_round_up(dimensions_, dimensions_per_value<value_type>()) * sizeof(value_type);
+                std::memset(static_cast<void *>(data_), byte_pattern, byte_count);
+                return true;
+            }
+            else {
+                if (is_contiguous()) {
+                    std::memset(static_cast<void *>(data_), byte_pattern, dimensions_ * sizeof(value_type));
+                    return true;
+                }
+                for (size_type element_index = 0; element_index < dimensions_; ++element_index)
+                    std::memset(
+                        static_cast<void *>(data_ + static_cast<difference_type>(element_index) * stride_bytes_),
+                        byte_pattern, sizeof(value_type));
+                return true;
+            }
+        }
+        else {
+            if (is_contiguous()) {
+                auto *typed_data = reinterpret_cast<value_type *>(data_);
+                for (size_type element_index = 0; element_index < dimensions_; ++element_index)
+                    typed_data[element_index] = value;
+                return true;
+            }
+            for (size_type element_index = 0; element_index < dimensions_; ++element_index) {
+                auto *target =
+                    reinterpret_cast<value_type *>(data_ + static_cast<difference_type>(element_index) * stride_bytes_);
+                *target = value;
+            }
+            return true;
+        }
+    }
+
+    /** @brief Copy from a same-size view. memcpy on the contiguous fast path,
+     *  per-element copy on the strided slow path. Returns false on size mismatch. */
+    bool copy_from(vector_view<value_type> input) noexcept {
+        if (input.size() != dimensions_) return false;
+        if (dimensions_ == 0) return true;
+        if constexpr (dimensions_per_value<value_type>() > 1) {
+            if (!is_contiguous() || !input.is_contiguous()) return false;
+            auto byte_count = divide_round_up(dimensions_, dimensions_per_value<value_type>()) * sizeof(value_type);
+            std::memcpy(static_cast<void *>(data_), static_cast<void const *>(input.byte_data()), byte_count);
+            return true;
+        }
+        else {
+            if (is_contiguous() && input.is_contiguous()) {
+                std::memcpy(static_cast<void *>(data_), static_cast<void const *>(input.byte_data()),
+                            dimensions_ * sizeof(value_type));
+                return true;
+            }
+            auto input_stride_bytes = input.stride_bytes();
+            for (size_type element_index = 0; element_index < dimensions_; ++element_index) {
+                auto *target =
+                    reinterpret_cast<value_type *>(data_ + static_cast<difference_type>(element_index) * stride_bytes_);
+                auto const *source = reinterpret_cast<value_type const *>(
+                    input.byte_data() + static_cast<difference_type>(element_index) * input_stride_bytes);
+                *target = *source;
+            }
+            return true;
+        }
+    }
 };
 
 #pragma endregion Vector Span
@@ -751,6 +835,15 @@ struct vector {
     iterator end() noexcept { return {*this, dimensions_}; }
     const_iterator end() const noexcept { return {*this, dimensions_}; }
     const_iterator cend() const noexcept { return {*this, dimensions_}; }
+
+    /** @brief Zero-fill every element. */
+    bool fill_zeros() noexcept { return span().fill_zeros(); }
+
+    /** @brief Fill every element with `value`. */
+    bool fill(value_type value) noexcept { return span().fill(value); }
+
+    /** @brief Copy from a same-size view. */
+    bool copy_from(vector_view<value_type> input) noexcept { return span().copy_from(input); }
 };
 
 /** @brief Non-member swap. */

package/numkong/javascript/@numkong-darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/darwin-arm64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "macOS arm64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/@numkong-darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/darwin-x64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "macOS x64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/@numkong-linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/linux-arm64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "Linux arm64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/@numkong-linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/linux-x64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "Linux x64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/@numkong-win32-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/win32-arm64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "Windows arm64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/@numkong-win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@numkong/win32-x64",
-  "version": "7.6.0",
+  "version": "7.8.1",
   "description": "Windows x64 native binary for NumKong",
   "repository": {
     "type": "git",

package/numkong/javascript/README.md

@@ -31,15 +31,18 @@ This binding stays centered on the vector families it actually exports.
 
 ## Ecosystem Comparison
 
-| Feature                      | NumKong                                                        | [mathjs](https://github.com/josdejong/mathjs) | [tensorflow.js](https://github.com/tensorflow/tfjs) |
-| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------- |
-| Operation families           | dots, distances, binary, probability, cast, packed, symmetric  | general arithmetic, matrix ops, statistics    | matmul, elementwise, reductions                     |
-| Precision                    | BFloat16 through sub-byte; automatic widening; Kahan summation | Float64 only; standard accuracy               | Float32 primarily; no sub-byte; standard accuracy   |
-| Runtime SIMD dispatch        | auto-selects best ISA per-thread across x86, ARM, RISC-V       | none; pure JS                                 | fixed at build time via WASM SIMD or WebGL          |
-| Packed matrix, GEMM-like     | `dotsPack` + `dotsPacked`; persistent packing; amortized       | `math.multiply` — no persistent packing       | `tf.matMul` — no persistent packing                 |
-| Symmetric kernels, SYRK-like | `dotsSymmetric`; upper triangle only; row-range partitioning   | no duplicate-pair skipping                    | no duplicate-pair skipping                          |
-| WASM fallback                | yes — portable, runs in browser without native addon           | yes — pure JS, no native required             | yes — also WebGL/WebGPU                             |
-| Bundle size                  | small                                                          | moderate                                      | large                                               |
+| Feature                      | NumKong                                                        | [mathjs][mathjs]                           | [tensorflow.js][tensorflow-js]                    |
+| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------- |
+| Operation families           | dots, distances, binary, probability, cast, packed, symmetric  | general arithmetic, matrix ops, statistics | matmul, elementwise, reductions                   |
+| Precision                    | BFloat16 through sub-byte; automatic widening; Kahan summation | Float64 only; standard accuracy            | Float32 primarily; no sub-byte; standard accuracy |
+| Runtime SIMD dispatch        | auto-selects best ISA per-thread across x86, ARM, RISC-V       | none; pure JS                              | fixed at build time via WASM SIMD or WebGL        |
+| Packed matrix, GEMM-like     | `dotsPack` + `dotsPacked`; persistent packing; amortized       | `math.multiply` — no persistent packing    | `tf.matMul` — no persistent packing               |
+| Symmetric kernels, SYRK-like | `dotsSymmetric`; upper triangle only; row-range partitioning   | no duplicate-pair skipping                 | no duplicate-pair skipping                        |
+| WASM fallback                | yes — portable, runs in browser without native addon           | yes — pure JS, no native required          | yes — also WebGL/WebGPU                           |
+| Bundle size                  | small                                                          | moderate                                   | large                                             |
+
+[mathjs]: https://github.com/josdejong/mathjs
+[tensorflow-js]: https://github.com/tensorflow/tfjs
 
 ## Installation
 
@@ -74,11 +77,7 @@ For self-hosted WASM, download the binaries from a [GitHub Release](https://gith
 
 ```html
 <script type="module">
-  import * as numkong from "./numkong-emscripten.js";
-  import NumKongModule from "./numkong.js";
-
-  const wasm = await NumKongModule();
-  numkong.initWasm(wasm);
+  import * as numkong from "./numkong.js";
 
   const a = new Float32Array([1, 2, 3]);
   const b = new Float32Array([4, 5, 6]);
@@ -86,6 +85,9 @@ For self-hosted WASM, download the binaries from a [GitHub Release](https://gith
 </script>
 ```
 
+The release archive ships `numkong.js`, `numkong-emscripten.js`, and `numkong.wasm`.
+Only `numkong.js` is imported — it locates the other two next to itself and instantiates the module before any export is used.
+
 Or import the subpath from a bundler or Node.js (without the native addon):
 
 ```js
@@ -186,11 +188,11 @@ console.log(a8.byteLength);
 
 If the underlying storage is a raw `Uint16Array` or `Uint8Array`, JS itself cannot know whether those bytes mean integers, `f16`, `bf16`, mini-floats, or packed bits.
 That is exactly when the `DType` tag becomes mandatory.
-You can also pass it to `cast` to convert many values between all supported types:
+`cast` converts many values between all supported types, naming both sides by their dtype string:
 
 ```ts
 numkong.cast(f32Source, "f32", bf16Dest, "bf16");
-numkong.cast(f32Source, "f32", bf16Dest, DType.E4M3);
+numkong.cast(f32Source, "f32", e4m3Dest, "e4m3");
 ```
 
 ## Vector Views and Owned Buffers

package/numkong/javascript/numkong.c

@@ -9,16 +9,11 @@
 
 #include <string.h> // `strcmp` function
 
-#if defined(NK_USE_OPENMP)
-#include <omp.h>
-#endif
-
 #include <node_api.h> // `napi_*` functions — N-API v6+ for BigInt (Node ≥ 10.20)
 
 #include <numkong/numkong.h> // `nk_*` functions — must be first to bring `_GNU_SOURCE`
 
-#define NK_PARALLEL_PACKED_TILE    64
-#define NK_PARALLEL_SYMMETRIC_TILE 32
+#include "parallel.h" // `nk_parallel_for_tiles`, tile sizes
 
 /** @brief Global variable that caches the CPU capabilities, and is computed just once, when the module is loaded. */
 nk_capability_t static_capabilities = nk_cap_serial_k;
@@ -484,6 +479,28 @@ static napi_value api_dots_pack(napi_env env, napi_callback_info info) {
     return result_obj;
 }
 
+/** @brief One tile of rows of C = A × Bᵀ with B pre-packed. */
+typedef struct packed_task_t {
+    nk_dots_packed_punned_t kernel;
+    char const *a;
+    void const *b_packed;
+    char *c;
+    nk_size_t rows;
+    nk_size_t columns;
+    nk_size_t depth;
+    nk_size_t a_stride_bytes;
+    nk_size_t c_stride_bytes;
+} packed_task_t;
+
+static void packed_tile_(nk_size_t tile_index, void *context) {
+    packed_task_t const *task = (packed_task_t const *)context;
+    nk_size_t const row = tile_index * NK_PARALLEL_PACKED_TILE;
+    nk_size_t const chunk = (row + NK_PARALLEL_PACKED_TILE <= task->rows) ? NK_PARALLEL_PACKED_TILE
+                                                                          : (task->rows - row);
+    task->kernel(task->a + row * task->a_stride_bytes, task->b_packed, task->c + row * task->c_stride_bytes, chunk,
+                 task->columns, task->depth, task->a_stride_bytes, task->c_stride_bytes);
+}
+
 /**
  *  @brief Shared dispatcher for packed operations (dots, angulars, euclideans).
  *  Args: TypedArray a, ArrayBuffer packed, TypedArray result, numbers height/width/depth/aStride/resultStride, string
@@ -544,23 +561,17 @@ static napi_value api_packed_common(napi_env env, napi_callback_info info, nk_ke
     uint32_t threads = 1;
     if (argc == 10) napi_get_value_uint32(env, args[9], &threads);
 
-#if defined(NK_USE_OPENMP)
-    if (threads == 0) threads = (uint32_t)omp_get_max_threads();
-    omp_set_num_threads((int)threads);
-#endif
-
-    // `int` loop counter pre-declared: MSVC's OpenMP stays at 2.0 canonical
-    // form, which forbids in-init declarations and rejects 64-bit iterators
-    // — either would trip C3015.
-    int const tile_count = (int)nk_size_divide_round_up_(height, NK_PARALLEL_PACKED_TILE);
-    int tile_idx;
-#pragma omp parallel for schedule(dynamic, 1) if (threads > 1)
-    for (tile_idx = 0; tile_idx < tile_count; tile_idx++) {
-        nk_size_t row = (nk_size_t)tile_idx * NK_PARALLEL_PACKED_TILE;
-        nk_size_t chunk = (row + NK_PARALLEL_PACKED_TILE <= height) ? NK_PARALLEL_PACKED_TILE : (height - row);
-        kernel((char const *)a_data + row * a_stride, packed_data, (char *)result_data + row * result_stride, chunk,
-               (nk_size_t)width, (nk_size_t)depth, (nk_size_t)a_stride, (nk_size_t)result_stride);
-    }
+    packed_task_t task;
+    task.kernel = kernel;
+    task.a = a_data;
+    task.b_packed = packed_data;
+    task.c = result_data;
+    task.rows = height;
+    task.columns = width;
+    task.depth = depth;
+    task.a_stride_bytes = a_stride;
+    task.c_stride_bytes = result_stride;
+    nk_parallel_for_tiles(nk_size_divide_round_up_(height, NK_PARALLEL_PACKED_TILE), threads, packed_tile_, &task);
     return NULL;
 }
 
@@ -574,6 +585,29 @@ static napi_value api_euclideans_packed(napi_env env, napi_callback_info info) {
     return api_packed_common(env, info, nk_kernel_euclideans_packed_k);
 }
 
+/** @brief One tile of rows of C = A × Aᵀ. */
+typedef struct symmetric_task_t {
+    nk_dots_symmetric_punned_t kernel;
+    void const *vectors;
+    void *result;
+    nk_size_t vectors_count;
+    nk_size_t depth;
+    nk_size_t stride_bytes;
+    nk_size_t result_stride_bytes;
+    nk_size_t row_start;
+    nk_size_t row_end;
+} symmetric_task_t;
+
+static void symmetric_tile_(nk_size_t tile_index, void *context) {
+    symmetric_task_t const *task = (symmetric_task_t const *)context;
+    nk_size_t const tile_start = task->row_start + tile_index * NK_PARALLEL_SYMMETRIC_TILE;
+    nk_size_t const tile_rows = (tile_start + NK_PARALLEL_SYMMETRIC_TILE <= task->row_end)
+                                    ? NK_PARALLEL_SYMMETRIC_TILE
+                                    : (task->row_end - tile_start);
+    task->kernel(task->vectors, task->vectors_count, task->depth, task->stride_bytes, task->result,
+                 task->result_stride_bytes, tile_start, tile_rows);
+}
+
 /**
  *  @brief Shared dispatcher for symmetric operations (dots, angulars, euclideans).
  *  Args: TypedArray vectors, TypedArray result, numbers nVectors/depth/vectorsStride/resultStride/rowStart/rowCount,
@@ -630,23 +664,19 @@ static napi_value api_symmetric_common(napi_env env, napi_callback_info info, nk
     uint32_t threads = 1;
     if (argc == 10) napi_get_value_uint32(env, args[9], &threads);
 
-#if defined(NK_USE_OPENMP)
-    if (threads == 0) threads = (uint32_t)omp_get_max_threads();
-    omp_set_num_threads((int)threads);
-#endif
-
-    // `int` loop counter pre-declared: see note at `api_packed_common`.
-    int const tile_count = (int)nk_size_divide_round_up_(row_count, NK_PARALLEL_SYMMETRIC_TILE);
-    int tile_idx;
-#pragma omp parallel for schedule(dynamic, 1) if (threads > 1)
-    for (tile_idx = 0; tile_idx < tile_count; tile_idx++) {
-        nk_size_t tile_start = (nk_size_t)row_start + (nk_size_t)tile_idx * NK_PARALLEL_SYMMETRIC_TILE;
-        nk_size_t tile_rows = (tile_start + NK_PARALLEL_SYMMETRIC_TILE <= (nk_size_t)row_start + row_count)
-                                  ? NK_PARALLEL_SYMMETRIC_TILE
-                                  : ((nk_size_t)row_start + row_count - tile_start);
-        kernel(vectors_data, (nk_size_t)n_vectors, (nk_size_t)depth, (nk_size_t)vectors_stride, result_data,
-               (nk_size_t)result_stride, tile_start, tile_rows);
-    }
+    symmetric_task_t task;
+    task.kernel = kernel;
+    task.vectors = vectors_data;
+    task.result = result_data;
+    task.vectors_count = n_vectors;
+    task.depth = depth;
+    task.stride_bytes = vectors_stride;
+    task.result_stride_bytes = result_stride;
+    task.row_start = row_start;
+    // Widen before the sum so two `uint32_t` row bounds cannot wrap.
+    task.row_end = (nk_size_t)row_start + row_count;
+    nk_parallel_for_tiles(nk_size_divide_round_up_(row_count, NK_PARALLEL_SYMMETRIC_TILE), threads, symmetric_tile_,
+                          &task);
 
     return NULL;
 }