usearch 2.8.7 → 2.8.8

package/python/usearch/io.py

@@ -1,113 +0,0 @@
-import os
-import struct
-import typing
-
-import numpy as np
-
-
-def numpy_scalar_size(dtype) -> int:
-    return {
-        np.float64: 8,
-        np.int64: 8,
-        np.uint64: 8,
-        np.float32: 4,
-        np.int32: 4,
-        np.uint32: 4,
-        np.float16: 2,
-        np.int16: 2,
-        np.uint16: 2,
-        np.int8: 1,
-        np.uint8: 1,
-    }[dtype]
-
-
-def guess_numpy_dtype_from_filename(filename) -> typing.Optional[type]:
-    if filename.endswith(".fbin"):
-        return np.float32
-    elif filename.endswith(".dbin"):
-        return np.float64
-    elif filename.endswith(".hbin"):
-        return np.float16
-    elif filename.endswith(".ibin"):
-        return np.int32
-    elif filename.endswith(".bbin"):
-        return np.uint8
-    else:
-        return None
-
-
-def load_matrix(
-    filename: str,
-    start_row: int = 0,
-    count_rows: int = None,
-    view: bool = False,
-    dtype: typing.Optional[type] = None,
-) -> typing.Optional[np.ndarray]:
-    """Read *.ibin, *.bbib, *.hbin, *.fbin, *.dbin files with matrices.
-
-    :param filename: path to the matrix file
-    :param start_row: start reading vectors from this index
-    :param count_rows: number of vectors to read. If None, read all vectors
-    :param view: set to `True` to memory-map the file instead of loading to RAM
-
-    :return: parsed matrix
-    :rtype: numpy.ndarray
-    """
-    if dtype is None:
-        dtype = guess_numpy_dtype_from_filename(filename)
-        if dtype is None:
-            raise Exception("Unknown file type")
-    scalar_size = numpy_scalar_size(dtype)
-
-    if not os.path.exists(filename):
-        return None
-
-    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),
-            )
-        else:
-            return np.fromfile(
-                f,
-                count=rows * cols,
-                dtype=dtype,
-                offset=row_offset,
-            ).reshape(rows, cols)
-
-
-def save_matrix(vectors: np.ndarray, filename: str):
-    """Write *.ibin, *.bbib, *.hbin, *.fbin, *.dbin files with matrices.
-
-    :param vectors: the matrix to serialize
-    :type vectors: numpy.ndarray
-    :param filename: path to the matrix file
-    :type filename: str
-    """
-    if filename.endswith(".fbin"):
-        dtype = np.float32
-    elif filename.endswith(".dbin"):
-        dtype = np.float64
-    elif filename.endswith(".hbin"):
-        dtype = np.float16
-    elif filename.endswith(".ibin"):
-        dtype = np.int32
-    elif filename.endswith(".bbin"):
-        dtype = np.uint8
-    else:
-        dtype = vectors.dtype
-
-    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))
-        vectors.astype(dtype).flatten().tofile(f)

package/python/usearch/numba.py

