Portable Mixed-Precision BLAS-like Vector Math Library

6.5.16 · active · verified Thu Apr 09

SimSIMD is a highly optimized, mixed-precision math library providing over 350 SIMD-accelerated kernels for common vector similarity functions and dot-products. It is extensively used in AI, Search, and Database Management Systems workloads to achieve significant performance and accuracy improvements over standard NumPy and SciPy operations. The library is actively developed with frequent releases, though its main development has transitioned to a new project name, NumKong, starting with version 7.x.x.

Warnings

breaking The project `simsimd` has been renamed to `NumKong` starting from its major version 7.x.x. While `simsimd` 6.5.16 is available on PyPI, users seeking the latest features and fixes (v7.x.x) should refer to `NumKong`. This change introduces significant breaking API changes, including function renames (e.g., 'cosine' to 'angular') and altered data structures.
Fix: For new projects or major upgrades, consider migrating to `NumKong` and carefully review its documentation for updated API calls and data types. For existing `simsimd` 6.x.x projects, remain on the `simsimd` package or plan a full migration.
gotcha Older versions of `simsimd` (pre-v7.3.0 on GitHub, which corresponds to versions prior to the latest PyPI release `6.5.16`) contained a correctness bug in Arm Scalable Vector Extension (SVE) kernels. Specifically, `_x` (don't-care) predicated intrinsics could carry stale data, leading to incorrect results for non-power-of-two dimensions on real SVE hardware.
Fix: Upgrade to the latest available version of `simsimd` or `NumKong` to benefit from the corrected Arm SVE kernels, especially if deploying on Arm-based systems with SVE support.
gotcha When installing `simsimd` from source (i.e., when pre-built wheels are not available for your environment), older versions sometimes encountered a `FileNotFoundError: 'VERSION'` error during the build process. This issue was related to how the version was read during `pip install .` without wheels.
Fix: Ensure `pip` is up-to-date. If encountering this, try installing a specific known-working version (e.g., `5.5.1` as a historical workaround) or ensure your environment can use pre-built wheels. Cloning the repository and installing with `pip install .` might also be a workaround if the version file exists in the cloned repo. For current versions, this should be resolved by the use of `pyproject.toml`.

Install

pip install simsimd Install stable version

Imports

simsimd
```
import simsimd
```
Functions are directly available on the imported `simsimd` module, e.g., `simsimd.cosine()` or `simsimd.cdist()`.

Quickstart

This example demonstrates how to calculate various vector similarity metrics (cosine, squared Euclidean, inner product) between two NumPy arrays using SimSIMD. Ensure NumPy is installed as it's commonly used for array creation, although not a direct dependency of SimSIMD.

import simsimd
import numpy as np

# Create two random 1536-dimensional vectors for demonstration
vec1 = np.random.randn(1536).astype(np.float32)
vec2 = np.random.randn(1536).astype(np.float32)

# Calculate cosine similarity
distance = simsimd.cosine(vec1, vec2)
print(f"Cosine distance: {distance}")

# Calculate squared Euclidean distance
distance_sqeuclidean = simsimd.sqeuclidean(vec1, vec2)
print(f"Squared Euclidean distance: {distance_sqeuclidean}")

# Calculate inner product
inner_product = simsimd.inner(vec1, vec2)
print(f"Inner product: {inner_product}")

view raw JSON →