edu.northwestern.at.utils.math

## Class ArithUtils

- java.lang.Object
- - edu.northwestern.at.utils.math.ArithUtils

-     public class ArithUtils
      extends java.lang.Object

  Basic numeric operations not included in standard Java run-time library.

  The binomial methods are modified from those in the Colt library.

  The following methods for trigonometric functions come from the Sfun class written by Visual Numerics.

  - acosh
  - asinh
  - atanh
  - cot
  - cosh
  - sinh
  - tanh

  These methods are covered by the following license.

  ------------------------------------------------------------------------- $Id: Sfun.java,v 1.1.1.1 1999/03/05 21:43:39 brophy Exp $ ------------------------------------------------------------------------- Copyright (c) 1997 - 1998 by Visual Numerics, Inc. All rights reserved. Permission to use, copy, modify, and distribute this software is freely granted by Visual Numerics, Inc., provided that the copyright notice above and the following warranty disclaimer are preserved in human readable form. Because this software is licensed free of charge, it is provided "AS IS", with NO WARRANTY. TO THE EXTENT PERMITTED BY LAW, VNI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ITS PERFORMANCE, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. VNI WILL NOT BE LIABLE FOR ANY DAMAGES WHATSOEVER ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, PUNITIVE, AND EXEMPLARY DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. -------------------------------------------------------------------------

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static double` | `EPSILON_LARGE` The largest relative spacing for doubles.
    `static double` | `EPSILON_SMALL` The smallest relative spacing for doubles.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ArithUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static double` | `acosh(double x)` Return the inverse (arc) hyperbolic cosine of a double.
    `static boolean` | `areEqual(double a, double b)` Check if two doubles are equal to machine precision.
    `static boolean` | `areEqual(double a, double b, double tolerance)` Check if two doubles are equal to specified tolerance.
    `static double` | `asinh(double x)` Return the inverse (arc) hyperbolic sine of a double.
    `static double` | `atanh(double x)` Returns the inverse (arc) hyperbolic tangent of a double.
    `static double` | `binomial(double n, long k)` Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k".
    `static double` | `binomial(long n, long k)` Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k".
    `static double` | `cosh(double x)` Return the hyperbolic cosine of a double.
    `static double` | `cot(double x)` Return the contangent of a double.
    `static double` | `expm1(double x)` Get exp( x ) - 1.
    `static int` | `fuzzyCompare(double a, double b, double tolerance)` Perform fuzzy comparison of two doubles with specified tolerance.
    `static double` | `hypot(double a, double b)` Safely calculate hypotenuse value.
    `static boolean` | `isNegativeZero(double x)` Check if number is negative zero.
    `static double` | `log10(double x)` Get log base 10 of a double.
    `static double` | `log1p(double x)` Get log of a double + 1.
    `static double` | `log2(double x)` Get log base 2 of a double.
    `static double` | `logDiffLogs(double logX, double logY)` Get the log( exp( logX ) - exp( logY ) ).
    `static double` | `logSumLogs(double logX, double logY)` Get the log( exp( logX ) + exp( logY ) ).
    `static double` | `round(double x, int n)` Round double to specified number of decimal places.
    `static double` | `safeLog(double x)` Return natural log of a double.
    `static int` | `sign(double d)` Return sign of a double.
    `static double` | `sign(double x, double y)` Return the value of a double with the sign of another double.
    `static int` | `sign(int n)` Return sign of an integer.
    `static double` | `sinh(double x)` Compute hyperbolic sine of a double.
    `static double` | `tanh(double x)` Return the hyperbolic tangent of a double.
    `static double` | `trunc(double x)` Return the integer portion of a double as a double.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### EPSILON_SMALL

          public static final double EPSILON_SMALL

      The smallest relative spacing for doubles.

    - #### EPSILON_LARGE

          public static final double EPSILON_LARGE

      The largest relative spacing for doubles.

  - ### Constructor Detail

    - #### ArithUtils

          protected ArithUtils()

  - ### Method Detail

    - #### acosh

          public static double acosh(double x)

      Return the inverse (arc) hyperbolic cosine of a double.
      Parameters:
        `x` - Double whose inverse hyperbolic cosine is desired.
      Returns:
        The inverse hyperbolic cosine of x.

        If x is NaN or less than one, the result is NaN.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### areEqual

          public static boolean areEqual(double a,
                         double b)

      Check if two doubles are equal to machine precision.
      Parameters:
        `a` - First double.
        `b` - Second double.
      Returns:
        True if a and b are equal to machine precision.

    - #### areEqual

          public static boolean areEqual(double a,
                         double b,
                         double tolerance)

      Check if two doubles are equal to specified tolerance.
      Parameters:
        `a` - First double.
        `b` - Second double.
        `tolerance` - Tolerance.
      Returns:
        True if a and b are equal to specified tolerance.

    - #### asinh

          public static double asinh(double x)

      Return the inverse (arc) hyperbolic sine of a double.
      Parameters:
        `x` - The value whose inverse hyperbolic sine is desired.
      Returns:
        The inverse hyperbolic sine of x.

        If x is NaN, the result is NaN.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### atanh

          public static double atanh(double x)

      Returns the inverse (arc) hyperbolic tangent of a double.
      Parameters:
        `x` - The value whose inverse hyperbolic tangent is desired.
      Returns:
        The arc hyperbolic tangent of x.

        If x is NaN or |x|>1, the result is NaN.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### binomial

          public static double binomial(double n,
                        long k)

      Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k".

      The binomial coefficient is defined as `(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )`.

      - k<0`: `0`.`
      - k==0`: `1`.`
      - k==1`: `n`.`
      - else: `(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )`.
      Returns:
        The binomial coefficient.

    - #### binomial

          public static double binomial(long n,
                        long k)

      Efficiently returns the binomial coefficient, often also referred to as "n over k" or "n choose k".

      The binomial coefficient is defined as

      - k<0`: `0`.`
      - k==0 || k==n`: `1`.`
      - k==1 || k==n-1`: `n`.`
      - else: `(n * n-1 * ... * n-k+1 ) / ( 1 * 2 * ... * k )`.
      Returns:
        The binomial coefficient.

    - #### cosh

          public static double cosh(double x)

      Return the hyperbolic cosine of a double.
      Parameters:
        `x` - The value whose hyperbolic cosine is desired.
      Returns:
        The hyperbolic cosine of x.

        If x is NaN, the result is NaN.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### cot

          public static double cot(double x)

      Return the contangent of a double.
      Parameters:
        `x` - The number whose cotangent is desired.
      Returns:
        The cotangent.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### expm1

          public static double expm1(double x)

      Get exp( x ) - 1.
      Parameters:
        `x` - The number for which to find exp( x ) - 1.
      Returns:
        exp( x ) - 1.

        Example: expm1( 9.995003330835334E-4 ) is 0.001 .

        Implements a method suggested by William Kahan.

    - #### fuzzyCompare

          public static int fuzzyCompare(double a,
                         double b,
                         double tolerance)

      Perform fuzzy comparison of two doubles with specified tolerance.
      Parameters:
        `a` - First double.
        `b` - Second double.
        `tolerance` - Tolerance value.
      Returns:
        1 if a > b. 0 if a ~= b. -1 if a < b.

        This is an implementation of an algorithm suggested by Donald E. Knuth in Section 4.2.2 of Seminumerical Algorithms (3rd edition).

    - #### hypot

          public static double hypot(double a,
                     double b)

      Safely calculate hypotenuse value.
      Parameters:
        `a` - One leg of triangle.
        `b` - Second leg of triangle.
      Returns:
        Hypotenuse value.

        The hypotenuse value is given mathematically as the sqrt( a^2 + b^2 ). The method implemented here reduces the chances of cancellation and roundoff error. If the |a| > |b|, we compute the hypotenuse as:

        hypotenuse = |a| * sqrt( 1 + (b/a) * (b/a) )

        Otherwise b != 0 compute the hypotenuse as:

        hypotenuse = |b| * sqrt( 1 + (a/b) * (a/b) )

        If b is zero, the hypotenuse is zero.

    - #### isNegativeZero

          public static boolean isNegativeZero(double x)

      Check if number is negative zero.
      Parameters:
        `x` - The number to check.
      Returns:
        true if x is negative zero, false otherwise.

    - #### log2

          public static double log2(double x)

      Get log base 2 of a double.
      Parameters:
        `x` - The number whose log base 2 value is desired.
      Returns:
        The log base 2 of x. If x is <= 0, 0 is returned.

        Example: log2( 32 ) is 5.0D .

    - #### log10

          public static double log10(double x)

      Get log base 10 of a double.
      Parameters:
        `x` - The number whose log base 10 value is desired.
      Returns:
        The log base 10 of x. If x is <= 0, 0 is returned.

        Example: log10( 100.0D ) is 2.0D .

    - #### log1p

          public static double log1p(double x)

      Get log of a double + 1.
      Parameters:
        `x` - The number for which we want log( x + 1 ).
      Returns:
        The log of ( x + 1 ).

        Example: log1p( 0.001D ) is 9.995003330835334E-4

        Implements a method suggested by William Kahan.

    - #### logSumLogs

          public static double logSumLogs(double logX,
                          double logY)

      Get the log( exp( logX ) + exp( logY ) ).
      Parameters:
        `logX` - Log( x )
        `logY` - Log( y )
      Returns:
        log( x + y ) .

    - #### logDiffLogs

          public static double logDiffLogs(double logX,
                           double logY)

      Get the log( exp( logX ) - exp( logY ) ).
      Parameters:
        `logX` - Log( x )
        `logY` - Log( y )
      Returns:
        log( x - y ) .

    - #### round

          public static double round(double x,
                     int n)

      Round double to specified number of decimal places.
      Parameters:
        `x` - The double to round.
        `n` - The number of decimal places to round to.
      Returns:
        x rounded to n decimal places.

    - #### safeLog

          public static double safeLog(double x)

      Return natural log of a double.
      Parameters:
        `x` - The number whose natural log is desired.
      Returns:
        The natural log of x. If x is zero, returns 0.

    - #### sign

          public static int sign(int n)

      Return sign of an integer.
      Parameters:
        `n` - Number whose sign is desired.
      Returns:
        -1 if n < 0, 0 if n isn 0, 1 if n > 0.

    - #### sign

          public static int sign(double d)

      Return sign of a double.
      Parameters:
        `d` - double whose sign is desired.
      Returns:
        -1 if d < 0, 0 if d is 0, 1 if d > 0.

    - #### sign

          public static double sign(double x,
                    double y)

      Return the value of a double with the sign of another double.
      Parameters:
        `x` - First double.
        `y` - Second double.
      Returns:
        x with the sign of y.

    - #### sinh

          public static double sinh(double x)

      Compute hyperbolic sine of a double.
      Parameters:
        `x` - The number whose hyperbolic sine is desired.
      Returns:
        The hyperbolic sine of x.

        This method is a modified version of the one in the Visual Numerics Sfun class.

    - #### trunc

          public static double trunc(double x)

      Return the integer portion of a double as a double.
      Parameters:
        `x` - The double whose integer portion is to be found.
      Returns:
        The integer portion of x.

        Example: trunc( 30.12345D ) is 30.0D .

    - #### tanh

          public static double tanh(double x)

      Return the hyperbolic tangent of a double.
      Parameters:
        `x` - The value whose hyperbolic tangent is desired.
      Returns:
        The hyperbolic tangent of x.

        This method is a modified version of the one in the Visual Numerics Sfun class.