gov.sandia.cognition.math
Class LogNumber

java.lang.Object
  extended by java.lang.Number
      extended by gov.sandia.cognition.math.LogNumber
All Implemented Interfaces:
EuclideanRing<LogNumber>, Field<LogNumber>, Ring<LogNumber>, CloneableSerializable, Serializable, Cloneable, Comparable<LogNumber>

public class LogNumber
extends Number
implements Field<LogNumber>, Comparable<LogNumber>

Represents a number in log-space, storing the log of the absolute value log(|value|) and the sign of the value sign(value). It is used to operate on a number as if it were not being represented in log space. Thus if you have two log numbers, a and b such that a = log(x) and b = log(y), doing c = a * b will be result in c = log(x * y), not c = log(x) * log(y). This means that when you do a.getValue() you will get x and if you do a.getLogValue() you will get log(x).

This class is useful if you need to do a lot of operations on data with very large or very small exponents to avoid numerical overflow and underflow. This can be useful, for example, for probabilities that involve many products.

All of the logarithms done by the class are done using the natural base (e), which is often denoted as ln(x) instead of log(x).

If you know that all of your numbers are positive, such as if they are all probabilities, then you may want to use an UnsignedLogNumber instead, since it does not have to maintain the sign information, so it will consume less memory and will be faster.

Author:
Justin Basilico
See Also:
UnsignedLogNumber, LogMath, Serialized Form

Field Summary
protected  double logValue
          The log of the absolute value represented by this object, log(|value|).
protected  boolean negative
          The sign of the value, sign(value).
 
Constructor Summary
  LogNumber()
          Creates the LogNumber representing zero.
protected LogNumber(boolean negative, double logValue)
          Creates a new LogNumber from the given value in log-space.
  LogNumber(LogNumber other)
          Copies a given LogNumber.
 
Method Summary
 LogNumber absoluteValue()
          Returns a new LogNumber that represents the absolute value of this LogNumber.
 void absoluteValueEquals()
          Transforms this value to be its absolute value.
 LogNumber clone()
          Returns a smart copy of this, such that changing the values of the return class will not effect this
 int compareTo(LogNumber other)
           
static LogNumber createFromLogValue(boolean negative, double logValue)
          Creates a new LogNumber from the given value that is already in log-space.
static LogNumber createFromLogValue(double logValue)
          Creates a new LogNumber from the given value that is already in log-space.
static LogNumber createFromValue(double value)
          Creates a new LogNumber from the given value.
 LogNumber divide(LogNumber other)
          Divides this value by another value and returns the result.
 void divideEquals(LogNumber other)
          Divides this value by another value and stores the result in this value.
 LogNumber dotTimes(LogNumber other)
          Element-wise multiplication of this and other
 void dotTimesEquals(LogNumber other)
          Inline element-wise multiplication of this and other
 double doubleValue()
           
 boolean equals(LogNumber other, double effectiveZero)
          Determines if two RingType objects are effectively equal
 boolean equals(Object other)
          Determines if two RingType objects are equal
 float floatValue()
           
 double getLogValue()
          Gets the log of the value represented by this object, which is what is stored in the object.
 double getValue()
          Gets the value represented by the log number.
 int hashCode()
           
 int intValue()
           
 LogNumber inverse()
          Returns the inverse of this.
 void inverseEquals()
          Changes this value to be its inverse.
 boolean isNegative()
          Gets whether or not this value has a negative sign.
 boolean isZero()
          Determines if this ring is equal to zero.
 boolean isZero(double effectiveZero)
          Determines if this ring is equal to zero using the element-wise effective zero value.
 long longValue()
           
 LogNumber max(LogNumber other)
          A new LogNumber that is the maximum of this and another.
 void maxEquals(LogNumber other)
          Changes this value to be the maximum of this value or the given value.
 LogNumber min(LogNumber other)
          A new LogNumber that is the minimum of this and another.
 void minEquals(LogNumber other)
          Changes this value to be the minimum of this value or the given value.
 LogNumber minus(LogNumber other)
          Arithmetic subtraction of other from this
 void minusEquals(LogNumber other)
          Inline arithmetic subtraction of other from this
 LogNumber negative()
          Returns the element-wise negation of this, such that this.plus( this.negative() ) has only zero elements.
 void negativeEquals()
          Inline element-wise negation of this
 LogNumber plus(LogNumber other)
          Arithmetic addition of this and other
 void plusEquals(LogNumber other)
          Inline arithmetic addition of this and other
 LogNumber power(double power)
          Returns a new LogNumber representing this log number taken to the given power.
 void powerEquals(double power)
          Transforms this log number by taking it to the given power.
 LogNumber scale(double scaleFactor)
          Element-wise scaling of this by scaleFactor
 LogNumber scaledMinus(double scaleFactor, LogNumber other)
          Arithmetic subtraction other after element-wise scaling of other by scaleFactor from this.
 void scaledMinusEquals(double scaleFactor, LogNumber other)
          Inline arithmetic subtraction of other after element-wise scaling of other by scaleFactor from this.
 LogNumber scaledPlus(double scaleFactor, LogNumber other)
          Arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaledPlusEquals(double scaleFactor, LogNumber other)
          Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaleEquals(double scaleFactor)
          Inline element-wise scaling of this by scaleFactor
 void setLogValue(double logValue)
          Sets the log of the value represented by this object, which is what is stored in the object.
 void setNegative(boolean negative)
          Sets whether or not this value has a negative sign.
 void setValue(double value)
          Sets the value represented by the log number.
 LogNumber times(LogNumber other)
          Multiples this value times another value and returns the result.
 void timesEquals(LogNumber other)
          Multiplies this value times another value and stores the result in this value.
 String toString()
           
 void zero()
          Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );
 
