mbdlyb.formalisms.tensornet.reasoner
====================================

.. py:module:: mbdlyb.formalisms.tensornet.reasoner

.. autoapi-nested-parse::

   Tensor Network inference engine and reasoning operations.

   This module provides inference capabilities for tensor networks using quimb's
   tensor contraction operations. Includes support for inference, entropy computation,
   and conditional entropy calculations.

   Classes:
       TensorNetReasoner: The main inference engine for tensor networks.



Classes
-------

.. autoapisummary::

   mbdlyb.formalisms.tensornet.reasoner.TensorNetReasoner


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

.. py:class:: TensorNetReasoner(net: mbdlyb.formalisms.tensornet.base.TensorNet, **kwargs)

   Bases: :py:obj:`mbdlyb.MBDReasoner`


   Inference engine for tensor networks.

   Performs inference on tensor networks through contraction operations.
   Computes posterior probability distributions, d-separation relationships,
   entropy, and conditional entropy for probabilistic reasoning.

   :ivar _net: The TensorNet instance being reasoned over.
   :ivar _tn: The underlying quimb TensorNetwork structure.



   .. py:method:: add_evidence_to_tn(nodes: set[mbdlyb.MBDNode])

      Add evidence tensors to the network.

      For each node with evidence, creates a tensor representing the evidence
      likelihood and adds it to the tensor network.

      :param nodes: Set of nodes with new evidence to be added.



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

      Compute the conditional entropy H(Y|X).

      Calculates the entropy of variable set y given variable set x by
      contracting the tensor network and computing the Shannon entropy.

      Note: Evidence integration is not yet fully implemented.

      :param y: The set of nodes for which to compute entropy.
      :param x: The conditioning variable set.
      :param evidence: Optional evidence (currently not fully integrated).

      :returns: The conditional entropy H(Y|X) in bits.



   .. py:method:: drop_evidence_from_tn(evs: set[mbdlyb.MBDNode])

      Remove evidence tensors from the network.

      Removes tensors representing evidence that has been dropped from the
      reasoner.

      :param evs: Set of nodes whose evidence should be removed.



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

      Compute the entropy H(Y) of a set of nodes.

      Calculates the Shannon entropy of the joint distribution of a set of
      variables by contracting the tensor network.

      Note: Evidence integration is not yet fully implemented.

      :param y: The set of nodes for which to compute entropy.
      :param evidence: Optional evidence (currently not fully integrated).

      :returns: The entropy H(Y) in bits.



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

      Perform inference on target nodes given current evidence.

      Computes the posterior probability distributions for the specified target
      nodes by contracting the tensor network.

      :param \*targets: One or more MBDNode instances to compute posteriors for.

      :returns: A dictionary mapping each target node to a dictionary of its states
                and their posterior probabilities.



   .. py:method:: init()

      Initialize the inference engine.

      Converts the abstract tensor network to a quimb TensorNetwork and registers
      evidence update callbacks for maintaining consistency during inference.



   .. py:method:: is_d_separated(y: Union[mbdlyb.MBDNode, set[mbdlyb.MBDNode]], x: Union[mbdlyb.MBDNode, set[mbdlyb.MBDNode]], z: Optional[mbdlyb.Evidence] = None)
      :abstractmethod:


      Test d-separation between two sets of nodes.

      Note: This operation is not applicable to general tensor networks.
      D-separation is a concept specific to directed acyclic graphs (DAGs).

      :param y: A node or set of nodes to test for independence.
      :param x: A node or set of nodes to test for independence.
      :param z: An optional conditioning set (unused for tensor networks).

      :raises NotImplementedError: D-separation is not defined for tensor networks.