ptolemy.math

Class Precision

java.lang.Object

ptolemy.math.Precision

All Implemented Interfaces:

java.lang.Cloneable

public class Precision
extends java.lang.Object
implements java.lang.Cloneable

This class defines the precision of a signed or unsigned fixed point value. The precision of a fixed point value is represented as internally as three fields: the number of bits (n), the binary exponent (e), and a sign bit (s). The number of bits (n) defines the dynamic range of the format (2ⁿ). The exponent (e) determines the placement of the binary point for all values of this format. This binary point placement is "fixed" and is specified within the precision format rather than within individual Fixed point values. The mantissa bits of all fixed point values using this this precision format are multiplied by 2^m. Note that m can take on a positive, negative, or zero value. This allows the binary point to be placed anywhere necessary and even beyond the bounds of the mantissa (i.e. to the right of the lsb or to the left of the msb). The sign value s is used to indicate whether the fixed point precision value is treated as signed (s = 1) or unsigned (s = 0).

Signed fixed point formats are represented in a 2's complement format. As a consequence, a single bit is used to represent the sign of the number. The value of a multi-bit signed number is:

Signed(B) = 2^m x (- b_{n-1} x 2^{n-1} + \sum_{i=0}^{n-2} b_i x 2^i), where b_i is the value of bit i of the bit vector.

Unsigned fixed formats are represented as unsigned binary values. No bits are used to represent the sign and all values are positive. The actual value of a multi-bit unsigned fixed point number is:

Unsigned(B) = 2^m x (\sum_{i=0}^{n-1} b_i x 2^i)

This class supports several different String formats for specifying and displaying the Precision. These String formats are supported by several classes that extend the Precision.PrecisionFormat class. Several such classes have been created. Any given precision string format can be represented in any of the valid precision string formats. The four supported Precision String formats are shown in the table below. A static singleton object of each of these formats is provided in this class. Each String Representation column of the table represent equivalent Precision formats:

Precision Formats.

Format Name	Format Spec	String Representation
Precision.IntegerFractionPrecisionFormat	[integer bits].[fraction bits]	3.2	0.7	-2.12	12.-4	32.0	U1.7
Precision.LengthIntegerPrecisionFormat	[total bits]/[integer bits]	5/3	7/0	10/-2	8/12	32/32	U8/1
Precision.VHDLPrecisionFormat	[MSb position]:[LSb position]	2:-2	-1:-7	-3:-12	11:4	31:0	U0:-7
Precision.LengthExponentPrecisionFormat	[total bits]e[binary point position]	5e-2	7e-7	10e-12	8e4	32e0	U8e-7

An instance of the class is immutable, meaning that its value is set in the constructor and cannot then be modified.

Since:

Ptolemy II 0.4

Version:

$Id$

Author:

Bart Kienhuis, Contributor: Mike Wirthlin

See Also:

FixPoint

Pt.AcceptedRating:

Red (kienhuis)

Pt.ProposedRating:

Yellow (kienhuis)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Precision.ExpressionLanguagePrecisionFormat Precision format for use with the Expression Language.
static class	Precision.IntegerFractionPrecisionFormat Defines a Precision string format using the INTEGER.FRACTION precision format.
static class	Precision.LengthExponentPrecisionFormat Defines a Precision string format using the LENGTHeEXPONENT precision format.
static class	Precision.LengthIntegerPrecisionFormat Defines a Precision string format using the LENGTH/INTEGER precision format.
static class	Precision.PrecisionFormat Defines a String format for specifying a Precision object.
static class	Precision.VHDLPrecisionFormat Defines a Precision string format using the VHDL MSB:LSB precision format.

Field Summary

Fields

Modifier and Type	Field and Description
static Precision.PrecisionFormat	EXPRESSION_LANGUAGE static ExpressionLanguagePrecisionFormat object.
static Precision.PrecisionFormat	INTEGER_FRACTION static IntegerFractionPrecisionFormat object.
static Precision.PrecisionFormat	LENGTH_EXPONENT static LengthExponentPrecisionFormat object.
static Precision.PrecisionFormat	LENGTH_INTEGER static LengthIntegerPrecisionFormat object.
static Precision.PrecisionFormat	VHDL static VHDLPrecisionFormat object.

Constructor Summary

Constructors

