Potential and Instantiation¶
pyAgrum.Potential
is a multi-dimensional array with a pyAgrum.DiscreteVariable
associated to each dimension.
It is used to represent probabilities and utilities tables in aGrUMs’ multidimensional (graphical) models with some conventions.
- The data are stored by iterating over each variable in the sequence.
>>> a=gum.RangeVariable("A","variable A",1,3)
>>> b=gum.RangeVariable("B","variable B",1,2)
>>> p=gum.Potential().add(a).add(b).fillWith([1,2,3,4,5,6]);
>>> print(p)
<A:1|B:1> :: 1 /<A:2|B:1> :: 2 /<A:3|B:1> :: 3 /<A:1|B:2> :: 4 /<A:2|B:2> :: 5 /<A:3|B:2> :: 6
- If a
pyAgrum.Potential
with the sequence ofpyAgrum.DiscreteVariable
X,Y,Z represents a conditional probability Table (CPT), it will be P(X|Y,Z).
>>> print(p.normalizeAsCPT())
<A:1|B:1> :: 0.166667 /<A:2|B:1> :: 0.333333 /<A:3|B:1> :: 0.5 /<A:1|B:2> :: 0.266667 /<A:2|B:2> :: 0.333333 /<A:3|B:2> :: 0.4
- For addressing and looping in a
pyAgrum.Potential
structure, pyAgrum providesInstantiation
class which represents a multi-dimensionnal index.
>>> I=gum.Instantiation(p)
>>> print(I)
<A:1|B:1>
>>> I.inc();print(I)
<A:2|B:1>
>>> I.inc();print(I)
<A:3|B:1>
>>> I.inc();print(I)
<A:1|B:2>
>>> I.setFirst();print("{} -> {}".format(I,p.get(I)))
<A:1|B:1> -> 0.16666666666666666
>>> I["B"]="2";print("{} -> {}".format(I,p.get(I)))
<A:1|B:2> -> 0.26666666666666666
pyAgrum.Potential
include tensor operators (see for instance this notebook).
>>> c=gum.RangeVariable("C","variable C",1,5)
>>> q=gum.Potential().add(a).add(c).fillWith(1)
>>> print(p+q)
<A:1|C:1|B:1> :: 2 /<A:2|C:1|B:1> :: 3 /<A:3|C:1|B:1> :: 4 /<A:1|C:2|B:1> :: 2 /<A:2|C:2|B:1> :: 3 /<A:3|C:2|B:1> :: 4 /<A:1|C:3|B:1> :: 2 /<A:2|C:3|B:1> :: 3 /<A:3|C:3|B:1> :: 4 /<A:1|C:4|B:1> :: 2 /<A:2|C:4|B:1> :: 3 /<A:3|C:4|B:1> :: 4 /<A:1|C:5|B:1> :: 2 /<A:2|C:5|B:1> :: 3 /<A:3|C:5|B:1> :: 4 /<A:1|C:1|B:2> :: 5 /<A:2|C:1|B:2> :: 6 /<A:3|C:1|B:2> :: 7 /<A:1|C:2|B:2> :: 5 /<A:2|C:2|B:2> :: 6 /<A:3|C:2|B:2> :: 7 /<A:1|C:3|B:2> :: 5 /<A:2|C:3|B:2> :: 6 /<A:3|C:3|B:2> :: 7 /<A:1|C:4|B:2> :: 5 /<A:2|C:4|B:2> :: 6 /<A:3|C:4|B:2> :: 7 /<A:1|C:5|B:2> :: 5 /<A:2|C:5|B:2> :: 6 /<A:3|C:5|B:2> :: 7
>>> print((p*q).margSumOut(["B","C"])) # marginalize p*q over B and C(using sum)
<A:1> :: 25 /<A:2> :: 35 /<A:3> :: 45
Instantiation¶
-
class
pyAgrum.
Instantiation
(*args)¶ Class for assigning/browsing values to tuples of discrete variables.
Instantiation is designed to assign values to tuples of variables and to efficiently loop over values of subsets of variables.
Available ructors:
Instantiation() -> Instantiation
Instantiation(aI) -> Instantiation
Parameters: aI (pyAgrum.Instantiation) – The Instantiation we copy Returns: - pyAgrum.Instantiation – An empty tuple or a copy of the one in parameters
- Instantiation is subscriptable therefore values can be easily accessed/modified.
Examples
>>> ## Access the value of A in an instantiation aI >>> valueOfA = aI['A'] >>> ## Modify the value >>> aI['A'] = newValueOfA
-
add
(Instantiation self, DiscreteVariable v)¶ Adds a new variable in the Instantiation.
Parameters: v (pyAgrum.DiscreteVariable) – The new variable added to the Instantiation Raises: DuplicateElement
– If the variable is already in this Instantiation
-
chgVal
(Instantiation self, DiscreteVariable v, int newval)¶ chgVal(Instantiation self, DiscreteVariable v, int newval) -> Instantiation chgVal(Instantiation self, int varPos, int newval) -> Instantiation chgVal(Instantiation self, str var, int newval) -> Instantiation chgVal(Instantiation self, str var, str newval) -> Instantiation
Assign newval to v (or to the variable at position varPos) in the Instantiation.
Parameters: - v (pyAgrum.DiscreteVariable or string) – The variable whose value is assigned (or its name)
- varPos (int) – The index of the variable whose value is assigned in the tuple of variables of the Instantiation
- newval (int or string) – The index of the value assigned (or its name)
Returns: The modified instantiation
Return type: Raises: NotFound
– If variable v does not belong to the instantiation.OutOfBound
– If newval is not a possible value for the variable.
-
clear
(Instantiation self)¶ Erase all variables from an Instantiation.
-
contains
(Instantiation self, DiscreteVariable v)¶ contains(Instantiation self, DiscreteVariable v) -> bool
Indicates whether a given variable belongs to the Instantiation.
Parameters: v (pyAgrum.DiscreteVariable) – The variable for which the test is made. Returns: True if the variable is in the Instantiation. Return type: bool
-
dec
(Instantiation self)¶ Operator –.
-
decIn
(Instantiation self, Instantiation i)¶ Operator – for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to decrement in this Instantiation
-
decNotVar
(Instantiation self, DiscreteVariable v)¶ Operator – for vars which are not v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable not to decrement in this Instantiation.
-
decOut
(Instantiation self, Instantiation i)¶ Operator – for the variables not in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to not decrement in this Instantiation.
-
decVar
(Instantiation self, DiscreteVariable v)¶ Operator – for variable v only.
Parameters: v (pyAgrum.DiscreteVariable) – The variable to decrement in this Instantiation. Raises: NotFound
– If variable v does not belong to the Instantiation.
-
domainSize
(Instantiation self)¶ Returns: The product of the variable’s domain size in the Instantiation. Return type: int
-
empty
(Instantiation self)¶ Returns: True if the instantiation is empty. Return type: bool
-
end
(Instantiation self)¶ Returns: True if the Instantiation reached the end. Return type: bool
-
erase
(Instantiation self, DiscreteVariable v)¶ Parameters: v (pyAgrum.DiscreteVariable) – The variable to be removed from this Instantiation. Raises: NotFound
– If v does not belong to this Instantiation.
-
fromdict
(Instantiation self, PyObject * dict)¶ Change the values in an instantiation from a dict (variable_name:value) where value can be a position (int) or a label (string).
If a variable_name does not occur in the instantiation, nothing is done.
Warning
OutOfBounds raised if a value cannot be found.
-
hamming
(Instantiation self)¶ Returns: the hamming distance of this instantiation. Return type: int
-
inOverflow
(Instantiation self)¶ Returns: True if the current value of the tuple is correct Return type: bool
-
inc
(Instantiation self)¶ Operator ++.
-
incIn
(Instantiation self, Instantiation i)¶ Operator ++ for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to increment in this Instantiation.
-
incNotVar
(Instantiation self, DiscreteVariable v)¶ Operator ++ for vars which are not v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable not to increment in this Instantiation.
-
incOut
(Instantiation self, Instantiation i)¶ Operator ++ for the variables not in i.
Parameters: i (Instantiation) – The set of variable to not increment in this Instantiation.
-
incVar
(Instantiation self, DiscreteVariable v)¶ Operator ++ for variable v only.
Parameters: v (pyAgrum.DiscreteVariable) – The variable to increment in this Instantiation. Raises: NotFound
– If variable v does not belong to the Instantiation.
-
nbrDim
(Instantiation self)¶ Returns: The number of variables in the Instantiation. Return type: int
-
pos
(Instantiation self, DiscreteVariable v)¶ Returns: the position of the variable v. Return type: int Parameters: v (pyAgrum.DiscreteVariable) – the variable for which its position is return. Raises: NotFound
– If v does not belong to the instantiation.
-
rend
(Instantiation self)¶ Returns: True if the Instantiation reached the rend. Return type: bool
-
reorder
(Instantiation self, pyAgrum.Sequence< pyAgrum.DiscreteVariable * > v)¶ reorder(Instantiation self, Instantiation i)
Reorder vars of this instantiation giving the order in v (or i).
Parameters: - i (pyAgrum.Instantiation) – The sequence of variables with which to reorder this Instantiation.
- v (list) – The new order of variables for this Instantiation.
-
setFirst
(Instantiation self)¶ Assign the first values to the tuple of the Instantiation.
-
setFirstIn
(Instantiation self, Instantiation i)¶ Assign the first values in the Instantiation for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The variables to which their first value is assigned in this Instantiation.
-
setFirstNotVar
(Instantiation self, DiscreteVariable v)¶ Assign the first values to variables different of v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable that will not be set to its first value in this Instantiation.
-
setFirstOut
(Instantiation self, Instantiation i)¶ Assign the first values in the Instantiation for the variables not in i.
Parameters: i (pyAgrum.Instantiation) – The variable that will not be set to their first value in this Instantiation.
-
setFirstVar
(Instantiation self, DiscreteVariable v)¶ Assign the first value in the Instantiation for var v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable that will be set to its first value in this Instantiation.
-
setLast
(Instantiation self)¶ Assign the last values in the Instantiation.
-
setLastIn
(Instantiation self, Instantiation i)¶ Assign the last values in the Instantiation for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The variables to which their last value is assigned in this Instantiation.
-
setLastNotVar
(Instantiation self, DiscreteVariable v)¶ Assign the last values to variables different of v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable that will not be set to its last value in this Instantiation.
-
setLastOut
(Instantiation self, Instantiation i)¶ Assign the last values in the Instantiation for the variables not in i.
Parameters: i (pyAgrum.Instantiation) – The variables that will not be set to their last value in this Instantiation.
-
setLastVar
(Instantiation self, DiscreteVariable v)¶ Assign the last value in the Instantiation for var v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable that will be set to its last value in this Instantiation.
-
setVals
(Instantiation self, Instantiation i)¶ Assign the values from i in the Instantiation.
Parameters: i (pyAgrum.Instantiation) – An Instantiation in which the new values are searched Returns: a reference to the instantiation Return type: pyAgrum.Instantiation
-
todict
(Instantiation self, bool withLabels=False)¶ Create a dict (variable_name:value) from an instantiation
Parameters: withLabels (boolean) – The value will be a label (string) if True. It will be a position (int) if False. Returns: The dictionary Return type: Dict
-
unsetEnd
(Instantiation self)¶ Alias for unsetOverflow().
-
unsetOverflow
(Instantiation self)¶ Removes the flag overflow.
-
val
(Instantiation self, int i)¶ val(Instantiation self, DiscreteVariable var) -> int
Parameters: - i (int) – The index of the variable.
- var (pyAgrum.DiscreteVariable) – The variable the value of which we wish to know
Returns: the current value of the variable.
Return type: int
Raises: NotFound
– If the element cannot be found.
-
variable
(Instantiation self, int i)¶ variable(Instantiation self, str name) -> DiscreteVariable
Parameters: i (int) – The index of the variable Returns: the variable at position i in the tuple. Return type: pyAgrum.DiscreteVariable Raises: NotFound
– If the element cannot be found.
-
variablesSequence
(Instantiation self)¶ Returns: the sequence of DiscreteVariable of this instantiation. Return type: List
Potential¶
-
class
pyAgrum.
Potential
(*args)¶ Class representing a potential.
Available ructors:
Potential() -> Potential
Potential(src) -> Potential
Parameters: src (pyAgrum.Potential) – The Potential to copy Returns: The new Potential Return type: pyAgrum.Potential -
KL
(Potential self, Potential p)¶ Check the compatibility and compute the Kullback-Leibler divergence between the potential and.
Parameters: p (pyAgrum.Potential) – the potential from which we want to calculate the divergence.
Returns: The value of the divergence
Return type: float
Raises: gum.InvalidArgument
– If p is not compatible with the potential (dimension, variables)gum.FatalError
– If a zero is found in p or the potential and not in the other.
-
abs
(Potential self)¶ Apply abs on every element of the container
Returns: a reference to the modified potential. Return type: pyAgrum.Potential
-
add
(Potential self, DiscreteVariable v)¶ Add a discrete variable to the potential.
Parameters: v (pyAgrum.DiscreteVariable) – the var to be added
Raises: DuplicateElement
– If the variable is already in this Potential.InvalidArgument
– If the variable is empty.
-
argmax
(Potential self)¶
-
argmin
(Potential self)¶
-
contains
(Potential self, DiscreteVariable v)¶ Parameters: v (pyAgrum.Potential) – a DiscreteVariable. Returns: True if the var is in the potential Return type: bool
-
draw
(Potential self)¶ draw a value using the potential as a probability table.
Returns: the index of the drawn value Return type: int
-
empty
(Potential self)¶ Returns: Returns true if no variable is in the potential. Return type: bool
-
entropy
(Potential self)¶ Returns: the entropy of the potential Return type: double
-
extract
(Potential self, Instantiation inst)¶ extract(Potential self, PyObject * dict) -> Potential
create a new Potential extracted from self given a partial instantiation.
Parameters: - inst (pyAgrum.instantiation) – a partial instantiation
- dict (dict) – a dictionnary containing discrete variables (?)
Returns: the new Potential
Return type:
-
fill
(v)¶ Deprecated method in pyAgrum>0.12.0. See fillWith instead.
-
fillWith
(Potential self, Potential src)¶ fillWith(Potential self, Potential src, Vector_string mapSrc) -> Potential fillWith(Potential self, Vector v) -> Potential fillWith(Potential self, double v) -> Potential
Automatically fills the potential with v.
Parameters: v (number or list or pyAgrum.Potential the number of parameters of the Potential) – a value or a list/pyAgrum.Potential containing the values to fill the Potential with. Warning
if v is a list, the size of the list must be the if v is a pyAgrum.Potential. It must to contain variables with exactly the same names and labels but not necessarily the same variables.
Returns: a reference to the modified potentia Return type: pyAgrum.Potential Raises: gum.SizeError
– If v size’s does not matches the domain size.
-
findAll
(Potential self, double v)¶
-
get
(Potential self, Instantiation i)¶ Parameters: i (pyAgrum.Instantiation) – an Instantiation Returns: the value in the Potential at the position given by the instantiation Return type: double
-
isNonZeroMap
(Potential self)¶ Returns: a boolean-like potential using the predicate isNonZero Return type: pyAgrum.Potential
-
margMaxIn
(Potential self, PyObject * varnames)¶ Projection using max as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential
-
margMaxOut
(Potential self, PyObject * varnames)¶ Projection using max as operation.
Parameters: varnames (set) – the set of vars to eliminate Returns: the projected Potential Return type: pyAgrum.Potential Raises: gum.InvalidArgument
– If varnames contains only one variable that does not exist in the Potential
-
margMinIn
(Potential self, PyObject * varnames)¶ Projection using min as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential
-
margMinOut
(Potential self, PyObject * varnames)¶ Projection using min as operation.
Parameters: varnames (set) – the set of vars to eliminate Returns: the projected Potential Return type: pyAgrum.Potential Warning
InvalidArgument raised if varnames contains only one variable that does not exist in the Potential
-
margProdIn
(Potential self, PyObject * varnames)¶ Projection using multiplication as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential
-
margProdOut
(Potential self, PyObject * varnames)¶ Projection using multiplication as operation.
Parameters: varnames (set) – the set of vars to eliminate Returns: the projected Potential Return type: pyAgrum.Potential Raises: gum.InvalidArgument
– If varnames contains only one variable that does not exist in the Potential
-
margSumIn
(Potential self, PyObject * varnames)¶ Projection using sum as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential
-
margSumOut
(Potential self, PyObject * varnames)¶ Projection using sum as operation.
Parameters: varnames (set) – the set of vars to eliminate Returns: the projected Potential Return type: pyAgrum.Potential Raises: gum.InvalidArgument
– If varnames contains only one variable that does not exist in the Potential
-
max
(Potential self)¶ Returns: the maximum of all elements in the Potential Return type: double
-
maxNonOne
(Potential self)¶ Returns: the maximum of non one elements in the Potential Return type: double Raises: gum.NotFound
– If all value == 1.0
-
min
(Potential self)¶ Returns: the min of all elements in the Potential Return type: double
-
minNonZero
(Potential self)¶ Returns: the min of non zero elements in the Potential Return type: double Raises: gum.NotFound
– If all value == 0.0
-
nbrDim
(Potential self)¶ Returns: the number of vars in the multidimensional container. Return type: int
-
newFactory
(Potential self)¶ Erase the Potential content and create a new empty one.
Returns: a reference to the new Potential Return type: pyAgrum.Potential
-
normalize
(Potential self)¶ Normalize the Potential (do nothing if sum is 0)
Returns: a reference to the normalized Potential Return type: pyAgrum.Potential
-
normalizeAsCPT
(Potential self)¶ Normalize the Potential as a CPT
Returns: a reference to the normalized Potential Return type: pyAgrum.Potential Raises: gum.FatalError
– If some distribution sums to 0
-
populate
(v)¶ Deprecated method in pyAgrum>0.12.0. See fillWith instead.
-
pos
(Potential self, DiscreteVariable v)¶ Parameters: v (pyAgrum.DiscreteVariable) – The variable for which the index is returned. Returns: Return type: Returns the index of a variable. Raises: gum.NotFound
– If v is not in this multidimensional matrix.
-
product
(Potential self)¶ Returns: the product of all elements in the Potential Return type: double
-
putFirst
(Potential self, PyObject * varname)¶ Parameters: v (pyAgrum.DiscreteVariable) – The variable for which the index should be 0. Returns: a reference to the modified potential Return type: pyAgrum.Potential Raises: gum.InvalidArgument
– If the var is not in the potential
-
remove
(Potential self, DiscreteVariable var)¶ Parameters: v (pyAgrum.DiscreteVariable) – The variable to be removed Returns: a reference to the modified potential Return type: pyAgrum.Potential Warning
IndexError raised if the var is not in the potential
-
reorganize
(Potential self, vector< pyAgrum.DiscreteVariable *, allocator< pyAgrum.DiscreteVariable * > > vars)¶ reorganize(Potential self, PyObject * varnames) -> Potential
Create a new Potential with another order.
Returns: varnames – a list of the var names in the new order Return type: list Returns: a reference to the modified potential Return type: pyAgrum.Potential
-
scale
(Potential self, double v)¶ Create a new potential multiplied by v.
Parameters: v (double) – a multiplier Returns: Return type: a reference to the modified potential
-
set
(Potential self, Instantiation i, double value)¶ Change the value pointed by i
Parameters: - i (pyAgrum.Instantiation) – The Instantiation to be changed
- value (double) – The new value of the Instantiation
-
sq
(Potential self)¶ Square all the values in the Potential
-
sum
(Potential self)¶ Returns: the sum of all elements in the Potential Return type: double
-
toarray
()¶ Returns: the potential as an array Return type: array
-
tolist
()¶ Returns: the potential as a list Return type: list
-
translate
(Potential self, double v)¶ Create a new potential added with v.
Parameters: v (double) – The value to be added Returns: Return type: a reference to the modified potential
-
var_dims
¶ Returns: a list containing the dimensions of each variables in the potential Return type: list
-
var_names
¶ Returns: a list containing the name of each variables in the potential Return type: list Warning
Listed in reverse from the variable enumeration order
-
variable
(Potential self, int i)¶ variable(Potential self, str name) -> DiscreteVariable
Parameters: i (int) – An index of this multidimensional matrix. Returns: Return type: the varible at the ith index Raises: gum.NotFound
– If i does not reference a variable in this multidimensional matrix.
-
variablesSequence
()¶ Returns: a list containing the sequence of variables Return type: list
-