usearch 2.7.3 → 2.7.6

package/simsimd/include/simsimd/types.h

@@ -0,0 +1,196 @@
+#pragma once
+
+// Compiling for Arm: SIMSIMD_TARGET_ARM
+#if defined(__aarch64__) || defined(_M_ARM64)
+#define SIMSIMD_TARGET_ARM 1
+
+// Compiling for Arm: SIMSIMD_TARGET_ARM_NEON
+#if !defined(SIMSIMD_TARGET_ARM_NEON)
+#if defined(__ARM_NEON)
+#define SIMSIMD_TARGET_ARM_NEON 1
+#else
+#define SIMSIMD_TARGET_ARM_NEON 0
+#endif
+#endif
+
+// Compiling for Arm: SIMSIMD_TARGET_ARM_SVE
+#if !defined(SIMSIMD_TARGET_ARM_SVE)
+#if defined(__ARM_FEATURE_SVE)
+#define SIMSIMD_TARGET_ARM_SVE 1
+#else
+#define SIMSIMD_TARGET_ARM_SVE 0
+#endif
+#endif
+
+#undef SIMSIMD_TARGET_X86
+#undef SIMSIMD_TARGET_X86_AVX2
+#undef SIMSIMD_TARGET_X86_AVX512
+#define SIMSIMD_TARGET_X86 0
+#define SIMSIMD_TARGET_X86_AVX2 0
+#define SIMSIMD_TARGET_X86_AVX512 0
+
+// Compiling for x86: SIMSIMD_TARGET_X86
+#elif defined(__x86_64__) || defined(_M_X64)
+#define SIMSIMD_TARGET_X86 1
+
+// Compiling for x86: SIMSIMD_TARGET_X86_AVX2
+#if !defined(SIMSIMD_TARGET_X86_AVX2)
+#if defined(__AVX2__)
+#define SIMSIMD_TARGET_X86_AVX2 1
+#else
+#define SIMSIMD_TARGET_X86_AVX2 0
+#endif
+#endif
+
+// Compiling for x86: SIMSIMD_TARGET_X86_AVX512
+#if !defined(SIMSIMD_TARGET_X86_AVX512)
+#if defined(__AVX512F__) || defined(__AVX512VPOPCNTDQ__)
+#define SIMSIMD_TARGET_X86_AVX512 1
+#else
+#define SIMSIMD_TARGET_X86_AVX512 0
+#endif
+#endif
+
+#undef SIMSIMD_TARGET_ARM
+#undef SIMSIMD_TARGET_ARM_NEON
+#undef SIMSIMD_TARGET_ARM_SVE
+#define SIMSIMD_TARGET_ARM 0
+#define SIMSIMD_TARGET_ARM_NEON 0
+#define SIMSIMD_TARGET_ARM_SVE 0
+
+// Compiling for unknown hardware architecture
+#else
+#error Unknown hardware architecture!
+#endif
+
+#ifdef _MSC_VER
+#include <intrin.h>
+#else
+
+#if SIMSIMD_TARGET_ARM_NEON
+#include <arm_neon.h>
+#endif
+
+#if SIMSIMD_TARGET_ARM_SVE
+#include <arm_sve.h>
+#endif
+
+#if SIMSIMD_TARGET_X86_AVX2 || SIMSIMD_TARGET_X86_AVX512
+#include <immintrin.h>
+#endif
+
+#endif
+
+#ifndef SIMSIMD_RSQRT
+#include <math.h>
+#define SIMSIMD_RSQRT(x) (1 / sqrtf(x))
+#endif
+
+#ifndef SIMSIMD_LOG
+#include <math.h>
+#define SIMSIMD_LOG(x) (logf(x))
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef int simsimd_i32_t;
+typedef float simsimd_f32_t;
+typedef double simsimd_f64_t;
+typedef signed char simsimd_i8_t;
+typedef unsigned char simsimd_b8_t;
+typedef unsigned long long simsimd_size_t;
+
+#if !defined(SIMSIMD_NATIVE_F16)
+/**
+ *  @brief  Half-precision floating-point type.
+ *
+ *  - GCC or Clang on 64-bit ARM: `__fp16`, may require `-mfp16-format` option.
+ *  - GCC or Clang on 64-bit x86: `_Float16`.
+ *  - Default: `unsigned short`.
+ */
+#if (defined(__GNUC__) || defined(__clang__)) && (defined(__ARM_ARCH) || defined(__aarch64__)) &&                      \
+    (defined(__ARM_FP16_FORMAT_IEEE))
+#define SIMSIMD_NATIVE_F16 1
+typedef __fp16 simsimd_f16_t;
+#elif ((defined(__GNUC__) || defined(__clang__)) && (defined(__x86_64__) || defined(__i386__)) &&                      \
+       (defined(__SSE2__) || defined(__AVX512F__)))
+typedef _Float16 simsimd_f16_t;
+#define SIMSIMD_NATIVE_F16 1
+#else // Unknown compiler or architecture
+#define SIMSIMD_NATIVE_F16 0
+#endif // Unknown compiler or architecture
+#endif // !SIMSIMD_NATIVE_F16
+
+#if !SIMSIMD_NATIVE_F16
+typedef unsigned short simsimd_f16_t;
+#endif
+
+#define SIMSIMD_IDENTIFY(x) (x)
+
+/**
+ *  @brief  Returns the value of the half-precision floating-point number,
+ *          potentially decompressed into single-precision.
+ */
+#ifndef SIMSIMD_UNCOMPRESS_F16
+#if SIMSIMD_NATIVE_F16
+#define SIMSIMD_UNCOMPRESS_F16(x) SIMSIMD_IDENTIFY(x)
+#else
+#define SIMSIMD_UNCOMPRESS_F16(x) simsimd_uncompress_f16(x)
+#endif
+#endif
+
+typedef union {
+    unsigned i;
+    float f;
+} simsimd_f32i32_t;
+
+/**
+ *  @brief  Computes `1/sqrt(x)` using the trick from Quake 3, replacing
+ *          magic numbers with the ones suggested by Jan Kadlec.
+ */
+inline static simsimd_f32_t simsimd_approximate_inverse_square_root(simsimd_f32_t number) {
+    simsimd_f32i32_t conv;
+    conv.f = number;
+    conv.i = 0x5F1FFFF9 - (conv.i >> 1);
+    conv.f *= 0.703952253f * (2.38924456f - number * conv.f * conv.f);
+    return conv.f;
+}
+
+/**
+ *  @brief  Computes `log(x)` using the Mercator series.
+ *          The series converges to the natural logarithm for args between -1 and 1.
+ *          Published in 1668 in Logarithmotechnia.
+ */
+inline static simsimd_f32_t simsimd_approximate_log(simsimd_f32_t number) {
+    simsimd_f32_t x = number - 1;
+    simsimd_f32_t x2 = x * x;
+    simsimd_f32_t x3 = x * x * x;
+    return x - x2 / 2 + x3 / 3;
+}
+
+/**
+ *  @brief  For compilers that don't natively support the `_Float16` type,
+ *          upcasts contents into a more conventional `float`.
+ *
+ *  @warning  This function won't handle boundary conditions well.
+ *
+ *  https://stackoverflow.com/a/60047308
+ *  https://gist.github.com/milhidaka/95863906fe828198f47991c813dbe233
+ *  https://github.com/OpenCyphal/libcanard/blob/636795f4bc395f56af8d2c61d3757b5e762bb9e5/canard.c#L811-L834
+ */
+inline static float simsimd_uncompress_f16(unsigned short x) {
+    unsigned int exponent = (x & 0x7C00) >> 10;
+    unsigned int mantissa = (x & 0x03FF) << 13;
+    float mantissa_as_float = (float)mantissa;
+    unsigned int v = (*(unsigned int*)&mantissa_as_float) >> 23;
+    unsigned int result_as_uint =
+        (x & 0x8000) << 16 | (exponent != 0) * ((exponent + 112) << 23 | mantissa) |
+        ((exponent == 0) & (mantissa != 0)) * ((v - 37) << 23 | ((mantissa << (150 - v)) & 0x007FE000));
+    return *(float*)&result_as_uint;
+}
+
+#ifdef __cplusplus
+} // extern "C"
+#endif