Methods inherited from class java.lang.Number
byteValue, shortValue
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

negative

protected boolean negative
The sign of the value, sign(value). True for negative, and false for positive.


logValue

protected double logValue
The log of the absolute value represented by this object, log(|value|).

Constructor Detail

LogNumber

public LogNumber()
Creates the LogNumber representing zero.


LogNumber

protected LogNumber(boolean negative,
                    double logValue)
Creates a new LogNumber from the given value in log-space. This method is protected to avoid people calling it with being unsure if value or log(value) should be given. Thus, two separate static utility functions createFromValue and createFromLogValue are to be used instead.

Parameters:
negative - The flag indicating if the value is positive (false) or negative (true).
logValue - The log(value) for the value to be represented by this LogNumber.

LogNumber

public LogNumber(LogNumber other)
Copies a given LogNumber.

Parameters:
other - The LogNumber to copy.
Method Detail

createFromValue

public static LogNumber createFromValue(double value)
Creates a new LogNumber from the given value.

Parameters:
value - A normal value.
Returns:
The LogNumber representation of that value.

createFromLogValue

public static LogNumber createFromLogValue(double logValue)
Creates a new LogNumber from the given value that is already in log-space. Equivalent to calling createFromValue( exp(logValue)) or createFromLogValue(false, logValue).

Parameters:
logValue - The value that is already in log-space.
Returns:
The LogNumber representation of value = exp(logValue).

createFromLogValue

public static LogNumber createFromLogValue(boolean negative,
                                           double logValue)
Creates a new LogNumber from the given value that is already in log-space. Equivalent to calling createFromValue( (negative ? +1.0 : -1.0) * exp(logValue)).

Parameters:
negative - True if the value is negative.
logValue - The value that is already in log-space.
Returns:
The LogNumber representation of value = sign * exp(logValue).

clone

public LogNumber clone()
Description copied from interface: Ring
Returns a smart copy of this, such that changing the values of the return class will not effect this

Specified by:
clone in interface Ring<LogNumber>
Specified by:
clone in interface CloneableSerializable
Overrides:
clone in class Object
Returns:
smart copy of this

equals

public boolean equals(Object other)
Description copied from interface: Ring
Determines if two RingType objects are equal

Specified by:
equals in interface Ring<LogNumber>
Overrides:
equals in class Object
Parameters:
other - RingType to compare against this
Returns:
True if the two objects are equal, false otherwise

equals

public boolean equals(LogNumber other,
                      double effectiveZero)
Description copied from interface: Ring
Determines if two RingType objects are effectively equal

Specified by:
equals in interface Ring<LogNumber>
Parameters:
other - RingType to compare against this
effectiveZero - tolerance threshold for element-wise equality
Returns:
True if the two objects are equal, false otherwise

