usearch 0.18.2 → 0.18.3

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.18.2"
+version = "0.18.3"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '0.18.2'
+    version = '0.18.3'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/include/usearch/index.hpp

@@ -15,34 +15,38 @@
 
 // Inferring C++ version
 #if ((defined(_MSVC_LANG) && _MSVC_LANG >= 201703L) || __cplusplus >= 201703L)
-#define USEARCH_IS_CPP17
+#define USEARCH_DEFINED_CPP17
 #endif
 
 // Inferring target OS
 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__)
-#define USEARCH_IS_WINDOWS
+#define USEARCH_DEFINED_WINDOWS
 #elif defined(__APPLE__) && defined(__MACH__)
-#define USEARCH_IS_APPLE
+#define USEARCH_DEFINED_APPLE
 #elif defined(__linux__)
-#define USEARCH_IS_LINUX
+#define USEARCH_DEFINED_LINUX
 #endif
 
 // Inferring the compiler
 #if defined(__clang__)
-#define USEARCH_IS_CLANG
+#define USEARCH_DEFINED_CLANG
 #elif defined(__GNUC__)
-#define USEARCH_IS_GCC
+#define USEARCH_DEFINED_GCC
 #endif
 
 // Inferring hardware architecture: x86 vs Arm
 #if defined(__x86_64__)
-#define USEARCH_IS_X86
+#define USEARCH_DEFINED_X86
 #elif defined(__aarch64__)
-#define USEARCH_IS_ARM
+#define USEARCH_DEFINED_ARM
+#endif
+
+#if !defined(USEARCH_USE_OPENMP)
+#define USEARCH_USE_OPENMP 0
 #endif
 
 // OS-specific includes
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 #define _USE_MATH_DEFINES
 #include <Windows.h>
 #include <sys/stat.h> // `fstat` for file size
@@ -69,20 +73,20 @@
 #include <utility>   // `std::pair`
 
 // Prefetching
-#if defined(USEARCH_IS_GCC)
+#if defined(USEARCH_DEFINED_GCC)
 // https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
 // Zero means we are only going to read from that memory.
 // Three means high temporal locality and suggests to keep
 // the data in all layers of cache.
 #define prefetch_m(ptr) __builtin_prefetch((void*)(ptr), 0, 3)
-#elif defined(USEARCH_IS_X86)
+#elif defined(USEARCH_DEFINED_X86)
 #define prefetch_m(ptr) _mm_prefetch((void*)(ptr), _MM_HINT_T0)
 #else
 #define prefetch_m(ptr)
 #endif
 
 // Alignment
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 #define usearch_pack_m
 #define usearch_align_m __declspec(align(64))
 #else
@@ -225,11 +229,11 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct ip_
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim) const noexcept {
         result_type ab{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : ab)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i)
@@ -254,11 +258,11 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct cos
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim) const noexcept {
         result_t ab{}, a2{}, b2{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : ab, a2, b2)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i)
@@ -283,11 +287,11 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct l2s
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim) const noexcept {
         result_t ab_deltas_sq{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : ab_deltas_sq)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i)
@@ -313,11 +317,11 @@ template <typename scalar_at = std::uint64_t, typename result_at = std::size_t>
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t words) const noexcept {
         constexpr std::size_t bits_per_word_k = sizeof(scalar_t) * CHAR_BIT;
         result_t matches{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : matches)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != words; ++i)
@@ -344,11 +348,11 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
         constexpr std::size_t bits_per_word_k = sizeof(scalar_t) * CHAR_BIT;
         result_t and_count{};
         result_t or_count{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : and_count, or_count)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != words; ++i)
@@ -376,11 +380,11 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
         constexpr std::size_t bits_per_word_k = sizeof(scalar_t) * CHAR_BIT;
         result_t and_count{};
         result_t any_count{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : and_count, any_count)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != words; ++i)