package/simsimd/javascript/bench.js

@@ -0,0 +1,117 @@
+import benchmark from 'benchmark';
+import bindings from 'bindings';
+import * as math from 'mathjs';
+import usearch, { MetricKind } from 'usearch';
+
+const simsimd = bindings('simsimd');
+
+// Assuming the vectors are of the same length
+function cosineDistance(a, b) {
+    let dotProduct = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    return 1 - (dotProduct / (Math.sqrt(magA) * Math.sqrt(magB)));
+}
+
+function cosineDistanceMathJS(a, b) {
+    let dotProduct = math.dot(a, b);
+    let magA = math.sqrt(math.dot(a, a));
+    let magB = math.sqrt(math.dot(b, b));
+    return 1 - (dotProduct / (magA * magB));
+}
+
+// Generate random data for testing
+const dimensions = 1536;  // Adjust dimensions as needed
+const array1 = Array.from({ length: dimensions }, () => Math.random() * 100);
+const array2 = Array.from({ length: dimensions }, () => Math.random() * 100);
+const floatArray1 = new Float32Array(array1);
+const floatArray2 = new Float32Array(array2);
+const intArray1 = new Int8Array(array1);
+const intArray2 = new Int8Array(array2);
+
+// Generate random batch data for testing
+const batchSize = 1000;
+const matrix1 = Array.from({ length: dimensions * batchSize }, () => Math.random() * 100);
+const matrix2 = Array.from({ length: dimensions * batchSize }, () => Math.random() * 100);
+const floatMatrix1 = new Float32Array(matrix1);
+const floatMatrix2 = new Float32Array(matrix2);
+const intMatrix1 = new Int8Array(matrix1);
+const intMatrix2 = new Int8Array(matrix2);
+
+// Create benchmark suite
+const singleSuite = new benchmark.Suite('Single Vector Processing');
+const batchSuite = new benchmark.Suite('Batch Vector Processing');
+
+// Single-vector processing benchmarks
+singleSuite
+
+    // Pure JavaScript
+    .add('Array of Numbers', () => {
+        cosineDistance(array1, array2);
+    })
+    .add('TypedArray of Float32', () => {
+        cosineDistance(floatArray1, floatArray2);
+    })
+    .add('TypedArray of Int8', () => {
+        cosineDistance(intArray1, intArray2);
+    })
+
+    // Math JS
+    .add('Array of Numbers with MathJS', () => {
+        cosineDistanceMathJS(array1, array2);
+    })
+    .add('TypedArray of Float32 with MathJS', () => {
+        cosineDistanceMathJS(floatArray1, floatArray2);
+    })
+
+    // SimSIMD
+    .add('TypedArray of Float32 with SimSIMD', () => {
+        simsimd.cosine(floatArray1, floatArray2);
+    })
+    .add('TypedArray of Int8 with SimSIMD', () => {
+        simsimd.cosine(intArray1, intArray2);
+    })
+
+    .on('cycle', (event) => {
+        console.log(String(event.target));
+    })
+    .on('complete', () => {
+        console.log('Fastest Single-Vector Processing is ' + singleSuite.filter('fastest').map('name'));
+    })
+    .run({
+        noCache: true,
+        async: false,
+    });
+
+// Batch-vector processing benchmarks
+batchSuite
+    .add('2D Array of Numbers', () => {
+        for (let i = 0; i < batchSize; i++) {
+            for (let j = 0; j < batchSize; j++) {
+                const start = i * dimensions;
+                const end = start + dimensions;
+                cosineDistance(matrix1.slice(start, end), matrix2.slice(start, end));
+            }
+        }
+    })
+    .add('2D TypedArray of Float32 with exact USearch', () => {
+        usearch.exactSearch(floatMatrix1, floatMatrix2, dimensions, 1, MetricKind.Cos);
+    })
+    .add('2D TypedArray of Int8 with exact USearch', () => {
+        usearch.exactSearch(intMatrix1, intMatrix2, dimensions, 1, MetricKind.Cos);
+    })
+    .on('cycle', (event) => {
+        console.log(String(event.target));
+    })
+    .on('complete', () => {
+        console.log('Fastest Batch-Vector Processing is ' + batchSuite.filter('fastest').map('name'));
+    })
+    .run({
+        noCache: true,
+        async: false,
+    });

