ptolemy.math
Class FixPoint

java.lang.Object
  ptolemy.math.FixPoint

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

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

The FixPoint 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.

The FixPoint class represents signed numbers in a two's-complement format or unsigned numbers in a binary format with unlimited dynamic range and a resolution defined by a finite number of fractional bits. The precision is defined by the Precision class.

Because a fixed point data type uses a finite number of bits to represent a value, a real value is converted to a number that can be expressed with a given precision of the fixed point, thereby introducing a quantization error. The overflow and rounding strategies used for this quantization are defined by an instance of the Quantization class.

The design of the FixPoint class complies with a philosophy that all operators work losslessly, i.e. the fractional precision of the result is determined such there is no loss of precision. To insure lossless operations, the resulting Precision of these operators will expand as necessary. Subsequent results can be quantized as necessary.

Violations of the loss-less philosophy occur during construction, division and conversion to floating point. During construction from floating point values, the nearest fixed point representation is created. The preferred divide operator provides for explicit specification of the quantization. A deprecated divide operator guesses at the result precision. Conversion to floating point is limited by the available floating point accuracy.

The FixPoint implementation uses the Java class BigInteger to represent the finite value and so this implementation is truly platform independent. Note that the FixPoint does not put any restrictions on the maximum number of bits in the representation of a value.

Since:

Ptolemy II 0.4, rewritten for Ptolemy II 2.2

Version:

$Id: FixPoint.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Bart Kienhuis, Ed Willink, Contributor: Edward A. Lee, Mike Wirthlin

See Also:

Precision, Quantization, Serialized Form

Accepted Rating:

Red

Proposed Rating:

Red (Ed.Willink)

Nested Class Summary

static class

FixPoint.Error An instance of this class is used preserve backwards interface compatibility.

Field Summary

private FixPoint.Error	_error The obsolete error condition of the FixValue
private Precision	_precision The Precision of the given FixPoint value.
private java.math.BigInteger	_value The BigInteger comprising the logical floating point value multiplied by 2^exponent.

Constructor Summary

FixPoint(java.math.BigDecimal bigDecimal, Quantization quant)
Construct a FixPoint by converting a bigDecimal to comply with a quantization specification.

FixPoint(java.math.BigInteger unscaledIntegerValue, Precision precision)
Construct a FixPoint from an unscaled integerValue that with a given Precision constraint.

FixPoint(double doubleValue, Quantization quant)
Construct a FixPoint from a double.

FixPoint(FixPoint fix, Quantization quant)
Construct a new FixPoint object by requantizing the given FixPoint object with a new quantization specification.

FixPoint(int intValue)
Construct a FixPoint from an integer.

FixPoint(int intValue, boolean signed)
Construct a FixPoint from an integer.

FixPoint(int intValue, Quantization quant)
Construct a FixPoint from an integer.

FixPoint(java.lang.String string, Quantization quant)
Construct a FixPoint by converting the BigDecimal interpretation of a string to comply with a quantization specification.

Method Summary

