Crate ruvector_turboquant 

ruvector-turboquant

Turbo4: a 4-bit Lloyd-Max quantized vector datatype (ADR-296) — Qdrant-style primary-storage quantization, not a search-time cache:

• deterministic randomized Hadamard rotation (sign ⊙ permute ⊙ block-FWHT rounds, seeded SplitMix64 — bit-stable across platforms and versions, no rand dependency);
• precomputed 16-level Lloyd-Max tables for the rotated (≈ Gaussian) coordinates — no training pass, online ingest;
• packed nibble codes: D/2 + 8 bytes per vector (≈ 7.9× vs f32 at 1536-D) — the original float vector is never stored;
• direct scoring on packed codes: symmetric (code×code, for graph construction), asymmetric (int8 query×code, for traversal), and exact f32 rescoring — with runtime-dispatched AVX2 kernels and a scalar oracle they are tested bit-exact against.

use ruvector_turboquant::{Metric, Turbo4Codec, score};

let dim = 128;
let codec = Turbo4Codec::new(dim, 42).unwrap();
let a: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.37).sin()).collect();
let b: Vec<f32> = (0..dim).map(|i| (i as f32 * 0.11).cos()).collect();

let code_a = codec.encode(&a).unwrap();   // 64 + 8 bytes, floats discarded
let code_b = codec.encode(&b).unwrap();
let query = codec.encode_query(&a).unwrap();

let d_sym = score::symmetric_distance(Metric::Euclidean, &code_a, &code_b, dim);
let d_asym = score::asymmetric_distance(Metric::Euclidean, &query.blob, &code_b, dim);
let d_exact = score::rescore(Metric::Euclidean, &query, &code_b, dim);
assert!((d_asym - d_sym).abs() < 0.15 * d_sym.max(1.0));
assert!((d_exact - d_asym).abs() < 0.1 * d_asym.max(1.0));

Re-exports

pub use bits1::encode_bits;

pub use bits1::Bits1Query;

pub use codec::Turbo4Codec;

pub use codec::Turbo4Query;

pub use codec::META_BYTES;

pub use rotation::Rotation;

pub use score::asymmetric_distance;

pub use score::rescore;

pub use score::symmetric_distance;

pub use score::Metric;

Modules

bits1

1-bit sign codes over the Turbo4 rotation (ADR-297 phase C).

codec

Turbo4 encoder: rotated, standardized, 4-bit Lloyd-Max packed codes.

rotation

Deterministic randomized rotation for Turbo4 codes (ADR-296).

score

Metric scoring over Turbo4 blobs — no f32 reconstruction, ever.

simd

Integer dot-product kernels over packed Turbo4 codes.

tables

Precomputed Lloyd-Max tables for the 4-bit (16-level) quantizer.

Enums

TurboQuantError

Errors from the Turbo4 codec.