package/simsimd/javascript/lib.c

@@ -0,0 +1,102 @@
+/**
+ *  @file       lib.c
+ *  @brief      JavaScript bindings for SimSIMD.
+ *  @author     Ash Vardanian
+ *  @date       October 18, 2023
+ *
+ *  @copyright  Copyright (c) 2023
+ *  @see        NodeJS docs: https://nodejs.org/api/n-api.html
+ */
+
+#include <node_api.h>        // `napi_*` functions
+#include <simsimd/simsimd.h> // `simsimd_*` functions
+
+/// @brief  Global variable that caches the CPU capabilities, and is computed just onc, when the module is loaded.
+simsimd_capability_t static_capabilities = simsimd_cap_serial_k;
+
+napi_value runAPI(napi_env env, napi_callback_info info, simsimd_metric_kind_t metric_kind) {
+    size_t argc = 2;
+    napi_value args[2];
+    napi_status status;
+
+    // Get callback info and ensure the argument count is correct
+    status = napi_get_cb_info(env, info, &argc, args, NULL, NULL);
+    if (status != napi_ok || argc != 2) {
+        napi_throw_error(env, NULL, "Wrong number of arguments");
+        return NULL;
+    }
+
+    // Obtain the typed arrays from the arguments
+    void *data_a, *data_b;
+    size_t length_a, length_b;
+    napi_typedarray_type type_a, type_b;
+    napi_status status_a, status_b;
+    status_a = napi_get_typedarray_info(env, args[0], &type_a, &length_a, &data_a, NULL, NULL);
+    status_b = napi_get_typedarray_info(env, args[1], &type_b, &length_b, &data_b, NULL, NULL);
+    if (status_a != napi_ok || status_b != napi_ok || type_a != type_b || length_a != length_b) {
+        napi_throw_error(env, NULL, "Both arguments must be typed arrays of matching types and dimensionality");
+        return NULL;
+    }
+    if (type_a != napi_float32_array && type_a != napi_int8_array && type_a != napi_uint8_array) {
+        napi_throw_error(env, NULL, "Only `float32`, `int8` and `uint8` arrays are supported in JavaScript bindings");
+        return NULL;
+    }
+
+    simsimd_datatype_t datatype = simsimd_datatype_unknown_k;
+    switch (type_a) {
+    case napi_float32_array: datatype = simsimd_datatype_f32_k; break;
+    case napi_int8_array: datatype = simsimd_datatype_i8_k; break;
+    case napi_uint8_array: datatype = simsimd_datatype_b8_k; break;
+    default: break;
+    }
+
+    simsimd_metric_punned_t metric = NULL;
+    simsimd_capability_t capability = simsimd_cap_serial_k;
+    simsimd_find_metric_punned(metric_kind, datatype, static_capabilities, simsimd_cap_any_k, &metric, &capability);
+    if (metric == NULL) {
+        napi_throw_error(env, NULL, "Unsupported datatype");
+        return NULL;
+    }
+
+    simsimd_f32_t result = metric(data_a, data_b, length_a, length_b);
+
+    // Convert the result to a JavaScript number
+    napi_value js_result;
+    status = napi_create_double(env, result, &js_result);
+    if (status != napi_ok)
+        return NULL;
+
+    return js_result;
+}
+
+napi_value l2sqAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_sqeuclidean_k); }
+napi_value cosAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_cosine_k); }
+napi_value ipAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_ip_k); }
+napi_value klAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_kl_k); }
+napi_value jsAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_js_k); }
+napi_value hammingAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_hamming_k); }
+napi_value jaccardAPI(napi_env env, napi_callback_info info) { return runAPI(env, info, simsimd_metric_jaccard_k); }
+
+napi_value Init(napi_env env, napi_value exports) {
+
+    // Define an array of property descriptors
+    napi_property_descriptor sqeuclideanDesc = {"sqeuclidean", 0, l2sqAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor innerDesc = {"inner", 0, ipAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor cosineDesc = {"cosine", 0, cosAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor hammingDesc = {"hamming", 0, hammingAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor jaccardDesc = {"jaccard", 0, jaccardAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor klDesc = {"kullbackleibler", 0, klAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor jsDesc = {"jensenshannon", 0, jsAPI, 0, 0, 0, napi_default, 0};
+    napi_property_descriptor properties[] = {
+        sqeuclideanDesc, innerDesc, cosineDesc, hammingDesc, jaccardDesc, klDesc, jsDesc,
+    };
+
+    // Define the properties on the `exports` object
+    size_t propertyCount = sizeof(properties) / sizeof(properties[0]);
+    napi_define_properties(env, exports, propertyCount, properties);
+
+    static_capabilities = simsimd_capabilities();
+    return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/simsimd/javascript/simsimd.js

@@ -0,0 +1,45 @@
+const compiled = require('bindings')('simsimd');
+
+module.exports = {
+
+    /**
+     * @brief Computes the squared Euclidean distance between two vectors.
+     * @param {Float32Array|Int8Array} a - The first vector.
+     * @param {Float32Array|Int8Array} b - The second vector.
+     * @returns {number} The squared Euclidean distance between vectors a and b.
+     */
+    sqeuclidean: compiled.sqeuclidean,
+
+    /**
+     * @brief Computes the cosine similarity between two vectors.
+     * @param {Float32Array|Int8Array} a - The first vector.
+     * @param {Float32Array|Int8Array} b - The second vector.
+     * @returns {number} The cosine similarity between vectors a and b.
+     */
+    cosine: compiled.cosine,
+
+    /**
+     * @brief Computes the inner product of two vectors.
+     * @param {Float32Array} a - The first vector.
+     * @param {Float32Array} b - The second vector.
+     * @returns {number} The inner product of vectors a and b.
+     */
+    inner: compiled.inner,
+
+    /**
+     * @brief Computes the bitwise Hamming distance between two vectors.
+     * @param {Uint8Array} a - The first vector.
+     * @param {Uint8Array} b - The second vector.
+     * @returns {number} The Hamming distance between vectors a and b.
+     */
+    hamming: compiled.hamming,
+
+    /**
+     * @brief Computes the bitwise Jaccard similarity coefficient between two vectors.
+     * @param {Uint8Array} a - The first vector.
+     * @param {Uint8Array} b - The second vector.
+     * @returns {number} The Jaccard similarity coefficient between vectors a and b.
+     */
+    jaccard: compiled.jaccard,
+
+};

package/simsimd/javascript/test.js

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import bindings from 'bindings';
+import assert from 'node:assert';
+
+const simsimd = bindings('simsimd');
+
+const typedArray1 = new Float32Array([1.0, 2.0, 3.0]);
+const typedArray2 = new Float32Array([4.0, 5.0, 6.0]);
+
+function assertAlmostEqual(actual, expected, tolerance = 1e-6) {
+    const lowerBound = expected - tolerance;
+    const upperBound = expected + tolerance;
+    assert(actual >= lowerBound && actual <= upperBound, `Expected ${actual} to be almost equal to ${expected}`);
+}
+
+test('Squared Euclidean Distance', () => {
+    const result = simsimd.sqeuclidean(typedArray1, typedArray2);
+    assertAlmostEqual(result, 27.0, 0.01);
+});
+
+test('Inner Product', () => {
+    const result = simsimd.inner(typedArray1, typedArray2);
+    assertAlmostEqual(result, -31.0, 0.01);
+});
+
+test('Cosine Similarity', () => {
+    const result = simsimd.cosine(typedArray1, typedArray2);
+    assertAlmostEqual(result, 0.029, 0.01);
+});

package/simsimd/package.json

@@ -1,8 +1,37 @@
 {
+  "name": "simsimd",
+  "version": "3.1.0",
+  "description": "Vector Similarity Functions 3x-200x Faster than SciPy and NumPy",
+  "author": "Ash Vardanian",
+  "license": "Apache 2.0",
+  "main": "javascript/simsimd.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ashvardanian/simsimd.git"
+  },
+  "gypfile": true,
+  "engines": {
+    "node": "~10 >=10.20 || >=12.17"
+  },
+  "dependencies": {
+    "@types/node": "^20.4.5",
+    "bindings": "~1.2.1",
+    "node-addon-api": "^3.0.0"
+  },
+  "scripts": {
+    "test": "node --test ./javascript/test.js",
+    "bench": "node ./javascript/bench.js"
+  },
   "devDependencies": {
     "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "conventional-changelog-eslint": "^4.0.0",
-    "semantic-release": "^21.1.1"
+    "benchmark": "^2.1.4",
+    "conventional-changelog-eslint": "^3.0.9",
+    "mathjs": "^11.11.2",
+    "node-gyp": "^8.3.0",
+    "semantic-release": "^21.1.2",
+    "typescript": "^5.1.6",
+    "usearch": "^2.7.2"
   }
 }

package/simsimd/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=42", "wheel", "cmake>=3.22", "pybind11"]
+requires = ["setuptools>=42", "wheel", "numpy"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
@@ -9,10 +9,10 @@ xfail_strict = true
 filterwarnings = ["error"]
 
 [tool.cibuildwheel]
-test-requires = ["pytest"]
-test-command = "pytest {project}/python/test.py -x"
+test-requires = ["pytest", "pytest-repeat", "scipy"]
+test-command = "pytest {project}/python/test.py -s -x"
 build-verbosity = 0
-skip = ["*musllinux*", "*i686*", "pp*"]
+skip = ["*musllinux*", "*i686*", "pp*", "cp36-*", "cp37-*"]
 
 [tool.cibuildwheel.linux]
 before-build = [
@@ -30,7 +30,6 @@ repair-wheel-command = "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"
 [tool.cibuildwheel.macos]
 before-build = [
     "rm -rf {project}/build",
-    "brew install gcc@12",
 ]
 archs = ["x86_64", "arm64"]
 repair-wheel-command = "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}"
@@ -40,4 +39,4 @@ before-build = [
    "rd /s /q {project}\\build || echo Done",
 ]
 archs = ["x86", "AMD64"]
-skip = ["*win32*", "pp*"]
+skip = ["*win32*", "pp*"]