Package xal.tools.math

Class ElementaryFunction

java.lang.Object
xal.tools.math.ElementaryFunction
public final class ElementaryFunction extends Object

Utility case for defining elementary mathematical functions that are not, but should be, included in the java.lang.Math class. Several of the functions in this class are implemented using the methods of java.lang.Math.

Author:
Christopher K. Allen
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DBL_DEC_TO_BINARY
    conversion between significant digits in decimal to significant digits in binary log(10)/log(2)
    static final double
    EPS
    small tolerance value
    static final double
    PI_BY_2
    the value PI/2
    static final int
    ULPS_DEFLT_BRACKET
    number of Units in the Last Place (ULPs) used for bracketing approximately equal values

  • Method Summary

    Modifier and Type
    Method
    Description
    static final double
    acosh(double x)
    Inverse hyperbolic cosine function.
    static boolean
    approxEq(double x, double y)
    Test if two double precision numbers are approximately equal.
    static boolean
    approxEq(double x, double y, int cntUlps)
    Test if two double precision numbers are approximately equal.
    static final double
    asinh(double x)
    Inverse hyperbolic sine function.
    static final double
    atanh(double x)
    Inverse hyperbolic tangent function.
    static final double
    cosh(double x)
    Hyperbolic cosine function.
    static final int
    factorial(int n)
    Computes the factorial of the given integer.
    static boolean
    neighbors(double x, double y, double r)
    Test if two double precision numbers are in the same ball of radius r.
    static final double
    pow(double dblBase, int intExpon)
    Returns the value of the first argument raised to the power of the second argument dblBasedblExpon.
    static final long
    pow(int intBase, int intExpon)
    Returns the value of the first argument raised to the power of the second argument intBaseintExpon where the base is an integer.
    static boolean
    significantDigitsEqs(double x, double y, int cntDgts)
    Checks if two double precision numbers are equal up to the given number of significant digits.
    static double
    sinc(double x)
    Implementation of the sinc function where

      sinc(x) ≡ sin(x)/x.
    static double
    sinch(double x)
    Implementation of the sinch function where

      sinch(x) ≡ sinh(x)/x

    static double
    sinchm(double x)
    Returns the sinch(x2).
    static final double
    sinh(double x)
    Hyperbolic sine function.
    static final double
    tanh(double x)
    Hyperbolic tangent function.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • ULPS_DEFLT_BRACKET

      public static final int ULPS_DEFLT_BRACKET
      number of Units in the Last Place (ULPs) used for bracketing approximately equal values
      See Also:

    • DBL_DEC_TO_BINARY

      public static final double DBL_DEC_TO_BINARY
      conversion between significant digits in decimal to significant digits in binary log(10)/log(2)
      See Also:

    • PI_BY_2

      public static final double PI_BY_2
      the value PI/2
      See Also:

    • EPS

      public static final double EPS
      small tolerance value
      See Also:

  • Method Details

    • approxEq

      public static boolean approxEq(double x, double y)
      Test if two double precision numbers are approximately equal. This condition is checked using the the default number of Units in the Last Place (ULPs) bracketing the two numbers. The default number of ULPs is given in the class constant ULPS_DEFLT_BRACKET and current has the value 100.
      Parameters:
      x - double precision number
      y - double precision number
      Returns:
      true of y ~ x, false otherwise
      See Also:

    • approxEq

      public static boolean approxEq(double x, double y, int cntUlps)

      Test if two double precision numbers are approximately equal. This condition is defined with respect to the Units in Last Place (ULPs) bracketing procedure.

      The ULP values ulpx and ulpy are computed for each argument x and y. These values are the distances between the arguments and the nearest double precision number that can be represented by the IEEE 754 standard. The bracketing distances δx and δy for x and y are computed as 

            δx ≜ N × ulpx ,
      δy ≜ N × ulpy ,
      where N is the number of ULPs specified in the arguments. Two intervals are defined 
            Ix ≜ [x − δx,x + δx],
      Iy ≜ [y − δy,y + δy].
      If the intersection Ix ∩ Iy is finite then x and y are considered approximately equal.

      Parameters:
      x - double precision number
      y - double precision number
      cntUlps - number N of ULPs used to bracket the numbers
      Returns:
      true of y ~ x within N ULPs, false otherwise

    • significantDigitsEqs

      public static boolean significantDigitsEqs(double x, double y, int cntDgts)
      Checks if two double precision numbers are equal up to the given number of significant digits.
      Parameters:
      x - double precision number
      y - double precision number
      cntDgts - number N of significant digits to compare
      Returns:
      true if the first N digits of x and y agree, false otherwise
      Since:
      Dec 31, 2015, Christopher K. Allen

    • neighbors

      public static boolean neighbors(double x, double y, double r)

      Test if two double precision numbers are in the same ball of radius r.

      NOTES CKA

      · This is really a distance function and not a topological one.

      Parameters:
      x - double precision number
      y - double precision number
      r - radius defining the size of the neighborhood
      Returns:
      true of |y - x| <= r, false otherwise

    • factorial

      public static final int factorial(int n)
      Computes the factorial of the given integer. The factorial n! of the number n is defined

          n! ≡ 1 · 2 · … · (n - 1) · n
      Parameters:
      n - integer to be "factorialized"
      Returns:
      n! = factorial of argument
      Since:
      Dec 9, 2011

    • pow

      public static final double pow(double dblBase, int intExpon)

      Returns the value of the first argument raised to the power of the second argument dblBasedblExpon. Special cases:

      · If the second argument is positive or negative zero, then the result is 1.0.
      · If the second argument is 1.0, then the result is the same as the first argument.
      · If the second argument is NaN, then the result is NaN.
      · If the first argument is NaN and the second argument is nonzero, then the result is NaN.

      This method should be used over that of Math.pow(double, double) whenever the exponent is an integer. Since the later must consider the case of non-integer exponents the algorithm used there is more expensive than the simple multiplication used here.

      Parameters:
      dblBase - the base of the exponential
      intExpon - the exponent
      Returns:
      the value dblBasedblExpon
      Since:
      Dec 9, 2011

    • pow

      public static final long pow(int intBase, int intExpon)

      Returns the value of the first argument raised to the power of the second argument intBaseintExpon where the base is an integer. Special cases:

      · If the second argument is positive or negative zero, then the result is 1.
      · If the second argument is 1, then the result is the same as the first argument.
      · If the second argument is NaN, then the result is NaN.
      · If the first argument is NaN and the second argument is nonzero, then the result is NaN.

      This method should be used over that of Math.pow(double, double) whenever both the base and the exponent are integers. Since the later must consider the case of non-integer exponents the algorithm used here is less expensive.

      Parameters:
      intBase - the base of the exponential
      intExpon - the exponent
      Returns:
      the value intBaseintExpon
      Since:
      Dec 9, 2011

    • sinc

      public static double sinc(double x)

      Implementation of the sinc function where

        sinc(x) ≡ sin(x)/x.

      For small values of x we Taylor expand the sinc function to sixth order,

        sinc(x) ≈ 1 - x2/6 + x4/120 - x6/5040 + O(x8).

      otherwise we return sin(x)/x.

      Parameters:
      x - any real number
      Returns:
      sinc(x) ≡ sin(x)/x

    • sinch

      public static double sinch(double x)

      Implementation of the sinch function where

        sinch(x) ≡ sinh(x)/x

      For small values of x we Taylor expand the hyperbolic sine function to sixth order,

        sinch(x) ≈ 1 + x2/6 + x4/120 + x6/5040 + O(x8).

      Otherwise we return sinh(x)/x.

      Parameters:
      x - any real number
      Returns:
      sinh(x)/x.

    • sinchm

      public static double sinchm(double x)
      Returns the sinch(x2). I am not sure why this needs a special implementation, but it's here. There is not special computation, the result is computed directly as sinch(x2).
      Parameters:
      x - any real number
      Returns:
      sinch(x2)
      See Also:

    • sinh

      public static final double sinh(double x)
      Hyperbolic sine function. This should really be included in Java.
      Parameters:
      x - any real number
      Returns:
      ½(e+x - e-x)

    • cosh

      public static final double cosh(double x)
      Hyperbolic cosine function. This too.
      Parameters:
      x - any real number
      Returns:
      ½(e+x + e-x)

    • tanh

      public static final double tanh(double x)
      Hyperbolic tangent function.
      Returns:
      sinh(x)/cosh(x)

    • asinh

      public static final double asinh(double x)
      Inverse hyperbolic sine function.
      Parameters:
      x - any real number
      Returns:
      log[x + (x2 + 1)1/2]

    • acosh

      public static final double acosh(double x) throws IllegalArgumentException
      Inverse hyperbolic cosine function. Note that due to the nature of the hyperbolic cosine function the argument must be greater than 1.0.
      Parameters:
      x - a real number in the interval [1,+∞)
      Returns:
      log[x + (x2 - 1)1/2]
      Throws:
      IllegalArgumentException - argument value is outside the domain of definition

    • atanh

      public static final double atanh(double x) throws IllegalArgumentException
      Inverse hyperbolic tangent function. Note that do to the nature of the inverse hyperbolic tangent function overflow may occur for arguments close to the values -1 and 1.
      Parameters:
      x - a real number in the open interval (-1,1)
      Returns:
      ½log[(x + 1)/(x - 1)]
      Throws:
      IllegalArgumentException - argument value is outside the domain of definition