usearch 0.18.8 → 0.19.1

package/python/usearch/numba.py

@@ -3,34 +3,34 @@
 # Python tooling, linters, and static analyzers. It also embeds JIT
 # into the primary `Index` class, connecting USearch with Numba.
 from math import sqrt
-from typing import Callable
 
-import numpy as np
 from numba import cfunc, types, carray
 
-from usearch.compiled import MetricKind, ScalarKind
+from usearch.index import MetricKind, ScalarKind, MetricSignature, CompiledMetric
 
 
-signature_i8args = types.float32(types.CPointer(
-    types.int8), types.CPointer(types.int8))
+signature_i8args = types.float32(types.CPointer(types.int8), types.CPointer(types.int8))
 
-signature_f16args = types.float32(types.CPointer(
-    types.float16), types.CPointer(types.float16))
+signature_f16args = types.float32(
+    types.CPointer(types.float16), types.CPointer(types.float16)
+)
 
-signature_f32args = types.float32(types.CPointer(
-    types.float32), types.CPointer(types.float32))
+signature_f32args = types.float32(
+    types.CPointer(types.float32), types.CPointer(types.float32)
+)
 
-signature_f64args = types.float32(types.CPointer(
-    types.float64), types.CPointer(types.float64))
+signature_f64args = types.float32(
+    types.CPointer(types.float64), types.CPointer(types.float64)
+)
 
 
-def jit(ndim: int,
-        metric: MetricKind = MetricKind.Cos,
-        dtype: ScalarKind = ScalarKind.F32) -> Callable:
+def jit(
+    ndim: int, metric: MetricKind = MetricKind.Cos, dtype: ScalarKind = ScalarKind.F32
+) -> CompiledMetric:
     """JIT-compiles a distance metric specifically tuned for the target hardware
     and number of dimensions.
 
-    Uses Numba `cfunc` functionality, annotating it with Numba `types` instead 
+    Uses Numba `cfunc` functionality, annotating it with Numba `types` instead
     of `ctypes` to support half-precision.
     https://numba.readthedocs.io/en/stable/reference/jit-compilation.html#c-callbacks
     """
@@ -88,8 +88,7 @@ def jit(ndim: int,
         b_array = carray(b, ndim)
         ab_delta_sq = accumulator(0)
         for i in range(ndim):
-            ab_delta_sq += (a_array[i] - b_array[i]) * \
-                (a_array[i] - b_array[i])
+            ab_delta_sq += (a_array[i] - b_array[i]) * (a_array[i] - b_array[i])
         return types.float32(ab_delta_sq)
 
     scalar_kind_to_signature = {
@@ -108,4 +107,9 @@ def jit(ndim: int,
     if dtype == ScalarKind.F8 and metric == MetricKind.IP:
         metric = MetricKind.Cos
 
-    return cfunc(scalar_kind_to_signature[dtype])(metric_kind_to_function[metric])
+    pointer = cfunc(scalar_kind_to_signature[dtype])(metric_kind_to_function[metric])
+    return CompiledMetric(
+        pointer=pointer,
+        kind=metric,
+        signature=MetricSignature.ArrayArray,
+    )

package/python/usearch/server.py

@@ -26,10 +26,13 @@ def _ascii_to_vector(string: str) -> np.ndarray:
 
 
 def serve(
-        ndim_: int, metric: str = 'ip',
-        port: int = 8545, threads: int = 1,
-        path: str = 'index.usearch', immutable: bool = False):
-
+    ndim_: int,
+    metric: str = "ip",
+    port: int = 8545,
+    threads: int = 1,
+    path: str = "index.usearch",
+    immutable: bool = False,
+):
     server = Server(port=port)
     index = Index(ndim=ndim_, metric=metric)
 
@@ -57,7 +60,7 @@ def serve(
 
     @server
     def add_one(label: int, vector: np.ndarray):
-        print('adding', label, vector)
+        print("adding", label, vector)
         labels = np.array([label], dtype=Label)
         vectors = vector.flatten().reshape(vector.shape[0], 1)
         index.add(labels, vectors)
@@ -68,7 +71,7 @@ def serve(
 
     @server
     def search_one(vector: np.ndarray, count: int) -> List[dict]:
-        print('search', vector, count)
+        print("search", vector, count)
         vectors = vector.reshape(vector.shape[0], 1)
         results: Matches = index.search(vectors, count)
         return results.to_list()
@@ -93,33 +96,42 @@ def serve(
             index.save(path)
 
 
-if __name__ == '__main__':
-
+if __name__ == "__main__":
     parser = argparse.ArgumentParser()
-    parser.add_argument('-v', '--verbose', help='log server activity')
-    parser.add_argument(
-        '--ndim', type=int,
-        help='dimensionality of the vectors')
+    parser.add_argument("-v", "--verbose", help="log server activity")
+    parser.add_argument("--ndim", type=int, help="dimensionality of the vectors")
     parser.add_argument(
-        '--immutable', type=bool, default=False,
-        help='the index can not be updated')
+        "--immutable", type=bool, default=False, help="the index can not be updated"
+    )
 
     parser.add_argument(
-        '--metric', type=str, default='ip', choices=['ip', 'cos', 'l2sq', 'haversine'],
-        help='distance function to compare vectors')
+        "--metric",
+        type=str,
+        default="ip",
+        choices=["ip", "cos", "l2sq", "haversine"],
+        help="distance function to compare vectors",
+    )
     parser.add_argument(
-        '-p', '--port', type=int, default=8545,
-        help='port to open for client connections')
+        "-p",
+        "--port",
+        type=int,
+        default=8545,
+        help="port to open for client connections",
+    )
     parser.add_argument(
-        '-j', '--threads', type=int, default=1,
-        help='number of CPU threads to use')
+        "-j", "--threads", type=int, default=1, help="number of CPU threads to use"
+    )
     parser.add_argument(
-        '--path', type=str, default='index.usearch',
-        help='where to store the index')
+        "--path", type=str, default="index.usearch", help="where to store the index"
+    )
 
     args = parser.parse_args()
