Crate turbovec 

TurboQuant implementation for vector search.

Compresses high-dimensional vectors to 2-4 bits per coordinate with near-optimal distortion. Data-oblivious — no training required.

use turbovec::TurboQuantIndex;

// 1536-dim vectors compressed to 4 bits per coordinate.
let mut index = TurboQuantIndex::new(1536, 4).unwrap();

// `vectors` is a flat [f32] of length n * dim, `queries` likewise.
let vectors: Vec<f32> = vec![0.0; 1536 * 10];
let queries: Vec<f32> = vec![0.0; 1536 * 2];

index.add(&vectors);
let results = index.search(&queries, 10);
index.write("index.tv").unwrap();
let loaded = TurboQuantIndex::load("index.tv").unwrap();

Concurrent search

search takes &self and is safe to call from multiple threads concurrently. Internally the rotation matrix, the Lloyd-Max centroids and the SIMD-blocked code layout are initialised lazily via std::sync::OnceLock, so the first caller pays the one-time initialisation cost and every subsequent caller reads the caches without locking. TurboQuantIndex::prepare can be called once after add/load to pay that cost up front.

Mutation still flows through &mut self: add extends the packed codes and invalidates the blocked layout cache by replacing its OnceLock. This keeps the invariant that once a cache is populated from &self, it matches the current packed_codes.

Re-exports

pub use error::AddError;

pub use error::ConstructError;

pub use id_map::IdMapIndex;

Modules

codebook

Lloyd-Max scalar quantizer for the Beta distribution.

encode

Encode vectors: normalize, rotate, calibrate, quantize, bit-pack, scale.

error

Errors returned by the user-facing add and construct paths.

id_map

Stable external IDs on top of TurboQuantIndex.

io

Read/write TurboVec index files.

pack

Bit-plane to SIMD-blocked layout repacking.

rotation

Random orthogonal rotation matrix generation.

search

SIMD-accelerated search pipeline.

Structs

SearchResults

TurboQuantIndex

Constants

MAX_DIM

Upper bound on vector dimensionality. search/prepare lazily build a dim×dim f64 rotation matrix, an allocation that scales with dim² and is NOT bounded by the size of any loaded file — so an untrusted .tv/.tvim declaring a huge dim could otherwise drive a multi-gigabyte allocation (resource-exhaustion DoS) from a tiny file. 65536 is far above any real embedding dimension (largest in common use is ~4096) and rejects the catastrophic cases. Enforced at construction, first add, and load.

Functions

first_invalid_coord

Reject non-finite (NaN, +Inf, -Inf) or extremely-large input values. Returns the first offending vector/coord/value tuple, or None if the input is clean.