ptolemy.math
Class Overflow

java.lang.Object
  extended by ptolemy.math.Overflow
All Implemented Interfaces:
java.io.Serializable, 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, java.io.Serializable

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:

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: Overflow.java 57040 2010-01-27 20:52:32Z cxh $
Author:
Ed Willink
See Also:
FixPoint, Quantization, Rounding, Serialized Form
Accepted Rating:
Red
Proposed Rating:
Red (Ed.Willink)

Nested Class Summary
static class Overflow.Grow
          The grow overflow strategy.
static class Overflow.Minimize
          The minimize overflow strategy.
static class Overflow.Modulo
          The modulo overflow strategy.
static class Overflow.Saturate
          The saturate overflows strategy.
static class Overflow.ToZero
          The overflow to zero strategy.
static class Overflow.Trap
          The trap overflows strategy.
 
Field Summary
private  java.lang.String _name
           
private static java.util.Map _nameToOverflow
           
static Overflow.Saturate CLIP
          Singleton implementing Saturate overflow strategy.
static Overflow.Grow GENERAL
          Singleton implementing Grow overflow strategy.
static Overflow.Grow GROW
          Singleton implementing Grow overflow strategy.
static Overflow.Minimize MINIMIZE
          Singleton implementing Minimize overflow strategy.
static Overflow.Modulo MODULO
          Singleton implementing Modulo overflow strategy.
static Overflow.Saturate SATURATE
          Singleton implementing Saturate overflow strategy.
static Overflow.Trap THROW
          Singleton implementing Trap overflow strategy.
static Overflow.ToZero TO_ZERO
          Singleton implementing to zero overflow strategy.
static Overflow.Trap TRAP
          Singleton implementing Trap overflow strategy.
static Overflow.Modulo WRAP
          Singleton implementing Modulo overflow strategy.
 
Constructor Summary
protected Overflow(java.lang.String name)
          Construct an Overflow object with the given String name.
 
Method Summary
(package private) static void _addOverflow(Overflow type, java.lang.String name)
           
 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.


_name

private java.lang.String _name

_nameToOverflow

private static java.util.Map _nameToOverflow
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.

_addOverflow

static void _addOverflow(Overflow type,
                         java.lang.String name)