Quantization

java.lang.Object
- ptolemy.math.Quantization

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

FixPointQuantization
```
public abstract class Quantization
extends java.lang.Object
implements java.lang.Cloneable
```
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$

Author:

Ed Willink

See Also:

FixPoint, FixPointQuantization, Precision, Overflow, Rounding

Pt.AcceptedRating:

Red

Pt.ProposedRating:

Red (Ed.Willink)

Field Summary

Fields
Modifier and Type Field and Description

protected Overflow _overflow
The overflow strategy.

protected Rounding _rounding
The rounding strategy.

Fields
Modifier and Type	Field and Description
`protected Overflow`	`_overflow` The overflow strategy.
`protected Rounding`	`_rounding` The rounding strategy.

Constructor Summary

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

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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
```
@Deprecated
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.

Class Quantization

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_overflow

_rounding

Constructor Detail

Quantization

Method Detail

clone

equals

getEpsilonValue

getExactOverflow

getExactRounding

getExponentBitLength

getFractionBitLength

getIntegerBitLength

getMantissaBitLength

getMantissaPrecision

getMaximumUnscaledValue

getMaximumValue

getMinimumUnscaledValue

getMinimumValue

getModuloUnscaledValue

getNumberOfBits

getNumberOfLevels

getOverflow

getPrecision

getRounding

getTinyValue

hashCode

toString