Package ptolemy.math

Class FixPoint

  • All Implemented Interfaces:
    java.lang.Cloneable

    public class FixPoint
    extends java.lang.Object
    implements java.lang.Cloneable
    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$
    Author:
    Bart Kienhuis, Ed Willink, Contributor: Edward A. Lee, Mike Wirthlin
    See Also:
    Precision, Quantization
    Pt.AcceptedRating:
    Red
    Pt.ProposedRating:
    Red (Ed.Willink)
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  FixPoint.Error
      An instance of this class is used preserve backwards interface compatibility.
    • Constructor Summary

      Constructors 
      Constructor Description
      FixPoint​(double doubleValue, Quantization quant)
      Construct a FixPoint from a double.
      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.
      FixPoint​(java.math.BigDecimal bigDecimal, Quantization quant)
      Construct a FixPoint by converting a bigDecimal to comply with a quantization specification.
      FixPoint​(FixPoint fix, Quantization quant)
      Construct a new FixPoint object by requantizing the given FixPoint object with a new quantization specification.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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.
      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
    • 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.
    • 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

        @Deprecated
        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.