gov.sandia.cognition.math

Class LogMath

java.lang.Object

gov.sandia.cognition.math.LogMath

public class LogMath
extends java.lang.Object

A utility class for doing math with numbers represented as logarithms. Thus, the number x is instead represented as log(x). This can be useful when doing computation involving many products, such as with probabilities.

Since:

3.3.0

Author:

Justin Basilico

Field Summary

Fields

Modifier and Type	Field and Description
static double	LOG_0 The natural logarithm of 0 (log(0)), which is negative infinity.
static double	LOG_1 The natural logarithm of 1 (log(1)), which is 0.
static double	LOG_10 The natural logarithm of 10 (log(10)).
static double	LOG_2 The natural logarithm of 2 (log(2)).
static double	LOG_E The natural logarithm of e (log(e)), which is 1.

Constructor Summary

Constructors

Constructor and Description
LogMath()

Method Summary

Modifier and Type	Method and Description
static double	add(double logX, double logY) Adds two log-domain values.
static double	divide(double logX, double logY) Divides two log-domain values.
static double	fromLog(double logX) Converts a number from log-domain representation (x = exp(logX)).
static double	inverse(double logX) Takes the inverse of a log-domain value.
static double	multiply(double logX, double logY) Multiplies two log-domain values.
static double	subtract(double logX, double logY) Subtracts two log-domain values.
static double	toLog(double x) Converts a number to its log-domain representation (log(x)).

Methods inherited from class java.lang.Object

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

Field Detail

LOG_0

public static final double LOG_0

The natural logarithm of 0 (log(0)), which is negative infinity.

See Also:

Constant Field Values

LOG_1

public static final double LOG_1

The natural logarithm of 1 (log(1)), which is 0.

See Also:

Constant Field Values

LOG_2

public static final double LOG_2

The natural logarithm of 2 (log(2)).

LOG_E

public static final double LOG_E

The natural logarithm of e (log(e)), which is 1.

See Also:

Constant Field Values

LOG_10

public static final double LOG_10

The natural logarithm of 10 (log(10)).

Constructor Detail

LogMath

public LogMath()

Method Detail

toLog

public static double toLog(double x)

Converts a number to its log-domain representation (log(x)). Negative values will result in NaN.

Parameters:

x - The number. Should not be negative.

Returns:

The logarithm of x (log(x)).

fromLog

public static double fromLog(double logX)

Converts a number from log-domain representation (x = exp(logX)).

Parameters:

logX - The log-domain representation of the number x (log(x)).

Returns:

The value of x, which is exp(logX) = exp(log(x)).

add

public static double add(double logX,
                         double logY)

Adds two log-domain values. It uses a trick to prevent numerical overflow and underflow.

Parameters:

logX - The first log-domain value (log(x)). Must be the same basis as logY.

logY - The second log-domain value (log(y)). Must be the same basis as logX.

Returns:

The log of x plus y (log(x + y)).

subtract

public static double subtract(double logX,
                              double logY)

Subtracts two log-domain values. It uses a trick to prevent numerical overflow and underflow.

Parameters:

logX - The first log-domain value (log(x)). Must be the same basis as logY.

logY - The second log-domain value (log(y)). Must be the same basis as logX.

Returns:

The log of x minus y (log(x - y)).

multiply

public static double multiply(double logX,
                              double logY)

Multiplies two log-domain values. It uses the identity: log(x * y) = log(x) + log(y)

Parameters:

logX - The first log-domain value (log(x)). Must be the same basis as logY.

logY - The second log-domain value (log(y)). Must be the same basis as logX.

Returns:

The log of x divided by y (log(x * y)).

divide

public static double divide(double logX,
                            double logY)

Divides two log-domain values. It uses the identity: log(x / y) = log(x) - log(y)

Parameters:

logX - The first log-domain value (log(x)) used in the numerator. Must be the same basis as logY.

logY - The second log-domain value (log(y)) used in the denominator. Must be the same basis as logX.

Returns:

The log of x times y (log(x / y)).

inverse

public static double inverse(double logX)

Takes the inverse of a log-domain value. Using the same identity as the division one and that log(1) = 0 to be: log(x^-1) = log(1 / x) = log(1) - log(x) = -log(x)

Parameters:

logX - The log-domain value (log(x)) to invert.

Returns:

The log of x^-1 = 1 / x (log(1/x)).