usearch 2.15.3 → 2.16.1

package/simsimd/scripts/bench_vectors_live.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Module: bench_vectors_live.py
+
+This script visualizes the performance difference between SimSIMD and default
+numerics libraries like NumPy and SimSIMD for the most common kernels.
+
+One plot contains information about one distance function, but many data types
+and libraries. For each benchmark, the baseline is the NumPy/SciPy distance function
+applied to `float64` input data. The "x" axis represents the growth in the number of
+dimensions of the input vectors, while the "y" axis represents the speedup factor
+of every kernel against the baseline.
+"""
+import os
+import argparse
+from typing import List
+
+import numpy as np
+
+import perfplot
+
+from bench_vectors import (
+    metric_families,
+    dtype_names,
+    Kernel,
+    yield_kernels,
+    random_matrix,
+)
+
+
+def ndim_argument(value):
+    if value == "default":
+        return [2**k for k in range(16)]
+    try:
+        # Split the input string by commas and convert each part to an integer
+        return [int(x) for x in value.split(",")]
+    except ValueError:
+        raise argparse.ArgumentTypeError("Value must be 'default' or a comma-separated list of integers")
+
+
+def main():
+    # Argument parsing
+    parser = argparse.ArgumentParser(description="Visualize Performance Difference between SimSIMD and other libraries")
+    parser.add_argument(
+        "--ndim-min",
+        type=int,
+        default=2,
+        help="",
+    )
+    parser.add_argument(
+        "--ndim-max",
+        type=int,
+        default=1024 * 1024,
+        help="",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-path",
+        type=str,
+        default=None,
+        help="File to save the plot to (default: None, plot is shown live)",
+    )
+    parser.add_argument(
+        "-n",
+        "--count",
+        type=int,
+        default=1,
+        help="""Number of vectors per batch (default: 1)
+            
+        By default, when set to 1 the benchmark will generate many vectors of size (ndim, )
+        and call the functions on pairs of single vectors: both directly, and through `cdist`.
+        Alternatively, for larger batch sizes the benchmark will generate two matrices of 
+        size (n, ndim) and compute:
+            
+        - batch mode: (n) distances between vectors in identical rows of the two matrices,
+        - all-pairs mode: (n^2) distances between all pairs of vectors in the two matrices via `cdist`.
+        """,
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["batch", "all-pairs"],
+        default="batch",
+        help="""Choose between 'batch' and 'all-pairs' mode (default: batch)
+        
+        In 'batch' mode, the latency will generate two matrices of size (n, ndim) 
+        and compute (n) distances between vectors in identical rows of the two matrices.
+        In 'all-pairs' mode, the latency will generate two matrices of size (n, ndim)
+        and compute (n^2) distances between all pairs of vectors in the two matrices via `cdist`.
+        """,
+    )
+    parser.add_argument(
+        "--metric",
+        choices=metric_families,
+        default="dot",
+        help=f"Distance metric to use, profiles `dot` by default",
+    )
+    parser.add_argument(
+        "--dtype",
+        choices=dtype_names,
+        default="float64",
+        help=f"Defines numeric types to latency, profiles `float64` by default",
+    )
+    parser.add_argument("--scipy", action="store_true", help="Profile SciPy, must be installed")
+    parser.add_argument("--scikit", action="store_true", help="Profile scikit-learn, must be installed")
+    parser.add_argument("--torch", action="store_true", help="Profile PyTorch, must be installed")
+    parser.add_argument("--tf", action="store_true", help="Profile TensorFlow, must be installed")
+    parser.add_argument("--jax", action="store_true", help="Profile JAX, must be installed")
+
+    args = parser.parse_args()
+    assert args.count > 0, "Number of vectors per batch must be greater than 0"
+    assert args.ndim_min > 0, "Number of dimensions must be greater than 0"
+    assert args.ndim_max > 0, "Number of dimensions must be greater than 0"
+
+    ndim_range = [args.ndim_min]
+    while ndim_range[-1] <= args.ndim_max:
+        ndim_range.append(ndim_range[-1] * 2)
+
+    kernels: List[Kernel] = list(
+        yield_kernels(
+            [args.metric],
+            dtype_names,
+            include_scipy=args.scipy,
+            include_scikit=args.scikit,
+            include_torch=args.torch,
+            include_tf=args.tf,
+            include_jax=args.jax,
+        )
+    )
+    if len(kernels) == 0:
+        raise RuntimeError("No kernels found!")
+
+    def precomputed_flops(ndim: int) -> int:
+        if args.mode == "all-pairs":
+            return ndim * (args.count**2)
+        else:
+            return ndim * (args.count)
+
+    def generate_matrix(ndim: int) -> np.ndarray:
+        if args.count == 1:
+            return random_matrix(1, ndim, dtype=args.dtype).flatten()
+        else:
+            return random_matrix(args.count, ndim, dtype=args.dtype)
+
+    def wrap_binary_function(function):
+        def wrapped(A):
+            return function(A, A)
+
+        return wrapped
+
+    kernel_labels: List[str] = []
+    kernel_callables: List[callable] = []
+
+    # Add SimSIMD kernels
+    for kernel in kernels:
+        if not kernel.name.startswith("numpy.") and not kernel.name.startswith("scipy."):
+            continue
+        _, _, function_name = kernel.name.partition(".")
+        kernel_labels.append(f"simsimd.{function_name}<{kernel.dtype}>")
+        if args.mode == "all-pairs":
+            kernel_callables.append(wrap_binary_function(kernel.simsimd_all_pairs_func))
+        else:
+            kernel_callables.append(wrap_binary_function(kernel.simsimd_func))
+
+    # Add other kernels
+    for kernel in kernels:
+        kernel_labels.append(f"{kernel.name}<{kernel.dtype}>")
+        if args.mode == "all-pairs":
+            kernel_callables.append(wrap_binary_function(kernel.baseline_all_pairs_func))
+        elif args.count == 1:
+            kernel_callables.append(wrap_binary_function(kernel.baseline_one_to_one_func))
+        else:
+            kernel_callables.append(wrap_binary_function(kernel.baseline_many_to_many_func))
+
+    # Filter-out kernels that raise any exceptions
+    safe_callables = []
+    safe_labels = []
+    for kernel_label, kernel_callable in zip(kernel_labels, kernel_callables):
+        try:
+            kernel_callable(generate_matrix(ndim_range[0]))
+            safe_callables.append(kernel_callable)
+            safe_labels.append(kernel_label)
+        except:
+            print(f"Skipping {kernel_label}")
+
+    print(safe_callables)
+    print(safe_labels)
+
+    # Settings are mostly the same for live charts and exported ones
+    profiler_settings = dict(
+        setup=generate_matrix,
+        kernels=safe_callables,
+        labels=safe_labels,
+        n_range=ndim_range,
+        flops=precomputed_flops,
+        xlabel="ndim",
+        equality_check=None,  # bypass correctness check, we have tests for that
+    )
+
+    # Plot the results
+    if args.output_path is not None:
+        plot_fp = os.path.abspath(args.output_path)
+        profiler_settings["filename"] = plot_fp
+        profiler_settings["show_progress"] = False
+        results = perfplot.bench(**profiler_settings)
+        results.save(plot_fp, transparent=False, bbox_inches="tight", relative_to=0, logy="auto")
+    else:
+        profiler_settings.pop("flops")
+        perfplot.live(**profiler_settings)
+
+
+if __name__ == "__main__":
+    main()

package/simsimd/scripts/test.c

@@ -0,0 +1,155 @@
+/**
+ *  @file   test.c
+ *  @brief  Test focusing only on the simplest functionality.
+ */
+
+#include <assert.h> // `assert`
+#include <math.h>   // `sqrtf`
+#include <stdio.h>  // `printf`
+
+#define SIMSIMD_NATIVE_F16 0
+#define SIMSIMD_NATIVE_BF16 0
+#include <simsimd/simsimd.h>
+
+/**
+ *  @brief  Logs CPU capabilities supported by the current build (compile-time) and runtime.
+ */
+void print_capabilities(void) {
+    simsimd_capability_t runtime_caps = simsimd_capabilities();
+
+    // Log supported functionality
+    char const *flags[2] = {"false", "true"};
+    printf("Benchmarking Similarity Measures\n");
+    printf("- Compiler used native F16: %s\n", flags[SIMSIMD_NATIVE_F16]);
+    printf("- Compiler used native BF16: %s\n", flags[SIMSIMD_NATIVE_BF16]);
+    printf("\n");
+    printf("Compile-time settings:\n");
+    printf("- Arm NEON support enabled: %s\n", flags[SIMSIMD_TARGET_NEON]);
+    printf("- Arm SVE support enabled: %s\n", flags[SIMSIMD_TARGET_SVE]);
+    printf("- Arm SVE2 support enabled: %s\n", flags[SIMSIMD_TARGET_SVE2]);
+    printf("- x86 Haswell support enabled: %s\n", flags[SIMSIMD_TARGET_HASWELL]);
+    printf("- x86 Skylake support enabled: %s\n", flags[SIMSIMD_TARGET_SKYLAKE]);
+    printf("- x86 Ice Lake support enabled: %s\n", flags[SIMSIMD_TARGET_ICE]);
+    printf("- x86 Genoa support enabled: %s\n", flags[SIMSIMD_TARGET_GENOA]);
+    printf("- x86 Sapphire Rapids support enabled: %s\n", flags[SIMSIMD_TARGET_SAPPHIRE]);
+    printf("- x86 Turin support enabled: %s\n", flags[SIMSIMD_TARGET_TURIN]);
+    printf("- x86 Sierra Forest support enabled: %s\n", flags[SIMSIMD_TARGET_SIERRA]);
+    printf("\n");
+    printf("Run-time settings:\n");
+    printf("- Arm NEON support enabled: %s\n", flags[(runtime_caps & simsimd_cap_neon_k) != 0]);
+    printf("- Arm NEON F16 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_neon_f16_k) != 0]);
+    printf("- Arm NEON BF16 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_neon_bf16_k) != 0]);
+    printf("- Arm NEON I8 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_neon_i8_k) != 0]);
+    printf("- Arm SVE support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sve_k) != 0]);
+    printf("- Arm SVE F16 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sve_f16_k) != 0]);
+    printf("- Arm SVE BF16 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sve_bf16_k) != 0]);
+    printf("- Arm SVE I8 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sve_i8_k) != 0]);
+    printf("- Arm SVE2 support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sve2_k) != 0]);
+    printf("- x86 Haswell support enabled: %s\n", flags[(runtime_caps & simsimd_cap_haswell_k) != 0]);
+    printf("- x86 Skylake support enabled: %s\n", flags[(runtime_caps & simsimd_cap_skylake_k) != 0]);
+    printf("- x86 Ice Lake support enabled: %s\n", flags[(runtime_caps & simsimd_cap_ice_k) != 0]);
+    printf("- x86 Genoa support enabled: %s\n", flags[(runtime_caps & simsimd_cap_genoa_k) != 0]);
+    printf("- x86 Sapphire Rapids support enabled: %s\n", flags[(runtime_caps & simsimd_cap_sapphire_k) != 0]);
+    printf("- x86 Turin support enabled: %s\n", flags[(runtime_caps & simsimd_cap_turin_k) != 0]);
+    printf("\n");
+}
+
+/**
+ *  @brief  A trivial test that checks if the utility functions return the expected values.
+ */
+void test_utilities(void) {
+    simsimd_capability_t capabilities = simsimd_capabilities();
+
+    int uses_neon = simsimd_uses_neon();
+    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();
+    int uses_turin = simsimd_uses_turin();
+    int uses_sierra = simsimd_uses_sierra();
+
+    assert(uses_neon == ((capabilities & simsimd_cap_neon_k) != 0));
+    assert(uses_sve == ((capabilities & simsimd_cap_sve_k) != 0));
+    assert(uses_haswell == ((capabilities & simsimd_cap_haswell_k) != 0));
+    assert(uses_skylake == ((capabilities & simsimd_cap_skylake_k) != 0));
+    assert(uses_ice == ((capabilities & simsimd_cap_ice_k) != 0));
+    assert(uses_genoa == ((capabilities & simsimd_cap_genoa_k) != 0));
+    assert(uses_sapphire == ((capabilities & simsimd_cap_sapphire_k) != 0));
+    assert(uses_turin == ((capabilities & simsimd_cap_turin_k) != 0));
+    assert(uses_sierra == ((capabilities & simsimd_cap_sierra_k) != 0));
+}
+
+/**
+ *  @brief  A trivial test that calls every implemented distance function and their dispatch versions
+ *          on vectors A and B, where A and B are equal.
+ */
+void test_distance_from_itself(void) {
+    simsimd_f64_t f64s[1536];
+    simsimd_f32_t f32s[1536];
+    simsimd_f16_t f16s[1536];
+    simsimd_bf16_t bf16s[1536];
+    simsimd_i8_t i8s[1536];
+    simsimd_b8_t b8s[1536 / 8]; // 8 bits per word
+    simsimd_distance_t distance;
+
+    // Cosine distance between two vectors
+    simsimd_cos_i8(i8s, i8s, 1536, &distance);
+    simsimd_cos_f16(f16s, f16s, 1536, &distance);
+    simsimd_cos_bf16(bf16s, bf16s, 1536, &distance);
+    simsimd_cos_f32(f32s, f32s, 1536, &distance);
+    simsimd_cos_f64(f64s, f64s, 1536, &distance);
+
+    // Euclidean distance between two vectors
+    simsimd_l2sq_i8(i8s, i8s, 1536, &distance);
+    simsimd_l2sq_f16(f16s, f16s, 1536, &distance);
+    simsimd_l2sq_bf16(bf16s, bf16s, 1536, &distance);
+    simsimd_l2sq_f32(f32s, f32s, 1536, &distance);
+    simsimd_l2sq_f64(f64s, f64s, 1536, &distance);
+
+    // Inner product between two vectors
+    simsimd_dot_f16(f16s, f16s, 1536, &distance);
+    simsimd_dot_bf16(bf16s, bf16s, 1536, &distance);
+    simsimd_dot_f32(f32s, f32s, 1536, &distance);
+    simsimd_dot_f64(f64s, f64s, 1536, &distance);
+
+    // Complex inner product between two vectors
+    simsimd_dot_f16c(f16s, f16s, 1536, &distance);
+    simsimd_dot_bf16c(bf16s, bf16s, 1536, &distance);
+    // simsimd_dot_bf16c(bf16s, bf16s, 1536, &distance);
+    simsimd_dot_f32c(f32s, f32s, 1536, &distance);
+    simsimd_dot_f64c(f64s, f64s, 1536, &distance);
+
+    // Complex conjugate inner product between two vectors
+    simsimd_vdot_f16c(f16s, f16s, 1536, &distance);
+    simsimd_vdot_bf16c(bf16s, bf16s, 1536, &distance);
+    simsimd_vdot_f32c(f32s, f32s, 1536, &distance);
+    simsimd_vdot_f64c(f64s, f64s, 1536, &distance);
+
+    // Hamming distance between two vectors
+    simsimd_hamming_b8(b8s, b8s, 1536 / 8, &distance);
+
+    // Jaccard distance between two vectors
+    simsimd_jaccard_b8(b8s, b8s, 1536 / 8, &distance);
+
+    // Jensen-Shannon divergence between two vectors
+    simsimd_js_f16(f16s, f16s, 1536, &distance);
+    simsimd_js_bf16(bf16s, bf16s, 1536, &distance);
+    simsimd_js_f32(f32s, f32s, 1536, &distance);
+    simsimd_js_f64(f64s, f64s, 1536, &distance);
+
+    // Kullback-Leibler divergence between two vectors
+    simsimd_kl_f16(f16s, f16s, 1536, &distance);
+    simsimd_kl_bf16(bf16s, bf16s, 1536, &distance);
+    simsimd_kl_f32(f32s, f32s, 1536, &distance);
+    simsimd_kl_f64(f64s, f64s, 1536, &distance);
+}
+
+int main(int argc, char **argv) {
+
+    print_capabilities();
+    test_utilities();
+    test_distance_from_itself();
+    return 0;
+}

package/simsimd/{javascript → scripts}/test.mjs

@@ -23,9 +23,9 @@
 import test from "node:test";
 import assert from "node:assert";
 
-import * as simsimd from "./dist/esm/simsimd.js";
+import * as simsimd from "../javascript/dist/esm/simsimd.js";
 
-import * as fallback from "./dist/esm/fallback.js";
+import * as fallback from "../javascript/dist/esm/fallback.js";
 
 function assertAlmostEqual(actual, expected, tolerance = 1e-6) {
   const lowerBound = expected - tolerance;