blog
Interface PartialWorld

All Known Implementing Classes:
AbstractPartialWorld, DefaultPartialWorld, PartialWorld.EmptyPartialWorld, PartialWorldDiff, WorldInProgress

public interface PartialWorld

A partial description of a possible world in a BLOG model. A PartialWorld represents an event: the set of all possible worlds that satisfy the description. More specifically, a PartialWorld makes an assertion of the form:

There exist distinct objects obj_1, ..., obj_k such that X_1 = x_1, ..., X_n = x_n.
Here obj_1, ..., obj_k are object identifiers and X_1 = x_1, ..., X_n = x_n are assignments of values to random variables. The random variables can be basic variables (number variables and random function application variables) parameterized by concrete objects or object identifiers. They can also be origin variables, which specify the value of an origin function on an object identifier. The values asserted for the variables can be concrete objects or object identifiers.

Each PartialWorld object uses object identifiers to represent non-guaranteed objects of certain types, and concrete tuple representations for non-guaranteed objects of other types. The method getIdTypes returns the set of types for which object identifiers are used.

The identifiers obj_1, ..., obj_k about which a PartialWorld makes existential assertions are called its asserted identifiers. However, when a client iterates over the objects that exist in a PartialWorld, or samples an object randomly, the PartialWorld uses additional identifiers to represent the resulting objects. Specifically, such additional identifiers may be returned by the sample method of the set returned by getSatisfiers, and by the next method of iterators over this set. These identifiers, along with the asserted ones, form the common ground between a PartialWorld instance and its clients. The client can get and set the values of random variables on all identifiers in the common ground. The setValue method automatically adds identifiers to the asserted set when they are used as arguments or values of a variable.

A PartialWorld may automatically remove some identifiers from the common ground when a number variable is uninstantiated or has its value decreased, when a new asserted identifier is created using addIdentifierForPOPApp, or when an identifier is moved using moveIdentifier. Asserted identifiers are never removed automatically; only additional identifiers are removed. Note that when an identifier that is already in the common ground is added to the asserted set (either by assertIdentifier or automatically by setValue), this does not cause any other identifiers to be removed.

Because asserted identifiers can always be added using addIdentifierForPOPApp and are not automatically removed, it is possible to create a PartialWorld in which the number of identifiers asserted to satisfy a number variable is greater than the value asserted for that number variable. Such a PartialWorld describes an empty set of worlds. It is up to the client to avoid such partial worlds, explicitly removing asserted identifiers with removeIdentifier as necessary.


Nested Class Summary
static class PartialWorld.EmptyPartialWorld
           
 
Field Summary
static PartialWorld EMPTY_INST
          A partial world that has no asserted identifiers and does not assign values to any basic random variables.
static java.lang.Double UNDET
          Value used in the maps returned by varToLogProbMap and derivedVarToValueMap for basic variables that are not supported in the world, and for derived variables whose values are not determined.
 