Constructor and Description
Precision(int length, int integerBits) Construct a Precision object based on the length/integer bits format.
Precision(int sign, int length, int exponent) Construct a Precision object based on the sign, length, and exponent format.
Precision(java.lang.String str) Construct a Precision object based on the provided string.

Method Summary

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 is an instance of Precision and the precision format matches exactly.
java.math.BigDecimal	findMaximum() Return the maximum obtainable value in this precision.
java.math.BigDecimal	findMinimum() Return the minimum obtainable value for this precision.
java.math.BigDecimal	getEpsilon() Return the incremental value between discrete values under the given Precision format.
int	getExponent() Return the location of the binary exponent.
int	getFractionBitLength() Return the number of bits representing the fractional part.
int	getIntegerBitLength() Return the number of bits representing the integer part.
int	getLeastSignificantBitPosition() Return the bit position of the least significant bit of the given fixed point precision.
java.math.BigInteger	getMaximumUnscaledValue() Return the maximum integer value before scaling so that quantization levels are represented by adjacent integers.
java.math.BigInteger	getMinimumUnscaledValue() Return the minimum integer value before scaling so that quantization levels are represented by adjacent integers.
int	getMostSignificantBitPosition() Return the bit position of the most significant bit of the given fixed point precision.
int	getMostSignificantDataBitPosition() Return the bit position of the most significant data bit of the given fixed point precision.
int	getNumberOfBits() Return the total number of bits.
java.math.BigInteger	getNumberOfLevels() Return the total number of discrete values possible.
int	getSign() Return the sign (0 = unsigned, 1 = signed).
int	hashCode() Return a hash code value for this Precision.
boolean	isSigned() Determine if the fixed point format is signed or not.
static java.math.BigDecimal	shiftBigDecimal(java.math.BigDecimal val, int shiftval) Shift the BigDecimal value either right or left by a power of 2 value.
java.lang.String	toString() Return a string representing this precision.
java.lang.String	toString(Precision.PrecisionFormat format) Return a string representation of this format in one of several styles.
static Precision	union(Precision precisionA, Precision precisionB) Return the precision that is the maximum of the two supplied precisions in both the length and exponent.

Methods inherited from class java.lang.Object

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

Field Detail

INTEGER_FRACTION

public static final Precision.PrecisionFormat INTEGER_FRACTION

static IntegerFractionPrecisionFormat object.

LENGTH_EXPONENT

public static final Precision.PrecisionFormat LENGTH_EXPONENT

static LengthExponentPrecisionFormat object.

LENGTH_INTEGER

public static final Precision.PrecisionFormat LENGTH_INTEGER

static LengthIntegerPrecisionFormat object.

EXPRESSION_LANGUAGE

public static final Precision.PrecisionFormat EXPRESSION_LANGUAGE

static ExpressionLanguagePrecisionFormat object.

VHDL

public static final Precision.PrecisionFormat VHDL

static VHDLPrecisionFormat object.

Constructor Detail

Precision

public Precision(java.lang.String str)
          throws java.lang.IllegalArgumentException

Construct a Precision object based on the provided string. The string can describe the precision in any of the syntaxes explained in the description of this class.

Parameters:

str - The string representing the precision.

Throws:

java.lang.IllegalArgumentException - If the precision string supplied does not match one of the known formats.

Precision

public Precision(int length,
                 int integerBits)
          throws java.lang.IllegalArgumentException

Construct a Precision object based on the length/integer bits format. This constructor will create a new signed Precision object with length bits and an exponent of -fracBits.

Parameters:

length - The total number of bits.

integerBits - The number of integer bits.

Throws:

java.lang.IllegalArgumentException - If the given values are negative or when the integer number of bits is larger than the total number of bits.

Precision

public Precision(int sign,
                 int length,
                 int exponent)
          throws java.lang.IllegalArgumentException

Construct a Precision object based on the sign, length, and exponent format.

Parameters:

sign - The presence of a sign bit (1 = signed, 0 = unsigned).

length - The total number of bits.

exponent - The bit location of the exponent.

Throws:

java.lang.IllegalArgumentException - If the Precision arguments are inconsistent.

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

equals

public boolean equals(java.lang.Object object)

Return true if the indicated object is an instance of Precision and the precision format matches exactly.

Overrides:

equals in class java.lang.Object

Parameters:

object - Object to test for equality

Returns:

True if the precisions are equal.

findMaximum

public java.math.BigDecimal findMaximum()

Return the maximum obtainable value in this precision. This value is obtained by multiplying the result of getMaximumUnscaledValue() by 2^exponent.

