mbdlyb.reasoner
===============

.. py:module:: mbdlyb.reasoner

.. autoapi-nested-parse::

   Abstract base class for diagnostic reasoning engines.

   The MBDReasoner class provides the interface and base functionality for different
   reasoning paradigms (e.g., Bayesian Networks, Markov Networks) used to perform
   probabilistic inference on MBD models.



Attributes
----------

.. autoapisummary::

   mbdlyb.reasoner.T_DISCRETE_BELIEFS
   mbdlyb.reasoner.T_NODE_VALUATION
   mbdlyb.reasoner.T_POSTERIOR
   mbdlyb.reasoner.T_POSTERIORS


Classes
-------

.. autoapisummary::

   mbdlyb.reasoner.MBDReasoner


Module Contents
---------------

.. py:class:: MBDReasoner(net: mbdlyb.MBDNet, **kwargs)

   Bases: :py:obj:`abc.ABC`


   Abstract base class for Model-Based Diagnostic reasoners.

   An MBDReasoner implements the reasoning algorithm for a specific formalism
   (Bayesian networks, Markov networks, etc.) and provides methods for inference,
   evidence management, and information-theoretic queries.

   :ivar _net: The network structure to reason over.
   :vartype _net: MBDNet
   :ivar _evidence: The current evidence for reasoning.
   :vartype _evidence: Evidence
   :ivar _targets: Nodes to be queried during reasoning.

   :vartype _targets: set[MBDNode]


   .. py:method:: add_targets(*targets: mbdlyb.MBDNode, reset=False)

      Add nodes to the target set for inference.

      :param \*targets: Nodes to add as targets.
      :type \*targets: MBDNode
      :param reset: If True, clear existing targets before adding. Default is False.
      :type reset: bool



   .. py:method:: conditional_entropy(y: set[mbdlyb.MBDNode], x: set[mbdlyb.MBDNode], evidence: Optional[mbdlyb.Evidence] = None) -> float
      :abstractmethod:


      Compute conditional entropy H(Y|X) given evidence.

      Measures the uncertainty in Y given X, useful for information-based
      diagnostics and decision-making.

      :param y: The query variables.
      :type y: set[MBDNode]
      :param x: The conditioning variables.
      :type x: set[MBDNode]
      :param evidence: Evidence to condition on. If None, uses the
                       reasoner's current evidence.
      :type evidence: Optional[Evidence]

      :returns: The conditional entropy value.
      :rtype: float



   .. py:method:: drop_targets(*targets: mbdlyb.MBDNode)

      Remove nodes from the target set, or reset to all nodes if no targets specified.

      :param \*targets: Specific nodes to remove from targets. If empty,
                        targets are reset to all flat nodes in the network.
      :type \*targets: MBDNode



   .. py:method:: entropy(y: set[mbdlyb.MBDNode], evidence: Optional[mbdlyb.Evidence] = None) -> float
      :abstractmethod:


      Compute entropy H(Y) given evidence.

      Measures the uncertainty in a set of variables given current evidence,
      useful for assessing confidence in diagnostic conclusions.

      :param y: The variables to compute entropy for.
      :type y: set[MBDNode]
      :param evidence: Evidence to condition on. If None, uses the
                       reasoner's current evidence.
      :type evidence: Optional[Evidence]

      :returns: The entropy value.
      :rtype: float



   .. py:method:: infer(*targets: mbdlyb.MBDNode) -> T_POSTERIORS
      :abstractmethod:


      Perform inference to compute marginal probabilities for target nodes.

      :param \*targets: Nodes to query. If empty, uses the current target set.
      :type \*targets: MBDNode

      :returns: Mapping from target nodes to dictionaries of state->probability distributions.
      :rtype: T_POSTERIORS



   .. py:method:: infer_discrete(*targets: mbdlyb.MBDNode) -> T_DISCRETE_BELIEFS

      Perform inference and return discrete probability distributions.

      :param \*targets: Nodes to query. If empty, uses the current target set.
      :type \*targets: MBDNode

      :returns: Mapping from target nodes to their most probable state.
      :rtype: T_DISCRETE_BELIEFS



   .. py:method:: init()
      :abstractmethod:


      Initialize the reasoner's internal state for a network.

      Called to prepare the reasoner after construction, typically compiling
      the network or building internal data structures.

      Subclasses must implement this to perform formalism-specific initialization.



   .. py:method:: reset()

      Reset the reasoner to initial state, clearing evidence and targets.

      Clears all evidence and sets targets to all flat nodes in the network.



   .. py:property:: evidence
      :type: mbdlyb.Evidence


      Get the current evidence.

      :returns: The evidence container.
      :rtype: Evidence


   .. py:property:: targets
      :type: set[mbdlyb.MBDNode]


      Get the current target nodes for inference.

      :returns: The set of nodes to be queried.
      :rtype: set[MBDNode]


.. py:type:: T_DISCRETE_BELIEFS
   :canonical: dict[MBDNode, Hashable]


   Mapping from nodes to their most probable state.

.. py:type:: T_NODE_VALUATION
   :canonical: tuple[MBDNode, Hashable]


   A node and its assigned value/state.

.. py:type:: T_POSTERIOR
   :canonical: dict[Hashable, float]


   Mapping of a node's state->probability distribution.

.. py:type:: T_POSTERIORS
   :canonical: dict[MBDNode, T_POSTERIOR]


   Mapping from nodes to state->probability distributions