-    assert args.ndim is not None, 'Define the number of dimensions!'
+    assert args.ndim is not None, "Define the number of dimensions!"
     serve(
-        ndim_=args.ndim, metric=args.metric,
-        threads=args.threads, port=args.port,
-        path=args.path, immutable=args.immutable)
+        ndim_=args.ndim,
+        metric=args.metric,
+        threads=args.threads,
+        port=args.port,
+        path=args.path,
+        immutable=args.immutable,
+    )

package/setup.py

@@ -5,97 +5,94 @@ from setuptools import setup
 from pybind11.setup_helpers import Pybind11Extension
 
 
-compile_args = ['-std=c++11', '-O3']
+compile_args = []
 link_args = []
 macros_args = [
-    ('USEARCH_USE_NATIVE_F16', '0'),
-    ('USEARCH_USE_SIMSIMD', '0'),
+    ("USEARCH_USE_NATIVE_F16", "0"),
+    ("USEARCH_USE_SIMSIMD", "0"),
 ]
 
-if sys.platform == 'linux':
-    compile_args.append('-fopenmp')
-    link_args.append('-lgomp')
-    compile_args.append('-Wno-unknown-pragmas')
-    macros_args.append(('USEARCH_USE_OPENMP', '1'))
+if sys.platform == "linux":
+    compile_args.append("-std=c++11")
+    compile_args.append("-O3")
+    compile_args.append("-Wno-unknown-pragmas")
 
-if sys.platform == 'darwin':
+    macros_args.append(("USEARCH_USE_OPENMP", "1"))
+    compile_args.append("-fopenmp")
+    link_args.append("-lgomp")
+
+if sys.platform == "darwin":
     # 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')
-    compile_args.append('-Wno-unknown-pragmas')
+    compile_args.append("-mmacosx-version-min=10.15")
+    compile_args.append("-std=c++11")
+    compile_args.append("-O3")
+    compile_args.append("-Wno-unknown-pragmas")
 
-if sys.platform == 'win32':
-    compile_args = ['/std:c++14', '/O2']
+    # Linking OpenMP requires additional preparion in CIBuildWheel
+    # macros_args.append(("USEARCH_USE_OPENMP", "1"))
+    # compile_args.append("-Xpreprocessor -fopenmp")
+    # link_args.append("-Xpreprocessor -lomp")
 
