numkong 7.0.0 → 7.4.1

package/include/numkong/geospatial.h

@@ -78,15 +78,15 @@
  *  but only execute once per point-pair. The polynomial trig approximations use FMA chains.
  *  Note: ZMM sqrt is faster on Genoa (15c) than Ice Lake (19c) due to better 512-bit support.
  *
- *      Intrinsic               Instruction                     Ice         Genoa
- *      _mm256_sqrt_ps          VSQRTPS (YMM, YMM)              12c @ p0    15c @ p01
- *      _mm256_sqrt_pd          VSQRTPD (YMM, YMM)              13c @ p0    21c @ p01
- *      _mm512_sqrt_ps          VSQRTPS (ZMM, ZMM)              19c @ p05   15c @ p01
- *      _mm512_sqrt_pd          VSQRTPD (ZMM, ZMM)              23c @ p05   21c @ p01
- *      _mm256_div_ps           VDIVPS (YMM, YMM, YMM)          11c @ p0    11c @ p01
- *      _mm256_div_pd           VDIVPD (YMM, YMM, YMM)          13c @ p0    13c @ p01
- *      _mm256_fmadd_ps         VFMADD231PS (YMM, YMM, YMM)     4c @ p01    4c @ p01
- *      _mm256_fmadd_pd         VFMADD231PD (YMM, YMM, YMM)     4c @ p01    4c @ p01
+ *      Intrinsic        Instruction                  Icelake           Genoa
+ *      _mm256_sqrt_ps   VSQRTPS (YMM, YMM)           12cy @ p0         15cy @ p01
+ *      _mm256_sqrt_pd   VSQRTPD (YMM, YMM)           13cy @ p0         21cy @ p01
+ *      _mm512_sqrt_ps   VSQRTPS (ZMM, ZMM)           19cy @ p0+p0+p05  15cy @ p01
+ *      _mm512_sqrt_pd   VSQRTPD (ZMM, ZMM)           23cy @ p0+p0+p05  21cy @ p01
+ *      _mm256_div_ps    VDIVPS (YMM, YMM, YMM)       11cy @ p0         11cy @ p01
+ *      _mm256_div_pd    VDIVPD (YMM, YMM, YMM)       13cy @ p0         13cy @ p01
+ *      _mm256_fmadd_ps  VFMADD231PS (YMM, YMM, YMM)  4cy @ p01         4cy @ p01
+ *      _mm256_fmadd_pd  VFMADD231PD (YMM, YMM, YMM)  4cy @ p01         4cy @ p01
  *
  *  @section arm_instructions Relevant ARM NEON/SVE Instructions
  *
@@ -94,21 +94,21 @@
  *  acceptable since sqrt only appears once per distance calculation. FMA chains for trig
  *  polynomial evaluation pipeline well across all 4 V-units.
  *
- *      Intrinsic               Instruction     M1 Firestorm    Graviton 3      Graviton 4
- *      vfmaq_f32               FMLA.S (vec)    4c @ V0123      4c @ V0123      4c @ V0123
- *      vfmaq_f64               FMLA.D (vec)    4c @ V0123      4c @ V0123      4c @ V0123
- *      vsqrtq_f32              FSQRT.S (vec)   10c @ V02       10c @ V02       9c @ V02
- *      vsqrtq_f64              FSQRT.D (vec)   13c @ V02       16c @ V02       16c @ V02
+ *      Intrinsic   Instruction    M1 Firestorm  Graviton 3   Graviton 4
+ *      vfmaq_f32   FMLA.S (vec)   4cy @ V0123   4cy @ V0123  4cy @ V0123
+ *      vfmaq_f64   FMLA.D (vec)   4cy @ V0123   4cy @ V0123  4cy @ V0123
+ *      vsqrtq_f32  FSQRT.S (vec)  10cy @ V02    10cy @ V02   9cy @ V02
+ *      vsqrtq_f64  FSQRT.D (vec)  13cy @ V02    16cy @ V02   16cy @ V02
  *
  *  @section references References
  *
