LogNumber (Cognitive Foundry)

java.lang.Object
- java.lang.Number
- - gov.sandia.cognition.math.LogNumber

All Implemented Interfaces:

EuclideanRing<LogNumber>, Field<LogNumber>, Ring<LogNumber>, CloneableSerializable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<LogNumber>
```
public class LogNumber
extends java.lang.Number
implements Field<LogNumber>, java.lang.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

Fields
Modifier and Type	Field and Description
`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

Constructors
Modifier	Constructor and Description
	`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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(java.lang.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.
`java.lang.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 java.lang.Object
    
    Returns:
    
    smart copy of this
  - equals
```
public boolean equals(java.lang.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 java.lang.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 java.lang.Comparable<LogNumber>
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.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 java.lang.Number
  - longValue
```
public long longValue()
```
    Specified by:
    
    longValue in class java.lang.Number
  - floatValue
```
public float floatValue()
```
    Specified by:
    
    floatValue in class java.lang.Number
  - doubleValue
```
public double doubleValue()
```
    Specified by:
    
    doubleValue in class java.lang.Number

Class LogNumber

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Field Detail

negative

logValue

Constructor Detail

LogNumber

LogNumber

LogNumber

Method Detail

createFromValue

createFromLogValue

createFromLogValue

clone

equals

equals

compareTo

hashCode

toString

plus

plusEquals

minus

minusEquals

times

timesEquals

divide

divideEquals

dotTimes

dotTimesEquals

scale

scaleEquals

scaledPlus

scaledPlusEquals

scaledMinus

scaledMinusEquals

negative

negativeEquals

inverseEquals

inverse

zero

isZero

isZero

absoluteValue

absoluteValueEquals

power

powerEquals

min

minEquals

max

maxEquals

getValue

setValue

isNegative

setNegative

getLogValue

setLogValue

intValue

longValue

floatValue

doubleValue