MathUtil (Cognitive Foundry)

java.lang.Object
- gov.sandia.cognition.math.MathUtil

@CodeReview(reviewer="Kevin R. Dixon",
            date="2008-02-26",
            changesNeeded=false,
            comments={"Minor changes, log2 uses callback to main log() method.","Otherwise, looks fine."})
public class MathUtil
extends java.lang.Object

The MathUtil class implements mathematical utility functions.

Since:: 2.0
Author:: Justin Basilico, Kevin Dixon, Zachary Benz

Constructor Summary

Constructors
Constructor and Description

MathUtil()

Constructors
Constructor and Description
`MathUtil()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static int`	`binomialCoefficient(int N, int k)` Returns the binomial coefficient for "N choose k".
`static int`	`checkedAdd(int a, int b)` Safely checks for underflow/overflow before adding two integers.
`static int`	`checkedMultiply(int a, int b)` Safely checks for overflow before multiplying two integers.
`static double`	`expMinus1Plus(double x)` Computes exp(x - 1).
`protected static double`	`incompleteBetaContinuedFraction(double a, double b, double x)` Evaluates the continued fraction of the incomplete beta function.
`static double`	`incompleteGammaContinuedFraction(double a, double x)` Returns the incomplete Gamma function using the continued fraction expansion evaluation using Lentz's method
`protected static double`	`incompleteGammaSeriesExpansion(double a, double x)` Computes the series expansion approximation to the incomplete gamma function.
`static double`	`log(double x, double base)` Returns the log of the given base of the given value, y=log_b(x) such that x=b^y
`static double`	`log1MinusExp(double x)` Computes log(1 - exp(x)).
`static double`	`log1Plus(double x)` Computes log(1 + x).
`static double`	`log1PlusExp(double x)` Computes log(1 + exp(x)).
`static double`	`log2(double x)` Returns the base-2 logarithm of the given value.
`static double`	`logBetaFunction(double a, double b)` Compute the natural logarithm of the Beta Function.
`static double`	`logBinomialCoefficient(int N, int k)` Computes the natural logarithm of the binomial coefficient.
`static double`	`logFactorial(int n)` Returns the natural logarithm of n factorial log(n!) = log(n(n-1)...32*1)
`static double`	`logGammaFunction(double input)` Computes the logarithm of the Gamma function.
`static double`	`logMultinomialBetaFunction(Vector input)` Evaluates the natural logarithm of the multinomial beta function for the given input vector.
`static double`	`lowerIncompleteGammaFunction(double a, double x)` Computes the Lower incomplete gamma function.
`static double`	`regularizedIncompleteBetaFunction(double a, double b, double x)` Computes the regularized incomplete Beta function.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- MathUtil
```
public MathUtil()
```

Method Detail

log
```
public static double log(double x,
                         double base)
```
Returns the log of the given base of the given value, y=log_b(x) such that x=b^y

Parameters:

x - The value.

base - The base for the logarithm

Returns:

The log of x using the given base.

log2
```
public static double log2(double x)
```
Returns the base-2 logarithm of the given value. It is computed as log(x) / log(2).

Parameters:

x - The value.

Returns:

The base-2 logarithm.

logGammaFunction

@PublicationReference(author="Wikipedia",title="Gamma Function",type=WebPage,year=2010,url="http://en.wikipedia.org/wiki/Gamma_function") @PublicationReference(author="jdhedden",title="Bug in 2nd edition version of gammln()",type=WebPage,year=2005,url="http://www.numerical-recipes.com/forum/showthread.php?t=606")
public static double logGammaFunction(double input)

Computes the logarithm of the Gamma function.

Parameters:: input - Input to evaluate the Natural Logarithm of the Gamma Function
Returns:: Natural Logarithm of the Gamma Function about the input

lowerIncompleteGammaFunction

