Package ptolemy.math

Class Overflow

  • All Implemented Interfaces:
    java.lang.Cloneable
    Direct Known Subclasses:
    Overflow.Grow, Overflow.Minimize, Overflow.Modulo, Overflow.Saturate, Overflow.ToZero, Overflow.Trap
    public abstract class Overflow
extends java.lang.Object
implements java.lang.Cloneable
    The Overflow class provides a type safe enumeration of strategies for handling numeric overflows for FixPoint data types. Overflows are typically resolved after performing a FixPoint arithmetic operation or transformation.

    The active class functionality is provided by the quantize method. This method evaluates an unscaled BigInteger value and a Precision constraint and creates a FixPoint object with a new unscaled value and precision that conforms to the corresponding overflow strategy. Depending on the overflow strategy used, the unscaled integer value or the precision may be changed as part of the overflow process.

    The overflow strategies supported are as follows:

    • grow
      If the integer value does not fall within the dynamic range of the Precision constraint, increase the Precision to the minimum dynamic range needed to include the integerValue. Note that the actual integer unscaled value will not change during this overflow strategy. This rounding mode is supported by the static quantizeGrow method and the Overflow singletons GROW and GENERAL.
    • minimize
      Represent the unscaled integer value with the minimum number of data bits. The sign and exponent of the new precision constraint is determined by the Precision parameter. The use of this overflow strategy may increase or decrease the Precision of the value. Note that the actual integer unscaled value will not change during this overflow strategy. This rounding mode is supported by the static quantizeMinimize method and the Overflow singleton MINIMIZE .
    • modulo
      This overflow strategy will perform a twos complement modulo operation any integer values that are outside of the dynamic range of the Precision constraint. Note that the actual precision will not change during this overflow strategy. This rounding mode is supported by the static quantizeModulo method and the Overflow singletons MODULO and WRAP.
    • saturate
      If the integer value falls outside of the Precision dynamic range, this overflow strategy will saturate result. If the value is below the minimum of the range, the minimum value of the range is used. If the value is above the maximum of the range, the maximum value of the range is used. Note that the precision will not change during this overflow strategy. This rounding mode is supported by the static quantizeSaturate method and the Overflow singletons SATURATE and CLIP.
    • to_zero
      If the integer value falls outside of the Precision dynamic range, this overflow strategy will set the integer value to zero. Note that the actual precision will not change during this overflow strategy. This rounding mode is supported by the static quantizeToZero method and the Overflow singleton TO_ZERO.
    • trap
      If the integer value falls outside of the Precision dynamic range, a ArithmeticException is generated. This rounding mode is supported by the singleton TRAP.

    A specific strategy may be chosen dynamically by invoking forName or getName with one of the above strategy names. Alternatively a strategy may be selected by using one of the static singletons.

    Division by zero can trigger the use of the plusInfinity or minusInfinity methods, which return null, except in the case of the to_zero and saturate strategies for which infinity is well-defined.

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

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Overflow​(java.lang.String name)
      Construct an Overflow object with the given String name.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object clone()
      Return this, that is, return the reference to this object.
      boolean equals​(java.lang.Object object)
      Determine if the argument represents the same Overflow as this object.
      static Overflow forName​(java.lang.String name)
      Return an instance of this class with the specified name.
      static Overflow getName​(java.lang.String name)
      Return an instance of this class with the specified name, or null if none exists.
      int hashCode()
      Return a hash code value for this object.
      static boolean isOutOfRange​(java.math.BigInteger bigInt, Precision precision)
      Determines whether the given BigInteger unscaled value is considered an "underflow" or an "overflow" under the given Precision constraint.
      static boolean isOverflow​(java.math.BigInteger value, Precision precision)
      Determines whether the given BigInteger unscaled value is considered an "overflow" under the given Precision constraint.
      static boolean isUnderflow​(java.math.BigInteger bigInt, Precision precision)
      Determines whether the given BigInteger unscaled value is considered an "underflow" under the given Precision constraint.
      java.math.BigInteger minusInfinity​(Quantization quant)
      Return the value of minus infinity, or null if unrepresentable.
      static java.util.Iterator nameIterator()
      Return an iterator for the names of all overflow types.
      java.math.BigInteger plusInfinity​(Quantization quant)
      Return the value of plus infinity, or null if unrepresentable.
      abstract FixPoint quantize​(java.math.BigInteger integerValue, Precision precision)
      Return a new FixPoint object based on the given BigInteger value and Precision constraint.
      static FixPoint quantizeGrow​(java.math.BigInteger integerValue, Precision precision)
      Quantize a FixPoint value using a "grow" overflow strategy.
      static FixPoint quantizeMinimum​(java.math.BigInteger bigInt, Precision p)
      Generates a new FixPoint data value based on the unscaled value bigInt using as few bits as possible.
      static FixPoint quantizeModulo​(java.math.BigInteger integerValue, Precision precision)
      Quantize a FixPoint value using a "modulo" overflow strategy.
      static FixPoint quantizeSaturate​(java.math.BigInteger integerValue, Precision precision)
      Quantize a FixPoint value using a "saturate" overflow strategy.
      static FixPoint quantizeToZero​(java.math.BigInteger integerValue, Precision precision)
      Quantize a FixPoint value using a "to Zero" overflow strategy.
      java.lang.String toString()
      Return the string representation of this overflow.

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • GROW

        public static final Overflow.Grow GROW
        Singleton implementing Grow overflow strategy.

      • MODULO

        public static final Overflow.Modulo MODULO
        Singleton implementing Modulo overflow strategy.

      • MINIMIZE

        public static final Overflow.Minimize MINIMIZE
        Singleton implementing Minimize overflow strategy.

      • TRAP

        public static final Overflow.Trap TRAP
        Singleton implementing Trap overflow strategy.

      • SATURATE

        public static final Overflow.Saturate SATURATE
        Singleton implementing Saturate overflow strategy.

      • TO_ZERO

        public static final Overflow.ToZero TO_ZERO
        Singleton implementing to zero overflow strategy.

      • CLIP

        public static final Overflow.Saturate CLIP
        Singleton implementing Saturate overflow strategy.

      • GENERAL

        public static final Overflow.Grow GENERAL
        Singleton implementing Grow overflow strategy.

      • WRAP

        public static final Overflow.Modulo WRAP
        Singleton implementing Modulo overflow strategy.

      • THROW

        public static final Overflow.Trap THROW
        Singleton implementing Trap overflow strategy.

    • Constructor Detail

      • Overflow

        protected Overflow​(java.lang.String name)
        Construct an Overflow object with the given String name. This name is used for finding an Overflow object at a later time (@see #forName(String)). This constructor is protected to make a type safe enumeration.
        Parameters:
        name - The String name to give this Overflow 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 Overflow.

      • equals

        public boolean equals​(java.lang.Object object)
        Determine if the argument represents the same Overflow as this object.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - Another object.
        Returns:
        True if the argument represents the same Overflow as this object; false otherwise.

      • forName

        public static Overflow forName​(java.lang.String name)
        Return an instance of this class with the specified name.
        Parameters:
        name - The name of the Overflow strategy to find.
        Returns:
        An instance of Overflow or null.

      • getName

        public static Overflow getName​(java.lang.String name)
                        throws java.lang.IllegalArgumentException
        Return an instance of this class with the specified name, or null if none exists.
        Parameters:
        name - The name of the Overflow strategy to find.
        Returns:
        An instance of Overflow.
        Throws:
        java.lang.IllegalArgumentException - If the string does not match one of the known strategies.

      • hashCode

        public int hashCode()
        Return a hash code value for this object.
        Overrides:
        hashCode in class java.lang.Object

      • isOutOfRange

        public static boolean isOutOfRange​(java.math.BigInteger bigInt,
                                   Precision precision)
        Determines whether the given BigInteger unscaled value is considered an "underflow" or an "overflow" under the given Precision constraint. This will occur if the value is less than the minimum unscaled value of the given Precision constraint or more than the maximum unscaled value of the given Precision constraint.
        Parameters:
        bigInt - The value to test for underflow.
        precision - The Precision constraint to use for the test.
        Returns:
        true if the value is considered an "underflow" or "overflow, false otherwise.

      • isOverflow

        public static boolean isOverflow​(java.math.BigInteger value,
                                 Precision precision)
        Determines whether the given BigInteger unscaled value is considered an "overflow" under the given Precision constraint. This will occur if the value is larger than the maximum unscaled value of the given Precision constraint. (@see Precision#getMaximumUnscaledValue())
        Parameters:
        value - The value to test for overflow.
        precision - The Precision constraint to use for the test.
        Returns:
        true if the value is considered an "overflow", false if it is not an "overflow".

      • isUnderflow

        public static boolean isUnderflow​(java.math.BigInteger bigInt,
                                  Precision precision)
        Determines whether the given BigInteger unscaled value is considered an "underflow" under the given Precision constraint. This will occur if the value is less than the minimum unscaled value of the given Precision constraint. (@see Precision#getMinimumUnscaledValue())
        Parameters:
        bigInt - The value to test for underflow.
        precision - The Precision constraint to use for the test.
        Returns:
        true if the value is considered an "underflow", false if it is not an "underflow".

      • nameIterator

        public static java.util.Iterator nameIterator()
        Return an iterator for the names of all overflow types.
        Returns:
        An iterator for the names of all overflow types.

      • minusInfinity

        public java.math.BigInteger minusInfinity​(Quantization quant)
        Return the value of minus infinity, or null if unrepresentable.

        The saturation value is returned for the saturate and to_zero strategies for which infinity is quantizable. Null is returned for other strategies.

        Parameters:
        quant - The quantization specification.
        Returns:
        The value if defined, null if not..

      • plusInfinity

        public java.math.BigInteger plusInfinity​(Quantization quant)
        Return the value of plus infinity, or null if unrepresentable.

        The saturation value is returned for the saturate and to_zero strategies for which infinity is quantizable. Null is returned for other strategies.

        Parameters:
        quant - The quantization specification.
        Returns:
        The value if defined, null if not.

      • quantize

        public abstract FixPoint quantize​(java.math.BigInteger integerValue,
                                  Precision precision)
        Return a new FixPoint object based on the given BigInteger value and Precision constraint. This method will return a valid FixPoint object that conforms to the given overflow strategy implemented by the extending class.
        Parameters:
        integerValue - The unbounded integer value.
        precision - The Precision constraint of the quantization.
        Returns:
        A valid FixPoint value that conforms to the overflow strategy.

      • quantizeGrow

        public static FixPoint quantizeGrow​(java.math.BigInteger integerValue,
                                    Precision precision)
        Quantize a FixPoint value using a "grow" overflow strategy. If the Precision format does not provide sufficient dynamic range for the value, increase the Precision to the minimum dynamic range needed to include the integerValue. Note that the actual integer unscaled value will not change during this overflow strategy.
        Parameters:
        integerValue - unscaled integer value to check for overflow
        precision - the precision constraint used for the overflow check
        Returns:
        Valid FixPoint data object

      • quantizeMinimum

        public static FixPoint quantizeMinimum​(java.math.BigInteger bigInt,
                                       Precision p)
        Generates a new FixPoint data value based on the unscaled value bigInt using as few bits as possible. The sign and exponent of the precision are obtained from the Precision parameter.
        Parameters:
        bigInt - Unscaled value to use for the FixPoint result
        p - Used to obtain the sign and exponent of the new FixPoint value.
        Returns:
        FixPoint value with as few bits as necessary.

      • quantizeModulo

        public static FixPoint quantizeModulo​(java.math.BigInteger integerValue,
                                      Precision precision)
        Quantize a FixPoint value using a "modulo" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, modify the integer value to fit within the dynamic range using a modulo operation. Note that the Precision of the FixPoint value remains the same.
        Parameters:
        integerValue - unscaled integer value to check for overflow
        precision - the precision constraint used for the overflow check
        Returns:
        Valid FixPoint data object

      • quantizeSaturate

        public static FixPoint quantizeSaturate​(java.math.BigInteger integerValue,
                                        Precision precision)
        Quantize a FixPoint value using a "saturate" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, modify the integer value to fit within the dynamic range by saturating the value to the maximum or minimum value supported by the Precision constraint. Note that the Precision of the FixPoint value remains the same.
        Parameters:
        integerValue - unscaled integer value to check for overflow
        precision - the precision constraint used for the overflow check
        Returns:
        Valid FixPoint data object

      • quantizeToZero

        public static FixPoint quantizeToZero​(java.math.BigInteger integerValue,
                                      Precision precision)
        Quantize a FixPoint value using a "to Zero" overflow strategy. If the unscaled integer value is outside of the dynamic range provided by the Precision constraint, set the integer value to zero. Note that the Precision of the FixPoint value remains the same.
        Parameters:
        integerValue - unscaled integer value to check for overflow
        precision - the precision constraint used for the overflow check
        Returns:
        Valid FixPoint data object

      • toString

        public java.lang.String toString()
        Return the string representation of this overflow.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String.