usearch 0.18.6 → 0.19.0

package/python/usearch/io.py

@@ -4,9 +4,8 @@ import numpy as np
 
 
 def load_matrix(
-        filename: str,
-        start_row: int = 0, count_rows: int = None,
-        view: bool = False) -> np.ndarray:
+    filename: str, start_row: int = 0, count_rows: int = None, view: bool = False
+) -> np.ndarray:
     """Read *.ibin, *.bbib, *.hbin, *.fbin, *.dbin files with matrices.
 
     :param filename: path to the matrix file
@@ -19,36 +18,37 @@ def load_matrix(
     """
     dtype = np.float32
     scalar_size = 4
-    if filename.endswith('.fbin'):
+    if filename.endswith(".fbin"):
         dtype = np.float32
         scalar_size = 4
-    elif filename.endswith('.dbin'):
+    elif filename.endswith(".dbin"):
         dtype = np.float64
         scalar_size = 8
-    elif filename.endswith('.hbin'):
+    elif filename.endswith(".hbin"):
         dtype = np.float16
         scalar_size = 2
-    elif filename.endswith('.ibin'):
+    elif filename.endswith(".ibin"):
         dtype = np.int32
         scalar_size = 4
-    elif filename.endswith('.bbin'):
+    elif filename.endswith(".bbin"):
         dtype = np.int8
         scalar_size = 1
     else:
-        raise Exception('Unknown file type')
+        raise Exception("Unknown file type")
 
-    with open(filename, 'rb') as f:
+    with open(filename, "rb") as f:
         rows, cols = np.fromfile(f, count=2, dtype=np.int32)
         rows = (rows - start_row) if count_rows is None else count_rows
         row_offset = start_row * scalar_size * cols
 
         if view:
             return np.memmap(
-                f, dtype=dtype, mode='r', offset=8+row_offset, shape=(rows, cols))
+                f, dtype=dtype, mode="r", offset=8 + row_offset, shape=(rows, cols)
+            )
         else:
             return np.fromfile(
-                f, count=rows * cols,
-                dtype=dtype, offset=row_offset).reshape(rows, cols)
+                f, count=rows * cols, dtype=dtype, offset=row_offset
+            ).reshape(rows, cols)
 
 
 def save_matrix(vectors: np.ndarray, filename: str):
@@ -60,22 +60,22 @@ def save_matrix(vectors: np.ndarray, filename: str):
     :type filename: str
     """
     dtype = np.float32
-    if filename.endswith('.fbin'):
+    if filename.endswith(".fbin"):
         dtype = np.float32
-    elif filename.endswith('.dbin'):
+    elif filename.endswith(".dbin"):
         dtype = np.float64
-    elif filename.endswith('.hbin'):
+    elif filename.endswith(".hbin"):
         dtype = np.float16
-    elif filename.endswith('.ibin'):
+    elif filename.endswith(".ibin"):
         dtype = np.int32
-    elif filename.endswith('.bbin'):
+    elif filename.endswith(".bbin"):
         dtype = np.int8
     else:
-        raise Exception('Unknown file type')
+        raise Exception("Unknown file type")
 
-    assert len(vectors.shape) == 2, 'Input array must have 2 dimensions'
-    with open(filename, 'wb') as f:
+    assert len(vectors.shape) == 2, "Input array must have 2 dimensions"
+    with open(filename, "wb") as f:
         count, dim = vectors.shape
-        f.write(struct.pack('<i', count))
-        f.write(struct.pack('<i', dim))
+        f.write(struct.pack("<i", count))
+        f.write(struct.pack("<i", dim))
         vectors.astype(dtype).flatten().tofile(f)

package/python/usearch/join.py

@@ -7,7 +7,6 @@ from index import Index, Matches, Label
 
 
 class bidict(dict):
-
     def __init__(self, *args, **kwargs):
         super(bidict, self).__init__(*args, **kwargs)
         self.inverse = {}
@@ -37,10 +36,10 @@ def index_in_array(array: np.ndarray, item: Label) -> int:
 
 
 def semantic_join(a: Index, b: Index, resolution: int = 10) -> bidict:
-    """Performs a Semantic Join, matching one entry from `a` with 
+    """Performs a Semantic Join, matching one entry from `a` with
     one entry from `b`, converging towards a Stable Marriage.
     Assuming the collections can be different in size, classical solution
-    doesn't provide 
+    doesn't provide
 
     :param resolution: Approximate matches per member to consider, defaults to 10
     :type resolution: int, optional
@@ -65,7 +64,6 @@ def semantic_join(a: Index, b: Index, resolution: int = 10) -> bidict:
     idle_cycles: int = 0
     hopeless_men_count = len(men) - len(women)
     while len(free_men) > hopeless_men_count:
-
         # In the worst case scenario we may need to match more candidates for every
         # remaining man. This, however, may drastically increase the runtime.
         if len(free_men) == idle_cycles:

package/python/usearch/numba.py

@@ -3,50 +3,56 @@
 # 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
+from usearch.index import MetricKind, ScalarKind, MetricSignature, CompiledMetric
 
 
-signature_f16args = types.float32(types.CPointer(
-    types.float16), types.CPointer(types.float16))
+signature_i8args = types.float32(types.CPointer(types.int8), types.CPointer(types.int8))
 
-signature_f32args = types.float32(types.CPointer(
-    types.float32), types.CPointer(types.float32))
+signature_f16args = types.float32(
+    types.CPointer(types.float16), types.CPointer(types.float16)
+)
 
-signature_f64args = types.float32(types.CPointer(
-    types.float64), types.CPointer(types.float64))
+signature_f32args = types.float32(
+    types.CPointer(types.float32), types.CPointer(types.float32)
+)
 
+signature_f64args = types.float32(
+    types.CPointer(types.float64), types.CPointer(types.float64)
+)
 
-def jit(ndim: int,
-        metric: MetricKind = MetricKind.Cos,
-        dtype: np.generic = np.float32) -> 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
     """
