Class MathUtils

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double PI_SQUARED
      \(\pi^2\)
      static double SEMI_PI
      \(\pi/2\).
      static double TWO_PI
      \(2\pi\)
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void checkDimension​(int dimension, int otherDimension)
      Checks that the given dimensions match.
      static void checkFinite​(double x)
      Check that the argument is a real number.
      static void checkFinite​(double[] val)
      Check that all the elements are real numbers.
      static void checkNotNull​(Object o)
      Checks that an object is not null.
      static void checkNotNull​(Object o, Localizable pattern, Object... args)
      Checks that an object is not null.
      static void checkRangeInclusive​(double value, double lo, double hi)
      Checks that the given value is strictly within the range [lo, hi].
      static void checkRangeInclusive​(long value, long lo, long hi)
      Checks that the given value is strictly within the range [lo, hi].
      static byte copySign​(byte magnitude, byte sign)
      Returns the first argument with the sign of the second argument.
      static int copySign​(int magnitude, int sign)
      Returns the first argument with the sign of the second argument.
      static long copySign​(long magnitude, long sign)
      Returns the first argument with the sign of the second argument.
      static short copySign​(short magnitude, short sign)
      Returns the first argument with the sign of the second argument.
      static boolean equals​(double x, double y)
      Returns true if the values are equal according to semantics of Double.equals(Object).
      static int hash​(double value)
      Returns an integer hash code representing the given double value.
      static int hash​(double[] value)
      Returns an integer hash code representing the given double array.
      static <T extends CalculusFieldElement<T>>
      T
      max​(T e1, T e2)
      Find the maximum of two field elements.
      static <T extends CalculusFieldElement<T>>
      T
      min​(T e1, T e2)
      Find the minimum of two field elements.
      static double normalizeAngle​(double a, double center)
      Normalize an angle in a 2π wide interval around a center value.
      static <T extends CalculusFieldElement<T>>
      T
      normalizeAngle​(T a, T center)
      Normalize an angle in a 2π wide interval around a center value.
      static double reduce​(double a, double period, double offset)
      Reduce |a - offset| to the primary interval [0, |period|).
      static MathUtils.SumAndResidual twoSum​(double a, double b)
      Sums a and b using Møller's 2Sum algorithm.
      static <T extends FieldElement<T>>
      MathUtils.FieldSumAndResidual<T>
      twoSum​(T a, T b)
      Sums a and b using Møller's 2Sum algorithm.
    • Method Detail

      • hash

        public static int hash​(double value)
        Returns an integer hash code representing the given double value.
        Parameters:
        value - the value to be hashed
        Returns:
        the hash code
      • equals

        public static boolean equals​(double x,
                                     double y)
        Returns true if the values are equal according to semantics of Double.equals(Object).
        Parameters:
        x - Value
        y - Value
        Returns:
        Double.valueOf(x).equals(Double.valueOf(y))
      • hash

        public static int hash​(double[] value)
        Returns an integer hash code representing the given double array.
        Parameters:
        value - the value to be hashed (may be null)
        Returns:
        the hash code
      • normalizeAngle

        public static double normalizeAngle​(double a,
                                            double center)
        Normalize an angle in a 2π wide interval around a center value.

        This method has three main uses:

        • normalize an angle between 0 and 2π:
          a = MathUtils.normalizeAngle(a, FastMath.PI);
        • normalize an angle between -π and +π
          a = MathUtils.normalizeAngle(a, 0.0);
        • compute the angle between two defining angular positions:
          angle = MathUtils.normalizeAngle(end, start) - start;

        Note that due to numerical accuracy and since π cannot be represented exactly, the result interval is closed, it cannot be half-closed as would be more satisfactory in a purely mathematical view.

        Parameters:
        a - angle to normalize
        center - center of the desired 2π interval for the result
        Returns:
        a-2kπ with integer k and center-π <= a-2kπ <= center+π
      • normalizeAngle

        public static <T extends CalculusFieldElement<T>> T normalizeAngle​(T a,
                                                                           T center)
        Normalize an angle in a 2π wide interval around a center value.

        This method has three main uses:

        • normalize an angle between 0 and 2π:
          a = MathUtils.normalizeAngle(a, FastMath.PI);
        • normalize an angle between -π and +π
          a = MathUtils.normalizeAngle(a, zero);
        • compute the angle between two defining angular positions:
          angle = MathUtils.normalizeAngle(end, start).subtract(start);

        Note that due to numerical accuracy and since π cannot be represented exactly, the result interval is closed, it cannot be half-closed as would be more satisfactory in a purely mathematical view.

        Type Parameters:
        T - the type of the field elements
        Parameters:
        a - angle to normalize
        center - center of the desired 2π interval for the result
        Returns:
        a-2kπ with integer k and center-π <= a-2kπ <= center+π
      • max

        public static <T extends CalculusFieldElement<T>> T max​(T e1,
                                                                T e2)
        Find the maximum of two field elements.
        Type Parameters:
        T - the type of the field elements
        Parameters:
        e1 - first element
        e2 - second element
        Returns:
        max(a1, e2)
      • min

        public static <T extends CalculusFieldElement<T>> T min​(T e1,
                                                                T e2)
        Find the minimum of two field elements.
        Type Parameters:
        T - the type of the field elements
        Parameters:
        e1 - first element
        e2 - second element
        Returns:
        min(a1, e2)
      • reduce

        public static double reduce​(double a,
                                    double period,
                                    double offset)

        Reduce |a - offset| to the primary interval [0, |period|).

        Specifically, the value returned is
        a - |period| * floor((a - offset) / |period|) - offset.

        If any of the parameters are NaN or infinite, the result is NaN.

        Parameters:
        a - Value to reduce.
        period - Period.
        offset - Value that will be mapped to 0.
        Returns:
        the value, within the interval [0 |period|), that corresponds to a.
      • copySign

        public static byte copySign​(byte magnitude,
                                    byte sign)
                             throws MathRuntimeException
        Returns the first argument with the sign of the second argument.
        Parameters:
        magnitude - Magnitude of the returned value.
        sign - Sign of the returned value.
        Returns:
        a value with magnitude equal to magnitude and with the same sign as the sign argument.
        Throws:
        MathRuntimeException - if magnitude == Byte.MIN_VALUE and sign >= 0.
      • copySign

        public static short copySign​(short magnitude,
                                     short sign)
                              throws MathRuntimeException
        Returns the first argument with the sign of the second argument.
        Parameters:
        magnitude - Magnitude of the returned value.
        sign - Sign of the returned value.
        Returns:
        a value with magnitude equal to magnitude and with the same sign as the sign argument.
        Throws:
        MathRuntimeException - if magnitude == Short.MIN_VALUE and sign >= 0.
      • copySign

        public static int copySign​(int magnitude,
                                   int sign)
                            throws MathRuntimeException
        Returns the first argument with the sign of the second argument.
        Parameters:
        magnitude - Magnitude of the returned value.
        sign - Sign of the returned value.
        Returns:
        a value with magnitude equal to magnitude and with the same sign as the sign argument.
        Throws:
        MathRuntimeException - if magnitude == Integer.MIN_VALUE and sign >= 0.
      • copySign

        public static long copySign​(long magnitude,
                                    long sign)
                             throws MathRuntimeException
        Returns the first argument with the sign of the second argument.
        Parameters:
        magnitude - Magnitude of the returned value.
        sign - Sign of the returned value.
        Returns:
        a value with magnitude equal to magnitude and with the same sign as the sign argument.
        Throws:
        MathRuntimeException - if magnitude == Long.MIN_VALUE and sign >= 0.
      • checkNotNull

        public static void checkNotNull​(Object o,
                                        Localizable pattern,
                                        Object... args)
                                 throws NullArgumentException
        Checks that an object is not null.
        Parameters:
        o - Object to be checked.
        pattern - Message pattern.
        args - Arguments to replace the placeholders in pattern.
        Throws:
        NullArgumentException - if o is null.
      • checkRangeInclusive

        public static void checkRangeInclusive​(long value,
                                               long lo,
                                               long hi)
        Checks that the given value is strictly within the range [lo, hi].
        Parameters:
        value - value to be checked.
        lo - the lower bound (inclusive).
        hi - the upper bound (inclusive).
        Throws:
        MathIllegalArgumentException - if value is strictly outside [lo, hi].
      • checkRangeInclusive

        public static void checkRangeInclusive​(double value,
                                               double lo,
                                               double hi)
        Checks that the given value is strictly within the range [lo, hi].
        Parameters:
        value - value to be checked.
        lo - the lower bound (inclusive).
        hi - the upper bound (inclusive).
        Throws:
        MathIllegalArgumentException - if value is strictly outside [lo, hi].
      • checkDimension

        public static void checkDimension​(int dimension,
                                          int otherDimension)
        Checks that the given dimensions match.
        Parameters:
        dimension - the first dimension.
        otherDimension - the second dimension.
        Throws:
        MathIllegalArgumentException - if length != otherLength.
      • twoSum

        public static MathUtils.SumAndResidual twoSum​(double a,
                                                      double b)
        Sums a and b using Møller's 2Sum algorithm.

        References:

        • Møller, Ole. "Quasi double-precision in floating point addition." BIT 5, 37–50 (1965).
        • Shewchuk, Richard J. "Adaptive Precision Floating-Point Arithmetic and Fast Robust Geometric Predicates." Discrete & Computational Geometry 18, 305–363 (1997).
        • https://en.wikipedia.org/wiki/2Sum
        Parameters:
        a - first summand
        b - second summand
        Returns:
        sum and residual error in the sum
      • twoSum

        public static <T extends FieldElement<T>> MathUtils.FieldSumAndResidual<T> twoSum​(T a,
                                                                                          T b)
        Sums a and b using Møller's 2Sum algorithm.

        References:

        • Møller, Ole. "Quasi double-precision in floating point addition." BIT 5, 37–50 (1965).
        • Shewchuk, Richard J. "Adaptive Precision Floating-Point Arithmetic and Fast Robust Geometric Predicates." Discrete & Computational Geometry 18, 305–363 (1997).
        • https://en.wikipedia.org/wiki/2Sum
        Type Parameters:
        T - field element type
        Parameters:
        a - first summand
        b - second summand
        Returns:
        sum and residual error in the sum