Returns:

The maximum value obtainable for this precision.

findMinimum

public java.math.BigDecimal findMinimum()

Return the minimum obtainable value for this precision. This value is obtained by multiplying the result of getMinimumUnscaledValue() by 2^exponent.

Returns:

The minimum value obtainable for the given precision.

getEpsilon

public java.math.BigDecimal getEpsilon()

Return the incremental value between discrete values under the given Precision format. This is calculated as 2^exponent.

Returns:

Incremental (epsilon) value.

getExponent

public int getExponent()

Return the location of the binary exponent.

Returns:

the location of the fixed binary exponent.

getFractionBitLength

public int getFractionBitLength()

Return the number of bits representing the fractional part. The is computed as -exponent.

Returns:

The length of the fractional part.

getIntegerBitLength

public int getIntegerBitLength()

Return the number of bits representing the integer part. This is computed as length + exponent.

Returns:

the length of the integer part.

getLeastSignificantBitPosition

public int getLeastSignificantBitPosition()

Return the bit position of the least significant bit of the given fixed point precision. This value is the same as the exponent value of this format. Bit 0 refers to the bit just to the left of the binary point.

Returns:

Least significant bit position.

getMaximumUnscaledValue

public java.math.BigInteger getMaximumUnscaledValue()

Return the maximum integer value before scaling so that quantization levels are represented by adjacent integers. For signed values, this number is 2^(n-1) - 1 For unsigned values, this number is 2^(n) - 1

Returns:

The maximum inclusive value.

getMinimumUnscaledValue

public java.math.BigInteger getMinimumUnscaledValue()

Return the minimum integer value before scaling so that quantization levels are represented by adjacent integers. For signed values, this number is -(2^(n-1)) For unsigned values, this number is 0.

Returns:

The minimum unscaled value value obtainable for the given precision.

getMostSignificantBitPosition

public int getMostSignificantBitPosition()

Return the bit position of the most significant bit of the given fixed point precision. Bit 0 refers to the bit just to the left of the binary point.

Returns:

Least significant bit position.

getMostSignificantDataBitPosition

public int getMostSignificantDataBitPosition()

Return the bit position of the most significant data bit of the given fixed point precision. If this Precision is signed, this will return getMostSignificantBitPosition - 1. If this Precision is unsigned, this will return getMostSignificantBitPosition.

Returns:

Least significant bit position.

getNumberOfBits

public int getNumberOfBits()

Return the total number of bits.

Returns:

the total number of bits.

getNumberOfLevels

public java.math.BigInteger getNumberOfLevels()

Return the total number of discrete values possible.

Returns:

the total number of levels.

getSign

public int getSign()

Return the sign (0 = unsigned, 1 = signed).

Returns:

the sign status.

hashCode

public int hashCode()

Return a hash code value for this Precision. This method returns the bitwise and of the length, exponent and sign.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this Precision.

isSigned

public boolean isSigned()

Determine if the fixed point format is signed or not.

Returns:

true if format is signed

union

public static Precision union(Precision precisionA,
                              Precision precisionB)

Return the precision that is the maximum of the two supplied precisions in both the length and exponent. This method is used to align instances of FixPoint onto a single precision representation. If either Precision object is signed, the new Precision object will be signed.

Parameters:

precisionA - A precision

precisionB - Another precision

Returns:

A precision at least as precise as the two arguments.

shiftBigDecimal

public static java.math.BigDecimal shiftBigDecimal(java.math.BigDecimal val,
                                                   int shiftval)

Shift the BigDecimal value either right or left by a power of 2 value. This method will perform a multiplication by 2^^shiftval on the BigDecimal value when shiftval is positive and will perform a divide by 2^^-shiftval on the BigDecimal value when shiftval is negative.

Parameters:

val - BigDecimal value to shift.

shiftval - Amount of "power of 2" shifting to perform on the BigDecimal value

Returns:

shifted BigDecimal value.

toString

public java.lang.String toString()

Return a string representing this precision. The string is expressed as "(m.n)", where m indicates the number of integer bits and n represents the number of fractional bits.

Overrides:

toString in class java.lang.Object

Returns:

A string representing this precision.

toString

public java.lang.String toString(Precision.PrecisionFormat format)

Return a string representation of this format in one of several styles.

Parameters:

format - The String format represented desired for printing.

Returns:

String representation of the object using the given PrecisionFormat