mbdlyb.formulae

Formula evaluation and conditional probability table (CPT) generation.

This module provides classes for evaluating mathematical formulas and using them to compute conditional probability tables for Bayesian network nodes. It includes support for algebraic expressions, variable mappings, and formula serialization.

The module defines: - Formula: Represents and evaluates mathematical expressions - Evaluable: Abstract base for evaluable objects - EvaluableNode: MBD node with evaluable behavior - EvaluableCPTNode: Evaluable node with CPT computation - FormulaEnabledNode: Node with formula-based evaluation - FormulaCPTNode: Full-featured node combining all functionality

Attributes

`T_FORMULA`
`T_RAW_FORMULA`

Classes

`Evaluable`	Abstract base class for evaluable objects.
`EvaluableCPTNode`	Node that computes conditional probability tables from evaluable expressions.
`EvaluableNode`	MBD node with evaluable expression capability.
`Formula`	Mathematical formula for numerical evaluation.
`FormulaCPTNode`	Complete node implementation combining formula evaluation with CPT computation.
`FormulaEnabledNode`	Node with formula-based evaluation capability.

Functions

create_mapping(→ dict[str, str])

Create a mapping from parent names to variable identifiers.

Module Contents

class mbdlyb.formulae.Evaluable[T, S]

Bases: abc.ABC

Abstract base class for evaluable objects.

Defines the interface for objects that can be prepared with node context and then evaluated to produce values.

Type parameters:: T: The type of values produced by evaluation. S: The type of keys used in value dictionaries.

abstractmethod evaluate(values: dict[S, T]) → T

Evaluate the expression with the given values.

Parameters:: values – Dictionary mapping variable names/keys to their values.
Returns:: The result of evaluating the expression.

prepare(node: mbdlyb.MBDNode, parents: list[mbdlyb.MBDNode], **kwargs)

Prepare the evaluable for use with a specific node and parents.

Parameters:

node – The MBD node this evaluable is associated with.
parents – List of parent nodes that serve as inputs to evaluation.
**kwargs – Additional keyword arguments for subclass-specific preparation.

class mbdlyb.formulae.EvaluableCPTNode[T](name: str, states: list[T], net: MBDNet)

Bases: mbdlyb.formalisms.base.CPTEnabledNode[T], EvaluableNode[T], abc.ABC

Node that computes conditional probability tables from evaluable expressions.

Combines CPT computation with evaluable expressions to dynamically generate probability distributions based on formulas or other evaluable objects.

This class overrides CPT computation to delegate to evaluable objects when they are available.

class mbdlyb.formulae.EvaluableNode[T](name: str, states: list[T], net: MBDNet)

Bases: mbdlyb.MBDNode[T]

MBD node with evaluable expression capability.

Extends MBDNode to support expressions that can be evaluated to produce node values. This is the base for formula-based and other evaluable nodes.

Variables:: evaluable – The Evaluable object used to compute node values.

evaluable: Evaluable = None

class mbdlyb.formulae.Formula(formula: T_RAW_FORMULA, mapping: dict[mbdlyb.fqn.FQN, str] = None)

Bases: Evaluable[mbdlyb.T_NUMERICAL]

Mathematical formula for numerical evaluation.

Represents and evaluates mathematical expressions with support for variables, mapping, and algebraic operations. Can store simple numeric values or complex formulas that reference parent node values.

Variables:

_elementary – True if formula is a simple numeric value.
_formula – The formula string or numeric value.
mapping – Dictionary mapping parent FQNs to variable names used in formulas.

static create(f: T_FORMULA = None) → Formula | None

Create a Formula from a value.

Factory method that converts raw formula values to Formula objects or passes through existing Formula instances.

Parameters:: f – A formula value (string, int, float) or existing Formula object. Can be None.
Returns:: A Formula object, or None if the input is None.

evaluate(values: dict[str, mbdlyb.T_NUMERICAL]) → mbdlyb.T_NUMERICAL

Evaluate the formula with given values.

For elementary formulas, returns the constant value. For complex formulas, evaluates the expression with variable values.

Parameters:: values – Dictionary mapping variable names to their numerical values.
Returns:: The numerical result of evaluating the formula.

classmethod from_json(s: str | dict | None) → Formula | None

Deserialize a formula from JSON format.

Parameters:: s – JSON string or dictionary representation of a formula. Can be None.
Returns:: Deserialized Formula object, or None if input is None.

prepare(node: mbdlyb.MBDNode, parents: list[mbdlyb.MBDNode], overwrite: bool = False)

Prepare the formula for use with a specific node.

Creates or validates the mapping between parent nodes and formula variables.

Parameters:

node – The node this formula is assigned to.
parents – List of parent nodes for this formula.
overwrite – If True, allows overwriting existing mappings. If False, raises an error if the mapping is inconsistent with existing data.

Raises:

RuntimeError – If mapping already exists and doesn’t match the new parents, and overwrite is False.

to_json() → str

Serialize the formula to JSON format.

Returns:: JSON string representation containing the formula value and mapping.

property formula: T_RAW_FORMULA

Get the formula value or expression.

Returns:: The stored formula as a string or float value.

property is_elementary: bool

Check if this formula is a simple numeric value.

Returns:: True if the formula is a numeric constant rather than an expression.

mapping: dict[mbdlyb.fqn.FQN, str]

property rev_mapping: dict[str, mbdlyb.fqn.FQN]

Get the reverse mapping from variable names to parent FQNs.

Returns:: Dictionary mapping variable names back to their parent FQNs.

class mbdlyb.formulae.FormulaCPTNode[T](name: str, states: list[T_NUMERICAL | tuple[T_NUMERICAL, str]], net: MBDNet)

Bases: mbdlyb.MBDNumericalNode, EvaluableCPTNode[T], FormulaEnabledNode[T], abc.ABC

Complete node implementation combining formula evaluation with CPT computation.

Integrates formula-based evaluation, numerical node properties, and CPT-enabled functionality into a cohesive node type that can compute probability distributions from algebraic expressions.

This is the primary node type for formula-based probabilistic reasoning.

class mbdlyb.formulae.FormulaEnabledNode[T](name: str, states: list[T], net: MBDNet)

Bases: EvaluableNode[T]

Node with formula-based evaluation capability.

Specializes EvaluableNode to work specifically with Formula objects, providing convenience properties and methods for formula management.

Variables:: evaluable – A Formula object that defines the node’s computation.

evaluable: Formula = None

property formula: Formula | None

Get the formula assigned to this node.

Returns:: The Formula object or None if no formula is assigned.

mbdlyb.formulae.create_mapping(parents: dict[str, str]) → dict[str, str]

Create a mapping from parent names to variable identifiers.

Maps parent fully qualified names to single-character variable names (A, B, C, etc.) if the original names would create duplicate keys. Otherwise returns the original mapping.

Parameters:: parents – Dictionary mapping FQN strings to parent names.
Returns:: Dictionary mapping parent names to variable identifiers. If all values are unique, returns the original mapping; otherwise returns mapping to single letters.

type mbdlyb.formulae.T_FORMULA = T_RAW_FORMULA | 'Formula'

type mbdlyb.formulae.T_RAW_FORMULA = str | float | int