usearch 2.8.7 → 2.8.9

package/javascript/README.md

@@ -1,15 +1,16 @@
 # USearch for JavaScript
 
+USearch is a high-performance library for building and querying vector search indexes, optimized for Node.js and WASM environments.
+
 ## Installation
 
-USearch is available both for Node.js backend runtime and WASM frontend runtime.
-For the first option, use the conventional `npm install`:
+For Node.js environments, install USearch using `npm`:
 
 ```sh
 npm install usearch
 ```
 
-For latter:
+For front-end applications using WASM, use the Wasmer package manager:
 
 ```sh
 wasmer install unum/usearch
@@ -17,20 +18,71 @@ wasmer install unum/usearch
 
 ## Quickstart
 
+Create an index, add vectors, and perform searches with ease:
+
 ```js
-var index = new usearch.Index({ metric: 'cos', connectivity: 16n, dimensions: 3n })
-index.add(42n, new Float32Array([0.2, 0.6, 0.4]))
-var results = index.search(new Float32Array([0.2, 0.6, 0.4]), 10n)
+const usearch = require('usearch');
+const index = new usearch.Index({ metric: 'cos', connectivity: 16, dimensions: 3 });
+index.add(42n, new Float32Array([0.2, 0.6, 0.4]));
+const results = index.search(new Float32Array([0.2, 0.6, 0.4]), 10);
+
+assert(index.size() === 1);
+assert.deepEqual(results.keys, new BigUint64Array([42n]));
+assert.deepEqual(results.distances, new Float32Array([0]));
 
-assert.equal(index.size(), 1n)
-assert.deepEqual(results.keys, new BigUint64Array([42n]))
-assert.deepEqual(results.distances, new Float32Array([0]))
+index.remove(42n);
 ```
 
 ## Serialization
 
+Persist and restore your index with serialization methods:
+
+```js
+index.save('index.usearch'); // Save the index to a file
+index.load('index.usearch'); // Load the index from a file
+index.view('index.usearch'); // View the index from a file without loading into memory
+```
+
+## Advanced Index Configuration
+
+Customize your index with additional configuration options:
+
+```js
+const index = new usearch.Index({
+  dimensions: 128,
+  metric: 'ip',
+  quantization: 'f32',
+  connectivity: 10,
+  expansion_add: 5,
+  expansion_search: 3,
+  multi: true
+});
+```
+
+## Batch Operations
+
+Process multiple vectors at once for efficiency.
+For performance reasons we prefer a flattened `TypedArray` over an Array of Arrays:
+
+```js
+const keys = new BigUint64Array([15n, 16n]);
+const vectors = new Float32Array([10, 20, 10, 25]);
+index.add(keys, vectors);
+```
+
+Retrieve batch search results:
+
+```js
+const batchResults = index.search(vectors, 2);
+const firstMatch = batchResults.get(0);
+```
+
+## Index Introspection
+
+Inspect and interact with the index:
+
 ```js