compareTo

public int compareTo(LogNumber other)
Specified by:
compareTo in interface Comparable<LogNumber>

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object

plus

public LogNumber plus(LogNumber other)
Description copied from interface: Ring
Arithmetic addition of this and other

Specified by:
plus in interface Ring<LogNumber>
Parameters:
other - object to add to this
Returns:
sum of this and other

plusEquals

public void plusEquals(LogNumber other)
Description copied from interface: Ring
Inline arithmetic addition of this and other

Specified by:
plusEquals in interface Ring<LogNumber>
Parameters:
other - object to add to this

minus

public LogNumber minus(LogNumber other)
Description copied from interface: Ring
Arithmetic subtraction of other from this

Specified by:
minus in interface Ring<LogNumber>
Parameters:
other - object to subtract from this
Returns:
difference of this and other

minusEquals

public void minusEquals(LogNumber other)
Description copied from interface: Ring
Inline arithmetic subtraction of other from this

Specified by:
minusEquals in interface Ring<LogNumber>
Parameters:
other - object to subtract from this

times

public LogNumber times(LogNumber other)
Multiples this value times another value and returns the result.

Specified by:
times in interface EuclideanRing<LogNumber>
Parameters:
other - The other value.
Returns:
The result of this * other.

timesEquals

public void timesEquals(LogNumber other)
Multiplies this value times another value and stores the result in this value.

Specified by:
timesEquals in interface EuclideanRing<LogNumber>
Parameters:
other - The other value.

divide

public LogNumber divide(LogNumber other)
Divides this value by another value and returns the result.

Specified by:
divide in interface EuclideanRing<LogNumber>
Parameters:
other - The other value.
Returns:
The result of this / other.

divideEquals

public void divideEquals(LogNumber other)
Divides this value by another value and stores the result in this value.

Specified by:
divideEquals in interface EuclideanRing<LogNumber>
Parameters:
other - The other value.

dotTimes

public LogNumber dotTimes(LogNumber other)
Description copied from interface: Ring
Element-wise multiplication of this and other

Specified by:
dotTimes in interface Ring<LogNumber>
Parameters:
other - elements of other will be multiplied to the corresponding elements of this
Returns:
element-wise multiplication of this and other

dotTimesEquals

public void dotTimesEquals(LogNumber other)
Description copied from interface: Ring
Inline element-wise multiplication of this and other

Specified by:
dotTimesEquals in interface Ring<LogNumber>
Parameters:
other - elements of other will be multiplied to the corresponding elements of this

scale

public LogNumber scale(double scaleFactor)
Description copied from interface: Ring
Element-wise scaling of this by scaleFactor

Specified by:
scale in interface Ring<LogNumber>
Parameters:
scaleFactor - amount to scale the elements of this
Returns:
scaling of this

scaleEquals

public void scaleEquals(double scaleFactor)
Description copied from interface: Ring
Inline element-wise scaling of this by scaleFactor

Specified by:
scaleEquals in interface Ring<LogNumber>
Parameters:
scaleFactor - amount to scale the elements of this

scaledPlus

public LogNumber scaledPlus(double scaleFactor,
                            LogNumber other)
