scalib.attacks.BPState#

class scalib.attacks.BPState(factor_graph, nexec, public_values=None, gen_factors=None)[source]#

Belief propagation state associated to a FactorGraph.

This is a stateful object on which belief propagation operations can be run. See scalib.attacks.FactorGraph for usage example.

Methods

bp_acyclic(dest, *[, clear_intermediates, ...])

Runs the non-loopy belief propagation algorithm on the current state of the graph.

bp_loopy(it, initialize_states[, clear_beliefs])

Runs belief propagation algorithm on the current state of the graph.

debug()

Debug-print the current state.

drop_distribution(var)

Delete the current distribution of a variable in the BP.

get_belief_from_var(var, factor)

Returns the current belief from var to factor.

get_belief_to_var(var, factor)

Returns the current belief from factor to var.

get_distribution(var)

Returns the current distribution of a variable var.

is_cyclic()

Test is the graph is cyclic.

propagate_factor(factor[, vars])

Run belief propagation on the given factor.

propagate_var(var[, factors, clear_beliefs])

Run belief propagation on variable var.

set_distribution(var, distribution)

Sets current distribution of a variable in the BP.

set_evidence(var, distribution)

Sets prior distribution of a variable.

Attributes

fg

The associated factor graph.
Parameters:

  • factor_graph (FactorGraph) –

  • nexec (int) –

  • public_values (Mapping[str, int | Sequence[int]] | None) –

  • gen_factors (Mapping[str, GenFactor | Sequence[GenFactor]] | None) –

property fg: FactorGraph#

The associated factor graph.

set_evidence(var, distribution)[source]#

Sets prior distribution of a variable.

Parameters:

  • var (str) – Identifier of the variable to assign the distribution to.

  • distribution (numpy.typing.NDArray.numpy.float64 | None) – Distribution to assign. If var is SINGLE, must be of shape (nc,). If var is MULTI, must be of shape (nexec,nc). If None, sets the prior distribution to uniform.

bp_loopy(it, initialize_states, clear_beliefs=True)[source]#

Runs belief propagation algorithm on the current state of the graph.

This is a shortcut for calls to propagate_var() and propagate_factor(). It is equivalent to:

if initialize_states:
    for var in self.fg.vars():
        self.propagate_var(var)
for _ in range(it):
    for factor in self.fg.factors():
        self.propagate_factor(factor)
    for var in self.fg.vars():
        self.propagate_var(var)
Parameters:

  • it (int) – Number of iterations of belief propagation.

  • initialize_states (bool) – Whether to update variable distributions before running the BP iterations. Recommended after using BPState.set_evidence().

  • clear_beliefs (bool) – Whether to clear beliefs between vars -> factors. Setting to False can help debugging. Default value is True.

bp_acyclic(dest, *, clear_intermediates=True, clear_evidence=False)[source]#

Runs the non-loopy belief propagation algorithm on the current state of the graph. This only works if the graph is not cyclic.

Parameters:

  • dest (str) – Variable for which the belief propagation is computed.

  • clear_intermediates (bool) – Drop the intermetidate distributions and beliefs that are computed.

  • clear_evidence (bool) – Drop the evidence for the variables, once used in the algorithm.

get_distribution(var)[source]#

Returns the current distribution of a variable var.

Parameters:

var (string) – Identifier of the variable for which distribution must be returned. Distribution cannot be obtained for public variables.

Returns:

distribution – Distribution of var. If var is SINGLE, distribution has shape (nc). Else, it has shape (n,nc). If the variable has a uniform distribution, None may be returned (but this is not guaranteed).

Return type:

array_like, f64

is_cyclic()[source]#

Test is the graph is cyclic.

Return type:

bool

set_distribution(var, distribution)[source]#

Sets current distribution of a variable in the BP.

Deprecated since version 0.6.1: This method only impacts subsequent calls to get_distribution and does not affect the subsequent behavior of belief propagation, its use is therefore probably incorrect. For dropping state in order to reduce RAM usage, use drop_distribution.

Parameters:

  • var (str) – Identifier of the variable to assign the distribution to.

  • distribution (numpy.typing.NDArray.numpy.float64 | None) – Distribution to assign. If var is SINGLE, must be of shape (nc,). If var is MULTI, must be of shape (nexec,nc). If None, sets the distribution to uniform.

drop_distribution(var)[source]#

Delete the current distribution of a variable in the BP.

This method only impacts subsequent calls to get_distribution and does not affect the subsequent behavior of belief propagation, its main use-case is therefore reducing RAM usage.

Parameters:

var (str) – Identifier of the variable for which the distribution is deleted.

get_belief_to_var(var, factor)[source]#

Returns the current belief from factor to var.

Parameters:

  • var (string) – Identifier of the variable for which distribution must be returned.

  • factor (string) – Identifier of the factor for which distribution must be returned.

Returns:

distribution – Belief on the edge from factor to var. If factor is SINGLE, distribution has shape (nc). Else, it has shape (n,nc). If the belief is a uniform distribution, None may be returned (but this is not guaranteed).

Return type:

array_like, f64

get_belief_from_var(var, factor)[source]#

Returns the current belief from var to factor.

Parameters:

  • var (string) – Identifier of the variable for which distribution must be returned.

  • factor (string) – Identifier of the factor for which distribution must be returned.

Returns:

distribution – Belief on the edge from var to factor. If factor is SINGLE, distribution has shape (nc). Else, it has shape (n,nc). If the belief is a uniform distribution, None may be returned (but this is not guaranteed).

Return type:

array_like, f64

propagate_var(var, factors=None, clear_beliefs=True)[source]#

Run belief propagation on variable var.

This fetches beliefs from adjacent factors, computes the var distribution, and sends updated beliefs to all adjacent factors.

Parameters:

  • var (str) – Identifier of the variable.

  • factors (list[str] | None) – New beliefs are propagated from the variable to these factors. If None, then we propagate to all adjacent factors.

  • clear_beliefs (bool) – Whether to clear beliefs between vars -> factors. Setting to False can help debugging. Default value is True.

propagate_factor(factor, vars=None)[source]#

Run belief propagation on the given factor.

This fetches beliefs from adjacent variables and sends updated beliefs to all adjacent variables.

Parameters:

  • factor (str) – Identifier of the variable.

  • vars (list[str] | None) – New beliefs are propagated from the factor to these variables. If None, then we propagate to all adjacent variables.

debug()[source]#

Debug-print the current state.