private java.math.BigInteger	_alignToExponent(int exponent) Return the BigInteger whose fractional part is aligned with the provided precision.
private void	_initFromBigDecimal(java.math.BigDecimal bigDecimal, Quantization quant) Initialize the _value and _precision of this object from a BigDecimal value.
private void	_initFromBigInteger(java.math.BigInteger bigInteger, Quantization quant) Initialize the _value and _precision of this object from a BigInteger value.
FixPoint	abs() Return a FixPoint with a value equal to the absolute value of this FixPoint.
FixPoint	add(FixPoint arg) Return a FixPoint with a value equal to the sum of this FixPoint and the argument.
FixPoint	add(FixPoint arg, Quantization quant) Return a FixPoint with a value equal to the sum of this FixPoint and the argument.
static Precision	addPrecision(Precision leftArgument, Precision rightArgument) Determines the Precision of an add operation between two FixPoint values.
java.math.BigDecimal	bigDecimalValue() Return the value of this FixPoint as a BigDecimal number.
java.lang.Object	clone() Return this, that is, return the reference to this object.
FixPoint	divide(FixPoint arg) Return a FixPoint with a value equal to the division of this FixPoint by the argument.
FixPoint	divide(FixPoint arg, Quantization quant) Return a FixPoint equal to the division of this FixPoint by the argument, after application of a quantization specification to the result.
static Precision	dividePrecision(Precision leftArgument, Precision rightArgument) Determines the Precision of a divide operation between two FixPoint values.
double	doubleValue() Return the value of this FixPoint as a double.
boolean	equals(java.lang.Object arg) Return true if this FixPoint is equal to the argument.
FixPoint.Error	getError() Deprecated. Overflow and rounding status no longer form part of the functionality. Use an overflow and rounding mode that gives the required behaviour or use Overflow.TRAP and/or Rounding.UNNECESSARY to throw exceptions if external interaction is required.
Precision	getPrecision() Return a precision to represent this number.
java.math.BigInteger	getUnscaledValue() Return the unscaled BigInteger value used to represent this FixPoint value.
int	hashCode() Return a hash code value for this value.
FixPoint	minimumQuantization() Return a new FixPoint value that has the same value as this FixPoint value but with the minimum quantization necessary for representing the value.
FixPoint	multiply(FixPoint arg) Return a FixPoint with a value equal to the product of this FixPoint and the argument.
FixPoint	multiply(FixPoint arg, Quantization quant) Return a FixPoint with a value equal to the product of this FixPoint and the argument.
static Precision	multiplyPrecision(Precision leftArgument, Precision rightArgument) Determines the Precision of an multiply operation between two FixPoint values.
void	printFix() Print useful debug information about the FixPoint to standard out.
FixPoint	quantize(Quantization quant) Return the value after conversion to comply with a quantization specification.
FixPoint	subtract(FixPoint arg) Return a FixPoint with a value equal to the difference between this FixPoint and the argument.
FixPoint	subtract(FixPoint arg, Quantization quant) Return a FixPoint with a value equal to the difference of this FixPoint and the argument.
static Precision	subtractPrecision(Precision leftArgument, Precision rightArgument) Determines the Precision of an subtract operation between two FixPoint values.
java.lang.String	toBitString() Return a bit string representation of this number.
java.lang.String	toString() Return a string representation of this number.
java.lang.String	toStringPrecision() Return a string representation of this number along with the Precision of the number.
java.lang.String	toStringValuePrecision() Return a string representation of this number along with the unscaled value and Precision of the number.

Methods inherited from class java.lang.Object

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

Field Detail

_value

private java.math.BigInteger _value

The BigInteger comprising the logical floating point value multiplied by 2^exponent.

_precision

private Precision _precision

The Precision of the given FixPoint value.

_error

private FixPoint.Error _error

The obsolete error condition of the FixValue

Constructor Detail

FixPoint

public FixPoint(java.math.BigDecimal bigDecimal,
                Quantization quant)

Construct a FixPoint by converting a bigDecimal to comply with a quantization specification.

Parameters:

bigDecimal - The floating point value.

quant - The quantization specification.

FixPoint

public FixPoint(FixPoint fix,
                Quantization quant)

Construct a new FixPoint object by requantizing the given FixPoint object with a new quantization specification. TODO: This isn't the most efficient way of requantizing a value. Need to look into more efficient techniques for doing simple requantizations rather than converting into a BigDecimal. Proposal: - Create methods in Rounding to support Rounding of "shifted" BigInteger values - Perform rounding using shifting rather than conversion to BigDecimal

Parameters:

fix - The existing FixPoint value

quant - The quantization specification.

FixPoint

public FixPoint(double doubleValue,
                Quantization quant)

Construct a FixPoint from a double. Perform the conversion using the given quantization specification.

Parameters:

