# 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)
>>> 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

>>> 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 provides Instantiation 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

>>> c=gum.RangeVariable("C","variable C",1,5)
>>> 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.

Instantiation() -> Instantiation
default constructor
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 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) The modified instantiation pyAgrum.Instantiation 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. True if the variable is in the Instantiation. 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. 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. int
empty(Instantiation self)
Returns: True if the instantiation is empty. bool
end(Instantiation self)
Returns: True if the Instantiation reached the end. bool
erase(Instantiation self, DiscreteVariable v)
Parameters: v (pyAgrum.DiscreteVariable) – The variable to be removed from this Instantiation. 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. int
inOverflow(Instantiation self)
Returns: True if the current value of the tuple is correct 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. NotFound – If variable v does not belong to the Instantiation.
nbrDim(Instantiation self)
Returns: The number of variables in the Instantiation. int
pos(Instantiation self, DiscreteVariable v)
Returns: the position of the variable v. int v (pyAgrum.DiscreteVariable) – the variable for which its position is return. NotFound – If v does not belong to the instantiation.
rend(Instantiation self)
Returns: True if the Instantiation reached the rend. 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 a reference to the instantiation 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. The dictionary 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 the current value of the variable. int 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 the variable at position i in the tuple. pyAgrum.DiscreteVariable NotFound – If the element cannot be found.
variablesSequence(Instantiation self)
Returns: the sequence of DiscreteVariable of this instantiation. List

## Potential¶

class pyAgrum.Potential(*args)

Class representing a potential.

Potential() -> Potential
default constructor
Potential(src) -> Potential
Parameters:
• src (pyAgrum.Potential) – the Potential to copy
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. The value of the divergence float 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. pyAgrum.Potential
add(Potential self, DiscreteVariable v)

Add a discrete variable to the potential.

Parameters: v (pyAgrum.DiscreteVariable) – the var to be added 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. True if the var is in the potential bool
draw(Potential self)

draw a value using the potential as a probability table.

Returns: the index of the drawn value int
empty(Potential self)
Returns: Returns true if no variable is in the potential. bool
entropy(Potential self)
Returns: the entropy of the potential 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 (?) the new Potential pyAgrum.Potential
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 pyAgrum.Potential gum.SizeError – If v size’s does not matches the domain size.
fillWithFunction(s, noise=None)

Automatically fills the potential as a (quasi) deterministic CPT with the evaluation of the expression s.

The expression s gives a value for the first variable using the names of the last variables. The computed CPT is deterministic unless noise is used to add a ‘probabilistic’ noise around the exact value given by the expression.

Examples

>>> import pyAgrum as gum
>>> bn=gum.fastBN("A->B<-C")
>>> bn.cpt("B").fillWithFunction("(A+C)/2")

Parameters: s (str) – an expression using the name of the last variables of the Potential and giving a value to the first variable of the Potential noise (list) – an (odd) list of numerics giving a pattern of ‘probabilistic noise’ around the value.

Warning

The expression may have any numerical values, but will be then transformed to the closest correct value for the range of the variable.

Returns: a reference to the modified potential pyAgrum.Potential gum.InvalidArgument – If the first variable is Labelized or if the len of the noise is not odd.
findAll(Potential self, double v)
get(Potential self, Instantiation i)
Parameters: i (pyAgrum.Instantiation) – an Instantiation the value in the Potential at the position given by the instantiation double
isNonZeroMap(Potential self)
Returns: a boolean-like potential using the predicate isNonZero pyAgrum.Potential
margMaxIn(Potential self, PyObject * varnames)

Projection using max as operation.

Parameters: varnames (set) – the set of vars to keep the projected Potential pyAgrum.Potential
margMaxOut(Potential self, PyObject * varnames)

Projection using max as operation.

Parameters: varnames (set) – the set of vars to eliminate the projected Potential pyAgrum.Potential 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 the projected Potential pyAgrum.Potential
margMinOut(Potential self, PyObject * varnames)

Projection using min as operation.

Parameters: varnames (set) – the set of vars to eliminate the projected Potential 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 the projected Potential pyAgrum.Potential
margProdOut(Potential self, PyObject * varnames)

Projection using multiplication as operation.

Parameters: varnames (set) – the set of vars to eliminate the projected Potential pyAgrum.Potential 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 the projected Potential pyAgrum.Potential
margSumOut(Potential self, PyObject * varnames)

Projection using sum as operation.

Parameters: varnames (set) – the set of vars to eliminate the projected Potential pyAgrum.Potential 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 double
maxNonOne(Potential self)
Returns: the maximum of non one elements in the Potential double gum.NotFound – If all value == 1.0
min(Potential self)
Returns: the min of all elements in the Potential double
minNonZero(Potential self)
Returns: the min of non zero elements in the Potential double gum.NotFound – If all value == 0.0
nbrDim(Potential self)
Returns: the number of vars in the multidimensional container. int
newFactory(Potential self)

Erase the Potential content and create a new empty one.

Returns: a reference to the new Potential pyAgrum.Potential
noising(Potential self, double alpha)
normalize(Potential self)

Normalize the Potential (do nothing if sum is 0)

Returns: a reference to the normalized Potential pyAgrum.Potential
normalizeAsCPT(Potential self)

Normalize the Potential as a CPT

Returns: a reference to the normalized Potential pyAgrum.Potential 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 the index of a variable. gum.NotFound – If v is not in this multidimensional matrix.
product(Potential self)
Returns: the product of all elements in the Potential double
putFirst(Potential self, PyObject * varname)
Parameters: v (pyAgrum.DiscreteVariable) – The variable for which the index should be 0. a reference to the modified potential pyAgrum.Potential gum.InvalidArgument – If the var is not in the potential
random(Potential self)
randomCPT(Potential self)
randomDistribution(Potential self)
remove(Potential self, DiscreteVariable var)
Parameters: v (pyAgrum.DiscreteVariable) – The variable to be removed a reference to the modified potential 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 list a reference to the modified potential pyAgrum.Potential
scale(Potential self, double v)

Create a new potential multiplied by v.

Parameters: v (double) – a multiplier 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 double
toarray()
Returns: the potential as an array array
tolist()
Returns: the potential as a list list
translate(Potential self, double v)

Create a new potential added with v.

Parameters: v (double) – The value to be added a reference to the modified potential
var_dims
Returns: a list containing the dimensions of each variables in the potential list
var_names
Returns: a list containing the name of each variables in the potential 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. the varible at the ith index gum.NotFound – If i does not reference a variable in this multidimensional matrix.
variablesSequence()
Returns: a list containing the sequence of variables list