usearch 0.1.10 → 0.2.2

package/.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
 #     needs: versioning
     strategy:
       matrix:
-        os: [ubuntu-20.04, macOS-11]
+        os: [ubuntu-20.04, macOS-11, windows-2022]
 
     steps:
       - uses: actions/checkout@v3
@@ -130,6 +130,17 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  publish_swift:
+    name: Publish ObjC & Swift
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v3
+    - run: git submodule update --init --recursive
+    - name: Build
+      run: swift build
+    - name: Run tests
+      run: swift test
+
   deploy_docs:
     name: Deploy Docs
     environment: 

package/.vscode/launch.json

@@ -36,18 +36,19 @@
             }
         },
         {
-            "name": "Debug C++ Bench on Text-to-Image 1M @Cos",
+            "name": "Debug C++ Bench on Text-to-Image 1B @Cos",
             "type": "cppdbg",
             "request": "launch",
             "program": "${workspaceFolder}/build_debug/bench",
             "cwd": "${workspaceFolder}",
             "args": [
                 "--vectors",
-                "datasets/t2i_1M/base.1M.fbin",
+                "datasets/t2i_1B/base.1B.fbin",
                 "--queries",
-                "datasets/t2i_1M/query.public.100K.fbin",
+                "datasets/t2i_1B/query.public.100K.fbin",
                 "--neighbors",
-                "datasets/t2i_1M/groundtruth.public.100K.ibin",
+                "datasets/t2i_1B/groundtruth.public.100K.ibin",
+                "--cos"
             ],
             "environment": [
                 {

package/.vscode/settings.json

@@ -97,13 +97,19 @@
         "__memory": "cpp",
         "filesystem": "cpp",
         "__availability": "cpp",
-        "version": "cpp"
+        "version": "cpp",
+        "future": "cpp"
     },
     "cSpell.words": [
+        "astype",
+        "dtype",
         "equidimensional",
+        "hashable",
         "jaccard",
+        "longlong",
         "memmap",
         "ndim",
+        "preprocess",
         "simsimd",
         "usearch"
     ],

package/CMakeLists.txt

@@ -17,22 +17,18 @@ if(NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Release)
 endif()
 
-set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
-set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
-set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -pg -g")
-
 # List of all possible compiler IDs:
 # https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER_ID.html
 if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wno-conversion -Wno-unknown-pragmas")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wall -Wextra -Wno-conversion -Wno-unknown-pragmas")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fmax-errors=1")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
 
 elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wfatal-errors")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wfatal-errors")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
 
@@ -46,6 +42,15 @@ elseif(CMAKE_CXX_COMPILER_ID STREQUAL "NVIDIA" OR CMAKE_CXX_COMPILER_ID STREQUAL
 elseif(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -w")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ferror-limit=1")
+
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} /DEBUG")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} /O2")
+    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} /O2 /DEBUG")
+else()
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
+    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -pg -g")
 endif()
 
 if(APPLE)

package/CMakeListsInstructions.md

