Struct constriction::stream::model::LeakilyQuantizedDistribution

pub struct LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, const PRECISION: usize> { /* fields omitted */ }

An EntropyModel that approximates a parameterized probability Distribution.

A LeakilyQuantizedDistribution can be created with a LeakyQuantizer. It can be used for encoding and decoding with any of the stream codes provided by the constriction crate (it can only be used for decoding if the underlying Distribution implements the the trait Inverse from the probability crate).

When Should I Use This Type of Entropy Model?

Use a LeakilyQuantizedDistribution when you have a probabilistic model that is defined through some analytic expression (e.g., a mathematical formula for the probability density function of a continuous probability distribution, or a mathematical formula for the probability mass functions of some discrete probability distribution). Examples of probabilistic models that lend themselves to being quantized are continuous distributions such as Gaussian, Laplace, or Exponential, as well as discrete distributions with some analytic expression, such as Binomial.

Do not use a LeakilyQuantizedDistribution if your probabilistic model can only be presented as an explicit probability table. While you could, in principle, apply a LeakyQuantizer to such a Categorical distribution, you will get better computational performance (and also slightly better compression effectiveness) if you instead use one of the dedicated types ContiguousCategoricalEntropyModel, NonContiguousCategoricalEncoderModel, NonContiguousCategoricalDecoderModel, or LookupDecoderModel.

Examples

See examples for LeakyQuantizer.

Computational Efficiency

See discussion for LeakyQuantizer.

Implementations

impl<'q, F, Symbol, Probability, D, const PRECISION: usize> LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION> where
    Probability: BitArray + Into<F>,
    Symbol: PrimInt + AsPrimitive<Probability> + WrappingSub + WrappingAdd,
    F: Float, 

pub fn quantizer(&self) -> &'q LeakyQuantizer<F, Symbol, Probability, PRECISION>

Returns the quantizer that was used to create this entropy model.

You may want to reuse this quantizer to quantize further probability distributions.

pub fn inner(&self) -> &D

Returns a reference to the underlying (floating-point) probability Distribution.

Returns the floating-point probability distribution which this LeakilyQuantizedDistribution approximates in fixed-point arithmetic.

See also

• inner_mut
• into_inner

pub fn inner_mut(&mut self) -> &mut D

Returns a mutable reference to the underlying (floating-point) probability Distribution.

You can use this method to mutate parameters of the underlying Distribution after it was already quantized. This is safe and cheap since quantization is done lazily anyway. Note that you can’t mutate the support since it is a property of the LeakyQuantizer, not of the Distribution. If you want to modify the support then you have to create a new LeakyQuantizer with a different support.

See also

• inner
• into_inner

pub fn into_inner(self) -> D

Consumes the entropy model and returns the underlying (floating-point) probability Distribution.

Returns the floating-point probability distribution which this LeakilyQuantizedDistribution approximates in fixed-point arithmetic.

See also

• inner
• inner_mut

pub fn support(&self) -> RangeInclusive<Symbol>

Returns the exact range of symbols that have nonzero probability.

See LeakyQuantizer::support.

Trait Implementations

impl<'q, F: Clone, Symbol: Clone, Probability: Clone, D: Clone, const PRECISION: usize> Clone for LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION>

fn clone(
    &self
) -> LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'q, F: Debug, Symbol: Debug, Probability: Debug, D: Debug, const PRECISION: usize> Debug for LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION>

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

Formats the value using the given formatter.

impl<'q, Symbol, Probability, D, const PRECISION: usize> DecoderModel<PRECISION> for LeakilyQuantizedDistribution<'q, f64, Symbol, Probability, D, PRECISION> where
    f64: AsPrimitive<Probability>,
    Symbol: PrimInt + AsPrimitive<Probability> + Into<f64> + WrappingSub + WrappingAdd,
    Probability: BitArray + Into<f64>,
    D: Inverse,
    D::Value: AsPrimitive<Symbol>, 

fn quantile_function(
    &self,
    quantile: Probability
) -> (Self::Symbol, Probability, Probability::NonZero)

Looks up the symbol for a given quantile.

