ptolemy.math
Class FixPoint

java.lang.Object
  |
  +--ptolemy.math.FixPoint

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class FixPoint

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

This class provides a fixed point data type and a set of functions that operate on and return fixed point data. An instance of the class is immutable, meaning that its value is set in the constructor and cannot then be modified. This is similar to the Java built-in classes like Double, Integer, etc.

In an instance of FixPoint, a value is represented by a finite numbers of bits, as defined by the precision. The precision indicates how many bits are used to represent the integer part and the fractional part. The total number of bits used is thus equal to the total number of bits used for the integer and fractional part. The precision of a FixPoint can be expressed in different ways:

• (m/n): The total precision of the output is m bits, with the integer part having n bits. The fractional part thus has m-n bits.
• (m.n): The total precision of the output is n + m bits, with the integer part having m bits, and the fractional part having n bits.

The FixPoint class represents signed numbers in a two's-complement format.

Because a fixed point data type uses a finite number of bits to represent a value, a real value is rounded to the nearest number that can be expressed with a given precision of the fixed point, thereby introducing quantization and overflow errors.

In designing the FixPoint class, the main assumption is that all operators work losslessly, i.e. the precision of the result is changed such that no precision loss happens. These changes are different for the various operations.

When the precision of a fixed point value is changed, it might be that the new precision is less than the required precision to losslessly represent the fixed point. If the integer number of bits is changed, overflow may occur. When the fractional number of bits is changed, a quantization error may occur.

Overflows are handled in one of two ways:

• Saturate: The new fix point is set to the maximum or minimum value possible, depending on its sign, with the new given precision.
• Zero Saturate: The new fix point is set to zero with the new given precision.

The Quantizer class provides a number of convenient static methods for creating an instance of FixPoint. Indeed, the intent is that only those methods will be used to create instances of FixPoint. For this reason, this class has only a package friendly constructor.

The code for this FixPoint implementation is written from scratch. At its core, it uses the Java class BigInteger to represent the finite value captured in FixPoint. The use of the BigInteger class makes this FixPoint implementation truly platform independent. In some cases FixPoint also makes use of the BigDecimal class. Note that the FixPoint does not put any restrictions on the maximum number of bits used to represent a value.

Since:

Ptolemy II 0.4

Version:

$Id: FixPoint.java,v 1.40.2.1 2002/03/22 15:54:20 cxh Exp $

Author:

Bart Kienhuis, Contributor: Edward A. Lee

See Also:

Precision, Quantizer, Serialized Form

Inner Class Summary

static class

FixPoint.Error Instances of this class represent a type safe enumeration of error conditions of the FixValue.

Field Summary

static FixPoint.Error	NOOVERFLOW Indicator that an overflow has occurred
static FixPoint.Error	OVERFLOW Indicator that no overflow has occurred
static FixPoint.Error	ROUNDING Indicator that a rounding error has occurred

Method Summary

FixPoint	abs() Return a new FixPoint with a value equal to the absolute value of this fixed point.
FixPoint	add(FixPoint arg) Return a new FixPoint with a value equal to the sum of this FixPoint and the argument.
java.math.BigDecimal	bigDecimalValue() Return the value of this FixPoint as a BigDecimal number.
FixPoint	divide(FixPoint arg) Return a new FixPoint with a value equal to the division of this FixPoint by the argument.
double	doubleValue() Return the value of this FixPoint as a double.
boolean	equals(FixPoint arg) Return true if this FixPoint is equal to the argument.
FixPoint.Error	getError() Get the error condition of this FixPoint, which is one of OVERFLOW, ROUNDING, or NOOVERFLOW indicating that an overflow error has occurred, a rounding error has occurred, or no error has occurred.
Precision	getPrecision() Return the precision of this number.
FixPoint	multiply(FixPoint arg) Return a new FixPoint number with a value equal to the product of this number and the argument.
void	printFix() Print useful debug information about the FixPoint to standard out.
FixPoint	subtract(FixPoint arg) Return a new FixPoint number with a value equal to this number minus the argument.
java.lang.String	toBitString() Return a bit string representation of this fixed point in the form "integerBits .
java.lang.String	toString() Return a string representation of the value of this number.

Methods inherited from class java.lang.Object

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

Field Detail

OVERFLOW

public static final FixPoint.Error OVERFLOW

Indicator that no overflow has occurred

NOOVERFLOW

public static final FixPoint.Error NOOVERFLOW

Indicator that an overflow has occurred

ROUNDING