@@ -12,6 +12,7 @@ git submodule update --init --recursive
 
 ```sh
 cmake -B ./build_release \
+    -DCMAKE_CXX_COMPILER="g++-12" \
     -DCMAKE_BUILD_TYPE=Release \
     -DUSEARCH_USE_SIMD=1 \
     -DUSEARCH_USE_OPENMP=1 \
@@ -24,6 +25,14 @@ cmake -B ./build_release \
     --queries datasets/wiki_1M/query.public.100K.fbin \
     --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin
 
+# Large benchmark on a 1TB dataset:
+./build_release/bench \
+    --vectors datasets/t2i_1B/base.1B.fbin \
+    --queries datasets/t2i_1B/query.public.100K.fbin \
+    --neighbors datasets/t2i_1B/groundtruth.public.100K.ibin \
+    --output datasets/t2i_1B/index.usearch \
+    --cos
+
 # To benchmark in Python:
 python python/bench.py \
     --vectors datasets/wiki_1M/base.1M.fbin \
@@ -110,44 +119,57 @@ brew install --cask wolfram-engine
 BigANN benchmark is a good starting point, if you are searching for large collections of high-dimensional vectors.
 Those often come with precomputed ground-truth neighbors, which is handy for recall evaluation.
 
-| Dataset                         | Scalar Type | Dimensions | Metric |  Size  |
-| :------------------------------ | :---------: | :--------: | :----: | :----: |
-| [Microsoft SPACEV][spacev]      |    int8     |    100     |   L2   | 93 GB  |
-| [Microsoft Turing-ANNS][turing] |   float32   |    100     |   L2   | 373 GB |
-| [Yandex Deep1B][deep]           |   float32   |     96     |   L2   | 358 GB |
-| [Yandex Text-to-Image][t2i]     |   float32   |    200     |  Cos   | 750 GB |
+| Dataset                                 | Scalar Type | Dimensions | Metric |   Size    |
+| :-------------------------------------- | :---------: | :--------: | :----: | :-------: |
+| [Unum UForm Wiki][unum-wiki]            |   float32   |    256     |   IP   |   1 GB    |
+| [Yandex Text-to-Image Sample][unum-t2i] |   float32   |    200     |  Cos   |   1 GB    |
+|                                         |             |            |        |           |
+| [Microsoft SPACEV][spacev]              |    int8     |    100     |   L2   |   93 GB   |
+| [Microsoft Turing-ANNS][turing]         |   float32   |    100     |   L2   |  373 GB   |
+| [Yandex Deep1B][deep]                   |   float32   |     96     |   L2   |  358 GB   |
+| [Yandex Text-to-Image][t2i]             |   float32   |    200     |  Cos   |  750 GB   |
+|                                         |             |            |        |           |
+| [ViT-L/12 LAION][laion]                 |   float32   |    2048    |  Cos   | 2 - 10 TB |
 
 Luckily, smaller samples of those datasets are available.
 
+[unum-wiki]: https://huggingface.co/datasets/unum-cloud/ann-wiki-1m
+[unum-t2i]: https://huggingface.co/datasets/unum-cloud/ann-t2i-1m
 [spacev]: https://github.com/microsoft/SPTAG/tree/main/datasets/SPACEV1B
 [turing]: https://learning2hash.github.io/publications/microsoftturinganns1B/
 [t2i]: https://research.yandex.com/blog/benchmarks-for-billion-scale-similarity-search
 [deep]: https://research.yandex.com/blog/benchmarks-for-billion-scale-similarity-search
+[laion]: https://laion.ai/blog/laion-5b/#download-the-data
 
-### Yandex Deep1B
-
-There is a 10M subset available.
+### Unum UForm Wiki
 
 ```sh
-mkdir -p datasets/deep/ && \
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.1B.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.10M.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/query.public.10K.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/groundtruth.public.10K.ibin -P datasets/deep_1B/
+mkdir -p datasets/wiki_1M/ && \
+    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/base.1M.fbin -P datasets/wiki_1M/ &&
+    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/query.public.100K.fbin -P datasets/wiki_1M/ &&
+    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/groundtruth.public.100K.ibin -P datasets/wiki_1M/
 ```
 
 ### Yandex Text-to-Image
 
-There is a 1M subset available.
-
 ```sh
