mbdlyb.evidence
===============

.. py:module:: mbdlyb.evidence

.. autoapi-nested-parse::

   Evidence management for probabilistic reasoning in MBD models.

   The Evidence class manages observations or sensor readings for nodes in the model,
   supporting both hard evidence (specific state) and soft evidence (probability distributions).



Attributes
----------

.. autoapisummary::

   mbdlyb.evidence.T_NODE_EVIDENCE


Classes
-------

.. autoapisummary::

   mbdlyb.evidence.Evidence


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

.. py:class:: Evidence(evidence: Optional[dict[mbdlyb.MBDNode, T_NODE_EVIDENCE]] = None)

   Container for managing evidence about node states in diagnostic reasoning.

   Evidence stores probability distributions (or hard assignments) for nodes and
   supports callbacks when evidence is added or removed, enabling reactive updates
   in reasoners and other components.

   Evidence can be specified in three formats:
   - String: A single state (hard evidence)
   - Dict: Mapping of state names to probabilities
   - List: Ordered list of probabilities matching node states

   :ivar _evidence: Mapping of nodes to their probability distributions.
   :vartype _evidence: dict[MBDNode, list[float]]
   :ivar _add_cbs: Callbacks invoked when evidence is added.
   :vartype _add_cbs: list[Callable]
   :ivar _drop_cbs: Callbacks invoked when evidence is removed.

   :vartype _drop_cbs: list[Callable]


   .. py:method:: add(evidence: Union[Evidence, dict[mbdlyb.MBDNode, T_NODE_EVIDENCE]])

      Add evidence from another Evidence object or a dictionary.

      Non-empty probability distributions are added to this container. Any
      registered callbacks are invoked with the set of affected nodes.

      :param evidence: Evidence to add,
                       either from another Evidence object or as a dict mapping nodes to evidence.
      :type evidence: Union[Evidence, dict[MBDNode, T_NODE_EVIDENCE]]



   .. py:method:: add_addition_callback(cb: Callable[[set[mbdlyb.MBDNode]], None])

      Register a callback to be invoked when evidence is added.

      :param cb: Callback function taking a set of affected nodes.
      :type cb: Callable[[set[MBDNode]], None]



   .. py:method:: add_drop_callback(cb: Callable[[set[mbdlyb.MBDNode]], None])

      Register a callback to be invoked when evidence is removed.

      :param cb: Callback function taking a set of affected nodes.
      :type cb: Callable[[set[MBDNode]], None]



   .. py:method:: asdict() -> dict[str, list[float]]

      Get evidence as a dictionary mapping node FQN strings to probability lists.

      :returns:

                Dictionary with node FQN strings as keys and
                        probability distributions as values.
      :rtype: dict[str, list[float]]



   .. py:method:: drop(*evs: mbdlyb.MBDNode)

      Remove evidence for specified nodes.

      The nodes are removed from the evidence container and registered callbacks
      are invoked with the affected nodes.

      :param \*evs: Variable number of nodes whose evidence should be removed.
      :type \*evs: MBDNode



   .. py:method:: items()

      Iterate over (node, probabilities) pairs.

      :returns: Yields tuples of (MBDNode, list[float]).
      :rtype: Iterator



   .. py:method:: reset()

      Clear all evidence from this container.

      This does not trigger callbacks.



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


      Get all nodes that have evidence.

      :returns: Set of nodes with evidence.
      :rtype: set[MBDNode]


.. py:type:: T_NODE_EVIDENCE
   :canonical: Union[str, dict[str, float], list[float]]


   state string, state->probability dict, or probability list.

   :type: Type alias for evidence values