Struct ResidualCodebookV1 

pub struct ResidualCodebookV1 {
    pub schema_version: String,
    pub size: u32,
    pub block_dim: u32,
    pub codewords: Vec<f32>,
    pub codebook_digest: String,
}

A residual codebook — a small set of codewords for encoding the quantization residual from the main codebook.

Fields

schema_version: String

Stable schema marker.

size: u32

Number of residual codewords (typically 4-8).

block_dim: u32

Block dimension (must match the main codebook’s block_dim).

codewords: Vec<f32>

Row-major size × block_dim f32 codewords.

codebook_digest: String

Digest of the residual codebook.

Implementations

impl ResidualCodebookV1

pub fn build( profile: &FibQuantProfileV1, main_codebook: &FibCodebookV1, ) -> Result<Self>

Build a deterministic residual codebook.

The residual codebook is seeded from the main profile’s codebook_seed with a fixed offset. It uses a small set of unit-length directions scaled by a fraction of the expected residual magnitude.

pub fn train( profile: &FibQuantProfileV1, main_codebook: &FibCodebookV1, training_vectors: &[Vec<f32>], num_codewords: usize, ) -> Result<Self>

Train a residual codebook using Lloyd-Max on the residual distribution.

Collects residuals after encoding training vectors with the main codebook, then runs Lloyd-Max refinement to find optimal residual codewords adapted to the actual residual distribution (instead of random directions).

Arguments

• profile - The quantization profile (provides dims, rotation, seed).
• main_codebook - The main codebook to compute residuals against.
• training_vectors - Full ambient-dim training vectors (will be normalized + rotated).
• num_codewords - Number of residual codewords to train.

pub fn validate(&self) -> Result<()>

Validate the residual codebook.

pub fn nearest(&self, residual: &[f32]) -> Result<u32>

Find the nearest residual codeword for a given residual block.

pub fn codeword(&self, index: u32) -> Result<&[f32]>

Get a residual codeword by index.

pub fn bits_per_index(&self) -> u8

Bits per residual index.

Trait Implementations

impl Clone for ResidualCodebookV1

fn clone(&self) -> ResidualCodebookV1

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ResidualCodebookV1

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ResidualCodebookV1

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ResidualCodebookV1

fn eq(&self, other: &ResidualCodebookV1) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ResidualCodebookV1

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ResidualCodebookV1