ptolemy.math
Class Quantization

java.lang.Object
  ptolemy.math.Quantization

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

FixPointQuantization

public abstract class Quantization
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

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: Quantization.java 47513 2007-12-07 06:32:21Z cxh $

Author:

Ed Willink

See Also:

FixPoint, FixPointQuantization, Precision, Overflow, Rounding, Serialized Form

Accepted Rating:

Red

Proposed Rating:

Red (Ed.Willink)

Field Summary

protected Overflow	_overflow The overflow strategy.
protected Rounding	_rounding The rounding strategy.

Constructor Summary

Quantization(Overflow overflow, Rounding rounding)
Construct a Quantization with the given precision, overflow strategy, and rounding strategy.

Method Summary

java.lang.Object	clone() Return this, that is, return the reference to this object.
boolean	equals(java.lang.Object object) Return true if the indicated object describes the same mapping to quantized values.
double	getEpsilonValue() Return the separation between quantized values.
boolean	getExactOverflow() Return the overflow bit-truth.
boolean	getExactRounding() Return the rounding bit-truth.
int	getExponentBitLength() Return the number of bits to represent the exponent.
int	getFractionBitLength() Return the number of bits representing the fractional part of the mantissa.
int	getIntegerBitLength() Return the number of bits representing the integer part of the mantissa.
int	getMantissaBitLength() Return the number of bits to represent the mantissa.
abstract Precision	getMantissaPrecision() Return the precision fore the mantissa of a compliant 2's complement representation.
java.math.BigInteger	getMaximumUnscaledValue() Return the maximum quantizable value after scaling so that quantization levels are represented by adjacent integers.
double	getMaximumValue() Return the maximum quantizable value.
java.math.BigInteger	getMinimumUnscaledValue() Return the minimum quantizable value after scaling so that quantization levels are represented by adjacent integers.
double	getMinimumValue() Return the minimum quantizable value.
java.math.BigInteger	getModuloUnscaledValue() Deprecated. ?
int	getNumberOfBits() Return the number of bits to represent the value.
double	getNumberOfLevels() Return the number of quantization levels in the mantissa.
Overflow	getOverflow() Return the overflow strategy.
abstract Precision	getPrecision() Return the Precision.
Rounding	getRounding() Return the rounding strategy.
double	getTinyValue() Return the quantizable value nearest to and above zero.
int	hashCode() Return a hash code value for this Quantization.
abstract java.lang.String	toString() Return a string representing this quantization.

Methods inherited from class java.lang.Object

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

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

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.