Package ptolemy.math

Class Quantization

  • All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    FixPointQuantization
    public abstract class Quantization
extends java.lang.Object
implements java.lang.Cloneable
    The Quantization class defines the mapping of numeric values with unlimited precision to finite precision.

    It comprises a

    • precision: to define the accuracy of the finite precision numbers.
    • Overflow: to define the treatment of out-of-range numbers.
    • Rounding: to define the loss of precision for in-range numbers.
    The way in which precision is realised is a sub-class responsibility. The standard fixed point binary functionality using a Precision is provided by FixPointQuantization.

    This abstract class is designed to support specification of required numeric behavior through use of the yet-to-be-written FloatingQuantization and FixedQuantization classes. Knowledge of the required numeric behavior, rather than precise specification of an exact implementation, provides an opportunity for code generation to select appropriate types supported by a target architecture.

    FixedQuantization provides for modulo equi-spaced values between the inclusive maximum and minimum limits. epsilon, the separation between values is given by (maximum - minimum) / (modulo - 1). Whether values beyond the maximum and minimum wrap-around is determined by the overflow strategy. FixedQuantization therefore describes the requirements of a single fixed point range comprising just a mantissa.

    FloatingQuantization adds an exponent to support multiple floating point ranges; maximum defines the upper limit of the coarsest scale and tiny defines the smallest representable non-zero number on the finest scale. (tiny is the same as epsilon for FixedQuantization.)

    If exactRounding is specified, code generation must ensure that arithmetic rounds to the specified epsilon. Otherwise, the code generator may use arithmetic with higher precision.

    If exactOverflow is specified, code generation must ensure that arithmetic overflows saturate or wrap-around at the specified maximum and minimum. Otherwise, the code generator may use arithmetic with greater range.

    The active class functionality is provided by the quantize method, which is normally invoked from FixPoint.quantize or ScalarToken.quantize to enforce quantization constraints upon the result of an unconstrained computation.

    An instance of the class is immutable, meaning that its value is set in the constructor and cannot then be modified.

    Since:
    Ptolemy II 2.1
    Version:
    $Id$
    Author:
    Ed Willink
    See Also:
    FixPoint, FixPointQuantization, Precision, Overflow, Rounding
    Pt.AcceptedRating:
    Red
    Pt.ProposedRating:
    Red (Ed.Willink)

    • Field Detail

      • _overflow

        protected Overflow _overflow
        The overflow strategy.

      • _rounding

        protected Rounding _rounding
        The rounding strategy.

    • Constructor Detail

      • Quantization

        public Quantization​(Overflow overflow,
                    Rounding rounding)
        Construct a Quantization with the given precision, overflow strategy, and rounding strategy.
        Parameters:
        overflow - The Overflow object to use by this Quantization strategy.
        rounding - The Rounding object to use by this Quantization strategy.

    • Method Detail

      • clone

        public java.lang.Object clone()
        Return this, that is, return the reference to this object.
        Overrides:
        clone in class java.lang.Object
        Returns:
        This Quantization.

      • equals

        public boolean equals​(java.lang.Object object)
        Return true if the indicated object describes the same mapping to quantized values.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - The Quantization object to use for equality checking.
        Returns:
        True if the quantizations are equal.

      • getEpsilonValue

        public double getEpsilonValue()
        Return the separation between quantized values.
        Returns:
        The quantization interval.

      • getExactOverflow

        public boolean getExactOverflow()
        Return the overflow bit-truth.
        Returns:
        True if overflow must occur at the maximum and minimum values, false if greater range is acceptable.

      • getExactRounding

        public boolean getExactRounding()
        Return the rounding bit-truth.
        Returns:
        True if rounding must occur exactly at epsilon, false if finer resolution is acceptable.

      • getExponentBitLength

        public int getExponentBitLength()
        Return the number of bits to represent the exponent.
        Returns:
        The length of the exponent.

      • getFractionBitLength

        public int getFractionBitLength()
        Return the number of bits representing the fractional part of the mantissa.
        Returns:
        The length of the fractional part of the mantissa.

      • getIntegerBitLength

        public int getIntegerBitLength()
        Return the number of bits representing the integer part of the mantissa.
        Returns:
        The length of the integer part of the mantissa.

      • getMantissaBitLength

        public int getMantissaBitLength()
        Return the number of bits to represent the mantissa.
        Returns:
        The length of the mantissa.

      • getMantissaPrecision

        public abstract Precision getMantissaPrecision()
        Return the precision fore the mantissa of a compliant 2's complement representation.
        Returns:
        The precision.

      • getMaximumUnscaledValue

        public java.math.BigInteger getMaximumUnscaledValue()
        Return the maximum quantizable value after scaling so that quantization levels are represented by adjacent integers.
        Returns:
        The maximum inclusive value.

      • getMaximumValue

        public double getMaximumValue()
        Return the maximum quantizable value.
        Returns:
        The maximum inclusive value.

      • getMinimumUnscaledValue

        public java.math.BigInteger getMinimumUnscaledValue()
        Return the minimum quantizable value after scaling so that quantization levels are represented by adjacent integers.
        Returns:
        The minimum inclusive value.

      • getMinimumValue

        public double getMinimumValue()
        Return the minimum quantizable value.
        Returns:
        The minimum inclusive value.

      • getModuloUnscaledValue

        @Deprecated
public java.math.BigInteger getModuloUnscaledValue()
        Deprecated.
        ?
        Return the modulo quantization range after scaling so that quantization levels are represented by adjacent integers. This is the same as the number of quantization levels in the mantissa..
        Returns:
        The modulo value.

      • getNumberOfBits

        public int getNumberOfBits()
        Return the number of bits to represent the value.
        Returns:
        The number of bits.

      • getNumberOfLevels

        public double getNumberOfLevels()
        Return the number of quantization levels in the mantissa.
        Returns:
        The number of levels.

      • getOverflow

        public Overflow getOverflow()
        Return the overflow strategy.
        Returns:
        The overflow strategy.

      • getPrecision

        public abstract Precision getPrecision()
        Return the Precision.
        Returns:
        The Precision object.

      • getRounding

        public Rounding getRounding()
        Return the rounding strategy.
        Returns:
        The rounding strategy.

      • getTinyValue

        public double getTinyValue()
        Return the quantizable value nearest to and above zero.
        Returns:
        The positive value nearest to zero.

      • hashCode

        public int hashCode()
        Return a hash code value for this Quantization. This method returns the bitwise and of the hashcode of the overflow and the hashcode of the rounding.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code value for this Quantization.

      • toString

        public abstract java.lang.String toString()
        Return a string representing this quantization.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representing this quantization.