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

Available ructors:

`Instantiation() -> Instantiation`

`Instantiation(aI) -> Instantiation`

Parameters: aI (pyAgrum.Instantiation) – The Instantiation we copy 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
`thisown`

The membership flag

`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.

Available ructors:

`Potential() -> Potential`

`Potential(src) -> Potential`

Parameters: src (pyAgrum.Potential) – The Potential to copy The new Potential 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. 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.
`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
`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
`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
`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
`thisown`

The membership flag

`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