usearch 2.11.1 → 2.13.1

package/simsimd/CONTRIBUTING.md

@@ -5,13 +5,34 @@
 To rerun experiments utilize the following command:
 
 ```sh
-sudo apt install libopenblas-dev # BLAS installation is optional
-cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_BENCHMARKS=1 -DSIMSIMD_BUILD_TESTS=1 -B ./build_release
+sudo apt install libopenblas-dev # BLAS installation is optional, but recommended for benchmarks
+cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_TESTS=1 -DSIMSIMD_BUILD_BENCHMARKS=1 -DSIMSIMD_BUILD_BENCHMARKS_WITH_CBLAS=1 -B build_release
 cmake --build build_release --config Release
 build_release/simsimd_bench
 build_release/simsimd_bench --benchmark_filter=js
 build_release/simsimd_test_run_time
-build_release/simsimd_test_compile_time
+build_release/simsimd_test_compile_time # no need to run this one, it's just a compile-time test
+```
+
+To utilize newest instructions, use GCC 12 or newer, or Clang 16 or newer.
+To install them on Ubuntu 22.04, use:
+
+```sh
+sudo apt install gcc-12 g++-12
+sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100
+sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100
+```
+
+On MacOS it's recommended to use Homebrew and install Clang, as opposed to "Apple Clang".
+Replacing the default compiler is not recommended, as it may break the system, but you can pass it as an environment variable:
+
+```sh
+brew install llvm
+cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_TESTS=1 \
+    -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
+    -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
+    -B build_release
+cmake --build build_release --config Release
 ```
 
 ## Python
@@ -31,11 +52,31 @@ The `-Wd` will silence overflows and runtime warnings.
 Benchmarking:
 
 ```sh
-pip install numpy scipy scikit-learn    # for comparison baselines
-python python/bench.py                  # to run default benchmarks
-python python/bench.py --n 1000 --ndim 1000000 # batch size and dimensions
+pip install numpy scipy scikit-learn        # for comparison baselines
+python python/bench.py                      # to run default benchmarks
+python python/bench.py --n 1000 --ndim 1536 # batch size and dimensions
 ```
 
+You can also benchmark against other libraries:
+
+```sh
+$ python python/bench.py --help
+> usage: bench.py [-h] [--n N] [--ndim NDIM] [--scipy] [--scikit] [--torch] [--tf] [--jax]
+> 
+> Benchmark SimSIMD vs. other libraries
+> 
+> options:
+>   -h, --help   show this help message and exit
+>   --n N        Number of vectors (default: 1000)
+>   --ndim NDIM  Number of dimensions (default: 1536)
+>   --scipy      Profile SciPy
+>   --scikit     Profile scikit-learn
+>   --torch      Profile PyTorch
+>   --tf         Profile TensorFlow
+>   --jax        Profile JAX
+```
+
+
 Before merging your changes you may want to test your changes against the entire matrix of Python versions USearch supports.
 For that you need the `cibuildwheel`, which is tricky to use on MacOS and Windows, as it would target just the local environment.
 Still, if you have Docker running on any desktop OS, you can use it to build and test the Python bindings for all Python versions for Linux:
@@ -52,7 +93,7 @@ cibuildwheel --platform macos                   # works only on MacOS
 cibuildwheel --platform windows                 # works only on Windows
 ```
 
-You may need root previligies for multi-architecture builds:
+You may need root privileges for multi-architecture builds:
 
 ```sh
 sudo $(which cibuildwheel) --platform linux
@@ -70,7 +111,7 @@ python -m cibuildwheel --platform windows
 cargo test -p simsimd
 cargo test -p simsimd -- --nocapture # To see the output
 cargo bench
