usearch 0.1.0

package/.clang-format

@@ -0,0 +1,10 @@
+Language: Cpp
+BasedOnStyle:  LLVM
+IndentWidth: 4
+TabWidth: 4
+NamespaceIndentation: None
+ColumnLimit: 120
+ReflowComments: true
+UseTab: Never
+PointerAlignment: Left
+AllowShortCaseLabelsOnASingleLine: True

package/.github/workflows/package.json

@@ -0,0 +1,82 @@
+{
+  "devDependencies": {
+    "@semantic-release/exec": "github:semantic-release/exec",
+    "@semantic-release/git": "^10.0.1",
+    "conventional-changelog-eslint": "^3.0.9",
+    "semantic-release": "^20.1.3"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "debug": true,
+    "ci": true,
+    "dryRun": false,
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "eslint",
+          "releaseRules": [
+            {
+              "tag": "Add",
+              "release": "minor"
+            },
+            {
+              "tag": "Improve",
+              "release": "patch"
+            },
+            {
+              "tag": "Make",
+              "release": "patch"
+            },
+            {
+              "tag": "Refactor",
+              "release": false
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "eslint",
+          "releaseRules": [
+            {
+              "tag": "Add",
+              "release": "minor"
+            },
+            {
+              "tag": "Improve",
+              "release": "patch"
+            },
+            {
+              "tag": "Make",
+              "release": "patch"
+            },
+            {
+              "tag": "Refactor",
+              "release": false
+            }
+          ]
+        }
+      ],
+      "@semantic-release/github",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "echo '${nextRelease.version}' > VERSION"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "VERSION"
+          ],
+          "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}

package/.github/workflows/release.yml

@@ -0,0 +1,111 @@
+name: Release
+
+on:
+  push:
+    branches: ["main"]
+
+env:
+  BUILD_TYPE: Release
+  GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+
+#   versioning:
+#     name: Semantic Release
+#     runs-on: ubuntu-latest
+#     steps:
+#     - uses: actions/checkout@v3
+#       with:
+#         persist-credentials: false
+#     - uses: actions/setup-node@v3
+#     - run: cp .github/workflows/package.json . && npm install && npx semantic-release
+
+  build_wheels:
+    name: Build Wheels for ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+#     needs: versioning
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, macOS-11]
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: 'main'      
+      - uses: actions/setup-python@v3
+      - uses: crazy-max/ghaction-setup-docker@v1.0.0
+        with:
+          version: 23.0.1
+      - uses: docker/setup-qemu-action@v2.1.0
+
+      - name: Install CIBuildWheel
+        run: python -m pip install cibuildwheel
+
+      - name: Build wheels
+        run: python -m cibuildwheel
+        
+      - uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+  
+  
+  publish_wheels:
+    name: Publish Wheels to PyPi
+    runs-on: ubuntu-20.04
+    needs: build_wheels
+    environment:
+      name: pypi
+      url: https://pypi.org/p/usearch
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v3.0.2
+        with:
+          path: ./dist/
+
+      - name: Publish to PyPi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages_dir: ./dist/artifact
+          verbose: true
+          print_hash: true
+
+
+  deploy_docs:
+    name: Deploy Docs
+    environment: 
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-22.04
+    needs: publish_wheels
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: 'main'   
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v2
+      - name: Install dependencies
+        run: sudo apt update && sudo apt install -y doxygen graphviz dia git && pip install sphinx breathe furo m2r2 sphinxcontrib-googleanalytics==0.2.dev20220708 sphinxcontrib-jquery
+      - name: Install USearch from PyPi
+        run: pip install usearch
+      - name: Build documentation
+        run: cd docs && make html
+      - name: Copy assets
+        run: cp -r assets build/docs/html/
+      - name: Upload artifacts
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload entire repository
+          path: "./build/docs/html/"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

package/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "simsimd"]
+	path = simsimd
+	url = https://github.com/ashvardanian/simsimd
+[submodule "fp16"]
+	path = fp16
+	url = https://github.com/maratyszcza/fp16

package/.vscode/launch.json

