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.
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. |
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.
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 objectsvarToUninstParent
- Map from BayesNetVar to BasicVarnewVarLogProbs
- Map from BasicVar to DoublenewDerivedVarValues
- 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.