-index.save('index.usearch')
-index.load('index.usearch')
-index.view('index.usearch')
+const dimensions = index.dimensions(); // Get the number of dimensions
+const containsKey = index.contains(42n); // Check if a key is in the index
+const count = index.count(42n); // Get the count of vectors for a key
 ```

package/javascript/lib.cpp

@@ -181,7 +181,7 @@ Napi::Value CompiledIndex::Search(Napi::CallbackInfo const& ctx) {
     std::size_t tasks = queries.ElementLength() / native_->dimensions();
     std::size_t wanted = napi_argument_to_size(ctx[1]);
 
-    auto run_parallel = [&](auto vectors) {
+    auto run_parallel = [&](auto vectors) -> Napi::Value {
         Napi::Array result_js = Napi::Array::New(env, 3);
         Napi::BigUint64Array matches_js = Napi::BigUint64Array::New(env, tasks * wanted);
         Napi::Float32Array distances_js = Napi::Float32Array::New(env, tasks * wanted);
@@ -192,21 +192,29 @@ Napi::Value CompiledIndex::Search(Napi::CallbackInfo const& ctx) {
         auto counts_data = counts_js.Data();
 
         try {
+            bool failed = false;
             executor_stl_t executor;
             executor.fixed(tasks, [&](std::size_t /*thread_idx*/, std::size_t task_idx) {
                 auto result = native_->search(vectors + task_idx * native_->dimensions(), wanted);
                 if (!result) {
-                    // Handle the error appropriately
-                    // For example, log the error or set some flag in the result_js object
+                    failed = true;
+                    Napi::TypeError::New(env, result.error.release()).ThrowAsJavaScriptException();
                 } else {
                     counts_data[task_idx] = result.dump_to(matches_data + task_idx * native_->dimensions(),
                                                            distances_data + task_idx * native_->dimensions());
                 }
             });
+
+            if (failed)
+                return env.Null();
+
         } catch (std::bad_alloc const&) {
             Napi::TypeError::New(env, "Out of memory").ThrowAsJavaScriptException();
+            return env.Null();
+
         } catch (...) {
             Napi::TypeError::New(env, "Search failed").ThrowAsJavaScriptException();
+            return env.Null();
         }
 
         result_js.Set(0u, matches_js);

package/javascript/usearch.js

@@ -247,10 +247,12 @@ class Index {
         // Call the compiled method and create Matches or BatchMatches object with the result
         const result = this._compiledIndex.search(normalizedVectors, k);
         const countInQueries = normalizedVectors.length / Number(this._compiledIndex.dimensions());
+        const batchMatches = new BatchMatches(result[0], result[1], result[2], k);
+
         if (countInQueries === 1) {
-            return new Matches(result[0], result[1]);
+            return batchMatches.get(0);
         } else {
-            return new BatchMatches(result[0], result[1], result[2], k);
+            return batchMatches;
         }
     }
 

package/javascript/usearch.test.js

@@ -36,6 +36,21 @@ test('Batch operations', () => {
     assert.deepEqual(results.distances, new Float32Array([45, 130]), 'distances should be 45 and 130');
 });
 
+test("Expected results", () => {
+    var index = new usearch.Index({
+        metric: "cos",
+        connectivity: 16,
+        dimensions: 3,
+    });
+    index.add(42n, new Float32Array([0.2, 0.6, 0.4]));
+    var results = index.search(new Float32Array([0.2, 0.6, 0.4]), 10);
+
+    assert.equal(index.size(), 1);
+    assert.deepEqual(results.keys, new BigUint64Array([42n]));
+    assert.deepEqual(results.distances, new Float32Array([0]));
+});
+
+
 
 test('Operations with invalid values', () => {
     const indexBatch = new usearch.Index(2, 'l2sq');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.8.7",
+    "version": "2.8.9",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",
@@ -24,7 +24,6 @@
         "node-addon-api": "^3.0.0"
     },
     "scripts": {
-        "preinstall": "git submodule update --init --recursive",
         "test": "node --test ./javascript/usearch.test.js",
         "install": "node-gyp rebuild"
     },

package/setup.py

@@ -5,19 +5,49 @@ from setuptools import setup
 
 from pybind11.setup_helpers import Pybind11Extension
 
-
 compile_args = []
 link_args = []
 macros_args = []
 
-def is_gcc():
+
+def get_bool_env(name: str, preference: bool) -> bool:
+    return os.environ.get(name, "1" if preference else "0") == "1"
+
+
+def get_bool_env_w_name(name: str, preference: bool) -> bool:
+    return name, get_bool_env(name, preference)
+
+
+def get_is_gcc():
     try:
-        compiler_version = subprocess.check_output(["c++", "--version"], universal_newlines=True)
+        compiler_version = subprocess.check_output(
+            ["c++", "--version"], universal_newlines=True
+        )
         return "gcc" in compiler_version.lower()
     except Exception:
         return False
 
-if sys.platform == "linux":
+
+# Check the environment variables
+is_linux: bool = sys.platform == "linux"
+is_macos: bool = sys.platform == "darwin"
+is_windows: bool = sys.platform == "win32"
+
+prefer_simsimd: bool = is_linux or is_macos
+prefer_fp16lib: bool = True
+prefer_openmp: bool = is_linux and get_is_gcc()
+
+use_simsimd: bool = get_bool_env("USEARCH_USE_SIMSIMD", prefer_simsimd)
+use_fp16lib: bool = get_bool_env("USEARCH_USE_FP16LIB", prefer_fp16lib)
+use_openmp: bool = get_bool_env("USEARCH_USE_OPENMP", prefer_openmp)
+
+
+# Common arguments for all platforms
+macros_args.append(("USEARCH_USE_OPENMP", "1" if use_openmp else "0"))
+macros_args.append(("USEARCH_USE_SIMSIMD", "1" if use_simsimd else "0"))
+macros_args.append(("USEARCH_USE_FP16LIB", "1" if use_fp16lib else "0"))
+
+if is_linux:
     compile_args.append("-std=c++17")
     compile_args.append("-O3")  # Maximize performance
     compile_args.append("-ffast-math")  # Maximize floating-point performance
@@ -27,17 +57,21 @@ if sys.platform == "linux":
     # Simplify debugging, but the normal `-g` may make builds much longer!
     compile_args.append("-g1")
 
-    macros_args.append(("USEARCH_USE_NATIVE_F16", "0"))
-    macros_args.append(("USEARCH_USE_SIMSIMD", "1"))
-
-    if is_gcc():
-        macros_args.append(("USEARCH_USE_OPENMP", "1"))
+    if use_openmp:
         compile_args.append("-fopenmp")
         link_args.append("-lgomp")
-    else:
-        macros_args.append(("USEARCH_USE_OPENMP", "0"))
 
-if sys.platform == "darwin":
+    if use_simsimd:
+        macros_args.extend(
+            [
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX512", True),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_SVE", True),
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX2", True),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_NEON", True),
+            ]
+        )
+
+if is_macos:
     # MacOS 10.15 or higher is needed for `aligned_alloc` support.
     # https://github.com/unum-cloud/usearch/actions/runs/4975434891/jobs/8902603392
     compile_args.append("-mmacosx-version-min=10.15")
@@ -61,12 +95,34 @@ if sys.platform == "darwin":
     #     link_args.append("-lomp")
     #     macros_args.append(("USEARCH_USE_OPENMP", "1"))
 
-if sys.platform == "win32":
+    if use_simsimd:
+        macros_args.extend(
+            [
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX512", False),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_SVE", False),
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX2", True),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_NEON", True),
+            ]
+        )
+
+if is_windows:
     compile_args.append("/std:c++17")
     compile_args.append("/O2")
     compile_args.append("/fp:fast")  # Enable fast math for MSVC
     compile_args.append("/W1")  # Reduce warnings verbosity
 
+    # We don't actually want to use any SimSIMD stuff,
+    # as GCC attributes aren't compatible with MSVC
+    if use_simsimd:
+        macros_args.extend(
+            [
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX512", False),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_SVE", False),
+                get_bool_env_w_name("SIMSIMD_TARGET_X86_AVX2", False),
+                get_bool_env_w_name("SIMSIMD_TARGET_ARM_NEON", False),
+            ]
+        )
+
 ext_modules = [
     Pybind11Extension(
         "usearch.compiled",
@@ -80,11 +136,16 @@ ext_modules = [
 __version__ = open("VERSION", "r").read().strip()
 __lib_name__ = "usearch"
 
-
 this_directory = os.path.abspath(os.path.dirname(__file__))
 with open(os.path.join(this_directory, "README.md")) as f:
     long_description = f.read()
 
+# Depending on the macros, adjust the include directories
+include_dirs = ["include"]
+if use_simsimd:
+    include_dirs.append("simsimd/include")
+if use_fp16lib:
+    include_dirs.append("fp16/include")
 
 setup(
     name=__lib_name__,
@@ -118,7 +179,7 @@ setup(
         "Topic :: Database :: Database Engines/Servers",
         "Topic :: Scientific/Engineering :: Artificial Intelligence",
     ],
-    include_dirs=["include", "fp16/include", "simsimd/include"],
+    include_dirs=include_dirs,
     ext_modules=ext_modules,
     install_requires=[
         "numpy",

package/simsimd/README.md

@@ -30,24 +30,23 @@ SimSIMD leverages SIMD intrinsics, capabilities that only select compilers effec
 
 Given 1000 embeddings from OpenAI Ada API with 1536 dimensions, running on the Apple M2 Pro Arm CPU with NEON support, here's how SimSIMD performs against conventional methods:
 
-| Conventional                           | SimSIMD           | `f32` improvement | `f16` improvement | `i8` improvement |
-| :------------------------------------- | :---------------- | ----------------: | ----------------: | ---------------: |
-| `numpy.inner`                          | `inner`           |           __2 x__ |           __9 x__ |         __18 x__ |
-| `scipy.spatial.distance.cosine`        | `cosine`          |          __32 x__ |          __79 x__ |        __133 x__ |
-| `scipy.spatial.distance.sqeuclidean`   | `sqeuclidean`     |           __5 x__ |          __26 x__ |         __17 x__ |
-| `scipy.spatial.distance.jensenshannon` | `jensenshannon`   |          __31 x__ |          __53 x__ |                  |
-| `scipy.special.kl_div`                 | `kullbackleibler` |          __21 x__ |          __18 x__ |                  |
+| Kind           | `f32` improvement | `f16` improvement | `i8` improvement | Conventional method                    | SimSIMD         |
+| :------------- | ----------------: | ----------------: | ---------------: | :------------------------------------- | :-------------- |
+| Cosine         |          __32 x__ |          __79 x__ |        __133 x__ | `scipy.spatial.distance.cosine`        | `cosine`        |
+| Euclidean ²    |           __5 x__ |          __26 x__ |         __17 x__ | `scipy.spatial.distance.sqeuclidean`   | `sqeuclidean`   |
+| Inner Product  |           __2 x__ |           __9 x__ |         __18 x__ | `numpy.inner`                          | `inner`         |
+| Jensen Shannon |          __31 x__ |          __53 x__ |                  | `scipy.spatial.distance.jensenshannon` | `jensenshannon` |
 
 ### Intel Sapphire Rapids
 
 On the Intel Sapphire Rapids platform, SimSIMD was benchmarked against auto-vectorized code using GCC 12. GCC handles single-precision `float`, but might not be the best choice for `int8` and `_Float16` arrays, which has been part of the C language since 2011.
 
-|                 | GCC 12 `f32` | GCC 12 `f16` | SimSIMD `f16` | `f16` improvement |
-| :-------------- | -----------: | -----------: | ------------: | ----------------: |
-| `cosine`        |     3.28 M/s | _336.29 k/s_ |    _6.88 M/s_ |          __20 x__ |
-| `sqeuclidean`   |     4.62 M/s | _147.25 k/s_ |    _5.32 M/s_ |          __36 x__ |
-| `inner`         |     3.81 M/s | _192.02 k/s_ |    _5.99 M/s_ |          __31 x__ |
-| `jensenshannon` |     1.18 M/s |  _18.13 k/s_ |    _2.14 M/s_ |         __118 x__ |
+| Kind           | GCC 12 `f32` | GCC 12 `f16` | SimSIMD `f16` | `f16` improvement |
+| :------------- | -----------: | -----------: | ------------: | ----------------: |
+| Cosine         |     3.28 M/s | _336.29 k/s_ |    _6.88 M/s_ |          __20 x__ |
+| Euclidean ²    |     4.62 M/s | _147.25 k/s_ |    _5.32 M/s_ |          __36 x__ |
+| Inner Product  |     3.81 M/s | _192.02 k/s_ |    _5.99 M/s_ |          __31 x__ |
+| Jensen Shannon |     1.18 M/s |  _18.13 k/s_ |    _2.14 M/s_ |         __118 x__ |
 
 __Technical Insights__:
 
@@ -173,6 +172,8 @@ Stay updated with the latest advancements by always using the most recent compil
 
 Should you wish to integrate SimSIMD within USearch, simply compile USearch with the flag `USEARCH_USE_SIMSIMD=1`. Notably, this is the default setting on the majority of platforms.
 
+## Benchmarking and Contributing
+
 __To rerun experiments__ utilize the following command:
 
 ```sh