-open ./target/criterion/report/index.html
+open target/criterion/report/index.html
 ```
 
 ## JavaScript

package/simsimd/Cargo.lock

@@ -496,7 +496,7 @@ dependencies = [
 
 [[package]]
 name = "simsimd"
-version = "4.2.1"
+version = "5.0.0"
 dependencies = [
  "cc",
  "criterion",

package/simsimd/Cargo.toml

@@ -1,13 +1,10 @@
 [package]
 name = "simsimd"
 description = "Fastest SIMD-Accelerated Vector Similarity Functions for x86 and Arm"
-version = "4.2.2"
+version = "5.0.0"
 edition = "2021"
 license = "Apache-2.0"
-authors = [
-  "Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>",
-  "Pedro Planel <pplanel@gmail.com>",
-]
+authors = ["Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 repository = "https://github.com/ashvardanian/SimSIMD"
 documentation = "https://docs.rs/simsimd"
 homepage = "https://ashvardanian.com/posts/simsimd-faster-scipy"
@@ -19,6 +16,8 @@ categories = [
   "wasm",
   "external-ffi-bindings",
 ]
+include = ["/rust/**", "/c/**", "/include/**", "/build.rs"]
+
 
 [lib]
 name = "simsimd"
@@ -38,6 +37,12 @@ name = "sqeuclidean"
 harness = false
 path = "rust/benches/sqeuclidean.rs"
 
+[profile.bench]
+opt-level = 3     # Corresponds to -O3
+lto = true        # Enables Link Time Optimization for further optimizations
+codegen-units = 1 # May increase compilation time but optimizes further
+rpath = false     # On some systems, setting this to false can help with optimizations
+
 [dev-dependencies]
 criterion = { version = "0.5.1" }
 rand = { version = "0.8.5" }

package/simsimd/Package.swift

@@ -0,0 +1,16 @@
+// swift-tools-version:5.0
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "SimSIMD",
+    products: [
+        .library(name: "SimSIMD", targets: ["SimSIMD"]),
+    ],
+    targets: [
+        .testTarget(name: "SimSIMDTests", dependencies: ["SimSIMD"], path: "swift/tests"),
+        .target(name: "SimSIMD", dependencies: ["CSimSIMD"], path: "swift/source"),
+        .systemLibrary(name: "CSimSIMD", path: "include")
+    ]
+)

package/simsimd/README.md

@@ -1,12 +1,14 @@
 # SimSIMD 📏
 
-_Computing dot-products, similarity measures, and distances between low- and high-dimensional vectors is ubiquitous in Machine Learning, Scientific Computing, Geo-Spatial Analysis, and Information Retrieval.
+![SimSIMD banner](https://github.com/ashvardanian/ashvardanian/blob/master/repositories/SimSIMD.png?raw=true)
+
+Computing dot-products, similarity measures, and distances between low- and high-dimensional vectors is ubiquitous in Machine Learning, Scientific Computing, Geo-Spatial Analysis, and Information Retrieval.
 These algorithms generally have linear complexity in time, constant complexity in space, and are data-parallel.
 In other words, it is easily parallelizable and vectorizable and often available in packages like BLAS and LAPACK, as well as higher-level `numpy` and `scipy` Python libraries.
 Ironically, even with decades of evolution in compilers and numerical computing, [most libraries can be 3-200x slower than hardware potential][benchmarks] even on the most popular hardware, like 64-bit x86 and Arm CPUs.
 SimSIMD attempts to fill that gap.
 1️⃣ SimSIMD functions are practically as fast as `memcpy`.
-2️⃣ SimSIMD [compiles to more platforms than NumPy (105 vs 35)][compatibility] and has more backends than most BLAS implementations._
+2️⃣ SimSIMD [compiles to more platforms than NumPy (105 vs 35)][compatibility] and has more backends than most BLAS implementations.
 
 [benchmarks]: https://ashvardanian.com/posts/simsimd-faster-scipy
 [compatibility]: https://pypi.org/project/simsimd/#files
@@ -64,8 +66,8 @@ Moreover, SimSIMD...
 
 Due to the high-level of fragmentation of SIMD support in different x86 CPUs, SimSIMD uses the names of select Intel CPU generations for its backends.
 They, however, also work on AMD CPUs.
-Inel Haswell is compatible with AMD Zen 1/2/3, while AMD Genoa Zen 4 covers AVX-512 instructions added to Intel Skylake and Ice Lake.
-You can learn more about the technical implementation details in the following blogposts:
+Intel Haswell is compatible with AMD Zen 1/2/3, while AMD Genoa Zen 4 covers AVX-512 instructions added to Intel Skylake and Ice Lake.
+You can learn more about the technical implementation details in the following blog-posts:
 
 - [Uses Horner's method for polynomial approximations, beating GCC 12 by 119x](https://ashvardanian.com/posts/gcc-12-vs-avx512fp16/).
 - [Uses Arm SVE and x86 AVX-512's masked loads to eliminate tail `for`-loops](https://ashvardanian.com/posts/simsimd-faster-scipy/#tails-of-the-past-the-significance-of-masked-loads).
@@ -377,18 +379,49 @@ fn main() {
 }
 ```
 