doubleValue - The floating point value.

quant - The quantization specification.

Throws:

java.lang.IllegalArgumentException - If the doubleValue is equal to Double.NEGATIVE_INFINITY, Double.POSITIVE_INFINITY, or Double.NaN.

FixPoint

public FixPoint(int intValue,
                Quantization quant)

Construct a FixPoint from an integer. Perform the conversion using the given quantization specification. During conversion, overflow handling may result in a lossy conversion.

Parameters:

intValue - The integer value.

quant - The quantization specification.

FixPoint

public FixPoint(int intValue)

Construct a FixPoint from an integer. This is a loss-less conversion with a precision having as few bits as possible to represent the value and represented as a signed number.

Parameters:

intValue - The integer value.

FixPoint

public FixPoint(int intValue,
                boolean signed)

Construct a FixPoint from an integer. This is a loss-less conversion with a precision having as few bits as possible to represent the value and the signed determined by the signed parameter.

Parameters:

intValue - The integer value.

signed - if true, represent value as a signed number; otherwise represent value as an unsigned value.

FixPoint

public FixPoint(java.lang.String string,
                Quantization quant)

Construct a FixPoint by converting the BigDecimal interpretation of a string to comply with a quantization specification.

Parameters:

string - A string representation of the floating point value.

quant - The quantization specification.

Throws:

java.lang.IllegalArgumentException - If string is not a valid representation of a BigDecimal.

FixPoint

FixPoint(java.math.BigInteger unscaledIntegerValue,
         Precision precision)

Construct a FixPoint from an unscaled integerValue that with a given Precision constraint. This method will throw an exception if the precision is not sufficient to represent the given integer value.

Parameters:

unscaledIntegerValue - The integer value of the scaled floating point value.

precision - The precision to represent the new unscalled value.

Throws:

java.lang.ArithmeticException - when precision is not sufficient to represent integerValue. Note that this is package scope

Method Detail

addPrecision

public static Precision addPrecision(Precision leftArgument,
                                     Precision rightArgument)

Determines the Precision of an add operation between two FixPoint values. The Precision of the result of an add between two FixPoint values is the Precision union of the two arguments plus one (to allow for bit growth).

subtractPrecision

public static Precision subtractPrecision(Precision leftArgument,
                                          Precision rightArgument)

Determines the Precision of an subtract operation between two FixPoint values. The subtract precision will increment by one and always be signed.

multiplyPrecision

public static Precision multiplyPrecision(Precision leftArgument,
                                          Precision rightArgument)

Determines the Precision of an multiply operation between two FixPoint values. The resulting Precision of a multiply between two FixPoint arguments is as follows: the integer location is the sum of the integer locations of the two arguments and the fractional location is the sum of the fractional locations of the two arguments.

dividePrecision

public static Precision dividePrecision(Precision leftArgument,
                                        Precision rightArgument)

Determines the Precision of a divide operation between two FixPoint values. It is not possible to represent the result of an arbitrary divide with a finite precision. As such, this precision conversion rule is lossless. The rule for divide is as follows: - Integer part = left integer bits + right fraction bits + sign - Fraction part = left fractional bits + right integer bits + 1 - sign

abs

public FixPoint abs()

Return a FixPoint with a value equal to the absolute value of this FixPoint. The operation is lossless and the Precision of the result is the same Precision as this object.

Returns:

A non-negative fixed point.

add

public FixPoint add(FixPoint arg)

Return a FixPoint with a value equal to the sum of this FixPoint and the argument. The operation is lossless and will "expand" the Precision of the resulting FixPoint value to include the full precision of the result. This operation will operate on either signed or unsigned fixed values. If both operands of an operation are unsigned, the result will be unsigned. If either of the operations are signed, the result will be signed.

Parameters:

arg - The FixPoint addend.

Returns:

The FixPoint sum.

add

public FixPoint add(FixPoint arg,
                    Quantization quant)

