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 (2n). 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 2m. 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:

 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: Precision.java 70402 2014-10-23 00:52:20Z cxh$
Author:
Bart Kienhuis, Contributor: Mike Wirthlin
FixPoint
Accepted Rating:
 Red (kienhuis)
Proposed Rating:
 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

All Methods
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 2exponent.
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 2exponent.
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