Method Summary
 boolean addDerivedVar(DerivedVar var)
          Adds the given derived variable to this world's Bayes net, and sets its parents appropriately.
 ObjectIdentifier addIdentifierForPOPApp(NumberVar popApp)
          Returns a new object identifier that is asserted to satisfy the given POP application in this world, and to be distinct from all other object identifiers in this world's common ground.
 void addListener(WorldListener listener)
          Adds the given listener to a list of listeners to be notified when changes are made to this partial world.
 java.util.Map assertedIdToPOPAppMap()
          Map from asserted ObjectIdentifiers to the POP applications (NumberVars) that they satisfy.
 void assertIdentifier(ObjectIdentifier id)
          Asserts that the given object identifier satisfies the POP application that it satisfies in this world's common ground.
 void assertIdentifier(ObjectIdentifier id, NumberVar newPOPApp)
          Asserts that the given object identifier satisfies the given POP application.
 java.util.Map basicVarToValueMap()
          Map from instantiated BasicVars to their values.
 java.util.Map derivedVarToValueMap()
          Map from DerivedVars that are included in this world's Bayes net to their values.
 java.util.Set getAssertedIdentifiers()
          Returns the set of object identifiers that are asserted to exist in this partial world.
 IndexedSet getAssertedIdsForPOPApp(NumberVar popApp)
          Returns the set of object identifiers that are asserted to satisfy the given POP application in this partial world.
 DGraph getBayesNet()
          Returns a directed graph where the nodes are variables, and there is an edge from variable X to variable Y if Y depends directly on X given the context represented by this partial world.
 java.util.Set getDerivedVars()
          Returns the set of derived variables that are included in this world's Bayes net.
 java.util.Set getIdTypes()
          Returns the set of types that are represented with object identifiers in this partial world.
 java.util.Set getInstantiatedVars()
          Returns an unmodifiable Set representing the set of basic variables that are instantiated in this world.
 java.util.Set getInverseTuples(RandomFunction func, java.lang.Object val)
          Returns the set of argument lists that the function func maps to the value val.
 double getLogProbOfValue(BayesNetVar var)
          If var is an instantiated basic variable, this method returns the log probability of var having the value that it has in this world, given that its parents have the values specified in this world.
 NumberVar getPOPAppSatisfied(java.lang.Object obj)
          Returns the NumberVar (i.e., POP and generating objects) such that the given object satisfies that POP applied to those generating objects in this world.
 double getProbOfValue(BayesNetVar var)
          Uses getLogProbOfValue(BayesNetVar) in order to return the probability of a value given its parents.
 ObjectSet getSatisfiers(NumberVar popApp)
          Returns the set of objects that satisfy the given POP application in this world.
 java.lang.Object getValue(BayesNetVar var)
          Returns the value of the given variable in this partial world, or null if the given variable is an uninstantiated basic variable.
 java.util.Set getVarsWithArg(java.lang.Object arg)
          Returns the set of instantiated basic variables that have the given object as an argument.
 java.util.Set getVarsWithValue(java.lang.Object value)
          Returns the set of basic variables that have the given object as their value in this world.
 boolean isOverloaded(NumberVar popApp)
          Returns true if the given POP application is overloaded: that is, the number of identifiers that are asserted to satisfy it is greater than the value of the corresponding number variable, or some identifiers are asserted to satisfy it and its number variable is not instantiated.
 MultiMap objToUsesAsArgMap()
          MultiMap from objects to the instantiated BasicVars that have them as arguments.
 MultiMap objToUsesAsValueMap()
          MultiMap from objects to the instantiated BasicVars that have them as values.
 IndexedMultiMap popAppToAssertedIdsMap()
          Map from POP applications (NumberVars) to IndexedSets of the ObjectIdentifiers that are asserted to satisfy them.
 void print(java.io.PrintStream s)
          Prints this partial world to the given stream.
 boolean removeDerivedVar(DerivedVar var)
          Removes the given derived variable from this world's Bayes net.
 void removeIdentifier(ObjectIdentifier id)
          Removes the given object identifier from the set of asserted identifiers in this partial world, and from this world's common ground.
 void removeListener(WorldListener listener)
          Removes the given listener from the list of objects to be notified when changes are made to this partial world.
 void setValue(BasicVar var, java.lang.Object value)
          Instantiates the given variable to the given value (replacing any previous value), or uninstantiates the variable if the given value is null.
 void truncateList(RandomFunction f, java.lang.Object[] initialArgs, int len)
          Uninstantiates the variables for the values of f on all tuples of arguments of the form (arg1, ..., argK, i) where (arg1, ..., argK) are given by initialArgs and i is greater than or equal to len.
 void truncateNumberList(POP pop, java.lang.Object[] initialArgs, int len)
          Uninstantiates the number variables for pop on all tuples of arguments of the form (arg1, ..., argK, i) where (arg1, ..., argK) are given by initialArgs and i is greater than or equal to len.
 void updateBayesNet(DGraph newBayesNet, MapWithPreimages varToUninstParent, java.util.Map newVarLogProbs, java.util.Map newDerivedVarValues)
          Provides the Bayes net, the mapping from variables to uninstantiated parents, the mapping from basic variables to log probabilities, and the mapping from derived variables to values for this partial world.
 java.util.Map varToLogProbMap()
          Map from instantiated VarWithDistrib objects to Double values representing their log probabilities given their parents.
 MapWithPreimages varToUninstParentMap()
          MapWithPreimages from BayesNetVars to their first uninstantiated parents.
 

Field Detail

EMPTY_INST

static final PartialWorld EMPTY_INST
A partial world that has no asserted identifiers and does not assign values to any basic random variables.


UNDET

static final java.lang.Double UNDET
Value used in the maps returned by varToLogProbMap and derivedVarToValueMap for basic variables that are not supported in the world, and for derived variables whose values are not determined. This object is actually a Double object with value -1. When using derivedVarToValueMap, clients should compare values to UNDET with == to avoid confusion with other Double objects that have value -1.

Method Detail

getInstantiatedVars

java.util.Set getInstantiatedVars()
Returns an unmodifiable Set representing the set of basic variables that are instantiated in this world.

Returns:
unmodifiable Set of BasicVar objects

getValue

java.lang.Object getValue(BayesNetVar var)
Returns the value of the given variable in this partial world, or null if the given variable is an uninstantiated basic variable. Note that this method returns null on all basic variables that are not instantiated in this world, even if the value of the variable is determined because its arguments cannot exist.


setValue

void setValue(BasicVar var,
              java.lang.Object value)