impl<'q, Symbol, Probability, D, const PRECISION: usize> EncoderModel<PRECISION> for LeakilyQuantizedDistribution<'q, f64, Symbol, Probability, D, PRECISION> where
    f64: AsPrimitive<Probability>,
    Symbol: PrimInt + AsPrimitive<Probability> + Into<f64> + WrappingSub,
    Probability: BitArray + Into<f64>,
    D: Distribution,
    D::Value: AsPrimitive<Symbol>, 

fn left_cumulative_and_probability(
    &self,
    symbol: impl Borrow<Symbol>
) -> Option<(Probability, Probability::NonZero)>

Performs (one direction of) the quantization.

Panics

Panics if it detects some invalidity in the underlying probability distribution. This means that there is a bug in the implementation of Distribution for the distribution D: the cumulative distribution function is either not monotonically nondecreasing, returns NaN, or its values exceed the interval [0.0, 1.0] at some point.

More precisely, this method panics if the quantization procedure leads to a zero probability despite the added leakiness (and despite the fact that the constructor checks that min_symbol_inclusive < max_symbol_inclusive, i.e., that there are at least two symbols with nonzero probability and therefore the probability of a single symbol should not be able to overflow).

See requirements for correctness.

fn floating_point_probability<F>(&self, symbol: Self::Symbol) -> F where
    F: Float,
    Self::Probability: Into<F>, 

Returns the probability of the given symbol in floating point representation.

impl<'q, F, Symbol, Probability, D, const PRECISION: usize> EntropyModel<PRECISION> for LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION> where
    Probability: BitArray, 

type Probability = Probability

The type used to represent probabilities, cumulatives, and quantiles.

type Symbol = Symbol

The type of data over which the entropy model is defined.

impl<'m, 'q: 'm, Symbol, Probability, D, const PRECISION: usize> IterableEntropyModel<'m, PRECISION> for LeakilyQuantizedDistribution<'q, f64, Symbol, Probability, D, PRECISION> where
    f64: AsPrimitive<Probability>,
    Symbol: PrimInt + AsPrimitive<Probability> + AsPrimitive<usize> + Into<f64> + WrappingSub,
    Probability: BitArray + Into<f64>,
    D: Distribution + 'm,
    D::Value: AsPrimitive<Symbol>, 

type Iter = LeakilyQuantizedDistributionIter<Symbol, Probability, &'m Self, PRECISION>

The type of the iterator returned by symbol_table.

fn symbol_table(&'m self) -> Self::Iter

Iterates over all symbols in the unique order that is consistent with the cumulative distribution.

fn floating_point_symbol_table<F>(
    &'m self
) -> FloatingPointSymbolTable<F, Self::Iter, PRECISION> where
    F: From<Self::Probability>, 

Similar to symbol_table, but yields both cumulatives and probabilities in floating point representation.

fn entropy_base2<F>(&'m self) -> F where
    F: Float + Sum,
    Self::Probability: Into<F>, 

Returns the entropy in units of bits (i.e., base 2).

fn to_generic_encoder_model(
    &'m self
) -> NonContiguousCategoricalEncoderModel<Self::Symbol, Self::Probability, PRECISION> where
    Self::Symbol: Hash + Eq, 

Creates an EncoderModel from this EntropyModel

fn to_generic_decoder_model(
    &'m self
) -> NonContiguousCategoricalDecoderModel<Self::Symbol, Self::Probability, Vec<(Self::Probability, Self::Symbol)>, PRECISION> where
    Self::Symbol: Clone, 

Creates a DecoderModel from this EntropyModel

fn to_generic_lookup_decoder_model(
    &'m self
) -> LookupDecoderModel<Self::Symbol, Self::Probability, NonContiguousSymbolTable<Vec<(Self::Probability, Self::Symbol)>>, Box<[Self::Probability]>, PRECISION> where
    Self::Probability: Into<usize>,
    usize: AsPrimitive<Self::Probability>,
    Self::Symbol: Copy + Default, 

Creates a DecoderModel from this EntropyModel

impl<'q, F: Copy, Symbol: Copy, Probability: Copy, D: Copy, const PRECISION: usize> Copy for LeakilyQuantizedDistribution<'q, F, Symbol, Probability, D, PRECISION>