@@ -0,0 +1,116 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug C++ Bench on Wiki 1M @Cos",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build_debug/bench",
+            "cwd": "${workspaceFolder}",
+            "args": [
+                "--vectors",
+                "datasets/wiki_1M/base.1M.fbin",
+                "--queries",
+                "datasets/wiki_1M/query.public.100K.fbin",
+                "--neighbors",
+                "datasets/wiki_1M/groundtruth.public.100K.ibin",
+                "--ip"
+            ],
+            "environment": [
+                {
+                    "name": "ASAN_OPTIONS",
+                    "value": "detect_leaks=0:atexit=1:strict_init_order=1:strict_string_checks=1"
+                }
+            ],
+            "stopAtEntry": false,
+            "linux": {
+                "preLaunchTask": "Linux Build C++ Bench Debug",
+                "MIMode": "gdb"
+            },
+            "osx": {
+                "preLaunchTask": "MacOS Build C++ Bench Debug",
+                "MIMode": "lldb"
+            }
+        },
+        {
+            "name": "Debug C++ Bench on Text-to-Image 1M @Cos",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build_debug/bench",
+            "cwd": "${workspaceFolder}",
+            "args": [
+                "--vectors",
+                "datasets/t2i_1M/base.1M.fbin",
+                "--queries",
+                "datasets/t2i_1M/query.public.100K.fbin",
+                "--neighbors",
+                "datasets/t2i_1M/groundtruth.public.100K.ibin",
+            ],
+            "environment": [
+                {
+                    "name": "ASAN_OPTIONS",
+                    "value": "detect_leaks=0:atexit=1:strict_init_order=1:strict_string_checks=1"
+                }
+            ],
+            "stopAtEntry": false,
+            "linux": {
+                "preLaunchTask": "Linux Build C++ Bench Debug",
+                "MIMode": "gdb"
+            },
+            "osx": {
+                "preLaunchTask": "MacOS Build C++ Bench Debug",
+                "MIMode": "lldb"
+            }
+        },
+        {
+            "name": "Run C++ Bench on Text-to-Image 1M @Cos",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build_release/bench",
+            "cwd": "${workspaceFolder}",
+            "args": [
+                "--vectors",
+                "datasets/t2i_1M/base.1M.fbin",
+                "--queries",
+                "datasets/t2i_1M/query.public.100K.fbin",
+                "--neighbors",
+                "datasets/t2i_1M/groundtruth.public.100K.ibin",
+            ],
+            "stopAtEntry": false,
+            "preLaunchTask": "Linux Build C++ Bench Release",
+            "MIMode": "gdb"
+        },
+        {
+            "name": "Debug PyBind11 Test",
+            "type": "pythoncpp",
+            "request": "launch",
+            "pythonLaunchName": "Python: Current File",
+            "cppAttachName": "Debug PyBind11: Attach with GDB"
+        },
+        {
+            "name": "Debug PyBind11: Attach with GDB",
+            "type": "cppdbg",
+            "request": "attach",
+            "program": "/Users/av/miniconda3/bin/python",
+            "processId": "",
+            "MIMode": "lldb",
+            "setupCommands": [
+                {
+                    "description": "Enable pretty-printing for gdb",
+                    "text": "-enable-pretty-printing",
+                    "ignoreFailures": true
+                }
+            ]
+        },
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        }
+    ]
+}

package/.vscode/settings.json