-mkdir -p datasets/t2i/ && \
+mkdir -p datasets/t2i_1B/ && \
     wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/base.1B.fbin -P datasets/t2i_1B/ &&
     wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/base.1M.fbin -P datasets/t2i_1B/ &&
     wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/query.public.100K.fbin -P datasets/t2i_1B/ &&
     wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/groundtruth.public.100K.ibin -P datasets/t2i_1B/
 ```
 
+### Yandex Deep1B
+
+```sh
+mkdir -p datasets/deep_1B/ && \
+    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.1B.fbin -P datasets/deep_1B/ &&
+    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.10M.fbin -P datasets/deep_1B/ &&
+    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/query.public.10K.fbin -P datasets/deep_1B/ &&
+    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/groundtruth.public.10K.ibin -P datasets/deep_1B/
+```
+
 ### Profiling
 
 With `perf`:

package/Cargo.toml

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

package/Package.swift

@@ -0,0 +1,40 @@
+// swift-tools-version:5.3
+
+import PackageDescription
+
+let package = Package(
+    name: "USearch",
+    products: [
+        .library(
+            name: "USearch",
+            targets: ["USearchObjective", "USearch"]
+        )
+    ],
+    dependencies: [],
+    targets: [
+        .target(
+            name: "USearchObjective",
+            path: "objc",
+            sources: ["USearchObjective.mm"],
+            cxxSettings: [
+                .headerSearchPath("../include/"),
+                .headerSearchPath("../src/"),
+                .headerSearchPath("../fp16/include/"),
+                .headerSearchPath("../simismd/include/")
+            ]
+        ),
+        .target(
+            name: "USearch",
+            dependencies: ["USearchObjective"],
+            path: "swift",
+            sources: ["USearch.swift", "Index+Sugar.swift"]
+        ),
+        .testTarget(
+            name: "USearchTests",
+            dependencies: ["USearch"],
+            path: "swift",
+            sources: ["Test.swift"]
+        )
+    ],
+    cxxLanguageStandard: CXXLanguageStandard.cxx11
+)

package/README.md

@@ -30,7 +30,7 @@ Vector Search Engine<br/>
 - [x] [Bring your threads](#bring-your-threads), like OpenMP.
 - [x] Multiple vectors per label.
 - [x] [Python](#python) bindings: `pip install usearch`.
-- [x] [JavaScript](#java) bindings: `npm install usearch`.
+- [x] [JavaScript](#javascript) bindings: `npm install usearch`.
 - [x] [Rust](#rust) bindings: `cargo add usearch`.
 - [x] [Java](#java) bindings: `cloud.unum:usearch` on GitHub.
 - [ ] GoLang bindings.
@@ -108,7 +108,7 @@ So, if you are working on large datasets, but don't need the in-RAM throughput,
 ### Quantize on the Fly
 
 Most modern CPU have at least partial support for `half`-precision `f16_t` arithmetic.
-USearch supports automatic down-casting and up-casting between `f32_t`, `f16_t`, `f64_t`, and `i8q100_t` representations.
+USearch supports automatic down-casting and up-casting between `f32_t`, `f16_t`, `f64_t`, and `f8_t` representations.
 
 > Making vectors smaller will help pack more of them in-memory, while also increasing performance on CPUs implementing native support for target type.
 
@@ -160,7 +160,7 @@ 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.
+- `l2sq_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.
@@ -216,17 +216,26 @@ Assuming the presence of Global Interpreter Lock in Python, on large insertions
 $ pip install usearch
 
 import numpy as np
-import usearch
+from usearch.index import Index
 
-index = usearch.Index(
+index = Index(
     ndim=256, # Define the number of dimensions in input vectors
     metric='cos', # Choose the "metric" or "distance", default = 'ip', optional
-    dtype='f32', # Quantize to 'f16' or 'i8q100' if needed, default = 'f32', optional
+    dtype='f32', # Quantize to 'f16' or 'f8' 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
 )
 
+vector = np.random.uniform(0, 0.3, (index.ndim)).astype(np.float32)
+index.add(42, vector)
+matches, distances, count = index.search(vector, 10)
+```
+
+Same can be done with batches, rather than single entries.
+Under the hood, worker threads will be spawned, to parallelize the procedure.
+
+```py
 n = 100
 labels = np.array(range(n), dtype=np.longlong)
 vectors = np.random.uniform(0, 0.3, (n, index.ndim)).astype(np.float32)
@@ -234,9 +243,6 @@ 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)
 ```
 
@@ -267,7 +273,7 @@ Aside from the `add` and `search`, it also provides `add_in_thread` and `search_
 // cargo add usearch
 
 let quant: &str = "f16";
-let index = new_ip(5,  &quant, 0, 0, 0).unwrap();
+let index = new_ip(5, &quant, 0, 0, 0).unwrap();
 
 assert!(index.reserve(10).is_ok());
 assert!(index.capacity() >= 10);
@@ -292,8 +298,8 @@ assert!(index.load("index.usearch").is_ok());
 assert!(index.view("index.usearch").is_ok());
 
 // There are more "metrics" available
