Struct FibScorer 

pub struct FibScorer { /* private fields */ }

Approximate scorer for FibQuant codes.

Wraps a FibQuantizer with a precomputed Gram table. The scorer can estimate inner products between a raw query vector and a stored FibCodeV1 without decoding the stored code.

The scorer is cheap to construct (~1ms for N=32, k=4) and the Gram table is cached for the lifetime of the scorer.

Implementations

impl FibScorer

pub fn new(quantizer: FibQuantizer) -> Result<Self>

Build a scorer from a quantizer. Computes the Gram table once.

pub fn quantizer(&self) -> &FibQuantizer

Get a reference to the underlying quantizer.

pub fn gram_table(&self) -> &GramTable

Get a reference to the Gram table.

pub fn inner_product_estimate( &self, query: &[f32], code: &FibCodeV1, ) -> Result<f32>

Estimate the inner product <query, stored_vector> where stored_vector is represented by code.

This does NOT decode the stored vector. It:

1. Normalizes the query, applies the rotation.
2. For each block, finds the nearest codeword index for the query.
3. Looks up G[query_idx, stored_idx] from the Gram table.
4. Sums block-level estimates and scales by the stored norm.

Returns the approximate inner product.

pub fn score_batch( &self, query: &[f32], codes: &[FibCodeV1], ) -> Result<Vec<ScoredItem>>

Score a batch of stored codes against a single query.

Returns Vec<(idx, score)> sorted by descending score.

pub fn search( &self, query: &[f32], codes: &[FibCodeV1], top_k: usize, oversample: usize, ) -> Result<Vec<ScoredItem>>

Search the top-K closest codes to a query, with optional oversampling.

Returns the top-K ScoredItems by approximate inner product. oversample > 1 returns more candidates than top_k for downstream exact reranking.

pub fn prepare_query(&self, query: &[f32]) -> Result<FibPreparedQuery>

Prepare a query for batch scoring.

Normalizes the query, applies the rotation, converts to f32, and precomputes the nearest-codeword index for each block. The resulting FibPreparedQuery can be passed to score_prepared, score_batch_prepared, or search_prepared to avoid recomputing the rotation and argmin for every code in a batch.

pub fn score_prepared( &self, prepared: &FibPreparedQuery, code: &FibCodeV1, ) -> Result<f32>

Score a single code against a prepared query.

This skips the rotation and argmin steps (already done in prepare_query) and only performs:

1. Unpack the stored code’s indices.
2. For each block: Gram table lookup G[query_idx, stored_idx].
3. Sum and scale by query_norm * stored_norm.

pub fn score_batch_prepared( &self, prepared: &FibPreparedQuery, codes: &[FibCodeV1], ) -> Result<Vec<ScoredItem>>

Score a batch of codes against a prepared query.

Like score_batch but uses the pre-rotated query, avoiding redundant rotation + argmin per code. Returns Vec<ScoredItem> sorted by descending score.

pub fn search_prepared( &self, prepared: &FibPreparedQuery, codes: &[FibCodeV1], top_k: usize, oversample: usize, ) -> Result<Vec<ScoredItem>>

Search top-K closest codes to a prepared query, with optional oversampling.

Like search but uses the pre-rotated query.

pub fn l2_distance_sq_estimate( &self, query: &[f32], code: &FibCodeV1, ) -> Result<f32>

Estimate L2 distance ||query - stored|| without decoding the stored vector.

Uses the identity: ||q - v||^2 = ||q||^2 + ||v||^2 - 2<q, v> where <q, v> is the approximate inner product from the Gram table. Returns the estimated squared L2 distance (avoiding a sqrt for comparison purposes — callers can sqrt if needed).

pub fn cosine_estimate(&self, query: &[f32], code: &FibCodeV1) -> Result<f32>

Estimate cosine similarity <query, stored> / (||query|| * ||stored||) without decoding the stored vector.

pub fn l2_distance_sq_prepared( &self, prepared: &FibPreparedQuery, code: &FibCodeV1, ) -> Result<f32>

L2 distance using a prepared query — avoids recomputing query rotation.

pub fn cosine_prepared( &self, prepared: &FibPreparedQuery, code: &FibCodeV1, ) -> Result<f32>

Cosine similarity using a prepared query.