Instantiates the given variable to the given value (replacing any previous value), or uninstantiates the variable if the given value is null. This method instantiates the variable even if some of its arguments are concrete non-guaranteed objects that do not necessarily exist in this world.

If the variable is a number variable and the given value is less than its old value, then all variables defined on concrete non-guaranteed objects that no longer exist are uninstantiated. Variables defined on object identifiers that satisfy this number variable are not affected (we don't know which identifiers to remove). We also don't do anything about variables whose values no longer exist.


truncateList

void truncateList(RandomFunction f,
                  java.lang.Object[] initialArgs,
                  int len)
Uninstantiates the variables for the values of f on all tuples of arguments of the form (arg1, ..., argK, i) where (arg1, ..., argK) are given by initialArgs and i is greater than or equal to len. Assumes that in the current world, there are no instantiated variables beyond the first uninstantiated variable in this sequence.


truncateNumberList

void truncateNumberList(POP pop,
                        java.lang.Object[] initialArgs,
                        int len)
Uninstantiates the number variables for pop on all tuples of arguments of the form (arg1, ..., argK, i) where (arg1, ..., argK) are given by initialArgs and i is greater than or equal to len. Assumes that in the current world, there are no instantiated variables beyond the first uninstantiated variable in this sequence.


getVarsWithValue

java.util.Set getVarsWithValue(java.lang.Object value)
Returns the set of basic variables that have the given object as their value in this world.

Returns:
unmodifiable Set of BasicVar

getVarsWithArg

java.util.Set getVarsWithArg(java.lang.Object arg)
Returns the set of instantiated basic variables that have the given object as an argument.

Returns:
unmodifiable Set of BasicVar

getInverseTuples

java.util.Set getInverseTuples(RandomFunction func,
                               java.lang.Object val)
Returns the set of argument lists that the function func maps to the value val. This method requires func to be a random function, since the values of non-random and origin functions may not be represented explicitly.

Returns:
Set of List objects representing argument lists

getLogProbOfValue

double getLogProbOfValue(BayesNetVar var)
If var is an instantiated basic variable, this method returns the log probability of var having the value that it has in this world, given that its parents have the values specified in this world. Otherwise returns 0 (log of 1), because uninstantiated variables and non-basic variables do not contribute to the joint distribution. This method yields a fatal error if the world is not complete enough to determine the given variable's distribution.


getProbOfValue

double getProbOfValue(BayesNetVar var)
Uses getLogProbOfValue(BayesNetVar) in order to return the probability of a value given its parents.


getSatisfiers

ObjectSet getSatisfiers(NumberVar popApp)
Returns the set of objects that satisfy the given POP application in this world. The objects may be represented as concrete objects or identifiers, depending on the way this PartialWorld implementation handles objects of the relevant type.

The set returned by this method will remain correct if new basic random variables are instantiated or new object identifiers are added (to this world's common ground or its set of asserted identifiers). The set may not remain correct if already-instantiated random variables are changed, or if object identifiers are moved from one number variable to another or removed from the world.

Throws:
java.lang.IllegalStateException - if all the given generating objects exist in the world, but the corresponding number variable is not instantiated

getPOPAppSatisfied

NumberVar getPOPAppSatisfied(java.lang.Object obj)
Returns the NumberVar (i.e., POP and generating objects) such that the given object satisfies that POP applied to those generating objects in this world. Returns null if the given object does not satisfy any POP application (this includes the case where obj is an object identifier that is not valid in this world).


getIdTypes

java.util.Set getIdTypes()
Returns the set of types that are represented with object identifiers in this partial world.

Returns:
unmodifiable Set of Type

getAssertedIdentifiers

java.util.Set getAssertedIdentifiers()
Returns the set of object identifiers that are asserted to exist in this partial world.

Returns:
unmodifiable Set of ObjectIdentifier

getAssertedIdsForPOPApp

IndexedSet getAssertedIdsForPOPApp(NumberVar popApp)
Returns the set of object identifiers that are asserted to satisfy the given POP application in this partial world. The behavior of this method does not depend on whether the number variable for this POP application is instantiated or not.

Returns:
unmodifiable IndexedSet of ObjectIdentifier

assertIdentifier

void assertIdentifier(ObjectIdentifier id,
                      NumberVar newPOPApp)
Asserts that the given object identifier satisfies the given POP application. The given identifier does not need to be in this world's common ground already; if it is, any previous assertion about it is removed. The assertion is made even if the corresponding number variable is not instantiated, and even if adding this identifier will overload that number variable.

Throws:
java.lang.IllegalArgumentException - if the type of id is different from the type of object generated by newPOPApp

assertIdentifier

void assertIdentifier(ObjectIdentifier id)
Asserts that the given object identifier satisfies the POP application that it satisfies in this world's common ground. That is, this method adds id to the set of asserted identifiers in this world.

Throws:
java.lang.IllegalArgumentException - if id is not in this world's common ground

addIdentifierForPOPApp

ObjectIdentifier addIdentifierForPOPApp(NumberVar popApp)
Returns a new object identifier that is asserted to satisfy the given POP application in this world, and to be distinct from all other object identifiers in this world's common ground. The identifier is added even if the corresponding number variable is not instantiated, and even if adding this identifier will overload that number variable.


removeIdentifier

void removeIdentifier(ObjectIdentifier id)
Removes the given object identifier from the set of asserted identifiers in this partial world, and from this world's common ground. Automatically uninstantiates all variables that have this identifier as an argument (variables that have this identifier as a value are unaffected; the client should give new values to all such variables). Has no effect if the given identifier is not currently asserted or in the common ground.


isOverloaded

boolean isOverloaded(NumberVar popApp)
Returns true if the given POP application is overloaded: that is, the number of identifiers that are asserted to satisfy it is greater than the value of the corresponding number variable, or some identifiers are asserted to satisfy it and its number variable is not instantiated.


getBayesNet

DGraph getBayesNet()
Returns a directed graph where the nodes are variables, and there is an edge from variable X to variable Y if Y depends directly on X given the context represented by this partial world. The graph includes at least the variables that are instantiated in this partial world. It may also include certain derived variables that are not instantiated because their values are determined by the instantiated variables.

If a variable var is not supported in this world, then its parents in the returned graph are those variables accessed by var.getDistrib (or var.getValue if var is a derived variable) before the first uninstantiated variable.


updateBayesNet

void updateBayesNet(DGraph newBayesNet,
                    MapWithPreimages varToUninstParent,
                    java.util.Map newVarLogProbs,
                    java.util.Map newDerivedVarValues)
Provides the Bayes net, the mapping from variables to uninstantiated parents, the mapping from basic variables to log probabilities, and the mapping from derived variables to values for this partial world. This method relieves the partial world of the need to recompute parent sets, log probabilities, and derived variable values itself. It is useful when some other object -- such as a PartialWorldDiff -- has already updated these data structures.

Parameters:
newBayesNet - DGraph whose nodes are BayesNetVar objects
varToUninstParent - Map from BayesNetVar to BasicVar
newVarLogProbs - Map from BasicVar to Double
newDerivedVarValues - Map from DerivedVar to Object
Throws:
java.lang.IllegalArgumentException - if the given information is not sufficient to update this partial world's data structures without additional computation

getDerivedVars

java.util.Set getDerivedVars()
Returns the set of derived variables that are included in this world's Bayes net.

Returns:
unmodifiable Set of DerivedVar

addDerivedVar

boolean addDerivedVar(DerivedVar var)
Adds the given derived variable to this world's Bayes net, and sets its parents appropriately.

Returns:
true if the variable was actually added; false if it was already present

removeDerivedVar

boolean removeDerivedVar(DerivedVar var)
Removes the given derived variable from this world's Bayes net.

Returns:
true if the variable was actually removed; false if it was not present

addListener

void addListener(WorldListener listener)
Adds the given listener to a list of listeners to be notified when changes are made to this partial world.


removeListener

void removeListener(WorldListener listener)
Removes the given listener from the list of objects to be notified when changes are made to this partial world.


print

void print(java.io.PrintStream s)
Prints this partial world to the given stream.


basicVarToValueMap

java.util.Map basicVarToValueMap()
Map from instantiated BasicVars to their values.


objToUsesAsValueMap

MultiMap objToUsesAsValueMap()
MultiMap from objects to the instantiated BasicVars that have them as values.


objToUsesAsArgMap

MultiMap objToUsesAsArgMap()
MultiMap from objects to the instantiated BasicVars that have them as arguments.


assertedIdToPOPAppMap

java.util.Map assertedIdToPOPAppMap()
Map from asserted ObjectIdentifiers to the POP applications (NumberVars) that they satisfy.


popAppToAssertedIdsMap

IndexedMultiMap popAppToAssertedIdsMap()
Map from POP applications (NumberVars) to IndexedSets of the ObjectIdentifiers that are asserted to satisfy them. POP applications with no identifiers are not necessarily included in this map.


varToUninstParentMap

MapWithPreimages varToUninstParentMap()
MapWithPreimages from BayesNetVars to their first uninstantiated parents. A variable is included as a key in this map only if it is not supported by this world, which means it has an uninstantiated parent.


varToLogProbMap

java.util.Map varToLogProbMap()
Map from instantiated VarWithDistrib objects to Double values representing their log probabilities given their parents.


derivedVarToValueMap

java.util.Map derivedVarToValueMap()
Map from DerivedVars that are included in this world's Bayes net to their values.