Benchmarks and analysis of exact vector search algorithms and implementations.
Install the package:
uv add vector-search-studyBuild a normalized corpus and run deterministic exact top-k search:
import numpy as np
from vector_search_study import NumpyArgpartitionSearcher, SearchObjective, normalize_rows
corpus = normalize_rows(np.asarray([[1.0, 0.0], [0.0, 1.0]], dtype=np.float32))
queries = normalize_rows(np.asarray([[0.8, 0.2]], dtype=np.float32))
index = NumpyArgpartitionSearcher(corpus, objective=SearchObjective.NORMALIZED_COSINE)
result = index.search(queries, k=1)
print(result.indices) # [[0]]Every implementation returns scores in descending order and resolves exact
ties by the smaller corpus index. Prepare queries once with prepare_queries
and call search_prepared when query validation and copying must stay outside
a timed operation.
The suite supports negative squared L2, inner product, and normalized cosine. It includes pure-Python and NumPy implementations plus optional exact adapters for scikit-learn brute/KDTree/BallTree, SciPy cKDTree, Faiss Flat L2/IP, and CPU PyTorch matmul/topk. Unsupported objective/backend pairings are omitted explicitly rather than approximated.
Install the optional backends and run the tiny correctness-guarded benchmark harness with:
make benchmark-smokeThe full discovery catalog is deliberately not a Cartesian product. It uses a 33-case one-factor core split into 24 standard and nine filtered stress cases, plus a 12-case small profile. Scalable untimed oracles validate every measured cell and persist result digests in raw artifacts. See the benchmark design before collecting data.
The research workflow can collect the complete study from a clean revision, audit and summarize raw artifacts, render source-backed tables and static plots, and run predeclared paired AB/BA experiments under a common benchmark identity. Precision pilots and fresh confirmatory samples are kept separate. See the statistical workflow before interpreting generated reports.
On Intel macOS, use the linux/amd64 devcontainer to run CPU PyTorch and every
other optional backend. See development for the
real-backend and artifact-preserving smoke commands.
For local development from this repository:
make readyThe documentation source lives under docs/. The MkDocs site builds in
strict mode and generates API reference pages from package docstrings.
| Start here | Use it for |
|---|---|
| Development | Local setup, test commands, and repository layout. |
| Tooling | The validation, release, and automation stack. |
| API reference | Generated package API pages. |
| Release runbook | Release metadata and publishing workflow. |
Vector Search Study is distributed under the MIT license.