usearch 2.21.4 → 2.25.1

package/javascript/usearch.ts

@@ -5,7 +5,7 @@ import { getFileName, getRoot } from "bindings";
 
 const compiled: Compiled = build(getBuildDir(getDirName()));
 
-type Vector = Float32Array | Float64Array | Int8Array;
+type Vector = Float32Array | Float64Array | Int8Array | Uint8Array;
 type Matrix = Vector[];
 type VectorOrMatrix = Vector | Matrix;
 
@@ -68,11 +68,16 @@ export enum MetricKind {
  */
 export enum ScalarKind {
   Unknown = "unknown",
-  F32 = "f32",
   F64 = "f64",
-  F16 = "f16",
+  F32 = "f32",
   BF16 = "bf16",
+  F16 = "f16",
+  E5M2 = "e5m2",
+  E4M3 = "e4m3",
+  E3M2 = "e3m2",
+  E2M3 = "e2m3",
   I8 = "i8",
+  U8 = "u8",
   B1 = "b1",
 }
 
@@ -167,7 +172,8 @@ function isVector(vectors: unknown) {
   return (
     vectors instanceof Float32Array ||
     vectors instanceof Float64Array ||
-    vectors instanceof Int8Array
+    vectors instanceof Int8Array ||
+    vectors instanceof Uint8Array
   );
 }
 
@@ -541,7 +547,8 @@ export class Index {
 type NumberArrayConstructor =
   | Float64ArrayConstructor
   | Float32ArrayConstructor
-  | Int8ArrayConstructor;
+  | Int8ArrayConstructor
+  | Uint8ArrayConstructor;
 /**
  * Performs an exact search on the given dataset to find the best matching vectors for each query.
  *
@@ -606,7 +613,8 @@ export function exactSearch(
   let targetType: NumberArrayConstructor;
   if (dataset instanceof Float64Array) targetType = Float64Array;
   else if (dataset instanceof Int8Array) targetType = Int8Array;
-  else targetType = Float32Array; // default to Float32Array if dataset is not Float64Array or Int8Array
+  else if (dataset instanceof Uint8Array) targetType = Uint8Array;
+  else targetType = Float32Array; // default to Float32Array if dataset is not Float64Array, Int8Array, or Uint8Array
 
   dataset = normalizeVectors(dataset, dimensions, targetType);
   queries = normalizeVectors(queries, dimensions, targetType);

package/numkong/.clang-tidy

@@ -0,0 +1,30 @@
+# Conservative clang-tidy configuration for a SIMD-heavy C99/C++23 library.
+# Intrinsics-heavy code triggers many false positives in certain checkers,
+# so we keep the enabled set narrow and focused on real bugs.
+---
+Checks: >
+  -*,
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-narrowing-conversions,
+  -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-assignment-in-if-condition,
+  -bugprone-casting-through-void,
+  -bugprone-macro-parentheses,
+  misc-redundant-expression,
+  misc-unused-using-decls,
+  performance-*,
+  -performance-avoid-endl,
+  readability-duplicate-include,
+  readability-misleading-indentation,
+  readability-redundant-preprocessor,
+
+WarningsAsErrors: ''
+
+HeaderFilterRegex: 'include/numkong/.*'
+
+FormatStyle: file
+
+CheckOptions:
+  - key: bugprone-assert-side-effect.AssertMacros
+    value: 'assert,NK_ASSERT'

package/{simsimd → numkong}/.cmake-format.py

@@ -17,3 +17,21 @@ with section("format"):
     # If a statement is wrapped to more than one line, than dangle the closing
     # parenthesis on its own line.
     dangle_parens = True
+
+    # Allow many positional arguments before forcing vertical layout
+    # (default 6 splits target_compile_definitions onto one-per-line)
+    max_pargs_hwrap = 40
+
+    # Allow more sub-groups before forcing vertical layout
+    max_subgroups_hwrap = 4
+
+    # Allow horizontal wrapping to span more lines (default 2 forces
+    # one-per-line when word-wrapping exceeds 2 lines)
+    max_lines_hwrap = 8
+
+# ----------------------------------
+# Options affecting comment handling.
+# ----------------------------------
+with section("markup"):
+    # Do not reflow comment text
+    enable_markup = False

package/numkong/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,mjs,cjs,ts,mts,json}]
+indent_size = 2

package/numkong/.git-blame-ignore-revs

@@ -0,0 +1,123 @@
+962d36ce18d18cf48e93e7fc7ac2562abecce662
+de1e3df94e275546c8980640002b9016b954b0aa
+bba0df2717b6148d1d3c407269ae4e9b402dd756
+4fd1e56c3f56c1f1a2ff9382e1a2f92e7827b00c
+88be861f5854d3693de2d958b1ac043486eb64c1
+a4022a988287e527757ecc9bc16a4f2e7dc4770e
+750c59f5116a2000507a0cec09db009fd7d31232
+b480b5c3ebddd6de0f8e1c179cdc02f18edbb8ae
+55e6f7a48ce10afe421c7b94fe01062cb6336e90
+d79fe7abe32561cb3447bb3d2e832984b468e355
+37dd664b16a6e1d7d54aea5b78a84ae658517c19
+dd060989521f4cc2b3b7b736f0a413bf24e39dff
+ddac3514c66b7a411cd319e5956c78ad772dba15
+c4d02406513110efd8b199a0b6febff6061ae9c3
+7370fe55bbdfe83b28135182c5b1e110a927a77d
+7ccec27fc044db5f4b41ab3b635e7ae3abf1c6a4
+36cf2bd77ce6621ac1555e84bb31bb39b4c615b7
+ed3973c56ce8f94bb9e400e43d1dda4c4ef83372
+0f964498aa2f2969df3295d368e674167727d561
+6265b0acb90adb2e331b9da16588045e70245c24
+10cfc27088de412cf78609d4950877fc2ad92763
+6410193b420e80115b258f07df0d369c5014dd60
+7b5af935865cf4c56061b531f28004bff5d30f8c
+626177d4fb9deb52535e629f4f80f64ac9d0a00c
+d0589f66f05b082ee55b405b20bf20f648b60a66
+ead0955991ff43116cebefa42440496c684bea60
+9d5146f359b14087f6453c1a74ceb3bb13f5f8c2
+d5df6be574082bc754972c11866be5fbf9698151
+0b86dd4601986555578f017f3ff37ab39bf0193b
+e75b8ffbeab01a3f8c4e2df9edde021217308df7
+821907e0c6f99bc8846869db26faee508fa5155c
+a83f6ee3b7e7ae66f0375090a6b1db4720a9849e
+85c27bd0ba9ee032c899a230d5eae64e8756826b
+5ca93f14ec5fc5b779b0a8785200a8ff325c26ac
+16b93b0720f9ffc00e8e891d60a322a093c3a8b8
+3a7ce06024b28fdd29c4e494bbe0a2b007fea3cc
+10378640dbd0f3063e1f4d3de8c080ce85b17184
+0aa22702d72c925b7c0896ac46eb9c92f1ba9330
+a76aac381808cc22445c471b5ed8580bf0bb555c
+9a1fa9ef7d3a02bc62508a0d7fe5b951ea0d469e
+b38118fa6216dd310214c8ec49eae7de645be3b9
+39ccd0cf42240549145dc0581a0b967cebea2a3f
+43e6294e8e8b12af9dd9f3033c71dbd6c34174aa
+140efb9213beeeade76f06daae52709f87fe70da
+47d0e3748e3aed9b7b59d72e11c975d4768f6b28
+bb1001fcaee1fff0fbf9d7eb63a96253709e05e8
+c8f85f4f40076f3c63341a962942f4eef461b42f
+34039a2fcb31287723eff779bac0ffb228c10ede
+87984bf5d212443eeb0940bd05ef49ae9b512a5e
+e78ca7b57499456f0a6c83e7d4f7d6b64de4f7b3
+489a74a056a758f1475e1ff2ce52ef3ae642d5e3
+378f11c89f23a7fe9a76242d8b834486effb9c4e
+2ea7cb19e7b3e70d4768eca643e75c92ad7c13f4
+acb40dc196328ffe831e4f59f9c1f0b0a247925b
+a918a68a87a3a10f68ba84bf57e780f1910e6564
+fcde24a4cdf8d04319612e2e3ae79fd8d702ec90
+564b778a40bc16ad32850f6e6f8fe4a70785a8b7
+fcf687908a4134e023329271fade845c8a489701
+1c713ed445a51e3c7ceb7457bf1ad9640cdd2933
+fed878a7337438399399bc2ffdf8901144b8051e
+dbed5d244972064cf68a331cd74242f90d50695b
+f29b5ea9127edfb18ec84ccb6143e5e5627d20e7
+34b59661fe7165f3f9551c10789fdda28fd933ef
+c574af91c0f589ea9f2e2b2dee29c5c1335e8547
+4779d0a85a3470881880c386f28186abb2706f3b
+29b87633c57facd4b9f7e0e13ae2313890dd956b
+3ff23a0a604e7b3c9303a6f0ccf0242cea86dc15
+a8400c0ba26fe94bbef82d8eba80351edffa0f34
+a4ad87abde8c0b34ac1ccf302648a91e61518836
+b35f05b3efb913156308e43761c8de511622534a
+ff062f0414889f469391f2b859ffae15e4c0bd41
+4309f546d4695d38b6024e2c79ab445017aacc22
+ffa009e2e073ac10301bedda7de60e3b71260720
+5d75880b19faed89b39bd7c09542ec67fe40c83f
+b988721ed3c8f3112dcd5009ea1d5332fcaaf69e
+13b4d9930345e72dad26f60b8c341aacc578b2b7
+9ed34d74fd8124e788509c552527ae3ce9aaa937
+c839a6096378f68e7d075626cdcde2c53203bb41
+9707a5f16c087ef7794ac048af05bc697a866b4a
+8051bfd337ecec6e9c5e2ff6f47c241e8625877d
+e3dc82a401553698c3647c3f19cbd86d5dcf81c6
+514ac91895b597206480d4a0b5dd34c43b30ac00
+43844491f9ef897e37c48246ce9542fe9ffbbfc7
+801910b77e77070f283faf0eb10dde482c0e8a50
+10f593e2dd47faf7e2e9d06a9c638a18a481ef2c
+b6024d83996923ee4f0a3467539148691e8d3875
+6ba298c7a7f9093ce8d099c18731f4b2abd63d7c
+e6c0a8aa9cbdc466969b0a85e4dabe29eba59727
+39e5bbc88e3d28d9ba82ebdb106b7ad03d86689e
+8d7c5fa745383153859de008b9ec28dad8fa350d
+6b86a390f18ebc048323f78bbbf08df6e1f5576d
+178dffd5d119f881dcf649fd84fdba678ab4e4c6
+29c190984e0e99cec25736c68b06f0f3b74d2558
+185e43613f6a3d46aaa55680d2572db8ffa67278
+67050ed740d6af9d64dd2a43915f60d2eb63c28b
+202a63fd4aac97504a3cc4ffb6baa2559da44c25
+86784018da0209029fa7c8860459716524845dac
+7f64075a0213832132893dcc5a5190a42458e132
+b808cd041d6a15a7cd661094780b0056eb180c54
+a73f2a98fbeb6c65678a97afeb9129473cb07cfd
+0089ac8e9dbe1fa602a9ebd539c521b5e2210f5a
+e6a43fb8f209d702536abfa2376c4e6127e3018f
+c21e0bb3730156259a498b7aeee2ceacc24998a1
+87ed8cb448d17dcb24857243d24afbdf88fd181b
+a6d1ed7a19a8f416b83dd8b441d5391dba017c08
+6a71d532989449c94e233360f001c400fb0f5784
+b824f5913be3738b525558de669987b971ad71a3
+08aa80fe60071268fed0083bffaf38ad9617b406
+dcdb3289b8170cc4f855194fb9e3d75987e9154f
+17e97d9b2d28eb607ee9a1cdf32baf15bf16d5ec
+617c99f3d9dbc98f46417bb6e25d5802dbf52222
+342c7459dd64ccfe3eed53315d3f8675c7669f90
+1f02420dfd6e5073b3b2199d1ff4f9a9953bb7ef
+51fb41d0fb61ab22099a1db4ed0fc90046af687c
+74cedfd1e8f18bac291a4463f7b3d6ceb60542b0
+3e03f400aa4b6b725b8ca4110d2f4d327eaeda90
+1361f04f2371c9b9ca70fcc476cbfe7e5a291be3
+42845bdd0a616843c2f4cc478917c5b5a242293f
+e405dd3f8f23a774ef6f21f1be043c010f0edd4a
+8322ba6d5e471eaebc551fa28564edc3f314be19
+4c6c9b3ca554e741c61b93ff75f66e222cac9d0a
+ff20886eaf7e338e3e79c0af4aa5f56f9c4bde5e
+53627463d6283b8d0fc0f90ac7bab97e7ae8d3fa

package/numkong/.mailmap

@@ -0,0 +1,15 @@
+# Primary maintainer
+Ash Vardanian <1983160+ashvardanian@users.noreply.github.com> Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>
+
+# Contributors with multiple emails
+Alexey Milovidov <18581488+alexey-milovidov@users.noreply.github.com> Alexey Milovidov <milovidov@clickhouse.com>
+Robert Schulze <100446237+rschu1ze@users.noreply.github.com> Robert Schulze <robert@clickhouse.com>
+Michael Grinshpon <8979562+mgrinshpon@users.noreply.github.com> Michael Grinshpon <mgrinshpon@gmail.com>
+Michael Grinshpon <8979562+mgrinshpon@users.noreply.github.com> Michael Grinshpon <michael@visionbyscope.com>
+Laurens Priem <81471280+laurenspriem@users.noreply.github.com> Laurens Priem <laurens@ente.io>
+Laurens Priem <81471280+laurenspriem@users.noreply.github.com> Laurens Priem <l+github@lrns.me>
+Vsevolod Oparin <462138+vsevolod-oparin@users.noreply.github.com> Vsevolod Oparin <oparin.vsevolod@gmail.com>
+Alexander Kjäll <647710+alexanderkjall@users.noreply.github.com> Alexander Kjäll <alexander.kjall@gmail.com>
+Pedro Gabriel Planel <pplanel@users.noreply.github.com> Pedro Gabriel <pedro.planel@2gofintech.com.br>
+Raufs Dunamalijevs <30183178+rienath@users.noreply.github.com> Raufs Dunamalijevs <raufs.dunamalijevs@clickhouse.com>
+Eren K. <90657474+real-eren@users.noreply.github.com> real-eren <erenalpkahriman@gmail.com>

package/numkong/.spi.yml

@@ -0,0 +1,11 @@
+# Swift Package Index build configuration — must live at the repo root.
+# Controls which platforms appear on the package page at swiftpackageindex.com.
+version: 1
+builder:
+  configs:
+    - platform: macos-xcodebuild
+    - platform: macos-xcodebuild-arm
+    - platform: ios
+    - platform: tvos
+    - platform: watchos
+    - platform: linux

package/numkong/.swift-format

@@ -0,0 +1,14 @@
+{
+    "version": 1,
+    "indentation": {
+        "spaces": 4
+    },
+    "tabWidth": 4,
+    "maximumBlankLines": 1,
+    "respectsExistingLineBreaks": true,
+    "lineBreakBeforeControlFlowKeywords": false,
+    "lineBreakBeforeEachArgument": false,
+    "lineBreakBeforeEachGenericRequirement": false,
+    "indentConditionalCompilationBlocks": false,
+    "lineLength": 120
+}

package/numkong/CITATION.cff

@@ -0,0 +1,81 @@
+cff-version: 1.2.0
+title: "NumKong: 2000 Mixed Precision Kernels For All"
+message: "If you use this software, please cite it as below."
+type: software
+license: Apache-2.0
+version: 7.5.0
+repository-code: https://github.com/ashvardanian/NumKong
+url: https://ashvardanian.com/posts/numkong/
+abstract: >-
+  Portable mixed-precision math, linear-algebra, & retrieval library
+  with 2'000+ SIMD kernels for x86, Arm, RISC-V, LoongArch, Power, & WebAssembly,
+  leveraging rare algebraic transforms with both 1D & 2D registers like AMX & SME,
+  covering 15+ numeric types from 4-bit integers & 6-bit floats to 128-bit complex numbers,
+  validated against 118-bit extended-precision baselines
+  with saturation, casting, & rounding edge-case coverage,
+  in a 5-100x smaller binary than other BLAS-like alternatives,
+  co-designed with Tensor abstractions in C++, Python, Rust, JavaScript, GoLang, & Swift.
+
+authors:
+  - family-names: Vardanian
+    given-names: Ash
+    alias: ashvardanian
+    orcid: https://orcid.org/0000-0002-4882-1815
+
+references:
+  - type: article
+    title: "SciPy Distances up to 200x Faster with AVX-512 & SVE"
+    url: https://ashvardanian.com/posts/simsimd-faster-scipy/
+    date-published: 2023-10-07
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "GCC Compiler vs Human - 119x Faster Assembly"
+    url: https://ashvardanian.com/posts/gcc-12-vs-avx512fp16/
+    date-published: 2023-10-23
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "Accelerating JavaScript Arrays by 10x for Vector Search"
+    url: https://ashvardanian.com/posts/javascript-ai-vector-search/
+    date-published: 2023-10-21
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "Python, C, Assembly - 2'500x Faster Cosine Similarity"
+    url: https://ashvardanian.com/posts/python-c-assembly-comparison/
+    date-published: 2023-10-30
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "NumPy vs BLAS: Losing 90% of Throughput"
+    url: https://ashvardanian.com/posts/numpy-vs-blas-costs/
+    date-published: 2024-03-12
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "5x Faster Set Intersections: SVE2, AVX-512, & NEON"
+    url: https://ashvardanian.com/posts/simd-set-intersections-sve2-avx512/
+    date-published: 2024-09-16
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "Understanding SIMD: Infinite Complexity of Trivial Problems"
+    url: https://ashvardanian.com/posts/understanding-simd-complexity/
+    date-published: 2024-11-25
+    authors:
+      - family-names: Vardanian
+        given-names: Ash
+  - type: article
+    title: "Hiding x86 Port Latency for 330 GB/s/core Reductions"
+    url: https://ashvardanian.com/posts/cpu-ports/
+    date-published: 2025-01-19
+    authors:
+      - family-names: Vardanian
+        given-names: Ash