@@ -437,11 +441,11 @@ template <typename scalar_at = float, typename result_at = float> struct pearson
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim) const noexcept {
         result_t a_sum{}, b_sum{}, ab_sum{};
         result_t a_sq_sum{}, b_sq_sum{};
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : a_sum, b_sum, ab_sum, a_sq_sum, b_sq_sum)
-#elif defined(USEARCH_IS_CLANG)
+#elif defined(USEARCH_DEFINED_CLANG)
 #pragma clang loop vectorize(enable)
-#elif defined(USEARCH_IS_GCC)
+#elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i) {
@@ -603,7 +607,7 @@ template <typename allocator_at = std::allocator<char>> class visits_bitset_gt {
     inline bool test(std::size_t i) const noexcept { return slots_[i / bits_per_slot()] & (1ul << (i & bits_mask())); }
     inline void set(std::size_t i) noexcept { slots_[i / bits_per_slot()] |= (1ul << (i & bits_mask())); }
 
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 
     inline bool atomic_set(std::size_t i) noexcept {
         slot_t mask{1ul << (i & bits_mask())};
@@ -890,7 +894,7 @@ class sorted_buffer_gt {
     static bool less(element_t const& a, element_t const& b) noexcept { return comparator_t{}(a, b); }
 };
 
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 #pragma pack(push, 1) // Pack struct elements on 1-byte alignment
 #endif
 
@@ -904,7 +908,7 @@ class usearch_pack_m uint40_t {
     inline uint40_t() noexcept { std::memset(octets, 0, 5); }
     inline uint40_t(std::uint32_t n) noexcept { std::memcpy(octets + 1, (char*)&n, 4), octets[0] = 0; }
     inline uint40_t(std::uint64_t n) noexcept { std::memcpy(octets, (char*)&n + 3, 5); }
-#if defined(USEARCH_IS_CLANG) && defined(USEARCH_IS_APPLE)
+#if defined(USEARCH_DEFINED_CLANG) && defined(USEARCH_DEFINED_APPLE)
     inline uint40_t(std::size_t n) noexcept { std::memcpy(octets, (char*)&n + 3, 5); }
 #endif
 
@@ -935,7 +939,7 @@ class usearch_pack_m uint40_t {
     }
 };
 
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
 #pragma pack(pop) // Reset alignment to default
 #endif
 
@@ -1093,7 +1097,7 @@ static_assert(sizeof(file_header_t) == 64, "File header should be exactly 64 byt
 /// @brief  C++17 and newer version deprecate the `std::result_of`
 template <typename metric_at, typename... args_at>
 using return_type_gt =
-#if defined(USEARCH_IS_CPP17)
+#if defined(USEARCH_DEFINED_CPP17)
     typename std::invoke_result<metric_at, args_at...>::type;
 #else
     typename std::result_of<metric_at(args_at...)>::type;
@@ -2034,7 +2038,7 @@ class index_gt {
      */
     serialization_result_t view(char const* file_path) noexcept {
         serialization_result_t result;
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
         return result.failed("Memory-mapping is not yet available for Windows");
 #else
         int open_flags = O_RDONLY;

package/include/usearch/index_punned_dense.hpp

@@ -7,16 +7,11 @@
 #include <thread>       // `std::thread`
 #include <vector>       // `std::vector`
 
-#include <fp16/fp16.h>
-#include <tsl/robin_map.h>
-
-#if defined(USEARCH_USE_SIMSIMD)
-#include <simsimd/simsimd.h>
-#endif
-
 #include <usearch/index.hpp>
 #include <usearch/index_punned_helpers.hpp>
 
+#include <tsl/robin_map.h>
+
 namespace unum {
 namespace usearch {
 
@@ -27,6 +22,13 @@ struct cos_f8_t {
     inline cos_f8_t(std::size_t dims) noexcept : dimensions(dims) {}
     inline punned_distance_t operator()(f8_bits_t const* a, f8_bits_t const* b) const noexcept {
         std::int32_t ab{}, a2{}, b2{};
+#if USEARCH_USE_OPENMP
+#pragma omp simd reduction(+ : ab, a2, b2)
+#elif defined(USEARCH_DEFINED_CLANG)
+#pragma clang loop vectorize(enable)
+#elif defined(USEARCH_DEFINED_GCC)
+#pragma GCC ivdep
+#endif
         for (std::size_t i = 0; i != dimensions; i++) {
             std::int16_t ai{a[i]};
             std::int16_t bi{b[i]};
@@ -45,6 +47,13 @@ struct l2sq_f8_t {
     inline l2sq_f8_t(std::size_t dims) noexcept : dimensions(dims) {}
     inline punned_distance_t operator()(f8_bits_t const* a, f8_bits_t const* b) const noexcept {
         std::int32_t ab_deltas_sq{};
+#if USEARCH_USE_OPENMP
+#pragma omp simd reduction(+ : ab_deltas_sq)
+#elif defined(USEARCH_DEFINED_CLANG)
+#pragma clang loop vectorize(enable)
+#elif defined(USEARCH_DEFINED_GCC)
+#pragma GCC ivdep
+#endif
         for (std::size_t i = 0; i != dimensions; i++)
             ab_deltas_sq += square(std::int16_t(a[i]) - std::int16_t(b[i]));
         return ab_deltas_sq;
@@ -495,8 +504,8 @@ class index_punned_dense_gt {
 
     static metric_and_meta_t ip_metric_f32_(std::size_t dimensions) {
         (void)dimensions;
-#if defined(USEARCH_USE_SIMSIMD)
-#if defined(USEARCH_IS_X86)
+#if USEARCH_USE_SIMSIMD
+#if defined(USEARCH_DEFINED_X86)
         if (dimensions % 4 == 0)
             return {
                 pun_metric_<simsimd_f32_t>([=](simsimd_f32_t const* a, simsimd_f32_t const* b) {
@@ -504,7 +513,7 @@ class index_punned_dense_gt {
                 }),
                 isa_t::avx2_k,
             };
-#elif defined(USEARCH_IS_ARM)
+#elif defined(USEARCH_DEFINED_ARM)
         if (supports_arm_sve())
             return {
                 pun_metric_<simsimd_f32_t>([=](simsimd_f32_t const* a, simsimd_f32_t const* b) {
@@ -526,8 +535,8 @@ class index_punned_dense_gt {
 
     static metric_and_meta_t cos_metric_f16_(std::size_t dimensions) {
         (void)dimensions;
-#if defined(USEARCH_USE_SIMSIMD)
-#if defined(USEARCH_IS_X86)
+#if USEARCH_USE_SIMSIMD
+#if defined(USEARCH_DEFINED_X86)
         if (dimensions % 16 == 0)
             return {
                 pun_metric_<simsimd_f16_t>([=](simsimd_f16_t const* a, simsimd_f16_t const* b) {
@@ -535,7 +544,7 @@ class index_punned_dense_gt {
                 }),
                 isa_t::avx512_k,
             };
-#elif defined(USEARCH_IS_ARM)
+#elif defined(USEARCH_DEFINED_ARM)
         if (dimensions % 4 == 0)
             return {
                 pun_metric_<simsimd_f16_t>([=](simsimd_f16_t const* a, simsimd_f16_t const* b) {
@@ -550,8 +559,8 @@ class index_punned_dense_gt {
 
     static metric_and_meta_t cos_metric_f8_(std::size_t dimensions) {
         (void)dimensions;
-#if defined(USEARCH_USE_SIMSIMD)
-#if defined(USEARCH_IS_ARM)
+#if USEARCH_USE_SIMSIMD
+#if defined(USEARCH_DEFINED_ARM)
         if (dimensions % 16 == 0)
             return {
                 pun_metric_<int8_t>(

package/include/usearch/index_punned_helpers.hpp

@@ -6,21 +6,41 @@
 #include <thread>  // `std::thread`
 #include <vector>  // `std::vector`
 
-#include <fp16/fp16.h>
+#include <usearch/index.hpp> // `expected_gt` and macros
 
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 #include <omp.h> // `omp_get_num_threads()`
 #endif
 
-#if defined(USEARCH_IS_LINUX)
+#if defined(USEARCH_DEFINED_LINUX)
 #include <sys/auxv.h> // `getauxval()`
 #endif
 
-#if defined(USEARCH_IS_ARM)
+#if defined(USEARCH_DEFINED_ARM)
 #include <arm_fp16.h> // `__fp16`
 #endif
 
-#include <usearch/index.hpp> // `expected_gt`
+#if !defined(USEARCH_USE_NATIVE_F16)
+#if defined(__AVX512F__)
+#define USEARCH_USE_NATIVE_F16 1
+#elif defined(USEARCH_DEFINED_ARM)
+#define USEARCH_USE_NATIVE_F16 1
+#else
+#define USEARCH_USE_NATIVE_F16 0
+#include <fp16/fp16.h>
+#endif
+#else
+#define USEARCH_USE_NATIVE_F16 0
+#include <fp16/fp16.h>
+#endif
+
+#if !defined(USEARCH_USE_SIMSIMD)
+#define USEARCH_USE_SIMSIMD 0
+#endif
+
+#if USEARCH_USE_SIMSIMD
+#include <simsimd/simsimd.h>
+#endif
 
 namespace unum {
 namespace usearch {
@@ -57,8 +77,8 @@ inline char const* isa_name(isa_t isa) noexcept {
 }
 
 inline bool supports_arm_sve() noexcept {
-#if defined(USEARCH_IS_ARM)
-#if defined(USEARCH_IS_LINUX)
+#if defined(USEARCH_DEFINED_ARM)
+#if defined(USEARCH_DEFINED_LINUX)
     unsigned long capabilities = getauxval(AT_HWCAP);
     if (capabilities & HWCAP_SVE)
         return true;
@@ -161,26 +181,16 @@ using punned_metric_t = std::function<punned_distance_t(punned_vector_view_t, pu
 class f8_bits_t;
 class f16_bits_t;
 
-// using f16_native_t = __bf16;
-
-#if defined(__AVX512F__)
-#define USEARCH_F16_NATIVE_SUPPORT 1
+#if USEARCH_USE_NATIVE_F16
 using f16_native_t = _Float16;
-#elif defined(USEARCH_IS_ARM)
-#define USEARCH_F16_NATIVE_SUPPORT 1
-using f16_native_t = __fp16;
-#else
-using f16_native_t = void;
-#endif
-
-#if defined(USEARCH_F16_NATIVE_SUPPORT)
 using f16_t = f16_native_t;
 #else
+using f16_native_t = void;
 using f16_t = f16_bits_t;
 #endif
 
 inline float f16_to_f32(std::uint16_t u16) noexcept {
-#if defined(USEARCH_F16_NATIVE_SUPPORT)
+#if USEARCH_USE_NATIVE_F16
     f16_native_t f16;
     std::memcpy(&f16, &u16, sizeof(std::uint16_t));
     return float(f16);
@@ -190,7 +200,7 @@ inline float f16_to_f32(std::uint16_t u16) noexcept {
 }
 
 inline std::uint16_t f32_to_f16(float f32) noexcept {
-#if defined(USEARCH_F16_NATIVE_SUPPORT)
+#if USEARCH_USE_NATIVE_F16
     f16_native_t f16 = f16_native_t(f32);
     std::uint16_t u16;
     std::memcpy(&u16, &f16, sizeof(std::uint16_t));
@@ -316,7 +326,7 @@ class executor_stl_t {
     }
 };
 
-#if defined(USEARCH_USE_OPENMP)
+#if USEARCH_USE_OPENMP
 
 class executor_openmp_t {
   public:
@@ -362,7 +372,7 @@ class aligned_allocator_gt {
         // void* result = nullptr;
         // int status = posix_memalign(&result, alignment, length_bytes);
         // return status == 0 ? (pointer)result : nullptr;
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
         return (pointer)_aligned_malloc(length_bytes, alignment);
 #else
         return (pointer)aligned_alloc(alignment, length_bytes);
@@ -370,7 +380,7 @@ class aligned_allocator_gt {
     }
 
     void deallocate(pointer begin, size_type) const {
-#if defined(USEARCH_IS_WINDOWS)
+#if defined(USEARCH_DEFINED_WINDOWS)
         _aligned_free(begin);
 #else
         free(begin);
@@ -380,7 +390,7 @@ class aligned_allocator_gt {
 
 using aligned_allocator_t = aligned_allocator_gt<>;
 
-#if !defined(USEARCH_IS_WINDOWS)
+#if !defined(USEARCH_DEFINED_WINDOWS)
 
 /**
  *  @brief  Memory-mapping allocator designed for "alloc many, free at once" usage patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.18.2",
+    "version": "0.18.3",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",

package/python/lib.cpp

@@ -533,17 +533,9 @@ PYBIND11_MODULE(compiled, m) {
     m.attr("DEFAULT_EXPANSION_ADD") = py::int_(default_expansion_add());
     m.attr("DEFAULT_EXPANSION_SEARCH") = py::int_(default_expansion_search());
 
-#if defined(USEARCH_USE_OPENMP)
-    m.attr("USES_OPENMP") = py::int_(1);
-#else
-    m.attr("USES_OPENMP") = py::int_(0);
-#endif
-
-#if defined(USEARCH_USE_SIMSIMD)
-    m.attr("USES_SIMSIMD") = py::int_(1);
-#else
-    m.attr("USES_SIMSIMD") = py::int_(0);
-#endif
+    m.attr("USES_OPENMP") = py::int_(USEARCH_USE_OPENMP);
+    m.attr("USES_SIMSIMD") = py::int_(USEARCH_USE_SIMSIMD);
+    m.attr("USES_NATIVE_F16") = py::int_(USEARCH_USE_NATIVE_F16);
 
     py::enum_<metric_kind_t>(m, "MetricKind")
         .value("Unknown", metric_kind_t::unknown_k)

package/python/usearch/index.py

@@ -19,6 +19,7 @@ from usearch.compiled import (
 
     USES_OPENMP,
     USES_SIMSIMD,
+    USES_NATIVE_F16,
 )
 
 MetricKindBitwise = (
@@ -337,6 +338,7 @@ class Index:
             'Expansion@Search': self.expansion_search,
             'OpenMP': USES_OPENMP,
             'SimSIMD': USES_SIMSIMD,
+            'NativeF16': USES_NATIVE_F16,
             'JIT': self.jit,
             'DType': self.dtype,
             'Path': self.path,

package/setup.py

@@ -7,13 +7,16 @@ from pybind11.setup_helpers import Pybind11Extension
 
 compile_args = ['-std=c++11', '-O3']
 link_args = []
-macros_args = []
+macros_args = [
+    ('USEARCH_USE_NATIVE_F16', '0'),
+    ('USEARCH_USE_SIMSIMD', '1'),
+]
 
 if sys.platform == 'linux':
     compile_args.append('-fopenmp')
     link_args.append('-lgomp')
-    macros_args.append(('USEARCH_USE_OPENMP', '1'))
     compile_args.append('-Wno-unknown-pragmas')
+    macros_args.append(('USEARCH_USE_OPENMP', '1'))
 
 if sys.platform == 'darwin':
     # MacOS 10.15 or higher is needed for `aligned_alloc` support.