package/simsimd/include/simsimd/probability.h

@@ -425,8 +425,8 @@ simsimd_avx512_f32_js_cycle:
     __mmask16 nonzero_mask_b = _mm512_cmp_ps_mask(b_vec, epsilon_vec, _CMP_GE_OQ);
     __mmask16 nonzero_mask = nonzero_mask_a & nonzero_mask_b;
     __m512 m_recip_approx = _mm512_rcp14_ps(m_vec);
-    __m512 ratio_a_vec = _mm512_div_ps(a_vec, m_vec);
-    __m512 ratio_b_vec = _mm512_div_ps(b_vec, m_vec);
+    __m512 ratio_a_vec = _mm512_mul_ps(a_vec, m_recip_approx);
+    __m512 ratio_b_vec = _mm512_mul_ps(b_vec, m_recip_approx);
     __m512 log_ratio_a_vec = simsimd_avx512_f32_log2(ratio_a_vec);
     __m512 log_ratio_b_vec = simsimd_avx512_f32_log2(ratio_b_vec);
     sum_a_vec = _mm512_maskz_fmadd_ps(nonzero_mask, a_vec, log_ratio_a_vec, sum_a_vec);

package/simsimd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simsimd",
-  "version": "3.5.3",
+  "version": "3.5.4",
   "description": "Vector Similarity Functions 3x-200x Faster than SciPy and NumPy",
   "author": "Ash Vardanian",
   "license": "Apache 2.0",

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.8.7"
+version="2.8.9"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"

