Package ptolemy.math

Class Quantizer

  • public class Quantizer
extends java.lang.Object
    This class provides a set of static methods for creating instances of the FixPoint class from doubles, integers, or fixed point numbers. The various round() methods return a fixed point value that is nearest to the specified number, but has the specified precision. The various roundToZero() and truncate() methods return a fixed point value that is nearest to the specified number, but no greater in magnitude. The various roundDown() methods return a the nearest fixed point less than the argument. The intention is to fill out this class with roundUp(), and roundNearestEven(). All of these methods may introduce quantization errors and/or overflow. This class has been reimplemented to perform all rounding by first constructing a FixPointQuantization and then using either the quantizing constructor of FixPoint or FixPoint.quantize. Users may find that their code simplifies if they do likewise.
    Since:
    Ptolemy II 0.4
    Version:
    $Id$
    Author:
    Bart Kienhuis, Edward A. Lee, Ed Willink
    See Also:
    FixPoint, Overflow, Precision, Rounding, Quantization
    Pt.AcceptedRating:
    Red (kienhuis)
    Pt.ProposedRating:
    Yellow (kienhuis)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Overflow OVERFLOW_TO_ZERO
      Indicate that overflow should result in a zero value.
      static Overflow SATURATE
      Indicate that overflow should saturate.

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static FixPoint round​(double value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint round​(java.math.BigDecimal value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint round​(FixPoint value, Precision newPrecision, Overflow mode)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundDown​(double value, Precision precision)
      Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundDown​(java.math.BigDecimal value, Precision precision)
      Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundDown​(FixPoint value, Precision newPrecision, Overflow mode)
      Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundNearestEven​(double value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundNearestEven​(java.math.BigDecimal value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundNearestEven​(FixPoint value, Precision newPrecision, Overflow mode)
      Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundToZero​(double value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundToZero​(java.math.BigDecimal value, Precision precision)
      Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundToZero​(FixPoint value, Precision newPrecision, Overflow mode)
      Return the fixed point number that is nearest to the specified value, but has magnitude no greater than the specified value, and has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundUp​(double value, Precision precision)
      Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundUp​(java.math.BigDecimal value, Precision precision)
      Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint roundUp​(FixPoint value, Precision newPrecision, Overflow mode)
      Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
      static FixPoint truncate​(double value, Precision precision)
      Deprecated.
      Use roundToZero instead.
      static FixPoint truncate​(java.math.BigDecimal value, Precision precision)
      Deprecated.
      Use roundToZero instead.
      static FixPoint truncate​(FixPoint value, Precision newPrecision, Overflow mode)
      Deprecated.
      Use roundToZero instead.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • SATURATE

        public static final Overflow SATURATE
        Indicate that overflow should saturate.

      • OVERFLOW_TO_ZERO

        public static final Overflow OVERFLOW_TO_ZERO
        Indicate that overflow should result in a zero value.

    • Method Detail

      • round

        public static FixPoint round​(double value,
                             Precision precision)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • round

        public static FixPoint round​(java.math.BigDecimal value,
                             Precision precision)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • round

        public static FixPoint round​(FixPoint value,
                             Precision newPrecision,
                             Overflow mode)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.
        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.

      • roundDown

        public static FixPoint roundDown​(double value,
                                 Precision precision)
        Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundDown

        public static FixPoint roundDown​(java.math.BigDecimal value,
                                 Precision precision)
        Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundDown

        public static FixPoint roundDown​(FixPoint value,
                                 Precision newPrecision,
                                 Overflow mode)
        Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.
        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.

      • roundNearestEven

        public static FixPoint roundNearestEven​(double value,
                                        Precision precision)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. If the rounded digit is five, then the last digit that is not discarded will be rounded to make it even. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundNearestEven

        public static FixPoint roundNearestEven​(java.math.BigDecimal value,
                                        Precision precision)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. If the rounded digit is five, then the last digit that is not discarded will be rounded to make it even. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundNearestEven

        public static FixPoint roundNearestEven​(FixPoint value,
                                        Precision newPrecision,
                                        Overflow mode)
        Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. If the rounded digit is five, then the last digit that is not discarded will be rounded to make it even. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.
        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.

      • roundToZero

        public static FixPoint roundToZero​(double value,
                                   Precision precision)
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundToZero

        public static FixPoint roundToZero​(java.math.BigDecimal value,
                                   Precision precision)
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundToZero

        public static FixPoint roundToZero​(FixPoint value,
                                   Precision newPrecision,
                                   Overflow mode)
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater than the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.
        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.

      • roundUp

        public static FixPoint roundUp​(double value,
                               Precision precision)
        Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundUp

        public static FixPoint roundUp​(java.math.BigDecimal value,
                               Precision precision)
        Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.
        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • roundUp

        public static FixPoint roundUp​(FixPoint value,
                               Precision newPrecision,
                               Overflow mode)
        Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.
        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.

      • truncate

        @Deprecated
public static FixPoint truncate​(double value,
                                Precision precision)
        Deprecated.
        Use roundToZero instead.
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

        Note: This method does NOT perform truncation per most fixed-point DSP implementations, which simply drop the fractional bits. Most models of fixed-point algorithms will use the roundDown methods in this class instead.

        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • truncate

        @Deprecated
public static FixPoint truncate​(java.math.BigDecimal value,
                                Precision precision)
        Deprecated.
        Use roundToZero instead.
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

        Note: This method does NOT perform truncation per most fixed-point DSP implementations, which simply drop the fractional bits. Most models of fixed-point algorithms will use the roundDown methods in this class instead.

        Parameters:
        value - The value to represent.
        precision - The precision of the representation.
        Returns:
        A fixed-point representation of the value.

      • truncate

        @Deprecated
public static FixPoint truncate​(FixPoint value,
                                Precision newPrecision,
                                Overflow mode)
        Deprecated.
        Use roundToZero instead.
        Return the fixed point number that is nearest to the specified value, but has magnitude no greater than the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

        Note: This method does NOT perform truncation per most fixed-point DSP implementations, which simply drop the fractional bits. Most models of fixed-point algorithms will use the roundDown methods in this class instead.

        Parameters:
        value - The value to represent.
        newPrecision - The precision of the representation.
        mode - The overflow mode.
        Returns:
        A new fixed-point representation of the value.