public static final FixPoint.Error ROUNDING

Indicator that a rounding error has occurred

Method Detail

abs

public final FixPoint abs()

Return a new FixPoint with a value equal to the absolute value of this fixed point.

Returns:

A non-negative fixed point.

add

public FixPoint add(FixPoint arg)

Return a new FixPoint with a value equal to the sum of this FixPoint and the argument. The operation is lossless because the precision of the result is set to accommodate the result.

The precision of the result is equal to the maximum of the integer part and fractional part of the fixed point values added. So when a number with precision (6, 3) and (12.4) are added, the resulting precision is equal to (max(6, 12), max(3, 4)), which is (12.4). If the resulting value doesn't fits into this new precision, then the precision is changed to accommodate it. In particular, the number of bits for the integer part might be increased by one.

Parameters:

arg - A number to add to this one.

Returns:

The sum of this number and the argument.

bigDecimalValue

public java.math.BigDecimal bigDecimalValue()

Return the value of this FixPoint as a BigDecimal number. This is lossless.

Returns:

The BigDecimal value of this FixPoint.

divide

public FixPoint divide(FixPoint arg)

Return a new FixPoint with a value equal to the division of this FixPoint by the argument. The operation is not lossless. To realize the division, a trick is used to simplify the implementation of division for FixPoint values. The FixPoints are converted losslessly into BigDecimals, on which the actual division takes place. The result of the division is converted back to FixPoint with a precision equal to the maximum of the integer part and fractional part of the fixed point values divided. Thus when a number with precision (6, 3) is divided by a FixPoint with precision (12.4), then the resulting FixPoint will have a precision equal to (max(6, 12), max(3, 4)), which is (12.4). If the BigDecimal resulting from the division doesn't fit this precision, then this BigDecimal value is quantized to the closest value representable with the specified precision.

Parameters:

arg - A FixPoint.

Returns:

A new FixPoint.

doubleValue

public double doubleValue()

Return the value of this FixPoint as a double. Note that this is not necessarily lossless, since the precision of the fixed point number may exceed that of the double.

Returns:

The double value of this FixPoint.

equals

public boolean equals(FixPoint arg)

Return true if this FixPoint is equal to the argument. Two FixPoints are considered equal when the bit string representing them is the same.

Returns:

True if the FixPoints are equal; false otherwise.

See Also:

toBitString()

getError

public FixPoint.Error getError()

Get the error condition of this FixPoint, which is one of OVERFLOW, ROUNDING, or NOOVERFLOW indicating that an overflow error has occurred, a rounding error has occurred, or no error has occurred.

Returns:

The error condition

getPrecision

public Precision getPrecision()

Return the precision of this number.

Returns:

the precision of this number.

multiply

public FixPoint multiply(FixPoint arg)

Return a new FixPoint number with a value equal to the product of this number and the argument. The operation is lossless because the precision of the result is set to accommodate the result. The precision of the result is equal to the maximum of the integer parts and 2 times the maximum of the fractional parts of the fixed point values multiplied. If the new computed value doesn't fit into this new precision, then this precision is changed to accommodate the result. For multiplication this means that the number of bits for the integer part might be changed to lie between the maximum value of the integer parts and the sum of the two integer parts.

Parameters:

arg - The number to multiply this number by.

Returns:

A new FixPoint number representing the product.

printFix

public void printFix()

Print useful debug information about the FixPoint to standard out. This is used for debugging.

subtract

public FixPoint subtract(FixPoint arg)

Return a new FixPoint number with a value equal to this number minus the argument. The operation is lossless because the precision of the result is set to accommodate the result. The precision of the result is equal to the maximum of the integer part and fractional part of the fixed point values subtracted. So when a number with precision (6, 3) and (12.4) are subtracted, the resulting precision is equal to (max(6, 12), max(3, 4)), which is (12.4). If the resulting value doesn't fit into this new precision, then the precision is changed to accommodate the new value without loss of precision. For a subtraction this means that the number of bits for the integer part might be increased by one, The fractional part remains unchanged.

Parameters:

arg - The number to subtract from this number.

Returns:

This number minus the argument.

toBitString

public java.lang.String toBitString()

Return a bit string representation of this fixed point in the form "integerBits . fractionBits", where integerBits and fractionBits are each a sequence of "0" and "1".

Returns:

A bit string of the form "integerBits . fractionBits".

toString

public java.lang.String toString()

Return a string representation of the value of this number. This is calculated by first converting the number to a double, and then returning a string representation of the double.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of the value of this FixPoint.