Struct Codebook 

pub struct Codebook { /* private fields */ }

Immutable lookup table mapping quantized u8 indices to f32 values.

Construction always validates three invariants:

1. entries.len() == 1 << bit_width (matches CodecConfig::num_codebook_entries).
2. Entries are strictly ascending under f32::total_cmp.
3. All entries are distinct (no adjacent equals).

The inner buffer is an Arc<[f32]> so Clone is O(1). Equality compares the numerical contents, not the allocation identity.

Implementations

impl Codebook

pub fn new(entries: Box<[f32]>, bit_width: u8) -> Result<Self, CodecError>

Build a codebook from a caller-owned Box<[f32]>.

Errors

• CodecError::CodebookEntryCount — entries.len() does not equal 2^bit_width.
• CodecError::CodebookNotSorted — entries are not in strictly ascending order (excluding duplicates).
• CodecError::CodebookDuplicate — two adjacent entries compare equal.

pub fn train(vectors: &[f32], config: &CodecConfig) -> Result<Self, CodecError>

Train a codebook by uniform-quantile estimation over a flattened f32 sample buffer.

Mirrors Python’s np.quantile(flat.astype(np.float64), np.linspace(0, 1, num_entries)).astype(np.float32) exactly:

1. Promote every sample to f64.
2. Sort with f64::total_cmp.
3. For each k in 0..num_entries, compute the linearly- interpolated quantile value in f64.
4. Cast to f32 (round-to-nearest-even) and enforce distinctness.

config.bit_width determines the number of entries; config.seed and config.dimension are not consulted by this function.

Errors

• CodecError::InsufficientTrainingData — vectors is empty or produces fewer than num_entries distinct quantile representatives.
• Any error from Codebook::new on the freshly-built entries.

pub fn num_entries(&self) -> u32

Number of entries (2^bit_width).

pub const fn bit_width(&self) -> u8

The bit width this codebook was built for.

pub fn entries(&self) -> &[f32]

Borrow the underlying sorted entries.

pub fn quantize_into( &self, values: &[f32], indices: &mut [u8], ) -> Result<(), CodecError>

Quantize values into indices by finding the nearest entry for each value. Ties favor the right (higher-valued) neighbor, matching Python’s strict < tie-break.

Under feature = "simd" this delegates to [crate::codec::simd_api::quantize_into], which is the single source of truth for dispatch selection. Without the feature, it calls the scalar reference kernel directly.

Errors

• CodecError::LengthMismatch — values.len() != indices.len().

pub fn dequantize_into( &self, indices: &[u8], values: &mut [f32], ) -> Result<(), CodecError>

Dequantize indices into values by gathering the corresponding codebook entries.

Under feature = "simd" this delegates to [crate::codec::simd_api::dequantize_into].

Errors

• CodecError::LengthMismatch — indices.len() != values.len().
• CodecError::IndexOutOfRange — any index is >= num_entries().

pub fn quantize(&self, values: &[f32]) -> Result<Vec<u8>, CodecError>

Convenience: allocate and return the quantized indices.

Errors

See Codebook::quantize_into.

pub fn dequantize(&self, indices: &[u8]) -> Result<Vec<f32>, CodecError>

Convenience: allocate and return the dequantized values.

Errors

See Codebook::dequantize_into.

Trait Implementations

impl Clone for Codebook

fn clone(&self) -> Codebook

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Codebook

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

Formats the value using the given formatter.

impl PartialEq for Codebook

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.