@PublicationReference(author="Wikipedia",title="Incomplete gamma function",type=WebPage,year=2010,url="http://en.wikipedia.org/wiki/Incomplete_gamma_function") @PublicationReference(author={"William H. Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},title="Numerical Recipes in C, Second Edition",type=Book,year=1992,pages=218,notes="Function gammap",url="http://www.nrbook.com/a/bookcpdf.php")
public static double lowerIncompleteGammaFunction(double a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     double x)

Computes the Lower incomplete gamma function. Note that this has the reverse parameters order from octave.

Parameters:: a - Degrees of Freedom; x - Input value
Returns:: Value of the IncompleteGammaFunction(a,x)

incompleteGammaSeriesExpansion

@PublicationReference(author={"William H. Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},
                      title="Numerical Recipes in C, Second Edition",
                      type=Book,
                      year=1992,
                      pages={218,219},
                      url="http://www.nrbook.com/a/bookcpdf.php",
                      notes="Function gser()")
protected static double incompleteGammaSeriesExpansion(double a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                          double x)

Computes the series expansion approximation to the incomplete gamma function. Note that this has the reverse parameters order from octave.

Parameters:: a - Degrees of Freedom; x - Input value
Returns:: Value of the IncompleteGammaFunction(a,x)

incompleteGammaContinuedFraction

@PublicationReference(author={"William H. Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},
                      title="Numerical Recipes in C, Second Edition",
                      type=Book,
                      year=1992,
                      pages={216,219},
                      url="http://www.nrbook.com/a/bookcpdf.php")
public static double incompleteGammaContinuedFraction(double a,
                                                                                                                                                                                                                                                                                                                                                                                                                          double x)

Returns the incomplete Gamma function using the continued fraction expansion evaluation using Lentz's method

Parameters:: a - Degrees of Freedom; x - Input value
Returns:: Value of the IncompleteGammaFunction(a,x)

binomialCoefficient

@PublicationReference(author="Wikipedia",
                      title="Binomial coefficient",
                      type=WebPage,
                      year=2010,
                      url="http://en.wikipedia.org/wiki/Binomial_coefficient")
public static int binomialCoefficient(int N,
                                                                                                                                                                                                                                                                                        int k)

Returns the binomial coefficient for "N choose k". In other words, this is the number of different ways of choosing k objects from a total of N different ones, where order doesn't matter and without replacement.

Parameters:: N - Total number of objects in the bag; k - Total number of objects to choose, must be less than or equal to N
Returns:: Binomial coefficient for N choose k

logBinomialCoefficient
```
public static double logBinomialCoefficient(int N,
                                            int k)
```
Computes the natural logarithm of the binomial coefficient.

Parameters:

N - Total number of objects in the bag

k - Total number of objects to choose, must be less than or equal to N

Returns:

Natural logarithm of the binomial coefficient for N choose k

logFactorial
```
public static double logFactorial(int n)
```
Returns the natural logarithm of n factorial log(n!) = log(n*(n-1)*...*3*2*1)

Parameters:

n - Parameter for choose for n factorial

Returns:

n factorial

logBetaFunction

@PublicationReference(author="Wikipedia",
                      title="Beta function",
                      type=WebPage,
                      year=2010,
                      url="http://en.wikipedia.org/wiki/Beta_function")
public static double logBetaFunction(double a,
                                                                                                                                                                                                                                                                         double b)

Compute the natural logarithm of the Beta Function.

Parameters:: a - First parameter to the Beta function; b - Second parameter to the Beta function
Returns:: Natural logarithm of the Beta Function.

regularizedIncompleteBetaFunction

@PublicationReference(author="Wikipedia",title="Beta function, Incomplete Beta function",type=WebPage,year=2010,url="http://en.wikipedia.org/wiki/Beta_function#Incomplete_beta_function") @PublicationReference(author={"William H. Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},title="Numerical Recipes in C, Second Edition",type=Book,year=1992,pages=227,notes="Function betai",url="http://www.nrbook.com/a/bookcpdf.php")
public static double regularizedIncompleteBetaFunction(double a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    double b,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    double x)

Computes the regularized incomplete Beta function.

Parameters:: a - Parameter a to the Beta function; b - Parameter b to the Beta function; x - Parameter x to for the integral from 0 to x
Returns:: Incomplete beta function for I_x(a,b)

incompleteBetaContinuedFraction

@PublicationReference(author={"William H. Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},
                      title="Numerical Recipes in C, Second Edition",
                      type=Book,
                      year=1992,
                      pages=227,
                      notes="Incomplete Beta Function continued fraction terms for Lentz\'s method",
                      url="http://www.nrbook.com/a/bookcpdf.php")
protected static double incompleteBetaContinuedFraction(double a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           double b,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           double x)

Evaluates the continued fraction of the incomplete beta function. Based on the math from NRC's 6.4 "Incomplete Beta Function"

Parameters:: a - Parameter a to the beta continued fraction; b - Parameter b to the beta continued fraction; x - Parameter x to the beta continued fraction
Returns:: Incomplete beta function continued fraction

logMultinomialBetaFunction

@PublicationReference(author="Wikipedia",
                      title="Dirichlet distribution",
                      type=WebPage,
                      year=2009,
                      url="http://en.wikipedia.org/wiki/Dirichlet_distribution",
                      notes="Multinomial Beta Function found in the \"Probability density function\" section.")
public static double logMultinomialBetaFunction(Vector input)

Evaluates the natural logarithm of the multinomial beta function for the given input vector.

Parameters:: input - Input vector to consider.
Returns:: Natural logarithm of the Multinomial beta function evaluated at the given input.

checkedAdd

@PublicationReference(author={"Tov Are","Paul van Keep","Mike Cowlishaw","Pierre Baillargeon","Bill Wilkinson","Patricia Shanahan","Joseph Bowbeer","Charles Thomas","Joel Crisp","Eric Nagler","Daniel Leuck","William Brogden","Yves Bossu","Chad Loder"},
                      title="Java Gotchas",
                      type=WebPage,
                      year=2011,
                      url="http://202.38.93.17/bookcd/285/1.iso/faq/gloss/gotchas.html#OVERFLOW",
                      notes="")
public static int checkedAdd(int a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             int b)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      throws java.lang.ArithmeticException

Safely checks for underflow/overflow before adding two integers. If an underflow or overflow would occur as a result of the addition, an ArithmeticException is thrown.

Parameters:: a - The first integer to add; b - The second integer to add
Returns:: The sum of integers a and b
Throws:: java.lang.ArithmeticException - If an underflow or overflow will occur upon adding a and b

checkedMultiply

@PublicationReference(author={"Tov Are","Paul van Keep","Mike Cowlishaw","Pierre Baillargeon","Bill Wilkinson","Patricia Shanahan","Joseph Bowbeer","Charles Thomas","Joel Crisp","Eric Nagler","Daniel Leuck","William Brogden","Yves Bossu","Chad Loder"},
                      title="Java Gotchas",
                      type=WebPage,
                      year=2011,
                      url="http://202.38.93.17/bookcd/285/1.iso/faq/gloss/gotchas.html#OVERFLOW",
                      notes="")
public static int checkedMultiply(int a,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  int b)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           throws java.lang.ArithmeticException

Safely checks for overflow before multiplying two integers. If an overflow would occur as a result of the multiplication, an ArithmeticException is thrown.

Parameters:: a - The first integer to multiply; b - The second integer to multiply
Returns:: The result of multiplying the integers a and b
Throws:: java.lang.ArithmeticException - If an overflow will occur upon multiplying a and b

log1Plus
```
public static double log1Plus(double x)
```
Computes log(1 + x). For small values, this is closer to the actual value than actually calling log(1 + x). This is an alias for Math.log1p(x).

Parameters:

x - The value.

Returns:

The result of log(1 + x).

expMinus1Plus
```
public static double expMinus1Plus(double x)
```
Computes exp(x - 1). For small values, this is closer to the actual value than actually calling exp(x - 1). This is an alias for Math.expm1(x).

Parameters:

x - The value.

Returns:

The result of exp(x - 1).

log1MinusExp

@PublicationReference(title="Accurately Computing log(1 \u2212 exp(\u2212|a|)): Assessed by the Rmpfr package",
                      author="Martin Machler",
                      year=2012,
                      type=WebPage,
                      url="http://cran.r-project.org/web/packages/Rmpfr/vignettes/log1mexp-note.pdf")
public static double log1MinusExp(double x)

Computes log(1 - exp(x)). For small values, this is closer to the actual value than actually calling log(1 - exp(x)).

Parameters:: x - The value.
Returns:: The result of log(1 - exp(x)).

log1PlusExp

@PublicationReference(title="Accurately Computing log(1 \u2212 exp(\u2212|a|)): Assessed by the Rmpfr package",
                      author="Martin Machler",
                      year=2012,
                      type=WebPage,
                      url="http://cran.r-project.org/web/packages/Rmpfr/vignettes/log1mexp-note.pdf")
public static double log1PlusExp(double x)

Computes log(1 + exp(x)). For small values, this is closer to the actual value than actually calling log(1 + exp(x)).

Parameters:: x - The value.
Returns:: The result of log(1 + exp(x)).

Class MathUtil

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MathUtil