Description copied from interface: Ring
Arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x + a * y. It is typically a more efficient way of doing this.plus(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:
scaledPlus in interface Ring<LogNumber>
Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.
Returns:
The result of applying the scale factor to other then adding to this.

scaledPlusEquals

public void scaledPlusEquals(double scaleFactor,
                             LogNumber other)
Description copied from interface: Ring
Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x += a * y. It is typically a more efficient way of doing this.plusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:
scaledPlusEquals in interface Ring<LogNumber>
Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.

scaledMinus

public LogNumber scaledMinus(double scaleFactor,
                             LogNumber other)
Description copied from interface: Ring
Arithmetic subtraction other after element-wise scaling of other by scaleFactor from this. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x - a * y. It is typically a more efficient way of doing this.minus(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:
scaledMinus in interface Ring<LogNumber>
Parameters:
scaleFactor - The scale factor to multiply by the elements of other before subtracting from the elements of this.
other - Object to scale and then subtract from this.
Returns:
The result of applying the scale factor to other then subtract from this.

scaledMinusEquals

public void scaledMinusEquals(double scaleFactor,
                              LogNumber other)
Description copied from interface: Ring
Inline arithmetic subtraction of other after element-wise scaling of other by scaleFactor from this. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x -= a * y. It is typically a more efficient way of doing this.minusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:
scaledMinusEquals in interface Ring<LogNumber>
Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.

negative

public LogNumber negative()
Description copied from interface: Ring
Returns the element-wise negation of this, such that this.plus( this.negative() ) has only zero elements.

Specified by:
negative in interface Ring<LogNumber>
Returns:
element-wise negation of this

negativeEquals

public void negativeEquals()
Description copied from interface: Ring
Inline element-wise negation of this

Specified by:
negativeEquals in interface Ring<LogNumber>

inverseEquals

public void inverseEquals()
Description copied from interface: Field
Changes this value to be its inverse.

Specified by:
inverseEquals in interface Field<LogNumber>

inverse

public LogNumber inverse()
Description copied from interface: Field
Returns the inverse of this.

Specified by:
inverse in interface Field<LogNumber>
Returns:
The inverse of this field.

zero

public void zero()
Description copied from interface: Ring
Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );

Specified by:
zero in interface Ring<LogNumber>

isZero

public boolean isZero()
Description copied from interface: Ring
Determines if this ring is equal to zero.

Specified by:
isZero in interface Ring<LogNumber>
Returns:
True if all of the elements of this ring are zero.

isZero

public boolean isZero(double effectiveZero)
Description copied from interface: Ring
Determines if this ring is equal to zero using the element-wise effective zero value.

Specified by:
isZero in interface Ring<LogNumber>
Parameters:
effectiveZero - Tolerance threshold for element-wise equality
Returns:
True if all of the elements of this ring are effectively zero.

absoluteValue

public LogNumber absoluteValue()
Returns a new LogNumber that represents the absolute value of this LogNumber.

Returns:
The absolute value of this log number.

absoluteValueEquals

public void absoluteValueEquals()
Transforms this value to be its absolute value.


power

public LogNumber power(double power)
Returns a new LogNumber representing this log number taken to the given power.

Parameters:
power - The power.
Returns:
The log number to the given power.

powerEquals

public void powerEquals(double power)
Transforms this log number by taking it to the given power.

Parameters:
power - The power.

min

public LogNumber min(LogNumber other)
A new LogNumber that is the minimum of this and another.

Parameters:
other - Another value.
Returns:
A new object containing the minimum of this value or the given value.

minEquals

public void minEquals(LogNumber other)
Changes this value to be the minimum of this value or the given value.

Parameters:
other - Another value.

max

public LogNumber max(LogNumber other)
A new LogNumber that is the maximum of this and another.

Parameters:
other - Another value.
Returns:
A new object containing the maximum of this value or the given value.

maxEquals

public void maxEquals(LogNumber other)
Changes this value to be the maximum of this value or the given value.

Parameters:
other - Another value.

getValue

public double getValue()
Gets the value represented by the log number. Since the value is stored as log(value), this returns exp(log(value)) == value. Thus, it is equivalent to Math.exp(getLogValue()).

Returns:
The value represented by this object.

setValue

public void setValue(double value)
Sets the value represented by the log number. Since the value is stored as log(value), this sets the logValue to log(value). Thus, it is equivalent to doing setLogValue(Math.log(value)).

Parameters:
value - The value for this object to represent.

isNegative

public boolean isNegative()
Gets whether or not this value has a negative sign.

Returns:
True if this value has a negative sign.

setNegative

public void setNegative(boolean negative)
Sets whether or not this value has a negative sign.

Parameters:
negative - True if this value has a negative sign.

getLogValue

public double getLogValue()
Gets the log of the value represented by this object, which is what is stored in the object. That is, log(|value|).

Returns:
The log of the value represented by the object (log(|value|)).

setLogValue

public void setLogValue(double logValue)
Sets the log of the value represented by this object, which is what is stored in the object. That is, log(|value|).

Parameters:
logValue - The log of the value for this object to represent.

intValue

public int intValue()
Specified by:
intValue in class Number

longValue

public long longValue()
Specified by:
longValue in class Number

floatValue

public float floatValue()
Specified by:
floatValue in class Number

doubleValue

public double doubleValue()
Specified by:
doubleValue in class Number