com.aliasi.util
Class Math

java.lang.Object
  extended by com.aliasi.util.Math

public class Math
extends Object

A math utility class with static methods.

Since:
LingPipe1.0
Version:
3.9.1
Author:
Bob Carpenter

Field Summary
static long[] FIBONACCI_SEQUENCE
          An array of the Fibonacci sequence up the maximum value representable as a long integer.
static double GOLDEN_RATIO
          The value of the golden ratio.
static double LN_2
          The natural logarithm of 2.
static double LOG2_E
          The log base 2 of the constant e, which is the base of the natural logarithm.
 
Method Summary
static void assertFiniteNonNegative(String label, double x)
          Deprecated. Use Exceptions.finiteNonNegative(String,double) instead.
static int byteAsUnsigned(byte b)
          Returns the integer value of reading the specified byte as an unsigned value.
static double digamma(double x)
          Returns the value of the digamma function for the specified value.
static boolean isPrime(int num)
          Returns true if the specified number is prime.
static double log2(double x)
          Returns the log base 2 of the specivied value.
static double log2BinomialCoefficient(long n, long m)
          Returns the log (base 2) of the binomial coefficient of the specified arguments.
static double log2Factorial(long n)
          Returns the log (base 2) of the factorial of the specified long integer.
static double log2Gamma(double z)
          Returns the log (base 2) of the Γ function.
static double logBase2ToNaturalLog(double x)
          Converts a log base 2 logarithm to a natural logarithm.
static double logSumOfExponentials(double[] xs)
          This method returns the log of the sum of the natural exponentiated values in the specified array.
static double max(double... xs)
          Returns the maximum value of an element in xs.
static int max(int... xs)
          Returns the maximum value of an element in the specified array.
static double maximum(double... xs)
          Returns the maximum of the specified array of double values.
static double minimum(double... xs)
          Returns the minimum of the specified array of double values.
static double naturalLogToBase2Log(double x)
          Converts a natural logarithm to a base 2 logarithm.
static int nextPrime(int num)
          Returns the smallest prime number that is strictly larger than the specified integer.
static double relativeAbsoluteDifference(double x, double y)
          Returns the relative absolute difference between the specified values, defined to be:
static double sum(double... xs)
          Returns the sum of the specified array of double values.
static int sum(int... xs)
          Returns the sum of the specified integer array.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GOLDEN_RATIO

public static final double GOLDEN_RATIO
The value of the golden ratio. The golden ratio is defined to be the value φ such that:
φ = (φ + 1) / φ
Note that this is a quadratic equation (multiply both sides by φ) with the solution roughly 1.61803399.

See the following for a fascinating tour of the properties of the golden ratio:


LN_2

public static final double LN_2
The natural logarithm of 2.


LOG2_E

public static final double LOG2_E
The log base 2 of the constant e, which is the base of the natural logarithm. The constant e is determined by the java constant Math.E.


FIBONACCI_SEQUENCE

public static final long[] FIBONACCI_SEQUENCE
An array of the Fibonacci sequence up the maximum value representable as a long integer. The array is defined as follows:
 FIBONACCI_SEQUENCE[0] = 1
 FIBONACCI_SEQUENCE[1] = 2
 FIBONACCI_SEQUENCE[n+2] = FIBONACCI_SEQUENCE[n+1] + FIBONACCI_SEQUENCE[n]
 
So FIBONACCI_SEQUENCE[0] represents the second Fibonacci number in the traditional numbering. The inital entries are:
1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, ...
The length of the array is 91, and the largest value is:
FIBONACCI_SEQUENCE[90] = 7540113804746346429

See the following references for more information on the fascinating properties of Fibonacci numbers:

Method Detail

isPrime

public static boolean isPrime(int num)
Returns true if the specified number is prime. A prime is a positive number greater than 1 with no divisors other than 1 and itself, thus {2,3,5,7,11,13,...}.

Parameters:
num - Number to test for primality.
Returns:
true if the specified number is prime.

nextPrime

public static int nextPrime(int num)
Returns the smallest prime number that is strictly larger than the specified integer. See isPrime(int) for the definition of primality.

Parameters:
num - Base from which to look for the next prime.
Returns:
Smallest prime number strictly larget than specified number.

naturalLogToBase2Log

public static double naturalLogToBase2Log(double x)
Converts a natural logarithm to a base 2 logarithm. This inverts the operation of logBase2ToNaturalLog(double).

If the input is x = ln z, then the return value is log2 z. Recall that log2 z = ln z / ln 2.

Parameters:
x - Natural log of value.
Returns:
Log base 2 of value.

logBase2ToNaturalLog

public static double logBase2ToNaturalLog(double x)
Converts a log base 2 logarithm to a natural logarithm. This inverts the operation of naturalLogToBase2Log(double).


log2

public static double log2(double x)
Returns the log base 2 of the specivied value.

Parameters:
x - Value whose log is taken.
Returns:
Log of specified value.

byteAsUnsigned

public static int byteAsUnsigned(byte b)
Returns the integer value of reading the specified byte as an unsigned value. The computation is carried out by subtracting the minimum value, as defined by the constant Byte.MIN_VALUE.

Parameters:
b - Byte to convert.
Returns:
Unsigned value of specified byte.

log2Factorial

public static double log2Factorial(long n)
Returns the log (base 2) of the factorial of the specified long integer. The factorial of n is defined for n > 0 by:
n! = Πi < 0 <= n i
Taking logs of both sides gives:
log2 n! = Σi < 0 <= n log2 i
By convention, 0! is taken to be 1, and hence ln 0! = 0.

