dit.symbolic

Symbolic (sympy-backed) distributions and helpers.

This subpackage lets you build Distribution objects whose probabilities are sympy expressions rather than floats. Information measures (entropy, mutual information, and the multivariate/closed-form family) then return sympy expressions that can be manipulated and simplified exactly.

Example

>>> from dit.symbolic import symbolic_distribution, symbols
>>> from dit.multivariate import total_correlation
>>> p = symbols('p')
>>> d = symbolic_distribution(['00', '11'], [p, 1 - p])
>>> total_correlation(d)
-p*log(p)/log(2) + (p - 1)*log(1 - p)/log(2)

Functions

evaluate

Numerically evaluate a symbolic measure result at a point.

simplify

Simplify a symbolic measure result.

symbolic_distribution

Construct a Distribution with symbolic probabilities.

symbolic_min

Return sympy.Min over args, robust to unsimplified constants.

symbols

Create sympy symbols suitable for use as probabilities.

Reference

evaluate(expr, subs)[source]

Numerically evaluate a symbolic measure result at a point.

This is a robust alternative to expr.subs(subs) for expressions that contain Min/Max (as produced by e.g. I_min/I_mmi or CAEKL). sympy’s Min/Max can raise ValueError (“not comparable”) when a plain .subs leaves unsimplified constant arguments; evaluating through sympy.lambdify() sidesteps that by comparing the arguments numerically.

Parameters:
  • expr (sympy expression or number) – The expression to evaluate (e.g. a measure result).

  • subs (dict) – Mapping of symbols to numeric values.

Returns:

value – The numeric value of expr at subs.

Return type:

float

simplify(expr, **kwargs)[source]

Simplify a symbolic measure result.

A thin wrapper around sympy.simplify() for convenience, so callers need not import sympy directly.

Parameters:
  • expr (sympy expression) – The expression to simplify (e.g. the return value of a measure).

  • **kwargs – Forwarded to sympy.simplify().

Returns:

simplified

Return type:

sympy expression

symbolic_distribution(outcomes, pmf, rv_names=None, validate=True, **kwargs)[source]

Construct a Distribution with symbolic probabilities.

This is a convenience wrapper around Distribution that sympifies the pmf entries so that the resulting distribution stores exact, symbolic probabilities.

Parameters:
  • outcomes (sequence) – The outcomes, as accepted by Distribution (e.g. a list of strings such as ['00', '11']).

  • pmf (sequence) – The probabilities, as numbers and/or sympy expressions. Each entry is passed through sympy.sympify().

  • rv_names (list of str, optional) – Names for each random variable.

  • validate (bool) – If True, validate normalisation after construction. For pmfs containing free symbols normalisation is not decidable and is skipped.

  • **kwargs – Additional keyword arguments forwarded to Distribution.

Returns:

d – A distribution with d.is_symbolic() True.

Return type:

Distribution

symbolic_min(args)[source]

Return sympy.Min over args, robust to unsimplified constants.

sympy.Min raises ValueError when an argument is a constant it cannot immediately decide is comparable (e.g. 2 - log(4)/log(2), which equals 0). Simplifying each argument first resolves such constants while leaving genuinely symbolic arguments intact.

Parameters:

args (iterable of sympy expressions) – The values to minimise over.

Returns:

m – Min of the (simplified) arguments.

Return type:

sympy expression

symbols(names, positive=True, **assumptions)[source]

Create sympy symbols suitable for use as probabilities.

A thin wrapper around sympy.symbols() that defaults to positive=True (appropriate for probabilities, and helpful for simplification).

Parameters:
  • names (str) – Symbol names, e.g. 'p' or 'a b c' (see sympy.symbols()).

  • positive (bool) – Whether the symbols are assumed positive. Defaults to True.

  • **assumptions – Additional sympy assumptions forwarded to sympy.symbols().

Returns:

syms

Return type:

Symbol or tuple of Symbol