ptolemy.math

Class Quantizer

java.lang.Object

ptolemy.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$

Author:

Bart Kienhuis, Edward A. Lee, Ed Willink

See Also:

FixPoint, Overflow, Precision, Rounding, Quantization

Pt.AcceptedRating:

Red (kienhuis)

Pt.ProposedRating:

Yellow (kienhuis)

Field Summary

Fields

Modifier and Type	Field and Description
static Overflow	OVERFLOW_TO_ZERO Indicate that overflow should result in a zero value.
static Overflow	SATURATE Indicate that overflow should saturate.

Method Summary

Modifier and Type	Method and Description
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)

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(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)

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(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)

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(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)

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(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)

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(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

@Deprecated
public static FixPoint truncate(double value,
                                            Precision precision)

Deprecated. Use roundToZero instead.

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.

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

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

Deprecated. Use roundToZero instead.

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.

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

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

Deprecated. Use roundToZero instead.

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.

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.

newPrecision - The precision of the representation.

mode - The overflow mode.

Returns:

A new fixed-point representation of the value.