@@ -0,0 +1,109 @@
+{
+    "files.associations": {
+        "array": "cpp",
+        "atomic": "cpp",
+        "hash_map": "cpp",
+        "hash_set": "cpp",
+        "barrier": "cpp",
+        "bit": "cpp",
+        "*.tcc": "cpp",
+        "bitset": "cpp",
+        "cctype": "cpp",
+        "chrono": "cpp",
+        "cinttypes": "cpp",
+        "clocale": "cpp",
+        "cmath": "cpp",
+        "codecvt": "cpp",
+        "compare": "cpp",
+        "complex": "cpp",
+        "concepts": "cpp",
+        "condition_variable": "cpp",
+        "csignal": "cpp",
+        "cstdarg": "cpp",
+        "cstddef": "cpp",
+        "cstdint": "cpp",
+        "cstdio": "cpp",
+        "cstdlib": "cpp",
+        "cstring": "cpp",
+        "ctime": "cpp",
+        "cwchar": "cpp",
+        "cwctype": "cpp",
+        "deque": "cpp",
+        "forward_list": "cpp",
+        "list": "cpp",
+        "map": "cpp",
+        "set": "cpp",
+        "string": "cpp",
+        "unordered_map": "cpp",
+        "unordered_set": "cpp",
+        "vector": "cpp",
+        "exception": "cpp",
+        "algorithm": "cpp",
+        "functional": "cpp",
+        "iterator": "cpp",
+        "memory": "cpp",
+        "memory_resource": "cpp",
+        "numeric": "cpp",
+        "optional": "cpp",
+        "random": "cpp",
+        "ratio": "cpp",
+        "regex": "cpp",
+        "string_view": "cpp",
+        "system_error": "cpp",
+        "tuple": "cpp",
+        "type_traits": "cpp",
+        "utility": "cpp",
+        "fstream": "cpp",
+        "initializer_list": "cpp",
+        "iomanip": "cpp",
+        "iosfwd": "cpp",
+        "iostream": "cpp",
+        "istream": "cpp",
+        "limits": "cpp",
+        "mutex": "cpp",
+        "new": "cpp",
+        "numbers": "cpp",
+        "ostream": "cpp",
+        "semaphore": "cpp",
+        "sstream": "cpp",
+        "stdexcept": "cpp",
+        "stop_token": "cpp",
+        "streambuf": "cpp",
+        "thread": "cpp",
+        "typeindex": "cpp",
+        "typeinfo": "cpp",
+        "valarray": "cpp",
+        "variant": "cpp",
+        "__bit_reference": "cpp",
+        "__bits": "cpp",
+        "__config": "cpp",
+        "__debug": "cpp",
+        "__errc": "cpp",
+        "__hash_table": "cpp",
+        "__locale": "cpp",
+        "__mutex_base": "cpp",
+        "__node_handle": "cpp",
+        "__nullptr": "cpp",
+        "__split_buffer": "cpp",
+        "__string": "cpp",
+        "__threading_support": "cpp",
+        "__tree": "cpp",
+        "__tuple": "cpp",
+        "any": "cpp",
+        "ios": "cpp",
+        "locale": "cpp",
+        "queue": "cpp",
+        "stack": "cpp",
+        "__memory": "cpp",
+        "filesystem": "cpp",
+        "__availability": "cpp",
+        "version": "cpp"
+    },
+    "cSpell.words": [
+        "equidimensional",
+        "jaccard",
+        "ndim",
+        "simsimd",
+        "usearch"
+    ]
+}

package/.vscode/tasks.json

@@ -0,0 +1,35 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Linux Build C++ Bench Debug",
+            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DCMAKE_BUILD_TYPE=Debug -B ./build_debug && make bench -C ./build_debug",
+            "args": [],
+            "type": "shell",
+            "problemMatcher": [
+                "$gcc"
+            ]
+        },
+        {
+            "label": "Linux Build C++ Bench Release",
+            "command": "cmake -DCMAKE_CXX_COMPILER=gcc-12 -DCMAKE_CXX_COMPILER=g++-12 -DCMAKE_BUILD_TYPE=RelWithDebInfo -B ./build_release && make bench -C ./build_release",
+            "args": [],
+            "type": "shell",
+            "problemMatcher": [
+                "$gcc"
+            ]
+        },
+        {
+            "label": "MacOS Build C++ Bench Debug",
+            "command": "cmake -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ -DCMAKE_BUILD_TYPE=Debug -B ./build_debug && make bench -C ./build_debug",
+            "args": [],
+            "type": "shell",
+        },
+        {
+            "label": "MacOS Build C++ Bench Release",
+            "command": "cmake -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++ -DCMAKE_BUILD_TYPE=RelWithDebInfo -B ./build_release && make bench -C ./build_release",
+            "args": [],
+            "type": "shell"
+        }
+    ]
+}

package/CMakeLists.txt