Return a FixPoint with a value equal to the sum of this FixPoint and the argument. The precision of this operation is set by the Quantization parameter and the result of the operation may be lossy as dictated by the desired quantization.

Parameters:

arg - The FixPoint addend.

quant - The quantization specification.

Returns:

The FixPoint sum.

bigDecimalValue

public java.math.BigDecimal bigDecimalValue()

Return the value of this FixPoint as a BigDecimal number. This is lossless, since the scale of the BigDecimal is set to the number of fractional bits.

Returns:

The BigDecimal value of this FixPoint.

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 FixPoint.

divide

public FixPoint divide(FixPoint arg)
                throws java.lang.IllegalArgumentException

Return a FixPoint with a value equal to the division of this FixPoint by the argument. The operation is not lossless.

Parameters:

arg - The FixPoint.divisor.

Returns:

The FixPoint quotient.

Throws:

java.lang.IllegalArgumentException - If division by zero and infinity not quantizable.

divide

public FixPoint divide(FixPoint arg,
                       Quantization quant)
                throws java.lang.IllegalArgumentException

Return a FixPoint equal to the division of this FixPoint by the argument, after application of a quantization specification to the result. The operation is not lossless.

Division by zero results in a value of plus or minus infinity, which throws an exception if the overflow strategy defined by the quantization specification returns null for plusInfinity or minusInfinity.

Parameters:

arg - The FixPoint.divisor.

quant - The quantization specification.

Returns:

The FixPoint quotient.

Throws:

java.lang.IllegalArgumentException - If division by zero.

doubleValue

public double doubleValue()

Return the value of this FixPoint as a double. 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(java.lang.Object arg)

Return true if this FixPoint is equal to the argument. Two FixPoints are considered equal when the two values are precisely the same. The two FixPoints need not therefore have the same number of fraction bits, but any additional fractional bits in one value must be zero in the other.

Overrides:

equals in class java.lang.Object

Parameters:

arg - The FixPoint object to use for equality checking.

Returns:

True if the FixPoints are equal; false otherwise.

getError

public FixPoint.Error getError()

Deprecated. Overflow and rounding status no longer form part of the functionality. Use an overflow and rounding mode that gives the required behaviour or use Overflow.TRAP and/or Rounding.UNNECESSARY to throw exceptions if external interaction is required.

Get the Error condition from the FixValue.

Returns:

The error condition of the FixValue.

getPrecision

public Precision getPrecision()

Return a precision to represent this number. This is constructed from the necessary fraction precision and the integer precision annotation.

Returns:

The Precision of this number.

getUnscaledValue

public java.math.BigInteger getUnscaledValue()

Return the unscaled BigInteger value used to represent this FixPoint value.

Returns:

The BigInteger unscaled value of this number.

hashCode

public int hashCode()

Return a hash code value for this value. This method returns the low order 32 bits of the integer representation.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this value.

minimumQuantization

public FixPoint minimumQuantization()

Return a new FixPoint value that has the same value as this FixPoint value but with the minimum quantization necessary for representing the value. The first step of this requantization is to check for "zero" bits at the LSB positions of the unscaled value. The value is shifted until the first "1" is found and the exponent is adjusted. Next, the length of the unscaled value is examined and the precision is set to the minimum length possible to represent the value.

Returns:

The minimum quantize FixPoint value.

multiply

public FixPoint multiply(FixPoint arg)

Return a FixPoint with a value equal to the product of this FixPoint and the argument. The operation is lossless and will "expand" the Precision of the resulting FixPoint value to include the full precision of the result. This operation will operate on either signed or unsigned fixed values. If both operands of an operation are unsigned, the result will be unsigned. If either of the operations are signed, the result will be signed.

Parameters:

arg - The FixPoint multiplier.

Returns:

The FixPoint product.

multiply

public FixPoint multiply(FixPoint arg,
                         Quantization quant)

