Quantizer

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES All Classes

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

ptolemy.math
Class Quantizer

java.lang.Object
 extended byptolemy.math.Quantizer

public class Quantizer
extends java.lang.Object

This class provides a set of static methods for creating instances of the FixPoint class from doubles, integers, or fixed point numbers. The various round() methods return a fixed point value that is nearest to the specified number, but has the specified precision. The various roundToZero() and truncate() methods return a fixed point value that is nearest to the specified number, but no greater in magnitude. The various roundDown() methods return a the nearest fixed point less than the argument. The intention is to fill out this class with roundUp(), and roundNearestEven(). All of these methods may introduce quantization errors and/or overflow. This class has been reimplemented to perform all rounding by first constructing a FixPointQuantization and then using either the quantizing constructor of FixPoint or FixPoint.quantize. Users may find that their code simplifies if they do likewise.

Since:: Ptolemy II 0.4
Version:: $Id: Quantizer.java,v 1.41 2005年07月08日 19:59:28 cxh Exp $
Author:: Bart Kienhuis, Edward A. Lee, Ed Willink
See Also:: FixPoint, Overflow, Precision, Rounding, Quantization
Accepted Rating:: Red (kienhuis)
Proposed Rating:: Yellow (kienhuis)

Field Summary
`static Overflow`	`OVERFLOW_TO_ZERO` Indicate that overflow should result in a zero value.
`static Overflow`	`SATURATE` Indicate that overflow should saturate.

Method Summary
`static FixPoint`	`round(java.math.BigDecimal value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`round(double value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`round(FixPoint value, Precision newPrecision, Overflow mode)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundDown(java.math.BigDecimal value, Precision precision)` Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundDown(double value, Precision precision)` Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundDown(FixPoint value, Precision newPrecision, Overflow mode)` Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundNearestEven(java.math.BigDecimal value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundNearestEven(double value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundNearestEven(FixPoint value, Precision newPrecision, Overflow mode)` Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundToZero(java.math.BigDecimal value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundToZero(double value, Precision precision)` Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundToZero(FixPoint value, Precision newPrecision, Overflow mode)` Return the fixed point number that is nearest to the specified value, but has magnitude no greater than the specified value, and has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundUp(java.math.BigDecimal value, Precision precision)` Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundUp(double value, Precision precision)` Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`roundUp(FixPoint value, Precision newPrecision, Overflow mode)` Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors.
`static FixPoint`	`truncate(java.math.BigDecimal value, Precision precision)` Deprecated. Use roundToZero instead.
`static FixPoint`	`truncate(double value, Precision precision)` Deprecated. Use roundToZero instead.
`static FixPoint`	`truncate(FixPoint value, Precision newPrecision, Overflow mode)` Deprecated. Use roundToZero instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SATURATE

public static final Overflow SATURATE

Indicate that overflow should saturate.

OVERFLOW_TO_ZERO

public static final Overflow OVERFLOW_TO_ZERO

Indicate that overflow should result in a zero value.

Method Detail

round

public static FixPoint round(double value,
 Precision precision)

Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

round

public static FixPoint round(java.math.BigDecimal value,
 Precision precision)

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

round

public static FixPoint round(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.

roundDown

public static FixPoint roundDown(double value,
 Precision precision)

Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundDown

public static FixPoint roundDown(java.math.BigDecimal value,
 Precision precision)

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundDown

public static FixPoint roundDown(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Return the nearest fixed point number with less than or equal magnitude that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.

roundNearestEven

public static FixPoint roundNearestEven(double value,
 Precision precision)

Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. If the rounded digit is five, then the last digit that is not discarded will be rounded to make it even. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundNearestEven

public static FixPoint roundNearestEven(java.math.BigDecimal value,
 Precision precision)

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundNearestEven

public static FixPoint roundNearestEven(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Return the fixed point number that is nearest to the specified value, but has the given precision, possibly introducing quantization or overflow errors. If the rounded digit is five, then the last digit that is not discarded will be rounded to make it even. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.

roundToZero

public static FixPoint roundToZero(double value,
 Precision precision)

Return the fixed point number that is nearest to the specified value, but has magnitude no greater that the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundToZero

public static FixPoint roundToZero(java.math.BigDecimal value,
 Precision precision)

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundToZero

public static FixPoint roundToZero(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Return the fixed point number that is nearest to the specified value, but has magnitude no greater than the specified value, and has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.

roundUp

public static FixPoint roundUp(double value,
 Precision precision)

Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundUp

public static FixPoint roundUp(java.math.BigDecimal value,
 Precision precision)

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

roundUp

public static FixPoint roundUp(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Return the smallest greater than or equal fixed point number that has the given precision, possibly introducing quantization or overflow errors. An overflow error occurs if the specified number does not fit within the range possible with the specified precision. In that case, the returned value depends on the specified mode. If the mode is SATURATE, then the return value is either the maximum or minimum value possible with the given precision, depending on the sign of the specified number. If the mode is OVERFLOW_TO_ZERO, then the return value is zero.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.

truncate

public static FixPoint truncate(double value,
 Precision precision)

Deprecated. Use roundToZero instead.

Note: This method does NOT perform truncation per most fixed-point DSP implementations, which simply drop the fractional bits. Most models of fixed-point algorithms will use the roundDown methods in this class instead.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

truncate

public static FixPoint truncate(java.math.BigDecimal value,
 Precision precision)

Deprecated. Use roundToZero instead.

Parameters:: value - The value to represent.; precision - The precision of the representation.
Returns:: A fixed-point representation of the value.

truncate

public static FixPoint truncate(FixPoint value,
 Precision newPrecision,
 Overflow mode)

Deprecated. Use roundToZero instead.

Parameters:: value - The value to represent.; newPrecision - The precision of the representation.; mode - The overflow mode.
Returns:: A new fixed-point representation of the value.