usearch 0.4.0 → 0.8.0

package/java/cloud/unum/usearch/cloud_unum_usearch_Index.cpp

@@ -4,14 +4,14 @@
 
 #include <thread>
 
-#include "advanced.hpp"
+#include "punned.hpp"
 
 using namespace unum::usearch;
 using namespace unum;
 
 using label_t = jint;
 using distance_t = punned_distance_t;
-using native_index_t = auto_index_gt<label_t>;
+using punned_t = punned_gt<label_t>;
 using span_t = span_gt<float>;
 
 JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1create( //
@@ -39,10 +39,10 @@ JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1create( //
         std::size_t accuracy_length = (*env).GetStringUTFLength(accuracy);
 
         accuracy_t accuracy = accuracy_from_name(accuracy_cstr, accuracy_length);
-        native_index_t index = index_from_name<native_index_t>( //
+        punned_t index = index_from_name<punned_t>( //
             metric_cstr, metric_length, static_cast<std::size_t>(dimensions), accuracy, config);
 
-        native_index_t* result_ptr = new native_index_t(std::move(index));
+        punned_t* result_ptr = new punned_t(std::move(index));
         std::memcpy(&result, &result_ptr, sizeof(jlong));
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
@@ -59,7 +59,7 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1save(JNIEnv* env, jclass
     char const* path_cstr{};
     try {
         path_cstr = (*env).GetStringUTFChars(path, 0);
-        reinterpret_cast<native_index_t*>(c_ptr)->save(path_cstr);
+        reinterpret_cast<punned_t*>(c_ptr)->save(path_cstr);
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
         if (jc)
@@ -72,7 +72,7 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1load(JNIEnv* env, jclass
     char const* path_cstr{};
     try {
         path_cstr = (*env).GetStringUTFChars(path, 0);
-        reinterpret_cast<native_index_t*>(c_ptr)->load(path_cstr);
+        reinterpret_cast<punned_t*>(c_ptr)->load(path_cstr);
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
         if (jc)
@@ -85,7 +85,7 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1view(JNIEnv* env, jclass
     char const* path_cstr{};
     try {
         path_cstr = (*env).GetStringUTFChars(path, 0);
-        reinterpret_cast<native_index_t*>(c_ptr)->view(path_cstr);
+        reinterpret_cast<punned_t*>(c_ptr)->view(path_cstr);
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
         if (jc)
@@ -95,28 +95,28 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1view(JNIEnv* env, jclass
 }
 
 JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1destroy(JNIEnv*, jclass, jlong c_ptr) {
-    delete reinterpret_cast<native_index_t*>(c_ptr);
+    delete reinterpret_cast<punned_t*>(c_ptr);
 }
 
 JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1size(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<native_index_t*>(c_ptr)->size();
+    return reinterpret_cast<punned_t*>(c_ptr)->size();
 }
 
 JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1connectivity(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<native_index_t*>(c_ptr)->connectivity();
+    return reinterpret_cast<punned_t*>(c_ptr)->connectivity();
 }
 
 JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1dimensions(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<native_index_t*>(c_ptr)->dimensions();
+    return reinterpret_cast<punned_t*>(c_ptr)->dimensions();
 }
 
 JNIEXPORT jlong JNICALL Java_cloud_unum_usearch_Index_c_1capacity(JNIEnv*, jclass, jlong c_ptr) {
-    return reinterpret_cast<native_index_t*>(c_ptr)->capacity();
+    return reinterpret_cast<punned_t*>(c_ptr)->capacity();
 }
 
 JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1reserve(JNIEnv* env, jclass, jlong c_ptr, jlong capacity) {
     try {
-        return reinterpret_cast<native_index_t*>(c_ptr)->reserve(static_cast<std::size_t>(capacity));
+        return reinterpret_cast<punned_t*>(c_ptr)->reserve(static_cast<std::size_t>(capacity));
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
         if (jc)
@@ -132,7 +132,7 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1add( //
         vector_data = (*env).GetFloatArrayElements(vector, 0);
         jsize vector_dims = (*env).GetArrayLength(vector);
         span_t vector_span = span_t{vector_data, static_cast<std::size_t>(vector_dims)};
-        reinterpret_cast<native_index_t*>(c_ptr)->add(label, vector_span);
+        reinterpret_cast<punned_t*>(c_ptr)->add(label, vector_span);
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");
         if (jc)
@@ -159,8 +159,9 @@ JNIEXPORT jintArray JNICALL Java_cloud_unum_usearch_Index_c_1search( //
         vector_data = (*env).GetFloatArrayElements(vector, 0);
         jsize vector_dims = (*env).GetArrayLength(vector);
         span_t vector_span = span_t{vector_data, static_cast<std::size_t>(vector_dims)};
-        found = reinterpret_cast<native_index_t*>(c_ptr)->search( //
-            vector_span, static_cast<std::size_t>(wanted), matches_data, NULL);
+        found = reinterpret_cast<punned_t*>(c_ptr)
+                    ->search(vector_span, static_cast<std::size_t>(wanted))
+                    .dump_to(matches_data, NULL);
         (*env).SetIntArrayRegion(matches, 0, found, matches_data);
     } catch (...) {
         jclass jc = (*env).FindClass("java/lang/Error");

package/javascript/lib.cpp

@@ -20,14 +20,14 @@
 #include <napi.h>
 #include <node_api.h>
 
-#include "advanced.hpp"
+#include "punned.hpp"
 
 using namespace unum::usearch;
 using namespace unum;
 
 using label_t = std::uint32_t;
 using distance_t = punned_distance_t;
-using native_index_t = auto_index_gt<label_t>;
+using punned_t = punned_gt<label_t>;
 
 class Index : public Napi::ObjectWrap<Index> {
   public:
@@ -47,7 +47,7 @@ class Index : public Napi::ObjectWrap<Index> {
     void Add(Napi::CallbackInfo const& ctx);
     Napi::Value Search(Napi::CallbackInfo const& ctx);
 
-    std::unique_ptr<native_index_t> native_;
+    std::unique_ptr<punned_t> native_;
 };
 
 Napi::Object Index::Init(Napi::Env env, Napi::Object exports) {
@@ -79,7 +79,7 @@ Index::Index(Napi::CallbackInfo const& ctx) : Napi::ObjectWrap<Index>(ctx) {
     int length = ctx.Length();
     if (length == 0 || length >= 2 || !ctx[0].IsObject()) {
         Napi::TypeError::New(
-            env, "Pass args as named objects: dimensions: uint, capacity: uint, metric: [ip, cos, l2_sq, haversine]")
+            env, "Pass args as named objects: dimensions: uint, capacity: uint, metric: [ip, cos, l2sq, haversine]")
             .ThrowAsJavaScriptException();
         return;
     }
@@ -105,7 +105,7 @@ Index::Index(Napi::CallbackInfo const& ctx) : Napi::ObjectWrap<Index>(ctx) {
         else if (accuracy_str == "f8")
             accuracy = accuracy_t::f8_k;
         else {
-            Napi::TypeError::New(env, "Supported metrics are: [ip, cos, l2_sq, haversine]")
+            Napi::TypeError::New(env, "Supported metrics are: [ip, cos, l2sq, haversine]")
                 .ThrowAsJavaScriptException();
             return;
         }
@@ -114,28 +114,28 @@ Index::Index(Napi::CallbackInfo const& ctx) : Napi::ObjectWrap<Index>(ctx) {
     // By default we use the Inner Product similarity
     if (params.Has("metric")) {
         std::string name = params.Get("metric").As<Napi::String>().Utf8Value();
-        if (name == "l2_sq" || name == "euclidean_sq") {
+        if (name == "l2sq" || name == "euclidean_sq") {
             if (!dimensions) {
                 Napi::TypeError::New(env, "Please define the number of dimensions").ThrowAsJavaScriptException();
                 return;
             }
-            native_.reset(new native_index_t(native_index_t::l2(dimensions, accuracy, config)));
+            native_.reset(new punned_t(punned_t::l2sq(dimensions, accuracy, config)));
         } else if (name == "ip" || name == "inner" || name == "dot") {
             if (!dimensions) {
                 Napi::TypeError::New(env, "Please define the number of dimensions").ThrowAsJavaScriptException();
                 return;
             }
-            native_.reset(new native_index_t(native_index_t::ip(dimensions, accuracy, config)));
+            native_.reset(new punned_t(punned_t::ip(dimensions, accuracy, config)));
         } else if (name == "cos" || name == "angular") {
             if (!dimensions) {
                 Napi::TypeError::New(env, "Please define the number of dimensions").ThrowAsJavaScriptException();
                 return;
             }
-            native_.reset(new native_index_t(native_index_t::cos(dimensions, accuracy, config)));
+            native_.reset(new punned_t(punned_t::cos(dimensions, accuracy, config)));
         } else if (name == "haversine") {
-            native_.reset(new native_index_t(native_index_t::haversine(accuracy, config)));
+            native_.reset(new punned_t(punned_t::haversine(accuracy, config)));
         } else {
-            Napi::TypeError::New(env, "Supported metrics are: [ip, cos, l2_sq, haversine]")
+            Napi::TypeError::New(env, "Supported metrics are: [ip, cos, l2sq, haversine]")
                 .ThrowAsJavaScriptException();
             return;
         }
@@ -144,7 +144,7 @@ Index::Index(Napi::CallbackInfo const& ctx) : Napi::ObjectWrap<Index>(ctx) {
             Napi::TypeError::New(env, "Please define the number of dimensions").ThrowAsJavaScriptException();
             return;
         }
-        native_.reset(new native_index_t(native_index_t::ip(dimensions, accuracy, config)));
+        native_.reset(new punned_t(punned_t::ip(dimensions, accuracy, config)));
     }
 }
 
@@ -258,7 +258,7 @@ Napi::Value Index::Search(Napi::CallbackInfo const& ctx) {
     Napi::Uint32Array matches_js = Napi::Uint32Array::New(env, wanted);
     Napi::Float32Array distances_js = Napi::Float32Array::New(env, wanted);
     try {
-        std::size_t count = native_->search(vector, wanted, matches_js.Data(), distances_js.Data());
+        std::size_t count = native_->search(vector, wanted).dump_to(matches_js.Data(), distances_js.Data());
         Napi::Object result_js = Napi::Object::New(env);
         result_js.Set("labels", matches_js);
         result_js.Set("distances", distances_js);

package/javascript/test.js

@@ -1,7 +1,7 @@
 var assert = require('assert');
 var usearch = require('bindings')('usearch');
 
-var index = new usearch.Index({ metric: 'l2_sq', connectivity: 16, dimensions: 2 })
+var index = new usearch.Index({ metric: 'l2sq', connectivity: 16, dimensions: 2 })
 assert.equal(index.connectivity(), 16)
 assert.equal(index.dimensions(), 2)
 assert.equal(index.size(), 0)

package/objc/USearchObjective.mm

@@ -2,15 +2,15 @@
 
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wdocumentation"
-#import "advanced.hpp"
+#import "punned.hpp"
 #pragma clang diagnostic pop
 
 using namespace unum::usearch;
 using namespace unum;
 
 using distance_t = punned_distance_t;
-using native_index_t = auto_index_gt<UInt32>;
-using shared_index_t = std::shared_ptr<native_index_t>;
+using punned_t = punned_gt<UInt32>;
+using shared_index_t = std::shared_ptr<punned_t>;
 
 @interface Index ()
 
@@ -59,91 +59,108 @@ using shared_index_t = std::shared_ptr<native_index_t>;
 + (instancetype)indexIP:(UInt32)dimensions connectivity:(UInt32)connectivity {
     std::size_t dims = static_cast<std::size_t>(dimensions);
     config_t config;
+
     config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<native_index_t>(native_index_t::ip(dims, accuracy_t::f32_k, config));
+    shared_index_t ptr = std::make_shared<punned_t>(punned_t::ip(dims, accuracy_t::f32_k, config));
     return [[Index alloc] initWithIndex:ptr];
 }
 
-+ (instancetype)indexL2:(UInt32)dimensions connectivity:(UInt32)connectivity {
++ (instancetype)indexL2sq:(UInt32)dimensions connectivity:(UInt32)connectivity {
     std::size_t dims = static_cast<std::size_t>(dimensions);
     config_t config;
+
     config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<native_index_t>(native_index_t::l2(dims, accuracy_t::f32_k, config));
+    shared_index_t ptr = std::make_shared<punned_t>(punned_t::l2sq(dims, accuracy_t::f32_k, config));
     return [[Index alloc] initWithIndex:ptr];
 }
 
 + (instancetype)indexHaversine:(UInt32)connectivity {
     config_t config;
+
     config.connectivity = static_cast<std::size_t>(connectivity);
-    shared_index_t ptr = std::make_shared<native_index_t>(native_index_t::haversine(accuracy_t::f32_k, config));
+    shared_index_t ptr = std::make_shared<punned_t>(punned_t::haversine(accuracy_t::f32_k, config));
     return [[Index alloc] initWithIndex:ptr];
 }
 
 - (void)addSingle:(UInt32)label
-           vector:(Float32 const * _Nonnull)vector {
+           vector:(Float32 const *_Nonnull)vector {
     _native->add(label, vector);
 }
 
-- (UInt32)searchSingle:(Float32 const* _Nonnull)vector
+- (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)wanted
-                labels:(UInt32* _Nullable)labels
-             distances:(Float32* _Nullable)distances {
-    std::size_t found = _native->search(vector, static_cast<std::size_t>(wanted), labels, distances);
+                labels:(UInt32 *_Nullable)labels
+             distances:(Float32 *_Nullable)distances {
+    std::size_t found = _native->search(vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+
     return static_cast<UInt32>(found);
 }
 
 - (void)addPrecise:(UInt32)label
-            vector:(Float64 const * _Nonnull)vector {
+            vector:(Float64 const *_Nonnull)vector {
     _native->add(label, (f64_t const *)vector);
 }
 
-- (UInt32)searchPrecise:(Float64 const* _Nonnull)vector
+- (UInt32)searchPrecise:(Float64 const *_Nonnull)vector
                   count:(UInt32)wanted
-                 labels:(UInt32* _Nullable)labels
-              distances:(Float32* _Nullable)distances {
-    std::size_t found = _native->search((f64_t const *)vector, static_cast<std::size_t>(wanted), labels, distances);
+                 labels:(UInt32 *_Nullable)labels
+              distances:(Float32 *_Nullable)distances {
+    std::size_t found = _native->search((f64_t const *)vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+
     return static_cast<UInt32>(found);
 }
 
 - (void)addImprecise:(UInt32)label
-              vector:(void const * _Nonnull)vector {
+              vector:(void const *_Nonnull)vector {
     _native->add(label, (f16_bits_t const *)vector);
 }
 
-- (UInt32)searchImprecise:(void const* _Nonnull)vector
+- (UInt32)searchImprecise:(void const *_Nonnull)vector
                     count:(UInt32)wanted
-                   labels:(UInt32* _Nullable)labels
-                distances:(Float32* _Nullable)distances {
-    std::size_t found = _native->search((f16_bits_t const *)vector, static_cast<std::size_t>(wanted), labels, distances);
+                   labels:(UInt32 *_Nullable)labels
+                distances:(Float32 *_Nullable)distances {
+    std::size_t found = _native->search((f16_bits_t const *)vector, static_cast<std::size_t>(wanted)).dump_to(labels, distances);
+
     return static_cast<UInt32>(found);
 }
 
-- (void)clear { _native->clear(); }
+- (void)clear {
+    _native->clear();
+}
 
-- (void)save:(NSString*)path {
+- (void)save:(NSString *)path {
     char const *path_c = [path UTF8String];
-    if (!path_c)
+
+    if (!path_c) {
         @throw [NSException exceptionWithName:@"Can't save to disk"
                                        reason:@"The path must be convertible to UTF8"
                                      userInfo:nil];
+    }
+
     _native->save(path_c);
 }
 
-- (void)load:(NSString*)path {
+- (void)load:(NSString *)path {
     char const *path_c = [path UTF8String];
-    if (!path_c)
+
+    if (!path_c) {
         @throw [NSException exceptionWithName:@"Can't load from disk"
                                        reason:@"The path must be convertible to UTF8"
                                      userInfo:nil];
+    }
+
     _native->load(path_c);
 }
 
-- (void)view:(NSString*)path {
+- (void)view:(NSString *)path {
     char const *path_c = [path UTF8String];
-    if (!path_c)
+
+    if (!path_c) {
         @throw [NSException exceptionWithName:@"Can't view from disk"
                                        reason:@"The path must be convertible to UTF8"
                                      userInfo:nil];
+    }
+
     _native->view(path_c);
 }
 

package/objc/include/USearchObjective.h

@@ -11,7 +11,7 @@ typedef NS_ENUM(NSUInteger, Quantization) {
 };
 
 API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
-@interface Index: NSObject
+@interface Index : NSObject
 
 @property (readonly) UInt32 dimensions;
 @property (readonly) UInt32 connectivity;
@@ -22,47 +22,39 @@ API_AVAILABLE(ios(13.0), macos(10.15), tvos(13.0), watchos(6.0))
 @property (readonly) UInt32 capacity;
 @property (readonly) Boolean isEmpty;
 
-- (instancetype)init
-NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
 
 + (instancetype)indexIP:(UInt32)dimensions connectivity:(UInt32)connectivity NS_SWIFT_NAME(indexIP(dimensions:connectivity:));
-+ (instancetype)indexL2:(UInt32)dimensions connectivity:(UInt32)connectivity NS_SWIFT_NAME(l2(dimensions:connectivity:));
++ (instancetype)indexL2sq:(UInt32)dimensions connectivity:(UInt32)connectivity NS_SWIFT_NAME(l2sq(dimensions:connectivity:));
 + (instancetype)indexHaversine:(UInt32)connectivity NS_SWIFT_NAME(indexHaversine(connectivity:));
 
 - (void)addSingle:(UInt32)label
-           vector:(Float32 const* _Nonnull)vector
-NS_SWIFT_NAME(addSingle(label:vector:));
+           vector:(Float32 const *_Nonnull)vector NS_SWIFT_NAME(addSingle(label:vector:));
 
-- (UInt32)searchSingle:(Float32 const* _Nonnull)vector
+- (UInt32)searchSingle:(Float32 const *_Nonnull)vector
                  count:(UInt32)count
-                labels:(UInt32* _Nullable)labels
-             distances:(Float32* _Nullable)distances
-NS_SWIFT_NAME(searchSingle(vector:count:labels:distances:));
+                labels:(UInt32 *_Nullable)labels
+             distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchSingle(vector:count:labels:distances:));
 
 - (void)addPrecise:(UInt32)label
-            vector:(Float64 const* _Nonnull)vector
-NS_SWIFT_NAME(addPrecise(label:vector:));
+            vector:(Float64 const *_Nonnull)vector NS_SWIFT_NAME(addPrecise(label:vector:));
 
-- (UInt32)searchPrecise:(Float64 const* _Nonnull)vector
+- (UInt32)searchPrecise:(Float64 const *_Nonnull)vector
                   count:(UInt32)count
-                 labels:(UInt32* _Nullable)labels
-              distances:(Float32* _Nullable)distances
-NS_SWIFT_NAME(searchPrecise(vector:count:labels:distances:));
+                 labels:(UInt32 *_Nullable)labels
+              distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchPrecise(vector:count:labels:distances:));
 
 - (void)addImprecise:(UInt32)label
-              vector:(void const* _Nonnull)vector
-NS_SWIFT_NAME(addImprecise(label:vector:));
+              vector:(void const *_Nonnull)vector NS_SWIFT_NAME(addImprecise(label:vector:));
 
-- (UInt32)searchImprecise:(void const* _Nonnull)vector
+- (UInt32)searchImprecise:(void const *_Nonnull)vector
                     count:(UInt32)count
-                   labels:(UInt32* _Nullable)labels
-                distances:(Float32* _Nullable)distances
-NS_SWIFT_NAME(searchImprecise(vector:count:labels:distances:));
+                   labels:(UInt32 *_Nullable)labels
+                distances:(Float32 *_Nullable)distances NS_SWIFT_NAME(searchImprecise(vector:count:labels:distances:));
 
-
-- (void)save:(NSString*)path NS_SWIFT_NAME(dump(path:));
-- (void)load:(NSString*)path NS_SWIFT_NAME(load(path:));
-- (void)view:(NSString*)path NS_SWIFT_NAME(view(path:));
+- (void)save:(NSString *)path NS_SWIFT_NAME(dump(path:));
+- (void)load:(NSString *)path NS_SWIFT_NAME(load(path:));
+- (void)view:(NSString *)path NS_SWIFT_NAME(view(path:));
 - (void)clear NS_SWIFT_NAME(clear());
 
 @end

package/package.json

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

package/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=42", "wheel", "cmake>=3.22", "pybind11"]
+requires = ["setuptools>=42", "wheel", "cmake>=3.22", "pybind11", "numpy"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
@@ -9,8 +9,9 @@ xfail_strict = true
 filterwarnings = ["error"]
 
 [tool.cibuildwheel]
+test-requires = ["pytest", "numpy"]
+test-command = "pytest {project}/python/test.py"
 build-verbosity = 0
-
 skip = ["*musllinux*", "*i686*", "pp*"]
 
 [tool.cibuildwheel.linux]