+if sys.platform == "win32":
+    compile_args.append("/std:c++14")
+    compile_args.append("/O2")
 
 ext_modules = [
     Pybind11Extension(
-        'usearch.compiled',
-        ['python/lib.cpp'],
+        "usearch.compiled",
+        ["python/lib.cpp"],
         extra_compile_args=compile_args,
         extra_link_args=link_args,
         define_macros=macros_args,
     ),
 ]
 
-__version__ = open('VERSION', 'r').read().strip()
-__lib_name__ = 'usearch'
+__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:
+with open(os.path.join(this_directory, "README.md")) as f:
     long_description = f.read()
 
 
 setup(
-
     name=__lib_name__,
     version=__version__,
-    packages=['usearch'],
-    package_dir={'usearch': 'python/usearch'},
-
-    description='Smaller & Faster Single-File Vector Search Engine from Unum',
+    packages=["usearch"],
+    package_dir={"usearch": "python/usearch"},
+    description="Smaller & Faster Single-File Vector Search Engine from Unum",
     long_description=long_description,
-    long_description_content_type='text/markdown',
-    license='Apache-2.0',
-
+    long_description_content_type="text/markdown",
+    license="Apache-2.0",
     classifiers=[
-        'Development Status :: 5 - Production/Stable',
-
-        'Natural Language :: English',
-        'Intended Audience :: Developers',
-        'Intended Audience :: Information Technology',
-        'License :: OSI Approved :: Apache Software License',
-
-        'Programming Language :: C++',
-        'Programming Language :: Python :: 3 :: Only',
-        'Programming Language :: Python :: Implementation :: CPython',
-        'Programming Language :: Java',
-        'Programming Language :: JavaScript',
-        'Programming Language :: Objective C',
-        'Programming Language :: Rust',
-        'Programming Language :: Other',
-
-        'Operating System :: MacOS',
-        'Operating System :: Unix',
-        'Operating System :: Microsoft :: Windows',
-
-        'Topic :: System :: Clustering',
-        'Topic :: Database :: Database Engines/Servers',
-        'Topic :: Scientific/Engineering :: Artificial Intelligence',
+        "Development Status :: 5 - Production/Stable",
+        "Natural Language :: English",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Information Technology",
+        "License :: OSI Approved :: Apache Software License",
+        "Programming Language :: C++",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: Implementation :: CPython",
+        "Programming Language :: Java",
+        "Programming Language :: JavaScript",
+        "Programming Language :: Objective C",
+        "Programming Language :: Rust",
+        "Programming Language :: Other",
+        "Operating System :: MacOS",
+        "Operating System :: Unix",
+        "Operating System :: Microsoft :: Windows",
+        "Topic :: System :: Clustering",
+        "Topic :: Database :: Database Engines/Servers",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
     ],
-
-    include_dirs=[
-        'include',
-        'fp16/include', 'robin-map/include', 'simsimd/include'],
-
+    include_dirs=["include", "fp16/include", "robin-map/include", "simsimd/include"],
     ext_modules=ext_modules,
     install_requires=[
-        'numpy',
-        'pandas',
+        "numpy",
+        "pandas",
+        "tqdm",
         'ucall; python_version >= "3.9"',
     ],
-    extras_require={
-        'jit': ['numba', 'cppyy'],
-    },
 )

package/simsimd/.vscode/settings.json

@@ -63,7 +63,8 @@
         "streambuf": "cpp",
         "thread": "cpp",
         "typeinfo": "cpp",