-assert!(new_l2(5,  &quant, 0, 0, 0).is_ok());
-assert!(new_cos(5,  &quant, 0, 0, 0).is_ok());
+assert!(new_l2(5, &quant, 0, 0, 0).is_ok());
+assert!(new_cos(5, &quant, 0, 0, 0).is_ok());
 assert!(new_haversine(&quant, 0, 0, 0).is_ok());
 ```
 
@@ -306,6 +312,19 @@ index.add(42, vec);
 int[] labels = index.search(vec, 5);
 ```
 
+### Objective-C and Swift
+
+```swift
+let index = Index.l2(dimensions: 4, connectivity: 8)
+let vectorA: [Float32] = [0.3, 0.5, 1.2, 1.4]
+let vectorB: [Float32] = [0.4, 0.2, 1.2, 1.1]
+index.add(label: 42, vector: vectorA[...])
+index.add(label: 43, vector: vectorB[...])
+
+let results = index.search(vector: vectorA[...], count: 10)
+assert(results.0[0] == 42)
+```
+
 ### GoLang
 
 ### Wolfram
@@ -394,28 +413,27 @@ One can take an encoder model, like the multi-modal UForm, and a web-programming
 ```python
 import ucall.rich_posix as ucall
 import uform
-import usearch
+from usearch.index import Index
 
 import numpy as np
 from PIL import Image
 
 server = ucall.Server()
 model = uform.get_model('unum-cloud/uform-vl-multilingual')
-index = usearch.Index(ndim=256)
+index = Index(ndim=256)
 
 @server
 def add(label: int, photo: Image.Image):
     image = model.preprocess_image(photo)
     vector = model.encode_image(image).detach().numpy()
-    labels = np.array([label], dtype=np.longlong)
-    index.add(labels, vector, copy=True)
+    index.add(label, vector.flatten(), copy=True)
 
 @server
 def search(query: str) -> np.ndarray:
     tokens = model.preprocess_text(query)
     vector = model.encode_text(tokens).detach().numpy()
-    neighbors = index.search(vector, 3)
-    return neighbors[0][:neighbors[2][0]]
+    neighbors, _, _ = index.search(vector.flatten(), 3)
+    return neighbors
 
 server.run()
 ```

package/VERSION

@@ -1 +1 @@
-0.1.10
+0.2.2

package/build.gradle

@@ -56,11 +56,15 @@ model {
                 if (targetPlatform.operatingSystem.linux) {
                     cppCompiler.args '-I', "${Jvm.current().javaHome}/include/linux"
                     cppCompiler.args '-D_FILE_OFFSET_BITS=64'
+                    cppCompiler.args '-std=c++11'
                 } else if (targetPlatform.operatingSystem.macOsX) {
                     cppCompiler.args '-I', "${Jvm.current().javaHome}/include/darwin"
                     cppCompiler.args '-D_FILE_OFFSET_BITS=64'
+                    cppCompiler.args '-std=c++11'
+                } else if (targetPlatform.operatingSystem.windows){
+                    cppCompiler.args "-I${Jvm.current().javaHome}/include/win32"
+                    cppCompiler.args '/std:c++11'
                 }
-                cppCompiler.args '-std=c++11'
             }
         }
     }

package/cmake/jemalloc.cmake

@@ -76,5 +76,3 @@ else()
         JEMALLOC_INCLUDE_DIR
     )
 endif()
-
-message("JEMALLOC_LIBRARIES:" ${JEMALLOC_LIBRARIES})

package/conanfile.py

@@ -0,0 +1,18 @@
+from conans import ConanFile
+
+class USearchConan(ConanFile):
+    
+    name = 'USearch'
+    version = '0.2.2'
+    license = 'Apache 2.0'
+    url = 'https://github.com/unum-cloud/usearch'
+    description = 'Smaller & Faster Single-File Vector Search Engine from Unum'
+
+    # No settings/options are necessary, this is header only
+    # Potentially add unit-tests in the future:
+    # https://docs.conan.io/1/howtos/header_only.html#with-unit-tests
+    exports_sources = 'include/*'
+    no_copy_source = True
+
+    def package(self):
+        self.copy('*.h')