burlap.datastructures

Class BoltzmannDistribution

java.lang.Object

burlap.datastructures.BoltzmannDistribution

public class BoltzmannDistribution
extends java.lang.Object

This class provides methods for computing, sampling, and working with Boltzmann distributions/Softmax. The input is a set of "preference" values. The output is a probability distribution over those preferences with elements that had higher preferences having higher probability. Computation is performed using a log sum exponential re-expression trick that avoids overflow errors.

Author:

James MacGlashan

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	needsUpdate Indicates whether the probabilities need to be recomputed
protected double[]	preferences The preference values to turn into probabilities
protected double[]	probs The output probabilities
protected java.util.Random	rand The random object to use for sampling.
protected double	temperature The temperature value.
protected double[]	tempNormalized The preference values normalized by the temperature

Constructor Summary

Constructors

Constructor and Description
BoltzmannDistribution(double[] preferences) Initializes the distribution with the preference values that are to be turned into a soft max probability distribution.
BoltzmannDistribution(double[] preferences, double temperature) Initializes the distribution with the preference values that are to be turned into a soft max probability distribution and a temperature value to control how deterministic the probability output is.

Method Summary

Modifier and Type	Method and Description
protected void	computeProbs() Computes the probability distribution.
protected void	computeTempNormalized() Computes the temperature normalized preference values
double[]	getPreferences() Returns the input preferences
double[]	getProbabilities() Returns the output probability distribution.
double	getTemperature() Returns the temperature parameter
protected double	maxTNormed() Returns the maximum temperature normalized preference
int	preferenceLength() Returns the number of elements on which there are preferences
int	sample() Samples the output probability distribution.
void	setPreference(int i, double p) Sets the preference for the ith elemnt
void	setPreferences(double[] preferences) Sets the input preferences
void	setTemperature(double t) Sets the temperature value to use.

Methods inherited from class java.lang.Object

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

Field Detail

preferences

protected double[] preferences

The preference values to turn into probabilities

temperature

protected double temperature

The temperature value. Lower values produce more greedy deterministic probability outputs while higher values produce more uniform probability outputs

tempNormalized

protected double[] tempNormalized

The preference values normalized by the temperature

probs

protected double[] probs

The output probabilities

needsUpdate

protected boolean needsUpdate

Indicates whether the probabilities need to be recomputed

rand

protected java.util.Random rand

The random object to use for sampling.

Constructor Detail

BoltzmannDistribution

public BoltzmannDistribution(double[] preferences)

Initializes the distribution with the preference values that are to be turned into a soft max probability distribution.

Parameters:

preferences - the preference values to turn into a probability distribution

BoltzmannDistribution

public BoltzmannDistribution(double[] preferences,
                             double temperature)

Initializes the distribution with the preference values that are to be turned into a soft max probability distribution and a temperature value to control how deterministic the probability output is. Lower temperature values result in a more deterministic distribution; higher values produce a more uniform distribution.

Parameters:

preferences - the preference values to turn into a probability distribution

temperature - a value on 0 < temperature < +infinity

Method Detail

getPreferences

public double[] getPreferences()

Returns the input preferences

Returns:

the input preferences

getTemperature

public double getTemperature()

Returns the temperature parameter

Returns:

the temperature parameter

preferenceLength

public int preferenceLength()

Returns the number of elements on which there are preferences

Returns:

the number of elements on which there are preferences

getProbabilities

public double[] getProbabilities()

Returns the output probability distribution. This method computes the probabilities lazily and only when needed.

Returns:

the output probability distribution

setTemperature

public void setTemperature(double t)

Sets the temperature value to use.

Parameters:

t - a value on 0 < temperature < +infinity

setPreference

public void setPreference(int i,
                          double p)

Sets the preference for the ith elemnt

Parameters:

i - which element to set

p - the preference for that element

setPreferences

public void setPreferences(double[] preferences)

Sets the input preferences

Parameters:

preferences - the input preferences

sample

public int sample()

Samples the output probability distribution.

Returns:

the index of the sampled element

computeProbs

protected void computeProbs()

Computes the probability distribution. This method uses the log sum exp trick to avoid overflow issues.

computeTempNormalized

protected void computeTempNormalized()

Computes the temperature normalized preference values

maxTNormed

protected double maxTNormed()

Returns the maximum temperature normalized preference

Returns:

the maximum temperature normalized preference