Package org.apache.commons.numbers.core

Class ExtendedPrecision

  • final class ExtendedPrecision
extends java.lang.Object
    Computes extended precision floating-point operations.

    Extended precision computation is delegated to the DD class. The methods here are extensions to prevent overflow or underflow in intermediate computations.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static double DOWN_SCALE
      The scale to use when down-scaling during a split into a high part.
      private static double DOWN_SCALE2
      The downscale factor squared.
      private static double SAFE_LOWER
      The lower limit for a product x * y below which the round-off component may be sub-normal.
      private static double SAFE_UPPER
      The upper limit above which a number may overflow during the split into a high part.
      private static double UP_SCALE
      The scale to use when up-scaling during a split into a high part.
      private static double UP_SCALE2
      The upscale factor squared.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ExtendedPrecision()
      Private constructor.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static double productLow​(double x, double y, double xy)
      Compute the low part of the double length number (z,zz) for the exact product of x and y.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • SAFE_UPPER

        private static final double SAFE_UPPER
        The upper limit above which a number may overflow during the split into a high part. Assuming the multiplier is above 2^27 and the maximum exponent is 1023 then a safe limit is a value with an exponent of (1023 - 27) = 2^996. 996 is the value obtained from Math.getExponent(Double.MAX_VALUE / MULTIPLIER).
        See Also:
        Constant Field Values

      • SAFE_LOWER

        private static final double SAFE_LOWER
        The lower limit for a product x * y below which the round-off component may be sub-normal. This is set as 2^-1022 * 2^54.
        See Also:
        Constant Field Values

      • DOWN_SCALE

        private static final double DOWN_SCALE
        The scale to use when down-scaling during a split into a high part. This must be smaller than the inverse of the multiplier and a power of 2 for exact scaling.
        See Also:
        Constant Field Values

      • UP_SCALE

        private static final double UP_SCALE
        The scale to use when up-scaling during a split into a high part. This is the inverse of DOWN_SCALE.
        See Also:
        Constant Field Values

      • UP_SCALE2

        private static final double UP_SCALE2
        The upscale factor squared.
        See Also:
        Constant Field Values

      • DOWN_SCALE2

        private static final double DOWN_SCALE2
        The downscale factor squared.
        See Also:
        Constant Field Values

    • Constructor Detail

      • ExtendedPrecision

        private ExtendedPrecision()
        Private constructor.

    • Method Detail

      • productLow

        static double productLow​(double x,
                         double y,
                         double xy)
        Compute the low part of the double length number (z,zz) for the exact product of x and y. This is equivalent to computing a double containing the magnitude of the rounding error when converting the exact 106-bit significand of the multiplication result to a 53-bit significand.

        The method is written to be functionally similar to using a fused multiply add (FMA) operation to compute the low part, for example JDK 9's Math.fma function (note the sign change in the input argument for the product): 

          double x = ...;
  double y = ...;
  double xy = x * y;
  double low1 = Math.fma(x, y, -xy);
  double low2 = productLow(x, y, xy);

        Special cases:

        • If x * y is sub-normal or zero then the result is 0.0.
        • If x * y is infinite or NaN then the result is NaN.

        This method delegates to DD.twoProductLow(double, double, double) but uses scaling to avoid intermediate overflow.

        Parameters:
        x - First factor.
        y - Second factor.
        xy - Product of the factors (x * y).
        Returns:
        the low part of the product double length number
        See Also:
        DD.twoProductLow(double, double, double)