@@ -1,121 +0,0 @@
-# The purpose of this file is to provide Pythonic wrapper on top
-# the native precompiled CPython module. It improves compatibility
-# Python tooling, linters, and static analyzers. It also embeds JIT
-# into the primary `Index` class, connecting USearch with Numba.
-from math import sqrt
-
-from usearch.index import MetricKind, ScalarKind, MetricSignature, CompiledMetric
-
-
-def jit(
-    ndim: int,
-    metric: MetricKind = MetricKind.Cos,
-    dtype: ScalarKind = ScalarKind.F32,
-) -> CompiledMetric:
-    """JIT-compiles the metric for target hardware and number of dimensions.
-
-    This can result in up-to 3x performance difference on very large vectors
-    and very recent hardware, as the Python module is compiled with high
-    compatibility in mind and avoids very fancy assembly instructions.
-
-    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
-    """
-    assert isinstance(metric, MetricKind)
-    assert isinstance(dtype, ScalarKind)
-
-    from numba import cfunc, types, carray
-
-    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_f32args = types.float32(
-        types.CPointer(types.float32), types.CPointer(types.float32)
-    )
-
-    signature_f64args = types.float32(
-        types.CPointer(types.float64), types.CPointer(types.float64)
-    )
-
-    numba_supported_types = (
-        ScalarKind.I8,
-        # Half-precision is still unsupported
-        # https://github.com/numba/numba/issues/4402
-        # ScalarKind.F16: np.float16,
-        ScalarKind.F32,
-        ScalarKind.F64,
-    )
-    if dtype not in numba_supported_types:
-        return metric
-
-    scalar_kind_to_accumulator_type = {
-        ScalarKind.I8: types.int32,
-        ScalarKind.F16: types.float16,
-        ScalarKind.F32: types.float32,
-        ScalarKind.F64: types.float64,
-    }
-    accumulator = scalar_kind_to_accumulator_type[dtype]
-
-    def numba_ip(a, b):
-        a_array = carray(a, ndim)
-        b_array = carray(b, ndim)
-        ab = accumulator(0)
-        for i in range(ndim):
-            ab += a_array[i] * b_array[i]
-        return types.float32(1 - ab)
-
-    def numba_cos(a, b):
-        a_array = carray(a, ndim)
-        b_array = carray(b, ndim)
-        ab = accumulator(0)
-        a_sq = accumulator(0)
-        b_sq = accumulator(0)
-        for i in range(ndim):
-            ab += a_array[i] * b_array[i]
-            a_sq += a_array[i] * a_array[i]
-            b_sq += b_array[i] * b_array[i]
-        a_norm = sqrt(a_sq)
-        b_norm = sqrt(b_sq)
-        if a_norm == 0 and b_norm == 0:
-            return types.float32(0)
-        elif a_norm == 0 or b_norm == 0 or ab == 0:
-            return types.float32(1)
-        else:
-            return types.float32(1 - ab / (a_norm * b_norm))
-
-    def numba_l2sq(a, b):
-        a_array = carray(a, ndim)
-        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])
-        return types.float32(ab_delta_sq)
-
-    scalar_kind_to_signature = {
-        ScalarKind.I8: signature_i8args,
-        ScalarKind.F16: signature_f16args,
-        ScalarKind.F32: signature_f32args,
-        ScalarKind.F64: signature_f64args,
-    }
-
-    metric_kind_to_function = {
-        MetricKind.IP: numba_ip,
-        MetricKind.Cos: numba_cos,
-        MetricKind.L2sq: numba_l2sq,
-    }
-
-    if dtype == ScalarKind.I8 and metric == MetricKind.IP:
-        metric = MetricKind.Cos
-
-    pointer = cfunc(scalar_kind_to_signature[dtype])(metric_kind_to_function[metric])
-    return CompiledMetric(
-        pointer=pointer.address,
-        kind=metric,
-        signature=MetricSignature.ArrayArray,
-    )

package/python/usearch/server.py

