Package org.hipparchus.util

Class MathUtils

java.lang.Object
org.hipparchus.util.MathUtils
public final class MathUtils extends Object
Miscellaneous utility functions.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    MathUtils.FieldSumAndResidual<T extends FieldElement<T>>
    Result class for twoSum(FieldElement, FieldElement) containing the sum and the residual error in the sum.
    static final class 
    MathUtils.SumAndResidual
    Result class for twoSum(double, double) containing the sum and the residual error in the sum.

  • Field Summary

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

  • Method Summary

    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.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Method Details

    • 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.

    • checkFinite

      public static void checkFinite(double x) throws MathIllegalArgumentException
      Check that the argument is a real number.
      Parameters:
      x - Argument.
      Throws:
      MathIllegalArgumentException - if x is not a finite real number.

    • checkFinite

      public static void checkFinite(double[] val) throws MathIllegalArgumentException
      Check that all the elements are real numbers.
      Parameters:
      val - Arguments.
      Throws:
      MathIllegalArgumentException - if any values of the array is not a finite real number.

    • 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.

    • checkNotNull

      public static void checkNotNull(Object o) throws NullArgumentException
      Checks that an object is not null.
      Parameters:
      o - Object to be checked.
      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