- *  - x86 intrinsics: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/
+ *  - x86 intrinsics: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html
  *  - Arm intrinsics: https://developer.arm.com/architectures/instruction-sets/intrinsics/
  *  - Earth Ellipsoid: https://en.wikipedia.org/wiki/Earth_ellipsoid
  *  - Oblate Spheroid Geodesic: https://mathworld.wolfram.com/OblateSpheroidGeodesic.html
- *  - Staging experiments: https://github.com/ashvardanian/HaversineMathKong
  *  - Speeding up atan2f by 50x: https://mazzo.li/posts/vectorized-atan2.html
- *  - Simplifying the GNU C Sine Function: https://www.awelm.com/posts/simplifying-the-gnu-c-sine-function/
+ *  - Simplifying the GNU C Sine Function:
+ *    https://web.archive.org/web/20230605051610/https://www.awelm.com/posts/simplifying-the-gnu-c-sine-function/
  *
  */
 #ifndef NK_GEOSPATIAL_H

package/include/numkong/matrix.hpp

@@ -26,7 +26,7 @@
 
 namespace ashvardanian::numkong {
 
-#pragma region - Packing Utilities
+#pragma region Packing Utilities
 
 /**
  *  @brief Estimates the memory requirements for packed B matrix.
@@ -155,9 +155,9 @@ NK_PUBLIC void maxsim_pack(typename in_type_::raw_t const *vectors, std::size_t
     }
 }
 
-#pragma endregion - Packing Utilities
+#pragma endregion Packing Utilities
 
-#pragma region - Packed Containers
+#pragma region Packed Containers
 
 /**
  *  @brief Owning, move-only, pre-packed matrix for efficient GEMM.
@@ -329,7 +329,7 @@ class packed_maxsim {
     std::size_t size_bytes() const noexcept { return size_bytes_; }
 };
 
-#pragma endregion - Packed Containers
+#pragma endregion Packed Containers
 
 } // namespace ashvardanian::numkong
 

package/include/numkong/maxsim/README.md

@@ -4,21 +4,21 @@ NumKong implements ColBERT-style late-interaction scoring: the MaxSim score sums
 
 MaxSim score:
 
-```math
+$$
 \text{MaxSim}(Q, D) = \sum_{i=0}^{m-1} \min_{j=0}^{n-1} \text{angular}(q_i, d_j)
-```
+$$
 
 Coarse screening finds the best document via i8 dot products as a proxy for argmin angular:
 
-```math
+$$
 j^* = \arg\max_j \text{dot}_{\text{i8}}(q_i, d_j)
-```
+$$
 
 Full-precision refinement:
 
-```math
+$$
 \text{angular}(q_i, d_{j^*}) = 1 - \frac{\text{dot}(q_i, d_{j^*})}{\|q_i\| \cdot \|d_{j^*}\|}
-```
+$$
 
 Reformulating as Python pseudocode:
 
@@ -46,7 +46,7 @@ def maxsim(queries: np.ndarray, documents: np.ndarray) -> float:
 
 ## Optimizations
 
-### Dual Pre-Packing Advantage
+### Dual Pre-Packing
 
 `nk_maxsim_packed_bf16_sme`, `nk_maxsim_packed_f32_sme` benefit from having _both_ query and document matrices pre-packed into identical contiguous formats, unlike the `nk_dots_packed_*` family where only B is pre-packed and A is accessed with arbitrary stride.
 In the dots GEMM, one ZA tile must be reserved for A-side staging (loading unpacked A rows into the tile array), leaving 3 ZA tiles for accumulation.
@@ -172,16 +172,16 @@ Measured with Wasmtime v42 (Cranelift backend).
 
 #### WASM
 
-Measured with Wasmtime v42 (Cranelift backend).
+Measured with Wasmtime v43 (Cranelift backend).
 
 | Kernel                              |                     256³ |                    1024³ |                    4096³ |
 | :---------------------------------- | -----------------------: | -----------------------: | -----------------------: |
 | __f32__                             | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
-| `nk_maxsim_packed_f32_serial`       |    9.22 gso/s, 46.8K ulp |    10.1 gso/s, 46.8K ulp |    10.5 gso/s, 46.8K ulp |
-| `nk_maxsim_packed_f32_v128relaxed`  |    28.9 gso/s, 46.0K ulp |    31.2 gso/s, 46.0K ulp |    32.0 gso/s, 46.0K ulp |
+| `nk_maxsim_packed_f32_serial`       |    33.7 gso/s, 46.8K ulp |    35.0 gso/s, 46.8K ulp |    35.8 gso/s, 46.8K ulp |
+| `nk_maxsim_packed_f32_v128relaxed`  |    88.5 gso/s, 46.0K ulp |    98.1 gso/s, 46.0K ulp |    82.7 gso/s, 46.0K ulp |
 | __bf16__                            | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
-| `nk_maxsim_packed_bf16_serial`      |    8.95 gso/s, 49.2K ulp |    10.1 gso/s, 49.2K ulp |    10.0 gso/s, 49.2K ulp |
-| `nk_maxsim_packed_bf16_v128relaxed` |    29.6 gso/s, 49.4K ulp |    31.9 gso/s, 49.4K ulp |    31.6 gso/s, 49.4K ulp |
+| `nk_maxsim_packed_bf16_serial`      |    34.4 gso/s, 49.2K ulp |    35.1 gso/s, 49.2K ulp |    35.7 gso/s, 49.2K ulp |
+| `nk_maxsim_packed_bf16_v128relaxed` |    92.3 gso/s, 49.4K ulp |     100 gso/s, 49.4K ulp |    83.2 gso/s, 49.4K ulp |
 | __f16__                             | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ | ░░░░░░░░░░░░░░░░░░░░░░░░ |
-| `nk_maxsim_packed_f16_serial`       |    9.21 gso/s, 49.5K ulp |    10.3 gso/s, 49.5K ulp |    10.6 gso/s, 49.5K ulp |
-| `nk_maxsim_packed_f16_v128relaxed`  |    27.2 gso/s, 49.3K ulp |    33.7 gso/s, 49.3K ulp |    31.5 gso/s, 49.3K ulp |
+| `nk_maxsim_packed_f16_serial`       |    33.8 gso/s, 49.5K ulp |    35.0 gso/s, 49.5K ulp |    35.7 gso/s, 49.5K ulp |
+| `nk_maxsim_packed_f16_v128relaxed`  |    87.0 gso/s, 49.3K ulp |    95.8 gso/s, 49.3K ulp |    82.3 gso/s, 49.3K ulp |

package/include/numkong/maxsim/alder.h

@@ -57,7 +57,7 @@ NK_PUBLIC nk_size_t nk_maxsim_packed_size_f16_alder(nk_size_t vector_count, nk_s
 }
 
 NK_PUBLIC void nk_maxsim_pack_bf16_alder( //
-    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_bf16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -69,7 +69,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_alder( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_bf16_to_f32_serial,
@@ -83,7 +83,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_alder( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f32_alder( //
-    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f32_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -95,7 +95,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_alder( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f, nk_f32_to_f32_,
                                    &quantized_i8[vector_index * depth_i8_padded], &metadata[vector_index], &norm_sq);
@@ -108,7 +108,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_alder( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f16_alder( //
-    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -120,7 +120,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_alder( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_f16_to_f32_haswell,

package/include/numkong/maxsim/genoa.h

@@ -9,8 +9,8 @@
  *  Uses AVX-512 VNNI (VPDPBUSD) for coarse i8 screening via icelake.h, and VDPBF16PS for bf16 refinement.
  *  f32/f16 MaxSim variants live in icelake.h — this file only provides bf16 pack and compute.
  *
- *      Intrinsic                   Instruction     Genoa (Zen4)
- *      _mm512_dpbf16_ps            VDPBF16PS       6cy @ p01 (512-bit)
+ *      Intrinsic         Instruction  Genoa
+ *      _mm512_dpbf16_ps  VDPBF16PS    6cy @ p01
  */
 #ifndef NK_MAXSIM_GENOA_H
 #define NK_MAXSIM_GENOA_H
@@ -41,7 +41,7 @@ NK_PUBLIC nk_size_t nk_maxsim_packed_size_bf16_genoa(nk_size_t vector_count, nk_
 }
 
 NK_PUBLIC void nk_maxsim_pack_bf16_genoa( //
-    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_bf16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 64, element_bytes);
@@ -53,7 +53,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_genoa( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_bf16_to_f32_serial,

package/include/numkong/maxsim/haswell.h

@@ -49,7 +49,7 @@ NK_PUBLIC nk_size_t nk_maxsim_packed_size_f16_haswell(nk_size_t vector_count, nk
 }
 
 NK_PUBLIC void nk_maxsim_pack_bf16_haswell( //
-    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_bf16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -61,7 +61,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_haswell( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 79.0f,
                                    (nk_maxsim_to_f32_t)nk_bf16_to_f32_serial,
@@ -75,7 +75,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_haswell( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f32_haswell( //
-    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f32_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -87,7 +87,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_haswell( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 79.0f, nk_f32_to_f32_,
                                    &quantized_i8[vector_index * depth_i8_padded], &metadata[vector_index], &norm_sq);
@@ -100,7 +100,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_haswell( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f16_haswell( //
-    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 32, element_bytes);
@@ -112,7 +112,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_haswell( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 79.0f,
                                    (nk_maxsim_to_f32_t)nk_f16_to_f32_haswell,

package/include/numkong/maxsim/icelake.h

@@ -9,15 +9,15 @@
  *  Uses AVX-512 VNNI (VPDPBUSD) for coarse i8 screening. The coarse argmax kernel and reduce helper
  *  are shared with genoa.h — genoa.h imports them from this file for its bf16 compute path.
  *
- *  VPDPBUSD computes 4 groups of (u8 x i8) -> i32 per 128-bit lane, processing 64 i8 pairs
+ *  VPDPBUSD computes 4 groups of (u8 × i8) → i32 per 128-bit lane, processing 64 i8 pairs
  *  per ZMM register operation. Bias correction via XOR with 0x80 converts signed queries
  *  to unsigned, then subtracts 128 * sum(document_i8) after the depth loop.
  *
- *  4x4 register tiling: 4 queries x 4 documents = 16 ZMM accumulators per depth loop.
+ *  4x4 register tiling: 4 queries × 4 documents = 16 ZMM accumulators per depth loop.
  *  Each document load is amortized across 4 VPDPBUSDs, and each query load across 4 documents.
  *
- *      Intrinsic                   Instruction     Icelake         Genoa (Zen4)
- *      _mm512_dpbusd_epi32         VPDPBUSD        5cy @ p0        4cy @ p01 (512-bit)
+ *      Intrinsic            Instruction  Icelake   Genoa
+ *      _mm512_dpbusd_epi32  VPDPBUSD     5cy @ p0  4cy @ p01
  */
 #ifndef NK_MAXSIM_ICELAKE_H
 #define NK_MAXSIM_ICELAKE_H
@@ -44,14 +44,14 @@ extern "C" {
 #pragma GCC target("avx2", "avx512f", "avx512vl", "avx512bw", "avx512dq", "avx512vnni", "f16c", "fma", "bmi", "bmi2")
 #endif
 
-#pragma region Single Precision Floats
+#pragma region F32 Floats
 
 NK_PUBLIC nk_size_t nk_maxsim_packed_size_f32_icelake(nk_size_t vector_count, nk_size_t depth) {
     return nk_maxsim_packed_size_(vector_count, depth, sizeof(nk_f32_t), 64);
 }
 
 NK_PUBLIC void nk_maxsim_pack_f32_icelake( //
-    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f32_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 64, element_bytes);
@@ -63,7 +63,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_icelake( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f, nk_f32_to_f32_,
                                    &quantized_i8[vector_index * depth_i8_padded], &metadata[vector_index], &norm_sq);
@@ -75,16 +75,16 @@ NK_PUBLIC void nk_maxsim_pack_f32_icelake( //
     }
 }
 
-#pragma endregion
+#pragma endregion F32 Floats
 
-#pragma region Half Precision Floats
+#pragma region F16 Floats
 
 NK_PUBLIC nk_size_t nk_maxsim_packed_size_f16_icelake(nk_size_t vector_count, nk_size_t depth) {
     return nk_maxsim_packed_size_(vector_count, depth, sizeof(nk_f16_t), 64);
 }
 
 NK_PUBLIC void nk_maxsim_pack_f16_icelake( //
-    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 64, element_bytes);
@@ -96,7 +96,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_icelake( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_f16_to_f32_haswell,
@@ -109,7 +109,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_icelake( //
     }
 }
 
-#pragma endregion
+#pragma endregion F16 Floats
 
 #pragma region Coarse Argmax
 
@@ -117,7 +117,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_icelake( //
 NK_INTERNAL __m128i nk_maxsim_reduce_i32x16x4_icelake_(         //
     __m512i accumulator_a_i32x16, __m512i accumulator_b_i32x16, //
     __m512i accumulator_c_i32x16, __m512i accumulator_d_i32x16) {
-    // Step 1: 16 -> 8 (extract high 256-bit half and add to low half)
+    // Step 1: 16 → 8 (extract high 256-bit half and add to low half)
     __m256i sum_a_i32x8 = _mm256_add_epi32(_mm512_castsi512_si256(accumulator_a_i32x16),
                                            _mm512_extracti32x8_epi32(accumulator_a_i32x16, 1));
     __m256i sum_b_i32x8 = _mm256_add_epi32(_mm512_castsi512_si256(accumulator_b_i32x16),
@@ -126,12 +126,12 @@ NK_INTERNAL __m128i nk_maxsim_reduce_i32x16x4_icelake_(         //
                                            _mm512_extracti32x8_epi32(accumulator_c_i32x16, 1));
     __m256i sum_d_i32x8 = _mm256_add_epi32(_mm512_castsi512_si256(accumulator_d_i32x16),
                                            _mm512_extracti32x8_epi32(accumulator_d_i32x16, 1));
-    // Step 2: 8 -> 4 (extract high 128-bit half and add to low half)
+    // Step 2: 8 → 4 (extract high 128-bit half and add to low half)
     __m128i sum_a_i32x4 = _mm_add_epi32(_mm256_castsi256_si128(sum_a_i32x8), _mm256_extracti128_si256(sum_a_i32x8, 1));
     __m128i sum_b_i32x4 = _mm_add_epi32(_mm256_castsi256_si128(sum_b_i32x8), _mm256_extracti128_si256(sum_b_i32x8, 1));
     __m128i sum_c_i32x4 = _mm_add_epi32(_mm256_castsi256_si128(sum_c_i32x8), _mm256_extracti128_si256(sum_c_i32x8, 1));
     __m128i sum_d_i32x4 = _mm_add_epi32(_mm256_castsi256_si128(sum_d_i32x8), _mm256_extracti128_si256(sum_d_i32x8, 1));
-    // Step 3: 4x4 transpose + reduce -> [sum_a, sum_b, sum_c, sum_d]
+    // Step 3: 4x4 transpose + reduce → [sum_a, sum_b, sum_c, sum_d]
     __m128i transpose_ab_low_i32x4 = _mm_unpacklo_epi32(sum_a_i32x4, sum_b_i32x4);
     __m128i transpose_cd_low_i32x4 = _mm_unpacklo_epi32(sum_c_i32x4, sum_d_i32x4);
     __m128i transpose_ab_high_i32x4 = _mm_unpackhi_epi32(sum_a_i32x4, sum_b_i32x4);
@@ -258,7 +258,7 @@ NK_INTERNAL void nk_maxsim_coarse_argmax_icelake_(        //
             query_2_coarse_dots_i32x4 = _mm_sub_epi32(query_2_coarse_dots_i32x4, bias_correction_i32x4);
             query_3_coarse_dots_i32x4 = _mm_sub_epi32(query_3_coarse_dots_i32x4, bias_correction_i32x4);
 
-            // 4x4 transpose: [query][doc] -> [doc][query] for vectorized argmax
+            // 4x4 transpose: [query][doc] → [doc][query] for vectorized argmax
             __m128i transpose_queries_01_low_i32x4 = _mm_unpacklo_epi32(query_0_coarse_dots_i32x4,
                                                                         query_1_coarse_dots_i32x4);
             __m128i transpose_queries_23_low_i32x4 = _mm_unpacklo_epi32(query_2_coarse_dots_i32x4,
@@ -390,7 +390,7 @@ NK_INTERNAL void nk_maxsim_coarse_argmax_icelake_(        //
     }
 }
 
-#pragma endregion
+#pragma endregion Coarse Argmax
 
 #pragma region Compute Functions
 
@@ -463,7 +463,7 @@ NK_PUBLIC void nk_maxsim_packed_f16_icelake( //
     *result = (nk_f32_t)total_angular_distance;
 }
 
-#pragma endregion
+#pragma endregion Compute Functions
 
 #if defined(__clang__)
 #pragma clang attribute pop

package/include/numkong/maxsim/neonsdot.h

@@ -46,7 +46,7 @@ NK_PUBLIC nk_size_t nk_maxsim_packed_size_f16_neonsdot(nk_size_t vector_count, n
 }
 
 NK_PUBLIC void nk_maxsim_pack_bf16_neonsdot( //
-    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_bf16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_bf16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 16, element_bytes);
@@ -58,7 +58,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_neonsdot( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_bf16_to_f32_serial,
@@ -72,7 +72,7 @@ NK_PUBLIC void nk_maxsim_pack_bf16_neonsdot( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f32_neonsdot( //
-    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f32_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f32_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 16, element_bytes);
@@ -84,7 +84,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_neonsdot( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f, nk_f32_to_f32_,
                                    &quantized_i8[vector_index * depth_i8_padded], &metadata[vector_index], &norm_sq);
@@ -97,7 +97,7 @@ NK_PUBLIC void nk_maxsim_pack_f32_neonsdot( //
 }
 
 NK_PUBLIC void nk_maxsim_pack_f16_neonsdot( //
-    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride, void *packed) {
+    nk_f16_t const *vectors, nk_size_t vector_count, nk_size_t depth, nk_size_t stride_in_bytes, void *packed) {
 
     nk_size_t const element_bytes = sizeof(nk_f16_t);
     nk_size_t depth_i8_padded = nk_maxsim_packed_header_setup_(packed, vector_count, depth, 16, element_bytes);
@@ -109,7 +109,7 @@ NK_PUBLIC void nk_maxsim_pack_f16_neonsdot( //
     nk_size_t const original_stride = header->original_stride_bytes;
 
     for (nk_size_t vector_index = 0; vector_index < vector_count; vector_index++) {
-        char const *source_row = (char const *)vectors + vector_index * stride;
+        char const *source_row = (char const *)vectors + vector_index * stride_in_bytes;
         nk_f32_t norm_sq;
         nk_maxsim_quantize_vector_(source_row, element_bytes, depth, depth_i8_padded, 127.0f,
                                    (nk_maxsim_to_f32_t)nk_f16_to_f32_neon,
@@ -149,39 +149,39 @@ NK_INTERNAL void nk_maxsim_coarse_argmax_neonsdot_(
             // Depth loop: 16 bytes per step
             for (nk_size_t depth_index = 0; depth_index < depth_i8_padded; depth_index += 16) {
                 int8x16_t query_i8x16_0 = vld1q_s8(
-                    (int8_t const *)(query_i8 + (query_block_start_index + 0) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(query_i8 + (query_block_start_index + 0) * depth_i8_padded + depth_index));
                 int8x16_t query_i8x16_1 = vld1q_s8(
-                    (int8_t const *)(query_i8 + (query_block_start_index + 1) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(query_i8 + (query_block_start_index + 1) * depth_i8_padded + depth_index));
                 int8x16_t query_i8x16_2 = vld1q_s8(
-                    (int8_t const *)(query_i8 + (query_block_start_index + 2) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(query_i8 + (query_block_start_index + 2) * depth_i8_padded + depth_index));
                 int8x16_t query_i8x16_3 = vld1q_s8(
-                    (int8_t const *)(query_i8 + (query_block_start_index + 3) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(query_i8 + (query_block_start_index + 3) * depth_i8_padded + depth_index));
 
                 int8x16_t document_i8x16;
 
                 document_i8x16 = vld1q_s8(
-                    (int8_t const *)(document_i8 + (document_block_start_index + 0) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(document_i8 + (document_block_start_index + 0) * depth_i8_padded + depth_index));
                 accumulator_tiles_i32x4[0][0] = vdotq_s32(accumulator_tiles_i32x4[0][0], query_i8x16_0, document_i8x16);
                 accumulator_tiles_i32x4[1][0] = vdotq_s32(accumulator_tiles_i32x4[1][0], query_i8x16_1, document_i8x16);
                 accumulator_tiles_i32x4[2][0] = vdotq_s32(accumulator_tiles_i32x4[2][0], query_i8x16_2, document_i8x16);
                 accumulator_tiles_i32x4[3][0] = vdotq_s32(accumulator_tiles_i32x4[3][0], query_i8x16_3, document_i8x16);
 
                 document_i8x16 = vld1q_s8(
-                    (int8_t const *)(document_i8 + (document_block_start_index + 1) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(document_i8 + (document_block_start_index + 1) * depth_i8_padded + depth_index));
                 accumulator_tiles_i32x4[0][1] = vdotq_s32(accumulator_tiles_i32x4[0][1], query_i8x16_0, document_i8x16);
                 accumulator_tiles_i32x4[1][1] = vdotq_s32(accumulator_tiles_i32x4[1][1], query_i8x16_1, document_i8x16);
                 accumulator_tiles_i32x4[2][1] = vdotq_s32(accumulator_tiles_i32x4[2][1], query_i8x16_2, document_i8x16);
                 accumulator_tiles_i32x4[3][1] = vdotq_s32(accumulator_tiles_i32x4[3][1], query_i8x16_3, document_i8x16);
 
                 document_i8x16 = vld1q_s8(
-                    (int8_t const *)(document_i8 + (document_block_start_index + 2) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(document_i8 + (document_block_start_index + 2) * depth_i8_padded + depth_index));
                 accumulator_tiles_i32x4[0][2] = vdotq_s32(accumulator_tiles_i32x4[0][2], query_i8x16_0, document_i8x16);
                 accumulator_tiles_i32x4[1][2] = vdotq_s32(accumulator_tiles_i32x4[1][2], query_i8x16_1, document_i8x16);
                 accumulator_tiles_i32x4[2][2] = vdotq_s32(accumulator_tiles_i32x4[2][2], query_i8x16_2, document_i8x16);
                 accumulator_tiles_i32x4[3][2] = vdotq_s32(accumulator_tiles_i32x4[3][2], query_i8x16_3, document_i8x16);
 
                 document_i8x16 = vld1q_s8(
-                    (int8_t const *)(document_i8 + (document_block_start_index + 3) * depth_i8_padded + depth_index));
+                    (nk_i8_t const *)(document_i8 + (document_block_start_index + 3) * depth_i8_padded + depth_index));
                 accumulator_tiles_i32x4[0][3] = vdotq_s32(accumulator_tiles_i32x4[0][3], query_i8x16_0, document_i8x16);
                 accumulator_tiles_i32x4[1][3] = vdotq_s32(accumulator_tiles_i32x4[1][3], query_i8x16_1, document_i8x16);
                 accumulator_tiles_i32x4[2][3] = vdotq_s32(accumulator_tiles_i32x4[2][3], query_i8x16_2, document_i8x16);
@@ -211,27 +211,27 @@ NK_INTERNAL void nk_maxsim_coarse_argmax_neonsdot_(
             int32x4_t accumulator_i32x4_3 = vdupq_n_s32(0);
 
             for (nk_size_t depth_index = 0; depth_index < depth_i8_padded; depth_index += 16) {
-                int8x16_t document_i8x16 = vld1q_s8((int8_t const *)(document_i8_row + depth_index));
+                int8x16_t document_i8x16 = vld1q_s8((nk_i8_t const *)(document_i8_row + depth_index));
 
                 accumulator_i32x4_0 = vdotq_s32(
                     accumulator_i32x4_0,
                     vld1q_s8(
-                        (int8_t const *)(query_i8 + (query_block_start_index + 0) * depth_i8_padded + depth_index)),
+                        (nk_i8_t const *)(query_i8 + (query_block_start_index + 0) * depth_i8_padded + depth_index)),
                     document_i8x16);
                 accumulator_i32x4_1 = vdotq_s32(
                     accumulator_i32x4_1,
                     vld1q_s8(
-                        (int8_t const *)(query_i8 + (query_block_start_index + 1) * depth_i8_padded + depth_index)),
+                        (nk_i8_t const *)(query_i8 + (query_block_start_index + 1) * depth_i8_padded + depth_index)),
                     document_i8x16);
                 accumulator_i32x4_2 = vdotq_s32(
                     accumulator_i32x4_2,
                     vld1q_s8(
-                        (int8_t const *)(query_i8 + (query_block_start_index + 2) * depth_i8_padded + depth_index)),
+                        (nk_i8_t const *)(query_i8 + (query_block_start_index + 2) * depth_i8_padded + depth_index)),
                     document_i8x16);
                 accumulator_i32x4_3 = vdotq_s32(
                     accumulator_i32x4_3,
                     vld1q_s8(
-                        (int8_t const *)(query_i8 + (query_block_start_index + 3) * depth_i8_padded + depth_index)),
+                        (nk_i8_t const *)(query_i8 + (query_block_start_index + 3) * depth_i8_padded + depth_index)),
                     document_i8x16);
             }
 
@@ -260,8 +260,8 @@ NK_INTERNAL void nk_maxsim_coarse_argmax_neonsdot_(
             int32x4_t accumulator_i32x4 = vdupq_n_s32(0);
 
             for (nk_size_t depth_index = 0; depth_index < depth_i8_padded; depth_index += 16) {
-                int8x16_t query_i8x16 = vld1q_s8((int8_t const *)(query_i8_row + depth_index));
-                int8x16_t document_i8x16 = vld1q_s8((int8_t const *)(document_i8_row + depth_index));
+                int8x16_t query_i8x16 = vld1q_s8((nk_i8_t const *)(query_i8_row + depth_index));
+                int8x16_t document_i8x16 = vld1q_s8((nk_i8_t const *)(document_i8_row + depth_index));
                 accumulator_i32x4 = vdotq_s32(accumulator_i32x4, query_i8x16, document_i8x16);
             }