@@ -1,137 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-import os
-import argparse
-import numpy as np
-from typing import List
-
-from ucall.rich_posix import Server
-from usearch.index import Index, Matches, Key
-
-
-def _ascii_to_vector(string: str) -> np.ndarray:
-    """
-    WARNING: A dirty performance hack!
-    Assuming the `i8` vectors in our implementations are just integers,
-    and generally contain scalars in the [0, 100] range, we can transmit
-    them as JSON-embedded strings. The only symbols we must avoid are
-    the double-quote '"' (code 22) and backslash '\' (code 60).
-    Printable ASCII characters are in [20, 126].
-    """
-    vector = np.array(string, dtype=np.int8)
-    vector[vector == 124] = 60
-    vector -= 23
-    return vector
-
-
-def serve(
-    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)
-
-    if os.path.exists(path):
-        if immutable:
-            index.view(path)
-        else:
-            index.load(path)
-
-    @server
-    def size() -> int:
-        return len(index)
-
-    @server
-    def ndim() -> int:
-        return index.ndim
-
-    @server
-    def capacity() -> int:
-        return index.capacity()
-
-    @server
-    def connectivity() -> int:
-        return index.connectivity()
-
-    @server
-    def add_one(key: int, vector: np.ndarray):
-        print("adding", key, vector)
-        keys = np.array([key], dtype=Key)
-        vectors = vector.flatten().reshape(vector.shape[0], 1)
-        index.add(keys, vectors)
-
-    @server
-    def add_many(keys: np.ndarray, vectors: np.ndarray):
-        index.add(keys, vectors, threads=threads)
-
-    @server
-    def search_one(vector: np.ndarray, count: int) -> List[dict]:
-        print("search", vector, count)
-        vectors = vector.reshape(vector.shape[0], 1)
-        results: Matches = index.search(vectors, count)
-        return results.to_list()
-
-    @server
-    def search_many(vectors: np.ndarray, count: int) -> List[List[dict]]:
-        results: Matches = index.search(vectors, count)
-        return results.to_list()
-
-    @server
-    def add_ascii(key: int, string: str):
-        return add_one(key, _ascii_to_vector(string))
-
-    @server
-    def search_ascii(string: str, count: int):
-        return search_one(_ascii_to_vector(string), count)
-
-    try:
-        server.run()
-    except KeyboardInterrupt:
-        if not immutable:
-            index.save(path)
-
-
-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(
-        "--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",
-    )
-    parser.add_argument(
-        "-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"
-    )
-    parser.add_argument(
-        "--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!"
-    serve(
-        ndim_=args.ndim,
-        metric=args.metric,
-        threads=args.threads,
-        port=args.port,
-        path=args.path,
-        immutable=args.immutable,
-    )

package/rust/README.md

@@ -1,66 +0,0 @@
-# USearch for Rust
-
-## Installation
-
-```sh
-cargo add usearch
-```
-
-You can find [interface documentation on docs.rs](https://docs.rs/usearch/2.3.0/usearch/ffi/struct.Index.html).
-
-## Quickstart
-
-```rust
-
-let options = IndexOptions {
-    dimensions: 3,
-    metric: MetricKind::IP,
-    quantization: ScalarKind::F16,
-    connectivity: 0,
-    expansion_add: 0,
-    expansion_search: 0
-};
-
-let index = new_index(&options).unwrap();
-
-assert!(index.reserve(10).is_ok());
-assert!(index.capacity() >= 10);
-assert!(index.connectivity() != 0);
-assert_eq!(index.dimensions(), 3);
-assert_eq!(index.size(), 0);
-
-let first: [f32; 3] = [0.2, 0.1, 0.2];
-let second: [f32; 3] = [0.2, 0.1, 0.2];
-
-assert!(index.add(42, &first).is_ok());
-assert!(index.add(43, &second).is_ok());
-assert_eq!(index.size(), 2);
-
-// Read back the tags
-let results = index.search(&first, 10).unwrap();
-assert_eq!(results.keys.len(), 2);
-```
-
-## Serialization
-
-```rust
-assert!(index.save("index.usearch").is_ok());
-assert!(index.load("index.usearch").is_ok());
-assert!(index.view("index.usearch").is_ok());
-```
-
-Similarly, serializing to/from buffers is supported.
-
-```rust
-assert!(index.save_to_buffer(&mut serialization_buffer).is_ok());
-assert!(index.load_from_buffer(&serialization_buffer).is_ok());
-assert!(index.view_from_buffer(&serialization_buffer).is_ok());
-```
-
-## Metrics
-
-```rust
-assert!(new_l2sq(3, &quant, 0, 0, 0).is_ok());
-assert!(new_cos(3, &quant, 0, 0, 0).is_ok());
-assert!(new_haversine(&quant, 0, 0, 0).is_ok());
-```

package/rust/lib.cpp

@@ -1,136 +0,0 @@
-#include "lib.hpp"
-#include "usearch/rust/lib.rs.h"
-
-using namespace unum::usearch;
-using namespace unum;
-
-using index_t = index_dense_t;
-using add_result_t = typename index_t::add_result_t;
-using search_result_t = typename index_t::search_result_t;
-using labeling_result_t = typename index_t::labeling_result_t;
-using vector_key_t = typename index_dense_t::vector_key_t;
-
-template <typename scalar_at> Matches search_(index_dense_t& index, scalar_at const* vec, size_t count) {
-    Matches matches;
-    matches.keys.reserve(count);
-    matches.distances.reserve(count);
-    for (size_t i = 0; i != count; ++i)
-        matches.keys.push_back(0), matches.distances.push_back(0);
-    search_result_t result = index.search(vec, count);
-    result.error.raise();
-    count = result.dump_to(matches.keys.data(), matches.distances.data());
-    matches.keys.truncate(count);
-    matches.distances.truncate(count);
-    return matches;
-}
-
-NativeIndex::NativeIndex(std::unique_ptr<index_t> index) : index_(std::move(index)) {}
-
-// clang-format off
-void NativeIndex::add_i8(vector_key_t key, rust::Slice<int8_t const> vec) const { index_->add(key, vec.data()).error.raise(); }
-void NativeIndex::add_f16(vector_key_t key, rust::Slice<uint16_t const> vec) const { index_->add(key, (f16_t const*)vec.data()).error.raise(); }
-void NativeIndex::add_f32(vector_key_t key, rust::Slice<float const> vec) const { index_->add(key, vec.data()).error.raise(); }
-void NativeIndex::add_f64(vector_key_t key, rust::Slice<double const> vec) const { index_->add(key, vec.data()).error.raise(); }
-
-Matches NativeIndex::search_i8(rust::Slice<int8_t const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-Matches NativeIndex::search_f16(rust::Slice<uint16_t const> vec, size_t count) const { return search_(*index_, (f16_t const*)vec.data(), count); }
-Matches NativeIndex::search_f32(rust::Slice<float const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-Matches NativeIndex::search_f64(rust::Slice<double const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-
-size_t NativeIndex::get_i8(vector_key_t key, rust::Slice<int8_t> vec) const { if (vec.size() % dimensions()) throw std::invalid_argument("Vector length must be a multiple of index dimensionality"); return index_->get(key, vec.data(), vec.size() / dimensions()); }
-size_t NativeIndex::get_f16(vector_key_t key, rust::Slice<uint16_t> vec) const { if (vec.size() % dimensions()) throw std::invalid_argument("Vector length must be a multiple of index dimensionality"); return index_->get(key, (f16_t*)vec.data(), vec.size() / dimensions()); }
-size_t NativeIndex::get_f32(vector_key_t key, rust::Slice<float> vec) const { if (vec.size() % dimensions()) throw std::invalid_argument("Vector length must be a multiple of index dimensionality"); return index_->get(key, vec.data(), vec.size() / dimensions()); }
-size_t NativeIndex::get_f64(vector_key_t key, rust::Slice<double> vec) const { if (vec.size() % dimensions()) throw std::invalid_argument("Vector length must be a multiple of index dimensionality"); return index_->get(key, vec.data(), vec.size() / dimensions()); }
-// clang-format on
-
-size_t NativeIndex::expansion_add() const { return index_->expansion_add(); }
-size_t NativeIndex::expansion_search() const { return index_->expansion_search(); }
-void NativeIndex::change_expansion_add(size_t n) const { index_->change_expansion_add(n); }
-void NativeIndex::change_expansion_search(size_t n) const { index_->change_expansion_search(n); }
-
-size_t NativeIndex::remove(vector_key_t key) const {
-    labeling_result_t result = index_->remove(key);
-    result.error.raise();
-    return result.completed;
-}
-
-size_t NativeIndex::rename(vector_key_t from, vector_key_t to) const {
-    labeling_result_t result = index_->rename(from, to);
-    result.error.raise();
-    return result.completed;
-}
-
-size_t NativeIndex::count(vector_key_t key) const { return index_->count(key); }
-bool NativeIndex::contains(vector_key_t key) const { return index_->contains(key); }
-
-void NativeIndex::reserve(size_t capacity) const { index_->reserve(capacity); }
-
-size_t NativeIndex::dimensions() const { return index_->dimensions(); }
-size_t NativeIndex::connectivity() const { return index_->connectivity(); }
-size_t NativeIndex::size() const { return index_->size(); }
-size_t NativeIndex::capacity() const { return index_->capacity(); }
-size_t NativeIndex::serialized_length() const { return index_->serialized_length(); }
-
-void NativeIndex::save(rust::Str path) const { index_->save(output_file_t(std::string(path).c_str())).error.raise(); }
-void NativeIndex::load(rust::Str path) const { index_->load(input_file_t(std::string(path).c_str())).error.raise(); }
-void NativeIndex::view(rust::Str path) const {
-    index_->view(memory_mapped_file_t(std::string(path).c_str())).error.raise();
-}
-
-void NativeIndex::reset() const { index_->reset(); }
-size_t NativeIndex::memory_usage() const { return index_->memory_usage(); }
-
-void NativeIndex::save_to_buffer(rust::Slice<uint8_t> buffer) const {
-    index_->save(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
-}
-
-void NativeIndex::load_from_buffer(rust::Slice<uint8_t const> buffer) const {
-    index_->load(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
-}
-
-void NativeIndex::view_from_buffer(rust::Slice<uint8_t const> buffer) const {
-    index_->view(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
-}
-
-std::unique_ptr<NativeIndex> wrap(index_t&& index) {
-    std::unique_ptr<index_t> punned_ptr;
-    punned_ptr.reset(new index_t(std::move(index)));
-    std::unique_ptr<NativeIndex> result;
-    result.reset(new NativeIndex(std::move(punned_ptr)));
-    return result;
-}
-
-metric_kind_t rust_to_cpp_metric(MetricKind value) {
-    switch (value) {
-    case MetricKind::IP: return metric_kind_t::ip_k;
-    case MetricKind::L2sq: return metric_kind_t::l2sq_k;
-    case MetricKind::Cos: return metric_kind_t::cos_k;
-    case MetricKind::Pearson: return metric_kind_t::pearson_k;
-    case MetricKind::Haversine: return metric_kind_t::haversine_k;
-    case MetricKind::Divergence: return metric_kind_t::divergence_k;
-    case MetricKind::Hamming: return metric_kind_t::hamming_k;
-    case MetricKind::Tanimoto: return metric_kind_t::tanimoto_k;
-    case MetricKind::Sorensen: return metric_kind_t::sorensen_k;
-    default: return metric_kind_t::unknown_k;
-    }
-}
-
-scalar_kind_t rust_to_cpp_scalar(ScalarKind value) {
-    switch (value) {
-    case ScalarKind::I8: return scalar_kind_t::i8_k;
-    case ScalarKind::F16: return scalar_kind_t::f16_k;
-    case ScalarKind::F32: return scalar_kind_t::f32_k;
-    case ScalarKind::F64: return scalar_kind_t::f64_k;
-    case ScalarKind::B1: return scalar_kind_t::b1x8_k;
-    default: return scalar_kind_t::unknown_k;
-    }
-}
-
-std::unique_ptr<NativeIndex> new_native_index(IndexOptions const& options) {
-    metric_kind_t metric_kind = rust_to_cpp_metric(options.metric);
-    scalar_kind_t scalar_kind = rust_to_cpp_scalar(options.quantization);
-    metric_punned_t metric(options.dimensions, metric_kind, scalar_kind);
-    index_dense_config_t config(options.connectivity, options.expansion_add, options.expansion_search);
-    config.multi = options.multi;
-    return wrap(index_t::make(metric, config));
-}

package/rust/lib.hpp

@@ -1,69 +0,0 @@
-#pragma once
-#include "rust/cxx.h"
-
-#include <memory> // `std::shared_ptr`
-
-#include <usearch/index_dense.hpp>
-
-struct Matches;
-struct IndexOptions;
-
-class NativeIndex {
-  public:
-    using metric_t = unum::usearch::metric_punned_t;
-    using distance_t = unum::usearch::distance_punned_t;
-    using index_dense_t = unum::usearch::index_dense_t;
-    using add_result_t = typename index_dense_t::add_result_t;
-    using search_result_t = typename index_dense_t::search_result_t;
-    using vector_key_t = typename index_dense_t::vector_key_t;
-
-    NativeIndex(std::unique_ptr<index_dense_t> index);
-
-    void reserve(size_t) const;
-
-    void add_i8(vector_key_t key, rust::Slice<int8_t const> vector) const;
-    void add_f16(vector_key_t key, rust::Slice<uint16_t const> vector) const;
-    void add_f32(vector_key_t key, rust::Slice<float const> vector) const;
-    void add_f64(vector_key_t key, rust::Slice<double const> vector) const;
-
-    Matches search_i8(rust::Slice<int8_t const> vector, size_t count) const;
-    Matches search_f16(rust::Slice<uint16_t const> vector, size_t count) const;
-    Matches search_f32(rust::Slice<float const> vector, size_t count) const;
-    Matches search_f64(rust::Slice<double const> vector, size_t count) const;
-
-    size_t get_i8(vector_key_t key, rust::Slice<int8_t> vector) const;
-    size_t get_f16(vector_key_t key, rust::Slice<uint16_t> vector) const;
-    size_t get_f32(vector_key_t key, rust::Slice<float> vector) const;
-    size_t get_f64(vector_key_t key, rust::Slice<double> vector) const;
-
-    size_t expansion_add() const;
-    size_t expansion_search() const;
-    void change_expansion_add(size_t n) const;
-    void change_expansion_search(size_t n) const;
-
-    size_t count(vector_key_t key) const;
-    size_t remove(vector_key_t key) const;
-    size_t rename(vector_key_t from, vector_key_t to) const;
-    bool contains(vector_key_t key) const;
-
-    size_t dimensions() const;
-    size_t connectivity() const;
-    size_t size() const;
-    size_t capacity() const;
-    size_t serialized_length() const;
-
-    void save(rust::Str path) const;
-    void load(rust::Str path) const;
-    void view(rust::Str path) const;
-    void reset() const;
-    size_t memory_usage() const;
-
-    void save_to_buffer(rust::Slice<uint8_t> buffer) const;
-    void load_from_buffer(rust::Slice<uint8_t const> buffer) const;
-    void view_from_buffer(rust::Slice<uint8_t const> buffer) const;
-
-  private:
-    std::unique_ptr<index_dense_t> index_;
-};
-
-std::unique_ptr<NativeIndex> new_native_index(IndexOptions const& options);