Potentials and Instantiation¶
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
(self, 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
(self, v, newval)¶ chgVal(self, v, newval) > Instantiation chgVal(self, varPos, newval) > Instantiation chgVal(self, var, newval) > Instantiation chgVal(self, var, 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
(self)¶ Erase all variables from an Instantiation.

contains
(self, v)¶ contains(self, 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
(self)¶ Operator –.

decIn
(self, i)¶ Operator – for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to decrement in this Instantiation

decNotVar
(self, v)¶ Operator – for vars which are not v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable not to decrement in this Instantiation.

decOut
(self, i)¶ Operator – for the variables not in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to not decrement in this Instantiation.

decVar
(self, 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
(self)¶ Returns: The product of the variable’s domain size in the Instantiation. Return type: int

empty
(self)¶ Returns: True if the instantiation is empty. Return type: bool

end
(self)¶ Returns: True if the Instantiation reached the end. Return type: bool

erase
(self, v)¶ Parameters: v (pyAgrum.DiscreteVariable) – The variable to be removed from this Instantiation. Raises: NotFound
– If v does not belong to this Instantiation.

fromdict
(self, 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
(self)¶ Returns: the hamming distance of this instantiation. Return type: int

inOverflow
(self)¶ Returns: True if the current value of the tuple is correct Return type: bool

inc
(self)¶ Operator ++.

incIn
(self, i)¶ Operator ++ for the variables in i.
Parameters: i (pyAgrum.Instantiation) – The set of variables to increment in this Instantiation.

incNotVar
(self, v)¶ Operator ++ for vars which are not v.
Parameters: v (pyAgrum.DiscreteVariable) – The variable not to increment in this Instantiation.

incOut
(self, i)¶ Operator ++ for the variables not in i.
Parameters: i (Instantiation) – The set of variable to not increment in this Instantiation.

incVar
(self, 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
(self)¶ Returns: The number of variables in the Instantiation. Return type: int

pos
(self, 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
(self)¶ Returns: True if the Instantiation reached the rend. Return type: bool

reorder
(self, v)¶ reorder(self, 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
(self)¶ Assign the first values to the tuple of the Instantiation.

setFirstIn
(self, 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
(self, 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
(self, 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
(self, 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
(self)¶ Assign the last values in the Instantiation.

setLastIn
(self, 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
(self, 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
(self, 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
(self, 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
(self, 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
(self, withLabels=False)¶ todict(self) > PyObject *
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
(self)¶ Alias for unsetOverflow().

unsetOverflow
(self)¶ Removes the flag overflow.

val
(self, i)¶ val(self, 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
(self, i)¶ variable(self, 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
(self)¶ Returns: the sequence of DiscreteVariable of this instantiation. Return type: List
Potential¶

pyAgrum.
Potential
¶ alias of
pyAgrum.pyAgrum.Potential_double

class
pyAgrum.pyAgrum.
Potential_double
(*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
(self, p)¶ C heck the compatibility and compute the KullbackLeibler 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
(self)¶ Apply abs on every element of the container
Returns: a reference to the modified potential. Return type: pyAgrum.Potential

add
(self, v)¶ Add a discrete variable to the potential.
Parameters: v (pyAgrum.DiscreteVariable) – the var to be added Raises: gum.Error
– If DiscretizedVariable added with no Tick.

argmax
(self)¶

argmin
(self)¶

contains
(self, v)¶ Parameters: v (pyAgrum.Potential) – a DiscreteVariable. Returns: True if the var is in the potential Return type: bool

draw
(self)¶ draw a value using the potential as a probability table.
Returns: the index of the drawn value Return type: int

empty
(self)¶ Returns: Returns true if no variable is in the potential. Return type: bool

entropy
(self)¶ Returns: the entropy of the potential Return type: double

extract
(self, inst)¶ extract(self, 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: pyAgrum.Potential

fill
(v)¶ Deprecated method in pyAgrum>0.12.0. See fillWith instead.

fillWith
(self, src)¶ fillWith(self, src, mapSrc) > Potential fillWith(self, v) > Potential fillWith(self, v) > Potential

findAll
(self, v)¶

get
(self, i)¶ Parameters: i (pyAgrum.Instantiation) – an Instantiation Returns: the value of the instantiation Return type: double

isNonZeroMap
(self)¶ Returns: a booleanlike potential using the predicate isNonZero Return type: pyAgrum.Potential

margMaxIn
(self, varnames)¶ Projection using max as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential

margMaxOut
(self, 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
(self, varnames)¶ Projection using min as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential

margMinOut
(self, 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
(self, varnames)¶ Projection using multiplication as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential

margProdOut
(self, 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
(self, varnames)¶ Projection using sum as operation.
Parameters: varnames (set) – the set of vars to keep Returns: the projected Potential Return type: pyAgrum.Potential

margSumOut
(self, 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
(self)¶ Returns: the maximum of all elements in the Potential Return type: double

maxNonOne
(self)¶ Returns: the maximum of non one elements in the Potential Return type: double Raises: gum.NotFound
– If all value == 1.0

min
(self)¶ Returns: the min of all elements in the Potential Return type: double

minNonZero
(self)¶ Returns: the min of non zero elements in the Potential Return type: double Raises: gum.NotFound
– If all value == 0.0

nbrDim
(self)¶ Returns: the number of vars in the multidimensional container. Return type: int

newFactory
(self)¶ Erase the Potential content and create a new empty one.
Returns: a reference to the new Potential Return type: pyAgrum.Potential

normalize
(self)¶ Normalize the Potential (do nothing if sum is 0)
Returns: a reference to the normalized Potential Return type: pyAgrum.Potential

normalizeAsCPT
(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

pos
(self, 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
(self)¶ Returns: the product of all elements in the Potential Return type: double

putFirst
(self, 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
(self, 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
(self, vars)¶ reorganize(self, 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
(self, v)¶ Create a new potential multiplied by v.
Parameters: v (double) – a multiplier Returns: Return type: a reference to the modified potential

set
(self, i, 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
(self)¶ Square all the values in the Potential

sum
(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
(self, 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

variable
(self, i)¶ variable(self, 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
