com.cra.bnet.engine
Class Potential

java.lang.Object
  |
  +--com.cra.bnet.engine.Potential
Direct Known Subclasses:
Cpt

public class Potential
extends Object

Basic implementation of a potential. A potential is basically a real-valued function of multiple discrete nodes. That is, it maps each configuration of the nodes in its domain to a real-valued number. Probability tables (conditional, joint, etc.) are examples of potentials.

Note that the add, divideBy, marginalize, multiply, and normalize methods return new Potential instances; that is, those operations do not modify either the Potential object they are called on or the Potential object given as an argument.

During the addition, division, multiplication, and marginalization operations, a mapping between two potentials must be computed. If operations are performed repeatedly these computations can be quite expensive. However, if these operations are repetitive, as they are during probabilistic inferencing, these mappings can be cached and reused, saving a great amount of processing time. The PotentialMappings class serves this purpose: it computes the mappings and saves them for later use. Clients need not be concerned with this class if they don't care about the mappings. If they do care, there are methods for getting and setting the potential's mappings object.


Field Summary
protected  List nodes
           
protected  double[] table
           
protected  VbnConverter vbn
           
 
Constructor Summary
protected Potential()
          We need a default constructor so that the implicit call to super from a subclass can succeed.
  Potential(DiscreteNode node, double[] values)
          Creates a new potential over the specified node that has the specified values.
  Potential(List nodes)
          Creates a new potential over the specified nodes.
  Potential(List nodes, PotentialMappings mappings)
          Creates a new potential over the specified nodes that uses the specified potential mappings.
  Potential(Potential potential)
          Creates a new potential that is a copy of the specified potential.
 
Method Summary
 Potential add(Potential potential)
          Adds this potential to the specified potential and returns the result.
 Potential divideBy(Potential potential)
          Divides this potential by the specified potential and returns the result.
 void dump(PrintWriter out)
          Prints this potential to the specified print writer.
 boolean equals(Object obj)
          Compares the specified object with this potential for equality.
 double get(int index)
          Returns the value of this potential indexed by the specified DECIMAL index.
 double get(int[] index)
          Returns the value of this potential indexed by the specified index.
 PotentialMappings getMappings()
          Returns the mappings for this potential.
 List getNodes()
          Returns the domain list of this potential.
 int hashCode()
          Returns the hash code value for this potential.
 Potential marginalize(List variables)
          Marginalizes the specified nodes out of this potential and returns the resulting potential.
 Potential multiply(Potential potential)
          Multiplies this potential by the specified potential and returns the product.
 Potential normalize()
          Normalizes the values of this potential so that they sum to unity and returns the result.
 void set(int[] index, double value)
          Sets the value of this potential indexed by the specified index to the specified value.
 void set(int index, double value)
          Sets the value of this potential indexed by the specified integer index to the specified value.
 void setMappings(PotentialMappings mappings)
          Sets the mappings that this potential uses to the specified mappings.
 double[] toArray()
          Returns the values of this potential in an array.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

nodes

protected List nodes

table

protected double[] table

vbn

protected VbnConverter vbn
Constructor Detail

Potential

public Potential(DiscreteNode node,
                 double[] values)
Creates a new potential over the specified node that has the specified values. The length of the values array must be the same as the number of states of the node.

Parameters:
node - node of this potential.
values - values of this potential.

Potential

public Potential(List nodes)
Creates a new potential over the specified nodes. All entries in the table will be zero.

Parameters:
nodes - list of DiscreteNode objects for this potential (i.e. its domain). If this is being used as a CPT, the List consists of the target node and then the parents in some specified order.

Potential

public Potential(List nodes,
                 PotentialMappings mappings)
Creates a new potential over the specified nodes that uses the specified potential mappings. All entries in the table will be zero.

Parameters:
nodes - list of DiscreteNode objects for this potential (i.e. its domain).
mappings - mappings between potentials.

Potential

public Potential(Potential potential)
Creates a new potential that is a copy of the specified potential. This potential will use the same potential mappings that the specified potential uses.

Parameters:
potential - potential to copy.

Potential

protected Potential()
We need a default constructor so that the implicit call to super from a subclass can succeed.

Method Detail