+### Half-Precision Brain-Float Numbers
+
+The "brain-float-16" is a popular machine learning format.
+It's broadly supported in hardware and is very machine-friendly, but software support is still lagging behind. 
+[Unlike NumPy](https://github.com/numpy/numpy/issues/19808), you can already use `bf16` datatype in SimSIMD.
+Luckily, to downcast `f32` to `bf16` you only have to drop the last 16 bits:
+
+```py
+import numpy as np
+import simsimd as simd
+
+a = np.random.randn(ndim).astype(np.float32)
+b = np.random.randn(ndim).astype(np.float32)
+
+# NumPy doesn't natively support brain-float, so we need a trick!
+# Luckily, it's very easy to reduce the representation accuracy
+# by simply masking the low 16-bits of our 32-bit single-precision
+# numbers. We can also add `0x8000` to round the numbers.
+a_f32rounded = ((a.view(np.uint32) + 0x8000) & 0xFFFF0000).view(np.float32)
+b_f32rounded = ((b.view(np.uint32) + 0x8000) & 0xFFFF0000).view(np.float32)
+
+# To represent them as brain-floats, we need to drop the second half
+a_bf16 = np.right_shift(a_f32rounded.view(np.uint32), 16).astype(np.uint16)
+b_bf16 = np.right_shift(b_f32rounded.view(np.uint32), 16).astype(np.uint16)
+
+# Now we can compare the results
+expected = np.inner(a_f32rounded, b_f32rounded)
+result = simd.inner(a_bf16, b_bf16, "bf16")
+```
+
 ### Dynamic Dispatch
 
 SimSIMD provides a dynamic dispatch mechanism to select the most advanced micro-kernel for the current CPU.
 You can query supported backends and use the `SimSIMD::capabilities` function to select the best one.
 
 ```rust
-println!("uses neon: {}", capabilties::uses_neon());
-println!("uses sve: {}", capabilties::uses_sve());
-println!("uses haswell: {}", capabilties::uses_haswell());
-println!("uses skylake: {}", capabilties::uses_skylake());
-println!("uses ice: {}", capabilties::uses_ice());
-println!("uses sapphire: {}", capabilties::uses_sapphire());
+println!("uses neon: {}", capabilities::uses_neon());
+println!("uses sve: {}", capabilities::uses_sve());
+println!("uses haswell: {}", capabilities::uses_haswell());
+println!("uses skylake: {}", capabilities::uses_skylake());
+println!("uses ice: {}", capabilities::uses_ice());
+println!("uses genoa: {}", capabilities::uses_genoa());
+println!("uses sapphire: {}", capabilities::uses_sapphire());
 ```
 
 ## Using SimSIMD in JavaScript
@@ -400,8 +433,7 @@ To install, choose one of the following options depending on your environment:
 - `pnpm add simsimd`
 - `bun install simsimd`
 
-The package is distributed with prebuilt binaries for Node.js v10 and above for Linux (x86_64, arm64), macOS (x86_64, arm64), and Windows (i386, x86_64).
-If your platform is not supported, you can build the package from the source via `npm run build`.
+The package is distributed with prebuilt binaries, but if your platform is not supported, you can build the package from the source via `npm run build`.
 This will automatically happen unless you install the package with the `--ignore-scripts` flag or use Bun.
 After you install it, you will be able to call the SimSIMD functions on various `TypedArray` variants:
 
@@ -415,14 +447,34 @@ const distance = sqeuclidean(vectorA, vectorB);
 console.log('Squared Euclidean Distance:', distance);
 ```
 
-Other numeric types and precision levels are supported as well:
+Other numeric types and precision levels are supported as well.
+For double-precsion floating-point numbers, use `Float64Array`:
 
 ```js
 const vectorA = new Float64Array([1.0, 2.0, 3.0]);
 const vectorB = new Float64Array([4.0, 5.0, 6.0]);
-
 const distance = cosine(vectorA, vectorB);
-console.log('Cosine Similarity:', distance);
+```
+
+When doing machine learning and vector search with high-dimensional vectors you may want to quantize them to 8-bit integers.
+You may want to project values from the $[-1, 1]$ range to the $[-100, 100]$ range and then cast them to `Uint8Array`:
+
+```js
+const quantizedVectorA = new Uint8Array(vectorA.map(v => (v * 100)));
+const quantizedVectorB = new Uint8Array(vectorB.map(v => (v * 100)));
+const distance = cosine(quantizedVectorA, quantizedVectorB);
+```
+
+A more extreme quantization case would be to use binary vectors.
+You can map all positive values to `1` and all negative values and zero to `0`, packing eight values into a single byte.
+After that, Hamming and Jaccard distances can be computed.
+
+```js
+const { toBinary, hamming } = require('simsimd');
+
+const binaryVectorA = toBinary(vectorA);
+const binaryVectorB = toBinary(vectorB);
+const distance = hamming(binaryVectorA, binaryVectorB);
 ```
 
 ## Using SimSIMD in C
@@ -469,6 +521,7 @@ int uses_sve = simsimd_uses_sve();
 int uses_haswell = simsimd_uses_haswell();
 int uses_skylake = simsimd_uses_skylake();
 int uses_ice = simsimd_uses_ice();
+int uses_genoa = simsimd_uses_genoa();
 int uses_sapphire = simsimd_uses_sapphire();
 
 simsimd_capability_t capabilities = simsimd_capabilities();
@@ -590,6 +643,7 @@ To explicitly disable half-precision support, define the following macro before
 
 ```c
 #define SIMSIMD_NATIVE_F16 0 // or 1
+#define SIMSIMD_NATIVE_BF16 0 // or 1
 #include <simsimd/simsimd.h>
 ```
 

package/simsimd/binding.gyp

@@ -1,13 +1,11 @@
 {
-    "variables": {
-        "openssl_fips": ""
-    },
+    "variables": {"openssl_fips": ""},
     "targets": [
         {
             "target_name": "simsimd",
             "sources": ["javascript/lib.c"],
             "include_dirs": ["include"],
-            "defines": ["SIMSIMD_NATIVE_F16=0"],
+            "defines": ["SIMSIMD_NATIVE_F16=0", "SIMSIMD_NATIVE_BF16=0"],
             "cflags": [
                 "-std=c11",
                 "-ffast-math",
@@ -17,20 +15,17 @@
                 "-Wno-switch",
             ],
             "conditions": [
-                ["OS=='mac'", {
-                    "xcode_settings": {
-                        "MACOSX_DEPLOYMENT_TARGET": "11.0",
-                        "OTHER_CFLAGS": [
-                            "-arch arm64",
-                            "-arch x86_64"
-                        ],
-                        "OTHER_LDFLAGS": [
-                            "-arch arm64",
-                            "-arch x86_64"
-                        ]
-                    }
-                }]
-            ]
+                [
+                    "OS=='mac'",
+                    {
+                        "xcode_settings": {
+                            "MACOSX_DEPLOYMENT_TARGET": "11.0",
+                            "OTHER_CFLAGS": ["-arch arm64", "-arch x86_64"],
+                            "OTHER_LDFLAGS": ["-arch arm64", "-arch x86_64"],
+                        }
+                    },
+                ]
+            ],
         }
-    ]
+    ],
 }

package/simsimd/build.rs

@@ -5,6 +5,7 @@ fn main() {
         .file("c/lib.c")
         .include("include")
         .define("SIMSIMD_NATIVE_F16", "0")
+        .define("SIMSIMD_NATIVE_BF16", "0")
         .define("SIMSIMD_DYNAMIC_DISPATCH", "1")
         .flag("-O3")
         .flag("-std=c99") // Enforce C99 standard
@@ -19,6 +20,7 @@ fn main() {
             "arm" | "aarch64" => vec!["SIMSIMD_TARGET_NEON", "SIMSIMD_TARGET_SVE"],
             _ => vec![
                 "SIMSIMD_TARGET_SAPPHIRE",
+                "SIMSIMD_TARGET_GENOA",
                 "SIMSIMD_TARGET_ICE",
                 "SIMSIMD_TARGET_SKYLAKE",
                 "SIMSIMD_TARGET_HASWELL",

package/simsimd/c/lib.c

@@ -5,6 +5,7 @@
  */
 #define SIMSIMD_DYNAMIC_DISPATCH 1
 #define SIMSIMD_NATIVE_F16 0
+#define SIMSIMD_NATIVE_BF16 0
 
 /*  Depending on the Operating System, the following intrinsics are available
  *  on recent compiler toolchains:
@@ -28,6 +29,9 @@
 #if !defined(SIMSIMD_TARGET_ICE) && (defined(_MSC_VER) || defined(__linux__))
 #define SIMSIMD_TARGET_ICE 1
 #endif
+#if !defined(SIMSIMD_TARGET_GENOA) && (defined(__linux__))
+#define SIMSIMD_TARGET_GENOA 1
+#endif
 #if !defined(SIMSIMD_TARGET_SAPPHIRE) && (defined(__linux__))
 #define SIMSIMD_TARGET_SAPPHIRE 1
 #endif
@@ -67,22 +71,27 @@ simsimd_capability_t simsimd_capabilities(void) {
 
 // Dot products
 SIMSIMD_METRIC_DECLARATION(dot, f16, f16)
+SIMSIMD_METRIC_DECLARATION(dot, bf16, bf16)
 SIMSIMD_METRIC_DECLARATION(dot, f32, f32)
 SIMSIMD_METRIC_DECLARATION(dot, f64, f64)
 SIMSIMD_METRIC_DECLARATION(dot, f16c, f16)
+SIMSIMD_METRIC_DECLARATION(dot, bf16c, bf16)
 SIMSIMD_METRIC_DECLARATION(dot, f32c, f32)
 SIMSIMD_METRIC_DECLARATION(dot, f64c, f64)
 SIMSIMD_METRIC_DECLARATION(vdot, f16c, f16)
+SIMSIMD_METRIC_DECLARATION(vdot, bf16c, bf16)
 SIMSIMD_METRIC_DECLARATION(vdot, f32c, f32)
 SIMSIMD_METRIC_DECLARATION(vdot, f64c, f64)
 
 // Spatial distances
 SIMSIMD_METRIC_DECLARATION(cos, i8, i8)
 SIMSIMD_METRIC_DECLARATION(cos, f16, f16)
+SIMSIMD_METRIC_DECLARATION(cos, bf16, bf16)
 SIMSIMD_METRIC_DECLARATION(cos, f32, f32)
 SIMSIMD_METRIC_DECLARATION(cos, f64, f64)
 SIMSIMD_METRIC_DECLARATION(l2sq, i8, i8)
 SIMSIMD_METRIC_DECLARATION(l2sq, f16, f16)
+SIMSIMD_METRIC_DECLARATION(l2sq, bf16, bf16)
 SIMSIMD_METRIC_DECLARATION(l2sq, f32, f32)
 SIMSIMD_METRIC_DECLARATION(l2sq, f64, f64)
 
@@ -92,17 +101,26 @@ SIMSIMD_METRIC_DECLARATION(jaccard, b8, b8)
 
 // Probability distributions
 SIMSIMD_METRIC_DECLARATION(kl, f16, f16)
+SIMSIMD_METRIC_DECLARATION(kl, bf16, bf16)
 SIMSIMD_METRIC_DECLARATION(kl, f32, f32)
 SIMSIMD_METRIC_DECLARATION(kl, f64, f64)
 SIMSIMD_METRIC_DECLARATION(js, f16, f16)
+SIMSIMD_METRIC_DECLARATION(js, bf16, bf16)
 SIMSIMD_METRIC_DECLARATION(js, f32, f32)
 SIMSIMD_METRIC_DECLARATION(js, f64, f64)
 
 SIMSIMD_DYNAMIC int simsimd_uses_neon(void) { return (simsimd_capabilities() & simsimd_cap_neon_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_neon_f16(void) { return (simsimd_capabilities() & simsimd_cap_neon_f16_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_neon_bf16(void) { return (simsimd_capabilities() & simsimd_cap_neon_bf16_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_neon_i8(void) { return (simsimd_capabilities() & simsimd_cap_neon_i8_k) != 0; }
 SIMSIMD_DYNAMIC int simsimd_uses_sve(void) { return (simsimd_capabilities() & simsimd_cap_sve_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_sve_f16(void) { return (simsimd_capabilities() & simsimd_cap_sve_f16_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_sve_bf16(void) { return (simsimd_capabilities() & simsimd_cap_sve_bf16_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_sve_i8(void) { return (simsimd_capabilities() & simsimd_cap_sve_i8_k) != 0; }
 SIMSIMD_DYNAMIC int simsimd_uses_haswell(void) { return (simsimd_capabilities() & simsimd_cap_haswell_k) != 0; }
 SIMSIMD_DYNAMIC int simsimd_uses_skylake(void) { return (simsimd_capabilities() & simsimd_cap_skylake_k) != 0; }
 SIMSIMD_DYNAMIC int simsimd_uses_ice(void) { return (simsimd_capabilities() & simsimd_cap_ice_k) != 0; }
+SIMSIMD_DYNAMIC int simsimd_uses_genoa(void) { return (simsimd_capabilities() & simsimd_cap_genoa_k) != 0; }
 SIMSIMD_DYNAMIC int simsimd_uses_sapphire(void) { return (simsimd_capabilities() & simsimd_cap_sapphire_k) != 0; }
 
 #ifdef __cplusplus

package/simsimd/include/module.modulemap

@@ -0,0 +1,4 @@
+module CSimSIMD {
+    header "simsimd/simsimd.h"
+    export *
+}

package/simsimd/include/simsimd/binary.h

@@ -78,6 +78,7 @@ SIMSIMD_PUBLIC void simsimd_jaccard_b8_serial(simsimd_b8_t const* a, simsimd_b8_
 
 #if SIMSIMD_TARGET_ARM
 #if SIMSIMD_TARGET_NEON
+#pragma GCC push_options
 #pragma GCC target("+simd")
 #pragma clang attribute push(__attribute__((target("+simd"))), apply_to = function)
 
@@ -117,6 +118,7 @@ SIMSIMD_PUBLIC void simsimd_jaccard_b8_neon(simsimd_b8_t const* a, simsimd_b8_t
 #endif // SIMSIMD_TARGET_NEON
 
 #if SIMSIMD_TARGET_SVE
+#pragma GCC push_options
 #pragma GCC target("+sve")
 #pragma clang attribute push(__attribute__((target("+sve"))), apply_to = function)