-    normalize_dtype = {
+    assert isinstance(metric, MetricKind)
+    assert isinstance(dtype, ScalarKind)
+
+    numba_supported_types = (
+        ScalarKind.F8,
         # Half-precision is still unsupported
         # https://github.com/numba/numba/issues/4402
-        # 'f16': np.float16,
-        'f32': np.float32,
-        'f64': np.float64,
-    }
-    if dtype in normalize_dtype.keys():
-        dtype = normalize_dtype[dtype]
-    if dtype not in normalize_dtype.values():
+        # ScalarKind.F16: np.float16,
+        ScalarKind.F32,
+        ScalarKind.F64,
+    )
+    if dtype not in numba_supported_types:
         return None
 
     scalar_kind_to_accumulator_type = {
-        np.float16: types.float32,
-        np.float32: types.float32,
-        np.float64: types.float64,
+        ScalarKind.F8: types.int32,
+        ScalarKind.F16: types.float16,
+        ScalarKind.F32: types.float32,
+        ScalarKind.F64: types.float64,
     }
     accumulator = scalar_kind_to_accumulator_type[dtype]
 
@@ -82,14 +88,14 @@ 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 = {
-        np.float16: signature_f16args,
-        np.float32: signature_f32args,
-        np.float64: signature_f64args,
+        ScalarKind.F8: signature_i8args,
+        ScalarKind.F16: signature_f16args,
+        ScalarKind.F32: signature_f32args,
+        ScalarKind.F64: signature_f64args,
     }
 
     metric_kind_to_function = {
@@ -98,4 +104,12 @@ def jit(ndim: int,
         MetricKind.L2sq: numba_l2sq,
     }
 
-    return cfunc(scalar_kind_to_signature[dtype])(metric_kind_to_function[metric])
+    if dtype == ScalarKind.F8 and metric == MetricKind.IP:
+        metric = MetricKind.Cos
+
+    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/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>
@@ -185,19 +186,33 @@ inline static simsimd_f32_t simsimd_cos_f16x4neon(simsimd_f16_t const* a, simsim
 
 inline static simsimd_f32_t simsimd_cos_i8x16neon(int8_t const* a, int8_t const* b, size_t d) {
 #if defined(__ARM_NEON)
-    int8x16_t const* a8x16 = reinterpret_cast<int8x16_t const*>(a);
-    int8x16_t const* b8x16 = reinterpret_cast<int8x16_t const*>(b);
-
     int32x4_t ab_vec = vdupq_n_s32(0);
     int32x4_t a2_vec = vdupq_n_s32(0);
     int32x4_t b2_vec = vdupq_n_s32(0);
-    for (size_t i = 0; i != d / 16; ++i) {
-        int8x16_t a_vec = a8x16[i];
-        int8x16_t b_vec = b8x16[i];
+
+#if 0 // This 128-bit `vdot_s32` intrinsic is often unavailable, so we use the 64-bit `vdot_s32`.
+    for (size_t i = 0; i != d; i += 16) {
+        int8x16_t a_vec = vld1q_s8(a + i);
+        int8x16_t b_vec = vld1q_s8(b + i);
         ab_vec = vdotq_s32(ab_vec, a_vec, b_vec);
         a2_vec = vdotq_s32(a2_vec, a_vec, a_vec);
         b2_vec = vdotq_s32(b2_vec, b_vec, b_vec);
     }
+#else
+    for (size_t i = 0; i != d; i += 8) {
+        int16x8_t a_vec = vmovl_s8(vld1_s8(a + i));
+        int16x8_t b_vec = vmovl_s8(vld1_s8(b + i));
+        int16x8_t ab_part_vec = vmulq_s16(a_vec, b_vec);
+        int16x8_t a2_part_vec = vmulq_s16(a_vec, a_vec);
+        int16x8_t b2_part_vec = vmulq_s16(b_vec, b_vec);
+        ab_vec =
+            vaddq_s32(ab_vec, vaddq_s32(vmovl_s16(vget_high_s16(ab_part_vec)), vmovl_s16(vget_low_s16(ab_part_vec))));
+        a2_vec =
+            vaddq_s32(a2_vec, vaddq_s32(vmovl_s16(vget_high_s16(a2_part_vec)), vmovl_s16(vget_low_s16(a2_part_vec))));
+        b2_vec =
+            vaddq_s32(b2_vec, vaddq_s32(vmovl_s16(vget_high_s16(b2_part_vec)), vmovl_s16(vget_low_s16(b2_part_vec))));
+    }
+#endif
 
     int32x2_t ab_part = vadd_s32(vget_high_s32(ab_vec), vget_low_s32(ab_vec));
     int32_t ab = vget_lane_s32(vpadd_s32(ab_part, ab_part), 0);