add

public Potential add(Potential potential)
Adds this potential to the specified potential and returns the result.

Parameters:
potential - potential to be added to this potential.
Returns:
the sum of this potential and the specified potential.

divideBy

public Potential divideBy(Potential potential)
Divides this potential by the specified potential and returns the result. If the specified potential contains zero entries, divide-by-zero will occur. In this case, the result is defined to be zero. Example: 3/0 = 0.

Parameters:
potential - potential to divide this potential by.
Returns:
the result of dividing this potential by the specified potential.

dump

public void dump(PrintWriter out)
Prints this potential to the specified print writer.

Parameters:
out - print writer to print this potential to.

equals

public boolean equals(Object obj)
Compares the specified object with this potential for equality. Returns true if and only if the specified object is also a potential, both potentials have the same nodes (in any order) in their domains, and both potentials have the same entries in their tables.

Overrides:
equals in class Object
Parameters:
obj - object to be compared for equality with this potential.
Returns:
true if the specified object is equal to this potential.

get

public double get(int[] index)
Returns the value of this potential indexed by the specified index.

Parameters:
index - index used to retrieve the value.
Returns:
the value of this potential indexed by the specified index. When used for a CPT, this returns a single conditional probability when given a specific state of the target node followed by specific states of the parent nodes, in order. Answers "what is the prob of this state given the following parent states?".

get

public double get(int index)
Returns the value of this potential indexed by the specified DECIMAL index. Danger! Only use this when looping over everything! Use get(int[]) above when digging out one specific value.

Parameters:
index - index used to retrieve the value.
Returns:
the value of the potential at that index position.

getMappings

public PotentialMappings getMappings()
Returns the mappings for this potential.

Returns:
the mappings for this potential.

getNodes

public List getNodes()
Returns the domain list of this potential. Each element of the returned list is guaranteed to be of type DiscreteNode. The returned list is unmodifiable and will throw an UnsupportedOperationExection if an attempt to modify it is made.

Returns:
the domain list of this potential. When used as a CPT, the first DiscreteNode in the returned List corresponds to the target DiscreteNode and the rest correspond to the parents, in order.

hashCode

public int hashCode()
Returns the hash code value for this potential. The hash code of a potential is defined to be the sum of the hash codes of the nodes in its domain and the result of the following calculation on each value of the potential: long bits = Double.doubleToLongBits(value); hashCode += (int) (bits ^ (bits >>> 32)); These calculations were taken from the book Effective Java, Item 8, p. 38. Note that this definition may be changed in the future, to allow for more efficient hash code computation.

Overrides:
hashCode in class Object
Returns:
the hash code value for this potential.

marginalize

public Potential marginalize(List variables)
Marginalizes the specified nodes out of this potential and returns the resulting potential. Note that the specified nodes must be a subset of this potential's domain.

Parameters:
variables - list of nodes to marginalize out of this potential.
Returns:
the potential resulting from marginalizing the specified nodes out of this potential.

multiply

public Potential multiply(Potential potential)
Multiplies this potential by the specified potential and returns the product.

Returns:
the product of multiplying this potential by the specified potential.

normalize

public Potential normalize()
Normalizes the values of this potential so that they sum to unity and returns the result. If the normalization would cause a divide-by-zero to occur (i.e. if the values of this potential sum to zero), null is returned.

Returns:
the normalized version of this potential or null if divide-by-zero would occur.

set

public void set(int[] index,
                double value)
Sets the value of this potential indexed by the specified index to the specified value.

Parameters:
index - index for the new value.
value - the new value. When this is used as a CPT, index gives the specified states of the target node and its parents (in that order), and value is the probability you want to set.

set

public void set(int index,
                double value)
Sets the value of this potential indexed by the specified integer index to the specified value.

Parameters:
index - integer index for the new value.
value - the new value.

setMappings

public void setMappings(PotentialMappings mappings)
Sets the mappings that this potential uses to the specified mappings.

Parameters:
mappings - potential mappings for this potential to use.

toArray

public double[] toArray()
Returns the values of this potential in an array. The values are given in the array in the same order that they would be accessed from this potential while iterating over it using a VbnConverter object.

Returns:
the values of this potential in an array.