com.softnetConsult.utils.math
Class MathTools

java.lang.Object
  com.softnetConsult.utils.math.MathTools

public final class MathTools
extends java.lang.Object

This class is a collection of static mathematical utility methods and functions.

This product includes software developed by the SoftNet-Consult Java Utility Library project and its contributors.
(http://java-tools.sourceforge.net)
Copyright (c) 2007-2008 SoftNet-Consult.
Copyright (c) 2007-2008 G. Paperin.
All rights reserved.

File: MathTools.java
Library API version: "2.02"
Java compliance version: "1.5"

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following terms and conditions are met:

1. Redistributions of source code must retain the above acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above acknowledgement of the SoftNet-Consult Java Utility Library project, the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software or any derived software must display the following acknowledgement:
This product includes software developed by the SoftNet-Consult Java Utility Library project and its contributors.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version:

"2.02"

Author:

Greg Paperin (http://www.paperin.org)

Field Summary

private static int[]	factorialsInt Lookup tables of factorials that can be represented as an int.
private static long[]	factorialsLong Lookup tables of factorials that can be represented as a long.
private static double[]	gammaCoefficients Used for fast calculation of the gamma function.
private static double	ln2Pi Constant used for the canculation of the natural logarithm of the gamma function.
private static int[]	pow10 Powers of 10 as integers for fast fetching.
private static long[]	pow10L Powers of 10 as longs for fast fetchng.
private static double	sqrt2Pi Constant used for the calculation of the gamma function.

Constructor Summary

private

MathTools() Prevents instances of this class from being created as this class contains only static utility methods.

Method Summary

static <TX extends java.lang.Number,TY extends java.lang.Number> int	compare(TX x, TY y) Compares the specified parameters.
static double	factorial(double x) Computes an approximation to the factorial of a specified number using the fact that x! = gamma(x + 1).
static int	factorial(int x) Computes the factorial of a specified number.
static long	factorial(long x) Computes the factorial of a specified number.
static double	gamma(double x) Computes an approximation to the gamma function.
static double	lnFactorial(double x) Computes an approximation to the natural logarithm of the factorial of a specified number.
static double	lnGamma(double x) Computes an approximation to the natiral logarithm of the gamma function.
static double	log(double base, double x) Returns the logarithm of the specified value to the specified base.
static double	poisson(double lambda, int k) Probability mass function of the Poisson distribution.
static int	pow10(int exp) Raises 10 to a positive integer power.
static long	pow10L(int exp) Raises 10 to a positive integer power.
static double	round(double val, int pow10) Rounds the specified number to the nearest specified power of 10.
static float	round(float val, int pow10) Rounds the specified number to the nearest specified power of 10.
static int	round(int val, int pow10) Rounds the specified integer to the nearest specified power of 10. For example: round(12345, 0) = 12345 round(12345, 1) = 12340 round(12345, 2) = 12300 round(12345, 3) = 12000 round(12345, 4) = 10000 round(12345, 5) = 0 round(54321, 5) = 100000
static long	round(long val, int pow10) Rounds the specified long integer to the nearest specified power of 10. For example: round(12345, 0) = 12345 round(12345, 1) = 12340 round(12345, 2) = 12300 round(12345, 3) = 12000 round(12345, 4) = 10000 round(12345, 5) = 0 round(54321, 5) = 100000
static double	transToUnitInterval(double value, double valueRangeMin, double valueRangeMax) Linearly transforms the specified value value from the specified value range interval [valueRangeMin, valueRangeMax] into the unit interval [0, 1].

Methods inherited from class java.lang.Object

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

Field Detail

pow10

private static final int[] pow10

Powers of 10 as integers for fast fetching.

pow10L

private static final long[] pow10L

Powers of 10 as longs for fast fetchng.

factorialsInt

private static final int[] factorialsInt

Lookup tables of factorials that can be represented as an int.

factorialsLong

private static final long[] factorialsLong

Lookup tables of factorials that can be represented as a long.

gammaCoefficients

private static final double[] gammaCoefficients

Used for fast calculation of the gamma function.

sqrt2Pi

private static final double sqrt2Pi

Constant used for the calculation of the gamma function.

ln2Pi

private static final double ln2Pi

Constant used for the canculation of the natural logarithm of the gamma function.

Constructor Detail

MathTools

private MathTools()

Prevents instances of this class from being created as this class contains only static utility methods.

Method Detail

gamma

public static double gamma(double x)

Computes an approximation to the gamma function. In most cases, this approximation is correct for at least 15 significant digits.

Parameters:

x - The real parameter to the gamma function.

Returns:

The approximate value of the gamma function at x.

lnGamma

public static double lnGamma(double x)

Computes an approximation to the natiral logarithm of the gamma function. In most cases, this approximation is correct for at least 8 significant digits. This approximation is designed for positive arguments only; the return value for other agruments is unspecified and is most likely to be Double.NaN.

Parameters:

x - A positive real number.

Returns:

The approximate value of ln(gamma(x)).

factorial

public static int factorial(int x)

Computes the factorial of a specified number.

Parameters:

x - A number between 0 and 12 inclusive (the factorial of larger numbers cannot be represented as int).

Returns:

x!.

factorial

public static long factorial(long x)

Computes the factorial of a specified number.

Parameters:

x - A number between 0 and 20 inclusive (the factorial of larger numbers cannot be represented as long).

Returns:

x!.

factorial

public static double factorial(double x)

Computes an approximation to the factorial of a specified number using the fact that x! = gamma(x + 1).

Parameters:

x - A number.

Returns:

x! calculated as MathTools.gamma(x + 1.0).

See Also:

gamma(double)

lnFactorial

public static double lnFactorial(double x)

Computes an approximation to the natural logarithm of the factorial of a specified number. For values larger than 1.0 this method uses a direct approximation to the natural logarithm of the gamma function (i.e. ln(x!) = MathTools.lnGamma(x + 1.0)); for 1.0 and smaller values this method explicitly computes the factorial using MathTools.factorial(x) and then takes the natural logarithm using java.lang.Math.log().

Parameters:

x - A number larger than -1.

Returns:

THe approximate value of ln(x!).

See Also:

lnGamma(double), factorial(double)

poisson

public static double poisson(double lambda,
                             int k)

Probability mass function of the Poisson distribution.

Parameters:

lambda - LAMBDA-Poisson parameter.

k - K-Poisson parameter.

Returns:

Approximate value of the probability mass function of the Poisson distribution at given parameters.

transToUnitInterval

public static double transToUnitInterval(double value,
                                         double valueRangeMin,
                                         double valueRangeMax)

Linearly transforms the specified value value from the specified value range interval [valueRangeMin, valueRangeMax] into the unit interval [0, 1].

Parameters:

value - The value to transform.

valueRangeMin - Inclusive minimum of the value's original range.

valueRangeMax - Inclusive maximum of the value's original range.

Returns:

Image of the linear transform of the specified value into the unit inerval.

log

public static double log(double base,
                         double x)

Returns the logarithm of the specified value to the specified base.

Parameters:

base - The base for the logarithm.

x - The value to take the logarithm of.

Returns:

The logarithm of x to base base.

compare

public static <TX extends java.lang.Number,TY extends java.lang.Number> int compare(TX x,
                                                                                    TY y)

Compares the specified parameters. Returns a value smaller than 0 if the first parameter is smaller than the second; returns a value larger than 0 if the second parameter is smaller than the first; returns 0 if the parameters represent an equal value.
This method attempts to use the objects' own compareTo methods if both parameters are of same type and if that type is a standard Java type that inherits directly from Number and implements Comparable. If this fails, then the values returned by doubleValue() method are compared.

Type Parameters:

TX - A Number type.

TY - A Number type.

Parameters:

x - A number

y - A number.

Returns:

A value smaller than 0 if the first parameter is smaller than the second, a value larger than 0 if the second parameter is smaller than the first, 0 if the parameters represent an equal value.

pow10

public static int pow10(int exp)

Raises 10 to a positive integer power.

Parameters:

exp - Power to which to raise 10.

Returns:

If exp is negative - 0, otherwise 10^exp.

Throws:

java.lang.IllegalArgumentException - If exp > 9 as the result would be too large to be represented in a Java int.

pow10L

public static long pow10L(int exp)

Raises 10 to a positive integer power.

Parameters:

exp - Power to which to raise 10.

Returns:

If exp is negative - 0, otherwise 10^exp.

Throws:

java.lang.IllegalArgumentException - If exp > 18 as the result would be too large to be represented in a Java long.

round

public static int round(int val,
                        int pow10)

Rounds the specified integer to the nearest specified power of 10.
For example:
round(12345, 0) = 12345
round(12345, 1) = 12340
round(12345, 2) = 12300
round(12345, 3) = 12000
round(12345, 4) = 10000
round(12345, 5) = 0
round(54321, 5) = 100000

Parameters:

val - A number.

pow10 - The power of 10 to which to round, only non-negative positive values are permitted.

Returns:

The closest integer to val that is a multiple of 10^pow10. Midway rounding is towards the even number.

round

public static long round(long val,
                         int pow10)

Rounds the specified long integer to the nearest specified power of 10.
For example:
round(12345, 0) = 12345
round(12345, 1) = 12340
round(12345, 2) = 12300
round(12345, 3) = 12000
round(12345, 4) = 10000
round(12345, 5) = 0
round(54321, 5) = 100000

Parameters:

val - A number.

pow10 - The power of 10 to which to round, only non-negative positive values are permitted.

Returns:

The closest long integer to val that is a multiple of 10^pow10. Midway rounding is towards the even number.

round

public static double round(double val,
                           int pow10)

Rounds the specified number to the nearest specified power of 10. For example:
round(12345.12345, 0) = 12345.0
round(12345.12345, 1) = 12340.0
round(12345.12345, 2) = 12300.0
round(12345.12345, 3) = 12000.0
round(12345.12345, 4) = 10000.0
round(12345.12345, 5) = 0.0
round(54321.0, 5) = 100000.0
round(12345.12345, -1) = 12345.1
round(12345.12345, -2) = 12345.12
round(12345.12345, -3) = 12345.123
round(12345.12345, -4) = 12345.1234
round(12345.12345, -5) = 12345.12345
round(12345.12345, -6) = 12345.12345

Parameters:

val - A number.

pow10 - The power of 10 to which to round.

Returns:

The closest number to val that is a multiple of 10^pow10. Midway rounding is towards the even number.

round

public static float round(float val,
                          int pow10)

Rounds the specified number to the nearest specified power of 10. For example:
round(12345.12345, 0) = 12345.0
round(12345.12345, 1) = 12340.0
round(12345.12345, 2) = 12300.0
round(12345.12345, 3) = 12000.0
round(12345.12345, 4) = 10000.0
round(12345.12345, 5) = 0.0
round(54321.0, 5) = 100000.0
round(12345.12345, -1) = 12345.1
round(12345.12345, -2) = 12345.12
round(12345.12345, -3) = 12345.123
round(12345.12345, -4) = 12345.1234
round(12345.12345, -5) = 12345.12345
round(12345.12345, -6) = 12345.12345

Parameters:

val - A number.

pow10 - The power of 10 to which to round.

Returns:

The closest number to val that is a multiple of 10^pow10. Midway rounding is towards the even number.