-        "complex": "cpp"
+        "complex": "cpp",
+        "immintrin.h": "c"
     },
     "cSpell.words": [
         "dtype",

package/simsimd/CMakeLists.txt

@@ -52,7 +52,7 @@ endif()
 
 # Define our header-only library.
 add_library(simsimd INTERFACE)
-target_sources(simsimd INTERFACE include/simsimd/simsimd.hpp)
+target_sources(simsimd INTERFACE include/simsimd/simsimd.h)
 target_include_directories(simsimd INTERFACE "${PROJECT_SOURCE_DIR}/include")
 
 # Build the benchmarks if needed.

package/simsimd/README.md

@@ -66,8 +66,20 @@ With AVX2 and 256-bit registers the results should be better, but would be less
 
 ---
 
-To replicate on your hardware, please run:
+To replicate on your hardware, please run following on Linux:
 
 ```sh
-cmake -DCMAKE_BUILD_TYPE=Release -DUNSW_BUILD_BENCHMARKS=1 -B ./build && make -C ./build && ./build/simsimd_bench
+cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_BENCHMARKS=1 -B ./build && make -C ./build && ./build/simsimd_bench
 ```
+
+MacOS:
+
+```sh
+brew install llvm
+cmake -B ./build \
+    -DCMAKE_C_COMPILER="/opt/homebrew/opt/llvm/bin/clang" \
+    -DCMAKE_CXX_COMPILER="/opt/homebrew/opt/llvm/bin/clang++" \
+    -DSIMSIMD_BUILD_BENCHMARKS=1 \
+    && \
+    make -C ./build -j && ./build/simsimd_bench
+```

package/simsimd/bench.cxx

@@ -1,46 +1,35 @@
+#include <thread>
+
 #include <benchmark/benchmark.h>
 
-#include <simsimd/simsimd.hpp>
+#include <simsimd/simsimd.h>
 
 namespace bm = benchmark;
-using namespace av::simsimd;
 
-static constexpr std::size_t threads_k = 64;
-static constexpr std::size_t time_k = 100;
+static const std::size_t threads_k = std::thread::hardware_concurrency();
+static const std::size_t time_k = 10;
 
-template <typename metric_at, typename scalar_at, std::size_t bytes_per_vector_ak,
+template <typename scalar_at, typename metric_at, std::size_t bytes_per_vector_ak = 256,
           std::size_t dimensions_ak = bytes_per_vector_ak / sizeof(scalar_at)> //
-static void measure(bm::State& state) {
+static void measure(bm::State& state, metric_at metric) {
 
-    constexpr std::size_t buffer_size_k = bytes_per_vector_ak / sizeof(scalar_at);
-    alignas(64) scalar_at a[buffer_size_k]{};
-    alignas(64) scalar_at b[buffer_size_k]{};
-    scalar_at c{};
+    alignas(64) scalar_at a[dimensions_ak]{};
+    alignas(64) scalar_at b[dimensions_ak]{};
+    float c{};
 
-    std::fill_n(a, buffer_size_k, static_cast<scalar_at>(1));
-    std::fill_n(b, buffer_size_k, static_cast<scalar_at>(2));
+    std::fill_n(a, dimensions_ak, static_cast<scalar_at>(1));
+    std::fill_n(b, dimensions_ak, static_cast<scalar_at>(2));
 
     for (auto _ : state)
-        bm::DoNotOptimize((c = metric_at{}(a, b, dimensions_ak)));
+        bm::DoNotOptimize((c = metric(a, b, dimensions_ak)));
 
     state.SetBytesProcessed(state.iterations() * bytes_per_vector_ak * 2u);
     state.SetItemsProcessed(state.iterations());
 }
 
-BENCHMARK_TEMPLATE(measure, euclidean_distance_t, f32_t, 32)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, euclidean_distance_t, f32_t, 256)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, euclidean_distance_t, f16_t, 32)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, euclidean_distance_t, f16_t, 256)->Threads(threads_k)->MinTime(time_k);
-
-BENCHMARK_TEMPLATE(measure, cosine_similarity_t, f32_t, 32)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, cosine_similarity_t, f32_t, 256)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, cosine_similarity_f32x4k_t, f32_t, 32)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, cosine_similarity_f32x4k_t, f32_t, 256)->Threads(threads_k)->MinTime(time_k);
-
-BENCHMARK_TEMPLATE(measure, hamming_bits_distance_t, u64_t, 32, 256)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, hamming_bits_distance_t, u64_t, 256, 2048)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, hamming_bits_distance_u1x128k_t, u64_t, 32, 256)->Threads(threads_k)->MinTime(time_k);
-BENCHMARK_TEMPLATE(measure, hamming_bits_distance_u1x128k_t, u64_t, 256, 2048)->Threads(threads_k)->MinTime(time_k);
+template <typename scalar_at, typename metric_at> void register_(char const* name, metric_at distance_func) {
+    bm::RegisterBenchmark(name, measure<scalar_at, metric_at>, distance_func)->Threads(threads_k)->MinTime(time_k);
+}
 
 int main(int argc, char** argv) {
 
@@ -76,6 +65,34 @@ int main(int argc, char** argv) {
     bm::Initialize(&argc, argv);
     if (bm::ReportUnrecognizedArguments(argc, argv))
         return 1;
+
+#if defined(__ARM_FEATURE_SVE)
+    register_<simsimd_f32_t>("dot_f32sve", simsimd_dot_f32sve);
+    register_<simsimd_f32_t>("cos_f32sve", simsimd_cos_f32sve);
+    register_<simsimd_f32_t>("l2sq_f32sve", simsimd_l2sq_f32sve);
+    register_<std::int16_t>("l2sq_f16sve", simsimd_l2sq_f16sve);
+    register_<std::uint8_t>("hamming_b1x8sve", simsimd_hamming_b1x8sve);
+    register_<std::uint8_t>("hamming_b1x128sve", simsimd_hamming_b1x128sve);
+#endif
+
+#if defined(__ARM_NEON)
+    register_<simsimd_f32_t>("dot_f32x4neon", simsimd_dot_f32x4neon);
+    register_<std::int16_t>("cos_f16x4neon", simsimd_cos_f16x4neon);
+    register_<std::int8_t>("cos_i8x16neon", simsimd_cos_i8x16neon);
+    register_<simsimd_f32_t>("cos_f32x4neon", simsimd_cos_f32x4neon);
+#endif
+
+#if defined(__AVX2__)
+    register_<simsimd_f32_t>("dot_f32x4avx2", simsimd_dot_f32x4avx2);
+    register_<std::int8_t>("dot_i8x16avx2", simsimd_dot_i8x16avx2);
+    register_<simsimd_f32_t>("cos_f32x4avx2", simsimd_cos_f32x4avx2);
+#endif
+
+#if defined(__AVX512F__)
+    register_<std::int16_t>("cos_f16x16avx512", simsimd_cos_f16x16avx512);
+    register_<std::uint8_t>("hamming_b1x128avx512", simsimd_hamming_b1x128avx512);
+#endif
+
     bm::RunSpecifiedBenchmarks();
     bm::Shutdown();
     return 0;

package/simsimd/include/simsimd/simsimd.h

@@ -10,7 +10,8 @@
  */
 
 #pragma once
-#include <math.h> // `sqrt`
+#include <math.h>   // `sqrt`
+#include <stddef.h> // `size_t`
 
 #if defined(__AVX2__)
 #include <immintrin.h>

package/swift/Test.swift

@@ -6,16 +6,20 @@
 //
 
 import Foundation
+import XCTest
 import USearch
 
 @available(iOS 13, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
-func testUnit() throws {
-    let index = USearchIndex.make(metric:USearchMetric.l2sq, dimensions: 4, connectivity: 8, quantization:USearchScalar.F32)
-    let vectorA: [Float32] = [0.3, 0.5, 1.2, 1.4]
-    let vectorB: [Float32] = [0.4, 0.2, 1.2, 1.1]
-    index.add(label: 42, vector: vectorA[...])
-    index.add(label: 43, vector: vectorB[...])
-
-    let results = index.search(vector: vectorA[...], count: 10)
-    assert(results.0[0] == 42)
+class Test: XCTestCase {
+    func testUnit() throws {
+        let index = USearchIndex.make(metric:USearchMetric.l2sq, dimensions: 4, connectivity: 8, quantization:USearchScalar.F32)
+        let vectorA: [Float32] = [0.3, 0.5, 1.2, 1.4]
+        let vectorB: [Float32] = [0.4, 0.2, 1.2, 1.1]
+        index.reserve(2)
+        index.add(label: 42, vector: vectorA[...])
+        index.add(label: 43, vector: vectorB[...])
+        
+        let results = index.search(vector: vectorA[...], count: 10)
+        assert(results.0[0] == 42)
+    }
 }