Package ptolemy.math

Class 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:

    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)
    • Constructor Summary

      Constructors 
      Constructor 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 Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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
    • 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