usearch 0.1.7 → 0.1.8

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.1.7"
+version = "0.1.8"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "The Mighty Tiny Vector Search Engine with Automatic Quantization and Hardware Acceleration"
 edition = "2021"

package/README.md

@@ -44,33 +44,86 @@ Compact, yet Powerful<br/>
 
 ## Usage
 
+There are two usage patters:
+
+- Bare-bones with `usearch/usearch.hpp`, only available in C++.
+- Full-fat version with it's own threads, mutexes, type-punning, quantization, that is available both in C++ and is wrapped for higher-level bindings.
+
 ### C++
 
 To use in a C++ project simply copy the `include/usearch/usearch.hpp` header into your project.
+Alternatively fetch it with CMake:
+
+```cmake
+FetchContent_Declare(usearch GIT_REPOSITORY https://github.com/unum-cloud/usearch.git)
+FetchContent_MakeAvailable(usearch)
+```
+
+The simple usage example would require including the `unum::usearch` namespace and choosing the right "distance" function.
+That can be one of the following templates:
+
+- `cos_gt<float>` for "Cosine" or "Angular" distance.
+- `ip_gt<float>` for "Inner Product" or "Dot Product" distance.
+- `l2_squared_gt<float>` for the squared "L2" or "Euclidean" distance.
+- `jaccard_gt<int>` for "Jaccard" distance between two ordered sets of unique elements.
+- `bit_hamming_gt<uint>` for "Hamming" distance, as the number of shared bits in hashes.
+- `pearson_correlation_gt<float>` for "Pearson" correlation between probability distributions.
+- `haversine_gt<float>` for "Haversine" or "Great Circle" distance between coordinates.
+
+That list is easily extendible, and can include similarity measures for vectors that have a different number of elements/dimensions.
+The minimal example would be.
 
 ```c++
 using namespace unum::usearch;
 
 index_gt<cos_gt<float>> index;
 float vec[3] = {0.1, 0.3, 0.2};
+
+index.reserve(10);
 index.add(/* label: */ 42, /* vector: */ {&vec, 3});
 index.search(
-  /* query: */ {&vec, 3}, 10 /* results */,
-  /* callback: */ [](std::size_t label, float distance) { });
+  /* query: */ {&vec, 3}, /* top */ 5 /* results */,
+  /* with callback: */ [](std::size_t label, float distance) { });
 
 index.save("index.usearch"); // Serializing to disk
 index.load("index.usearch"); // Reconstructing from disk
 index.view("index.usearch"); // Memory-mapping from disk
 ```
 
-Alternatively fetch it with CMake:
+The `add` is thread-safe for concurrent index construction.
 
-```cmake
-FetchContent_Declare(usearch GIT_REPOSITORY https://github.com/unum-cloud/usearch.git)
-FetchContent_MakeAvailable(usearch)
-```
+### Python
+
+Python bindings are implemented with [`pybind/pybind11`](https://github.com/pybind/pybind11).
+Assuming the presence of Global Interpreter Lock in Python, on large insertions we spawn threads in the C++ layer.
 
+```sh
+$ pip install usearch
 
+import numpy as np
+import usearch
+
+index = usearch.Index(
+    dim=256, # Define the number of dimensions in input vectors
+    metric='cos', # Choose the "metric" or "distance", default = 'ip', optional
+    dtype='f16', # Quantize to 'f16' or 'i8q100' if needed, default = 'f32', optional
+    connectivity=16, # How frequent should the connections in the graph be, optional
+    expansion_add=128, # Control the recall of indexing, optional
+    expansion_search=64, # Control the quality of search, optional
+)
+
+n = 100
+labels = np.array(range(n), dtype=np.longlong)
+vectors = np.random.uniform(0, 0.3, (n, index.ndim)).astype(np.float32)
+
+# You can avoid copying the data
+# Handy when build 1B+ indexes of memory-mapped files
+index.add(labels, vectors, copy=True)
+assert len(index) == n
+
+# You can search a batch at once
+matches, distances, counts = index.search(vectors, 10)
+```
 
 ## Features
 
@@ -78,7 +131,6 @@ FetchContent_MakeAvailable(usearch)
 
 ## Performance
 
-
 ## TODO
 
 - JavaScript: Allow calling from "worker threads".

package/VERSION

@@ -1 +1 @@
-0.1.7
+0.1.8

package/java/test/IndexTest.java

@@ -19,7 +19,7 @@ public class IndexTest {
     public void test() {
         String path = "./tmp/";
         deleteDirectoryFiles(path);
-        new Index("cos", "f32", 1, 10, 1, 1, 1);
+        // new Index("cos", "f32", 1, 10, 1, 1, 1);
         System.out.println("Java Tests Passed!");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.1.7",
+    "version": "0.1.8",
     "description": "The Mighty Tiny Vector Search Engine with Automatic Quantization and Hardware Acceleration",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",

package/python/lib.cpp

@@ -198,6 +198,12 @@ PYBIND11_MODULE(usearch, m) {
         py::arg("count") = 10       //
     );
 
+    i.def("__len__", &native_index_t::size);
+    i.def_property_readonly("size", &native_index_t::size);
+    i.def_property_readonly("ndim", &native_index_t::dimensions);
+    i.def_property_readonly("connectivity", &native_index_t::connectivity);
+    i.def_property_readonly("capacity", &native_index_t::capacity);
+
     i.def("save", &save_index, py::arg("path"));
     i.def("load", &load_index, py::arg("path"));
     i.def("view", &view_index, py::arg("path"));