Skip to main content

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:

  1. Random Rotation: Input vectors are multiplied by a random orthogonal matrix, transforming coordinates to follow a known Beta distribution
  2. Lloyd-Max Scalar Quantization: Each coordinate is independently quantized using a precomputed optimal codebook for the Beta distribution
  3. 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: QuantizedMSE dataclass

dequantize_mse(quantized)

Reconstruct vectors from MSE quantization result.

  • quantized: QuantizedMSE — output of quantize_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: QuantizedProd dataclass

dequantize_prod(quantized)

Reconstruct vectors from Prod quantization result.

  • quantized: QuantizedProd — output of quantize_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)

Source distribution for pyturboquant-cpu 0.1.0
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)

Table of built distributions (wheels) for pyturboquant-cpu 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page