pyturboquant-cpu
CPU implementation of TurboQuant, a data-oblivious vector quantization algorithm for compressing high-dimensional vectors with near-optimal distortion.
Based on the paper: TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate (Zandieh et al., ICLR 2026).
Installation
pip install pyturboquant-cpu
For development:
git clone https://github.com/pyturboquant/pyturboquant-cpu.git
cd pyturboquant-cpu
pip install -e ".[dev]"
Quick Start
MSE-Optimal Quantization
Minimizes mean-squared reconstruction error:
import numpy as np
from pyturboquant_cpu import quantize_mse, dequantize_mse
# Random vectors (e.g., KV cache embeddings)
vectors = np.random.randn(100, 128) # 100 vectors of dimension 128
# Quantize at 3 bits per coordinate
quantized = quantize_mse(vectors, bits=3, seed=42)
# Reconstruct
reconstructed = dequantize_mse(quantized)
# Check reconstruction quality
mse = np.mean(np.sum((vectors - reconstructed) ** 2, axis=1))
print(f"MSE: {mse:.4f}")
Inner-Product-Optimal Quantization
Provides unbiased inner product estimates — essential for attention mechanisms and nearest-neighbor search:
from pyturboquant_cpu import quantize_prod, dequantize_prod
# Quantize at 4 bits total (3 bits MSE + 1 bit QJL correction)
quantized = quantize_prod(vectors, bits=4, seed=42)
reconstructed = dequantize_prod(quantized)
# Inner products are unbiased: E[⟨y, x̃⟩] = ⟨y, x⟩
query = np.random.randn(128)
true_ip = vectors @ query
approx_ip = reconstructed @ query
print(f"Mean IP error: {np.mean(np.abs(true_ip - approx_ip)):.4f}")
How It Works
TurboQuant is a data-oblivious algorithm — it requires no training data or calibration:
- Random Rotation: Input vectors are multiplied by a random orthogonal matrix, transforming coordinates to follow a known Beta distribution
- Lloyd-Max Scalar Quantization: Each coordinate is independently quantized using a precomputed optimal codebook for the Beta distribution
- QJL Residual Correction (Prod mode only): A 1-bit Quantized Johnson-Lindenstrauss sketch of the residual removes inner-product bias
Theoretical Distortion Bounds
For unit vectors on S^{d-1}:
| Bits | MSE Distortion | Inner Product Distortion |
|---|---|---|
| 1 | ≈ 0.36 | ≈ 1.57/d |
| 2 | ≈ 0.117 | ≈ 0.56/d |
| 3 | ≈ 0.03 | ≈ 0.18/d |
| 4 | ≈ 0.009 | ≈ 0.047/d |
These are within a factor of ~2.7× of the information-theoretic lower bound.
API Reference
quantize_mse(vectors, bits, dim=None, seed=None)
Quantize vectors using TurboQuant_MSE (MSE-optimal).
- vectors: array of shape
(..., d)— input vectors - bits: int in
[1, 8]— bits per coordinate - seed: int or None — random seed for reproducibility
- Returns:
QuantizedMSEdataclass
dequantize_mse(quantized)
Reconstruct vectors from MSE quantization result.
- quantized:
QuantizedMSE— output ofquantize_mse - Returns: ndarray with same shape as original input
quantize_prod(vectors, bits, dim=None, seed=None)
Quantize vectors using TurboQuant_Prod (unbiased inner products).
- vectors: array of shape
(..., d)— input vectors - bits: int in
[2, 8]— total bits per coordinate - seed: int or None — random seed
- Returns:
QuantizedProddataclass
dequantize_prod(quantized)
Reconstruct vectors from Prod quantization result.
- quantized:
QuantizedProd— output ofquantize_prod - Returns: ndarray with same shape as original input
GPU Version
For GPU-accelerated quantization using PyTorch, see the companion package:
pip install pyturboquant-gpu
Citation
@article{zandieh2025turboquant,
title={TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate},
author={Zandieh, Amir and Daliri, Majid and Hadian, Majid and Mirrokni, Vahab},
journal={arXiv preprint arXiv:2504.19874},
year={2025}
}
License
Apache 2.0
Metadata
Release files for pyturboquant-cpu 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyturboquant_cpu-0.1.0.tar.gz | 22.3 kB | With provenance | Details for pyturboquant_cpu-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyturboquant_cpu-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pyturboquant_cpu-0.1.0-py3-none-any.whl |
Total release size: 39.2 kB
Release files / pyturboquant_cpu-0.1.0.tar.gz
| Download URL | pyturboquant_cpu-0.1.0.tar.gz |
|---|---|
| Size | 22.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca3806fc689a311c115fbfd0acd1d2c1812392bade568fbf7486c00329feefa7
|
|
BLAKE2b-256 checksum How to use checksums |
f26c8e28159ec3b0f10c831d49796c66d2d2bd3dc69d74b2e87fd40fba77e9cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / pyturboquant_cpu-0.1.0-py3-none-any.whl
| Download URL | pyturboquant_cpu-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
281a87ac8425d84349322c63e37d303f3cbad42e3b2f45447cac5340c08900a5
|
|
BLAKE2b-256 checksum How to use checksums |
a2b94cf1f0c5e9adb4c230223506aa2c15261014d13fe8cde87830fcd8a54b55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logSecurity for pyturboquant-cpu 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pyturboquant_cpu-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.