Struct EntropyConstrainedQuantizer 

pub struct EntropyConstrainedQuantizer { /* private fields */ }

Lagrangian Rate-Distortion optimal scalar quantizer.

Minimizes D + λ·R where D is MSE distortion and R is empirical entropy. Implements an entropy-regularized Lloyd-Max algorithm:

1. Initialize bin edges from equal-mass (percentile) split of the signal.
2. Iterate:
   • Centroid update: recon[i] = mean of samples assigned to bin i.
   • Entropy-regularized edge update: edge[i] = 0.5·(recon[i-1]+recon[i]) + (λ/(recon[i]-recon[i-1]))·(ln p[i-1] − ln p[i])
   • Clamp edges to be strictly monotonic.
   • Recompute empirical probabilities.
   • Evaluate cost = D + λ·R and stop when Δcost < tol.

Implementations

impl EntropyConstrainedQuantizer

pub fn new( bin_edges: Vec<f32>, reconstruction_values: Vec<f32>, lambda: f32, ) -> Self

Construct directly from pre-computed edges and reconstruction values.

Uniform prior probabilities are assumed until fit_lagrangian is called.

pub fn fit_lagrangian( signal: &Array1<f32>, num_levels: usize, lambda: f32, max_iters: usize, tol: f32, ) -> TokenizerResult<Self>

Fit ECQ via entropy-regularized Lloyd-Max iteration.

Returns Err if num_levels < 2 or the signal is too short.

Arguments

• signal – Input signal samples.
• num_levels – Number of quantization bins (≥ 2).
• lambda – Lagrange multiplier; larger → more compression, less fidelity.
• max_iters – Maximum Lloyd-Max iterations.
• tol – Convergence threshold on |Δcost|.

pub fn encode_compressed( &self, signal: &Array1<f32>, ) -> TokenizerResult<(Vec<u8>, u64)>

Compress signal using Huffman coding built from the fitted bin probabilities.

Returns (compressed_bytes, symbol_count). The symbol_count is needed for lossless decompression.

pub fn decode_compressed( &self, bytes: &[u8], _symbol_count: u64, ) -> TokenizerResult<Array1<f32>>

Decompress bytes produced by encode_compressed back to a signal.

The symbol_count must match the value returned by encode_compressed.

pub fn fit_with_target_rate( signal: &Array1<f32>, num_levels: usize, target_bpp: f64, max_outer_iters: usize, ) -> TokenizerResult<Self>

Fit ECQ using binary search over λ to hit a target entropy rate.

Arguments

• signal – Training signal.
• num_levels – Number of quantization bins.
• target_bpp – Desired bits per symbol.
• max_outer_iters – Number of λ bisection steps.

pub fn compute_entropy_rate(&self, signal: &Array1<f32>) -> f64

Compute empirical Shannon entropy (bits/symbol) of the signal under this quantizer’s bin partition.

pub fn empirical_distortion(&self, signal: &Array1<f32>) -> f64

Compute mean-squared distortion of the signal under this quantizer.

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

Return a reference to the interior bin edges.

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

Return a reference to the reconstruction values.

pub fn lambda(&self) -> f32

Return the Lagrange multiplier used during fitting.

pub fn target_bits_per_symbol(&self) -> Option<f64>

Return the optional target bits-per-symbol set by fit_with_target_rate.

Trait Implementations

impl Quantizer for EntropyConstrainedQuantizer

fn quantize(&self, value: f32) -> i32

Quantize a continuous value to discrete level

fn dequantize(&self, level: i32) -> f32

Dequantize a discrete level back to continuous value

fn num_levels(&self) -> usize

Get number of quantization levels

impl SignalTokenizer for EntropyConstrainedQuantizer

fn encode(&self, signal: &Array1<f32>) -> TokenizerResult<Array1<f32>>

Encode a continuous signal into tokens/embeddings

fn decode(&self, tokens: &Array1<f32>) -> TokenizerResult<Array1<f32>>

Decode tokens/embeddings back to continuous signal

fn embed_dim(&self) -> usize

Get the embedding dimension

fn vocab_size(&self) -> usize

Get the vocabulary size (for discrete tokenizers, 0 for continuous)