Struct RaBitQIndex 

pub struct RaBitQIndex {
    pub rotation: Vec<f32>,
    pub centroid: Vec<f32>,
    pub dimension: usize,
}

RaBitQ index holding the random rotation matrix and dataset centroid.

Fields

rotation: Vec<f32>

Random orthogonal rotation matrix (flattened D x D, row-major).

centroid: Vec<f32>

Dataset centroid for centering.

dimension: usize

Vector dimension.

Implementations

impl RaBitQIndex

pub fn encode(&self, vector: &[f32]) -> Result<RaBitQVector, Error>

Encode a vector into a RaBitQVector.

Steps:

1. Center the vector (subtract centroid).
2. Compute the L2 norm of the centered vector.
3. Normalize (handle zero-norm gracefully).
4. Apply rotation matrix.
5. Extract sign bits into u64 words.
6. Compute correction factors.

Errors

Returns Error::InvalidQuantizerConfig if vector dimension mismatches.

pub fn distance(&self, query: &[f32], encoded: &RaBitQVector) -> f32

Estimate the L2 distance between a raw query vector and an encoded vector.

Uses XOR + popcount for fast Hamming-based inner product estimation, then applies affine correction with stored norms.

pub fn batch_distance( &self, query: &[f32], encoded: &[RaBitQVector], ) -> Vec<f32>

Batch distance: process query once, then iterate over encoded vectors.

Amortizes query preprocessing (centering, normalization, rotation, sign extraction).

impl RaBitQIndex

Training and persistence methods (require persistence feature for rayon).

pub fn train(vectors: &[Vec<f32>], seed: u64) -> Result<Self, Error>

Train a RaBitQ index from a set of vectors.

Computes dataset centroid and generates a random orthogonal rotation matrix via modified Gram-Schmidt orthogonalization of a random matrix.

Errors

Returns Error::InvalidQuantizerConfig if:

• vectors is empty
• vectors have inconsistent dimensions
• vector dimension is 0

pub fn save(&self, dir: &Path) -> Result<(), Error>

Save RaBitQ index to <dir>/rabitq.idx using postcard with atomic write.

Errors

Returns Error::Io if serialization or file I/O fails.

pub fn load(dir: &Path) -> Result<Option<Self>, Error>

Load RaBitQ index from <dir>/rabitq.idx. Returns None if file doesn’t exist.

The decoded index is validated (validate_loaded) so a corrupt rotation/centroid is rejected here rather than producing out-of-bounds indexing in apply_rotation_flat during search.

Errors

Returns Error::Io if deserialization or file I/O fails, or Error::IndexCorrupted if the file exceeds the size cap or the decoded rotation/centroid lengths are inconsistent with dimension.

Trait Implementations

impl Clone for RaBitQIndex

fn clone(&self) -> RaBitQIndex

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RaBitQIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RaBitQIndex

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RaBitQIndex

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.