Parameters:
n - Specified long integer.
Returns:
Log of factorial of specified integer.
Throws:
IllegalArgumentException - If the argument is negative.

sum

public static double sum(double... xs)
Returns the sum of the specified array of double values.

Parameters:
xs - Variable length list of values, or an array of values.
Returns:
The sum of the values.

minimum

public static double minimum(double... xs)
Returns the minimum of the specified array of double values. If the length of the array is zero, the result is Double.NaN.

Parameters:
xs - Variable length list of values, or an array.
Returns:
Minimum value in array.

maximum

public static double maximum(double... xs)
Returns the maximum of the specified array of double values. If the length of the array is zero, the result is Double.NaN.

Parameters:
xs - Variable length list of values, or an array.
Returns:
Maximum value in array.

log2BinomialCoefficient

public static double log2BinomialCoefficient(long n,
                                             long m)
Returns the log (base 2) of the binomial coefficient of the specified arguments. The binomial coefficient is equal to the number of ways to choose a subset of size m from a set of n objects, which is pronounced "n choose m", and is given by:
choose(n,m) = n! / ( m! * (n-m)!)
log2 choose(n,m) = log2 n - log2 m - log2 (n-m)

Returns:
The log (base 2) of the binomial coefficient of the specified arguments.

assertFiniteNonNegative

@Deprecated
public static void assertFiniteNonNegative(String label,
                                                      double x)
Deprecated. Use Exceptions.finiteNonNegative(String,double) instead.

Throws an illegal argument exception if the specified double value is not a finite non-negative number. The label is included in the generated exception's error message if necessary.

Parameters:
label - Label of variable for exception message.
x - Double value to check.
Throws:
IllegalArgumentException - If the specified double value is infinite, is not a number, or is negative.

log2Gamma

public static double log2Gamma(double z)
Returns the log (base 2) of the Γ function. The Γ function is defined by:
 Γ(z) = 0 tz-1 * e-t dt

The Γ function is the continuous generalization of the factorial function, so that for real numbers z > 0:

Γ(z+1) = z * Γ(z)
In particular, integers n >= 0, we have:
Γ(n+1) = n!

In general, Γ satisfies:

 Γ(z) = π / (sin(π * z) * Γ(1-z))
 

This method uses the Lanczos approximation which is accurate nearly to the full power of double-precision arithmetic. The Lanczos approximation is used for inputs in the range [0.5,1.5], converting numbers less than 0.5 using the above formulas, and reducing arguments greater than 1.5 using the factorial-like expansion above.

For more information on the Γ function and its computation, see:

Parameters:
z - The argument to the gamma function.
Returns:
The value of Γ(z).

digamma

public static double digamma(double x)
Returns the value of the digamma function for the specified value. The returned values are accurate to at least 13 decimal places.

The digamma function is the derivative of the log of the gamma function; see the method documentation for log2Gamma(double) for more information on the gamma function itself.

 Ψ(z)
 = d log Γ(z) / dz
 = Γ'(z) / Γ(z)
 

The numerical approximation is derived from:

Implementation Note: The recursive calls in the C implementation have been transformed into loops and accumulators, and the recursion for values greater than three replaced with a simpler reduction. The number of loops required before the fixed length expansion is approximately integer value of the absolute value of the input. Each loop requires a floating point division, two additions and a local variable assignment. The fixed portion of the algorithm is roughly 30 steps requiring four multiplications, three additions, one static final array lookup, and four assignments per loop iteration.

Parameters:
x - Value at which to evaluate the digamma function.
Returns:
The value of the digamma function at the specified value.

relativeAbsoluteDifference

public static double relativeAbsoluteDifference(double x,
                                                double y)
Returns the relative absolute difference between the specified values, defined to be:
 relAbsDiff(x,y) = abs(x-y) / (abs(x) + abs(y))

Parameters:
x - First value.
y - Second value.
Returns:
The absolute relative difference between the values.

logSumOfExponentials

public static double logSumOfExponentials(double[] xs)
This method returns the log of the sum of the natural exponentiated values in the specified array. Mathematically, the result is
 logSumOfExponentials(xs) = log ( Σi exp(xs[i]) )
But the result is not calculated directly. Instead, the calculation performed is:
 logSumOfExponentials(xs) = max(xs) + log ( Σi exp(xs[i] - max(xs)) )
which produces the same result, but is much more arithmetically stable, because the largest value for which exp() is calculated is 0.0.

Values of Double.NEGATIVE_INFINITY are treated as having exponentials of 0 and logs of negative infinity. That is, they are ignored for the purposes of this computation.

Parameters:
xs - Array of values.
Returns:
The log of the sum of the exponentiated values in the array.

max

public static double max(double... xs)
Returns the maximum value of an element in xs. If any of the values are Double.NaN, or if the input array is empty, the result is Double.NaN.

Parameters:
xs - Array in which to find maximum.
Returns:
Maximum value in array.

max

public static int max(int... xs)
Returns the maximum value of an element in the specified array.

Parameters:
xs - Array in which to find maximum.
Returns:
Maximum value in the array.
Throws:
ArrayIndexOutOfBoundsException - If the specified array does not contai at least one element.

sum

public static int sum(int... xs)
Returns the sum of the specified integer array. Note that there is no check for overflow. If the array is of length 0, the sum is defined to be 0.

Parameters:
xs - Array of integers to sum.
Returns:
Sum of the array.