Struct FibQuantizer 

pub struct FibQuantizer { /* private fields */ }

FibQuant encoder/decoder bound to one profile and codebook.

Implementations

impl FibQuantizer

pub fn new(profile: FibQuantProfileV1) -> Result<Self>

Build a quantizer by constructing the profile codebook.

pub fn from_codebook(codebook: FibCodebookV1) -> Result<Self>

Build a quantizer from a validated codebook.

pub fn profile(&self) -> &FibQuantProfileV1

Access the profile.

pub fn codebook(&self) -> &FibCodebookV1

Access the codebook.

pub fn rotation(&self) -> &StoredRotation

Access the stored rotation. Exposed so downstream consumers (scoring, residual, compat) don’t need to reconstruct it from the seed — saves an O(dim²) QR decomposition per call.

pub fn codebook_digest(&self) -> &str

Return the codebook digest (BLAKE3 hex of the codebook). Convenience accessor so downstream consumers (poly-kv, scr-runtime) don’t need to access the codebook field chain directly.

pub fn rotation_digest(&self) -> &str

Return the rotation digest (BLAKE3 hex of the rotation matrix).

pub fn nominal_compression_ratio(&self) -> f64

Nominal compression ratio (original_bytes / encoded_bytes) for the compact binary wire format at this profile’s default operating point. This is a theoretical ratio: (ambient_dim * 4) / compact_size(). Actual ratio depends on the vector data (norm magnitude, codebook index distribution).

pub fn default_degradation_threshold(&self) -> f64

Default degradation threshold for this codec — the maximum reconstruction MSE beyond which the compressed artifact should be considered degraded and exact fallback should be used. Based on empirical P26 measurements at k=4, N=32.

pub fn is_high_fidelity(&self) -> bool

Whether this codec is high-fidelity (cosine > 0.85 at default operating point). Used by quant-governor for routing decisions.

pub fn encode(&self, x: &[f32]) -> Result<FibCodeV1>

Encode a vector into a fixed-rate artifact.

pub fn decode(&self, code: &FibCodeV1) -> Result<Vec<f32>>

Decode a fixed-rate artifact.

pub fn encode_with_receipt( &self, x: &[f32], ) -> Result<(FibCodeV1, FibQuantCompressionReceiptV1)>

Encode and emit a receipt.

pub fn reconstruction_mse(&self, x: &[f32]) -> Result<f64>

Reconstruction MSE for one vector.

pub fn cosine_similarity(&self, x: &[f32]) -> Result<f64>

Reconstruction cosine similarity for one vector.

pub fn encode_batch(&self, vectors: &[&[f32]]) -> Result<Vec<FibCodeV1>>

Encode a batch of vectors. Uses gpu-backend for the Hadamard + Lloyd-Max portions when available, keeping the FibCodeV1 format identical to single encode.

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

Decode a batch of codes.

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

Fast batch decode. Optimized for the case where many small codes share the same profile (so the codebook + rotation are reused).

Key wins over decode_batch:

1. No per-index Vec<f64> allocation in the codeword gather — each codeword is copied in place into a single Vec<f32>.
2. The rotation matrix is converted to f32 once for the whole batch, then apply_inverse_f32 is called per code (no f32→f64 roundtrip on the rotation or the input).
3. The unpacked indices are reused via as_f32_slice() where possible.

Output is byte-identical to calling decode per code, modulo the final as f32 cast in decode (we also cast to f32 at the end; intermediate precision is below the codebook quantization noise floor and matches the original as f32 step exactly).

pub fn encode_layers( &self, layer_vectors: &[&[&[f32]]], ) -> Result<Vec<Vec<FibCodeV1>>>

Encode vectors across multiple KV-cache layers in one call.

This is an optimization for the multi-layer KV-cache case where layers slices of n vectors each share the same profile. The codebook and rotation are constructed once and reused across all layers, avoiding the per-layer quantizer rebuild that the naive encode_batch loop would incur.

layer_vectors is organized as [layer][vector][dim]. Each inner slice must have length ambient_dim. Returns [layer][vector] of FibCodeV1.

pub fn is_gpu_accelerated(&self) -> bool

Check if GPU acceleration is available.

This is a device-availability probe: it returns true if a CUDA device was found at init time. Whether an individual encode_batch call actually dispatches to GPU depends on the call’s batch size and vector dimension crossing the runtime thresholds.

Use Self::is_gpu_accelerated_for for an honest per-call check.

pub fn is_gpu_accelerated_for(&self, n: usize, d: usize) -> bool

Check if a batch of n vectors of dimension d would actually dispatch to GPU. Returns true only when:

• the gpu feature is compiled in,
• a CUDA device is available at runtime,
• n >= GPU_MIN_BATCH_SIZE and d >= GPU_MIN_DIM, AND
• the codebook size N is <= 32 (the codebook_lookup kernel is one warp wide and falls back to CPU otherwise).

This is the honest gate for receipts: a 4-doc corpus with dim 64 returns false even with --features gpu, because the batch is too small to overcome GPU launch overhead. A corpus with a codebook larger than 32 also returns false.

pub fn gpu_steps_for(&self, n: usize, d: usize) -> GpuStepReport

Per-step GPU dispatch report. hadamard is true if a batch of size n at dim d would dispatch the Hadamard rotation to GPU. codebook_lookup is true only if both the Hadamard AND the codebook-lookup step would dispatch (additionally requires codebook size <= 32). The latter is independent of the gpu_codebook_lookup feature gate — the feature controls whether the dispatch is enabled in encode_batch, not whether the kernel would be a win.

Trait Implementations

impl Clone for FibQuantizer

fn clone(&self) -> FibQuantizer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FibQuantizer

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

Formats the value using the given formatter.

impl VectorCodec for FibQuantizer

type EncodedBlock = FibCodeV1

type Error = QuantCodecError

fn encode_block(&self, input: &[f32]) -> Result<Self::EncodedBlock, Self::Error>

fn decode_block( &self, block: &Self::EncodedBlock, out: &mut [f32], ) -> Result<(), Self::Error>