package/. npmignore

@@ -1,14 +0,0 @@
-node_modules/
-.vscode/
-build/
-csharp/
-golang/
-java/
-objc/
-rust/
-swift/
-wolfram/
-python/
-docs/
-wasm/
-Package.swift

package/.gitignore

@@ -1,95 +0,0 @@
-# Ignore all files without an extension
-*
-!/**/
-!*.*
-
-# Temporary files
-.DS_Store
-*.fbin
-*.ibin
-datasets
-bin
-*.usearch
-.cache
-
-# C++ builds
-build
-build_release
-build_debug
-build_artifacts
-_deps
-CMakeCache.txt
-CMakeFiles
-cmake_install.cmake
-
-# Profiling with GProf and `perf` on Linux
-gmon.out
-perf.data
-
-# Python wrappers
-__pycache__
-*.egg-info
-dist/
-wheelhouse/
-
-# Python Environments
-venv/
-
-# JS wrappers
-package-lock.json
-node_modules/
-
-# Rust builds
-Cargo.lock
-target/
-
-# Java bindings
-.gradle
-*.class
-
-# ObjC and Swift
-.build
-.swiftpm
-
-# C# builds
-csharp/**/[Bb]in/
-csharp/**/[Oo]bj/
-csharp/lib
-csharp/packages
-
-# Prerequisites
-*.d
-
-# Compiled Object files
-*.slo
-*.lo
-*.o
-*.obj
-
-# Precompiled Headers
-*.gch
-*.pch
-
-# Compiled Dynamic libraries
-*.so
-*.dylib
-*.dll
-
-# Fortran module files
-*.mod
-*.smod
-
-# Allow golang go.mod
-!go.mod
-
-# Compiled Static libraries
-*.lai
-*.la
-*.a
-*.lib
-
-# Executables
-*.exe
-*.out
-*.app
-