ptolemy.math
Class Overflow

java.lang.Object
  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:

• 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: 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)