@@ -0,0 +1,84 @@
+cmake_minimum_required(VERSION 3.11 FATAL_ERROR)
+project(usearch LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED YES)
+set(CMAKE_CXX_EXTENSIONS NO)
+
+option(USEARCH_USE_JEMALLOC "Use JeMalloc for Faster Memory Allocations" OFF)
+option(USEARCH_USE_OPENMP "Use OpenMP for a thread pool" OFF)
+
+# Make "Release" by default
+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 "${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 "${CMAKE_CXX_FLAGS} -fopenmp")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
+
+elseif(CMAKE_CXX_COMPILER_ID STREQUAL "NVIDIA" OR CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC")
+    set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} --expt-relaxed-constexpr --extended-lambda")
+    set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -gencode arch=compute_86,code=sm_86")
+    set_property(SOURCE src/bench.cpp PROPERTY LANGUAGE CUDA)
+    set_target_properties(bench PROPERTIES POSITION_INDEPENDENT_CODE ON)
+    set_target_properties(bench PROPERTIES CUDA_ARCHITECTURES "86")
+
+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")
+
+endif()
+
+if(APPLE)
+    set(CMAKE_THREAD_LIBS_INIT "-lpthread")
+    set(CMAKE_HAVE_THREADS_LIBRARY 1)
+    set(CMAKE_USE_WIN32_THREADS_INIT 0)
+    set(CMAKE_USE_PTHREADS_INIT 1)
+    set(THREADS_PREFER_PTHREAD_FLAG ON)
+endif()
+find_package(Threads REQUIRED)
+
+if(${USEARCH_USE_OPENMP})
+    find_package(OpenMP REQUIRED)
+    include_directories(${OPENMP_INCLUDE_DIRS})
+endif()
+
+if(${USEARCH_USE_JEMALLOC})
+    include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/jemalloc.cmake")
+endif()
+include("${CMAKE_CURRENT_SOURCE_DIR}/cmake/clipp.cmake")
+
+include_directories("${CMAKE_CURRENT_SOURCE_DIR}/include")
+include_directories("${CMAKE_CURRENT_SOURCE_DIR}/fp16/include")
+include_directories("${CMAKE_CURRENT_SOURCE_DIR}/simsimd/include")
+
+# Define our header-only library.
+add_library(usearch INTERFACE)
+target_sources(usearch INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/include/usearch/usearch.hpp")
+target_include_directories(usearch INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/include")
+
+# Define the targets
+add_executable(bench src/bench.cpp)
+target_link_libraries(bench PRIVATE Threads::Threads)
+if(${USEARCH_USE_OPENMP})
+    target_link_libraries(bench PRIVATE ${OPENMP_LIBRARIES})
+endif()
+if(${USEARCH_USE_JEMALLOC})
+    target_link_libraries(bench PRIVATE ${JEMALLOC_LIBRARIES})
+endif()

package/CMakeListsInstructuons.md

@@ -0,0 +1,109 @@
+# Compiling USearch
+
+## Build
+
+Before building the first time, please pull submodules.
+
+```sh
+git submodule update --init --recursive
+```
+
+### Linux
+
+```sh
+cmake -B ./build_release \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DUSEARCH_USE_OPENMP=1 \
+    -DUSEARCH_USE_JEMALLOC=1 && \
+    make -C ./build_release -j
+
+# To benchmark:
+./build_release/bench \
+    --vectors datasets/wiki_1M/base.1M.fbin \
+    --queries datasets/wiki_1M/query.public.100K.fbin \
+    --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin \
+    --ip
+```
+
+### MacOS
+
+```sh
+brew install libomp llvm
+cmake \
+    -DCMAKE_C_COMPILER="/opt/homebrew/opt/llvm/bin/clang" \
+    -DCMAKE_CXX_COMPILER="/opt/homebrew/opt/llvm/bin/clang++" \
+     -B ./build_release && \
+    make -C ./build_release -j
+
+# To benchmark:
+./build_release/bench \
+    --vectors datasets/wiki_1M/base.1M.fbin \
+    --queries datasets/wiki_1M/query.public.100K.fbin \
+    --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin \
+    --ip     
+```
+
+### Python
+
+```sh
+pip install -e .
+python src/test.py
+
+# To benchmark:
+python src/bench.py \
+    --vectors datasets/wiki_1M/base.1M.fbin \
+    --queries datasets/wiki_1M/query.public.100K.fbin \
+    --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin \
+    --ip 
+```
+
+### JavaScript
+
+```sh
+npm install
+node src/test.js
+npm publish
+```
+
+### JavaScript
+
+```sh
+cargo run
+```
+
+## Benchmarks
+
+### Datasets
+
+### Evaluation
+
+Yandex Text-to-Image embeddings.
+
+```sh
+export path_vectors=datasets/t2i_1M/base.1M.fbin
+export path_queries=datasets/t2i_1M/query.public.100K.fbin
+export path_neighbors=datasets/t2i_1M/groundtruth.public.100K.ibin
+./build_release/bench
+```
+
+Wikipedia UForm embeddings.
+
+```sh
+export path_vectors=datasets/wiki_1M/base.1M.fbin
+export path_queries=datasets/wiki_1M/query.public.100K.fbin 
+export path_neighbors=datasets/wiki_1M/groundtruth.public.100K.ibin
+./build_release/bench
+```
+
+### Profiling
+
+With `perf`:
+
+```sh
+# Pass environment variables with `-E`, and `-d` for details
+sudo -E perf stat -d ./build_release/bench
+sudo -E perf mem -d ./build_release/bench
+# Sample on-CPU functions for the specified command, at 1 Kilo Hertz:
+sudo -E perf record -F 1000 ./build_release/bench
+perf record -d -e arm_spe// -- ./build_release/bench
+```