Struct VecqIndex 

pub struct VecqIndex { /* private fields */ }

A quantized vector database in memory.

Each vector is stored as padded_dim / 2 bytes of 4-bit Lloyd-Max codes (computed after RHDH rotation) plus one f32 correction factor. The score against an f32 query is an unbiased estimate of the cosine similarity after undoing the per-vector quantization scale.

Implementations

impl VecqIndex

pub fn to_bytes(&self) -> Vec<u8>

Serialize the index to bytes (format version 1.1, f16 scales).

pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

Parse an index from bytes produced by [to_bytes] (or a v1 file).

impl VecqIndex

pub fn new(dim: usize, seed: u64) -> Self

Create an empty index for dim-dimensional unit vectors. seed must be persisted with the index for cross-platform determinism.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn dim(&self) -> usize

pub fn seed(&self) -> u64

pub fn add(&mut self, v: &[f32])

Quantize and add one vector (any norm; normalized internally).

pub fn prepare_query(&self, q: &[f32]) -> PreparedQuery

Prepare an f32 query in rotated space (call once per query).

pub fn score(&self, pq: &PreparedQuery, idx: usize) -> f32

Asymmetric score of vector idx against a prepared query. Returns estimated cosine similarity in [-1, 1].

Dispatches to the explicit NEON path on aarch64 and the fixed 8-bucket scalar path elsewhere. Both use the identical association order (per code byte: mul, mul, add, then add into bucket j; final pairwise tree), so they produce the same f32 bits — guarded by neon_matches_scalar_bitwise in tests.

pub fn search(&self, q: &[f32], k: usize) -> Vec<(usize, f32)>

Brute-force top-k search. Returns (index, score) sorted by score desc.

Uses a bounded min-heap of size k (no O(n log n) sort, no O(n) allocation per query): push while the heap is not full, then only push-and-pop when the candidate beats the current k-th score.