Return a FixPoint with a value equal to the product of this FixPoint and the argument. The precision of this operation is set by the Quantization parameter and the result of the operation may be lossy as dictated by the desired quantization.

Parameters:

arg - The FixPoint multiplicand.

quant - The quantization specification.

Returns:

The FixPoint product.

printFix

public void printFix()

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

quantize

public FixPoint quantize(Quantization quant)

Return the value after conversion to comply with a quantization specification. This method calls FixPoint(FixPoint, Quantization).

Parameters:

quant - The quantization constraints.

Returns:

The bounded integer value.

subtract

public FixPoint subtract(FixPoint arg)

Return a FixPoint with a value equal to the difference between this FixPoint and the argument. The operation is lossless and will "expand" the Precision of the resulting FixPoint value to include the full precision of the result. This operation will operate on either signed or unsigned fixed values. If either of the operations are signed, the result will be signed. If both operands are unsigned and the result is positive, an unsigned value will be produced. If both operands are unsigned and the result is negative, a signed value will be generated.

Parameters:

arg - The FixPoint subtrahend.

Returns:

The FixPoint difference.

subtract

public FixPoint subtract(FixPoint arg,
                         Quantization quant)

Return a FixPoint with a value equal to the difference of this FixPoint and the argument. The precision of this operation is set by the Quantization parameter and the result of the operation may be lossy as dictated by the desired quantization.

Parameters:

arg - The FixPoint addend.

quant - The quantization specification.

Returns:

The FixPoint sum.

toBitString

public java.lang.String toBitString()

Return a bit string representation of this number. The string takes the form "sign integerBits . fractionBits", where sign is - or nothing, integerBits and fractionBits are each a sequence of "0" and "1". integerBits comprises no leading zeroes. fractionBits has exactly one digit per bit. If the fixed point number has zero or negative number of fraction bits, the dot is omitted.

Returns:

A binary string representation of the value.

toString

public java.lang.String toString()

Return a string representation of this number. This is calculated by first converting the number to a BigDecimal, and then returning its string representation. In order to avoid loss there may be as many decimal digits following the decimal point as there fractional bits in this FixPoint.

Overrides:

toString in class java.lang.Object

Returns:

A decimal string representation of the value.

toStringPrecision

public java.lang.String toStringPrecision()

Return a string representation of this number along with the Precision of the number.

Returns:

A decimal string representation of the value and its precision.

toStringValuePrecision

public java.lang.String toStringValuePrecision()

Return a string representation of this number along with the unscaled value and Precision of the number.

Returns:

A decimal string representation of the value and its precision.

_alignToExponent

private java.math.BigInteger _alignToExponent(int exponent)

Return the BigInteger whose fractional part is aligned with the provided precision. This never involves rounding, but only padding the fractional part with zeros

Parameters:

exponent - The precision with which to align

Returns:

A BigInteger with aligned precision

_initFromBigDecimal

private void _initFromBigDecimal(java.math.BigDecimal bigDecimal,
                                 Quantization quant)

Initialize the _value and _precision of this object from a BigDecimal value. There are three steps involved with converting a BigDecimal value into a FixPoint value. The first step is to shift the BigDecimal value in a way that preserves all of the desired precision. Next, the shifted BigDecimal value is rounded using the appropriate rounding mode. The third and final step is to apply the appropriate Overflow strategy to the resuling BigInteger object. After completing this method, the _value and _precision are set.

Parameters:

bigDecimal - The floating point value.

quant - The quantization specification.

_initFromBigInteger

private void _initFromBigInteger(java.math.BigInteger bigInteger,
                                 Quantization quant)

Initialize the _value and _precision of this object from a BigInteger value. The primary step in this method is to perform the "overflow" check and requantization. The BigInteger will be quantized using the overflow policy provided by the quantization parameter. See Overflow.quantize(BigInteger, Precision). After completing this method, the _value and _precision are set.

Parameters:

bigInteger - The integer value.

quant - The quantization specification.