:py:mod:`quimb.experimental.belief_propagation.d1bp`
====================================================

.. py:module:: quimb.experimental.belief_propagation.d1bp

.. autoapi-nested-parse::

   Belief propagation for standard tensor networks. This:

   - assumes no hyper indices, only standard bonds.
   - assumes a single ('dense') tensor per site
   - works directly on the '1-norm' i.e. scalar tensor network

   This is the simplest version of belief propagation, and is useful for
   simple investigations.



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

Classes
~~~~~~~

.. autoapisummary::

   quimb.experimental.belief_propagation.d1bp.D1BP



Functions
~~~~~~~~~

.. autoapisummary::

   quimb.experimental.belief_propagation.d1bp.initialize_messages
   quimb.experimental.belief_propagation.d1bp.contract_d1bp



.. py:function:: initialize_messages(tn, fill_fn=None)


.. py:class:: D1BP(tn, messages=None, damping=0.0, update='sequential', local_convergence=True, message_init_function=None)


   Bases: :py:obj:`quimb.experimental.belief_propagation.bp_common.BeliefPropagationCommon`

   Dense (as in one tensor per site) 1-norm (as in for 'classical' systems)
   belief propagation algorithm. Allows message reuse. This version assumes no
   hyper indices (i.e. a standard tensor network). This is the simplest
   version of belief propagation.

   :param tn: The tensor network to run BP on.
   :type tn: TensorNetwork
   :param messages: The initial messages to use, effectively defaults to all ones if not
                    specified.
   :type messages: dict[(str, int), array_like], optional
   :param damping: The damping factor to use, 0.0 means no damping.
   :type damping: float, optional
   :param update: Whether to update messages sequentially or in parallel.
   :type update: {'sequential', 'parallel'}, optional
   :param local_convergence: Whether to allow messages to locally converge - i.e. if all their
                             input messages have converged then stop updating them.
   :type local_convergence: bool, optional
   :param fill_fn: If specified, use this function to fill in the initial messages.
   :type fill_fn: callable, optional

   .. attribute:: tn

      The target tensor network.

      :type: TensorNetwork

   .. attribute:: messages

      The current messages. The key is a tuple of the index and tensor id
      that the message is being sent to.

      :type: dict[(str, int), array_like]

   .. attribute:: key_pairs

      A dictionary mapping the key of a message to the key of the message
      propagating in the opposite direction.

      :type: dict[(str, int), (str, int)]

   .. py:method:: iterate(tol=5e-06)


   .. py:method:: normalize_messages()

      Normalize all messages such that for each bond `<m_i|m_j> = 1` and
      `<m_i|m_i> = <m_j|m_j>` (but in general != 1).


   .. py:method:: get_gauged_tn()

      Gauge the original TN by inserting the BP-approximated transfer
      matrix eigenvectors, which may be complex. The BP-contraction of this
      gauged network is then simply the product of zeroth entries of each
      tensor.


   .. py:method:: contract(strip_exponent=False)



.. py:function:: contract_d1bp(tn, max_iterations=1000, tol=5e-06, damping=0.0, update='sequential', local_convergence=True, strip_exponent=False, info=None, progbar=False, **contract_opts)

   Estimate the contraction of standard tensor network ``tn`` using dense
   1-norm belief propagation.

   :param tn: The tensor network to contract, it should have no dangling or hyper
              indices.
   :type tn: TensorNetwork
   :param max_iterations: The maximum number of iterations to run for.
   :type max_iterations: int, optional
   :param tol: The convergence tolerance for messages.
   :type tol: float, optional
   :param damping: The damping parameter to use, defaults to no damping.
   :type damping: float, optional
   :param update: Whether to update messages sequentially or in parallel.
   :type update: {'sequential', 'parallel'}, optional
   :param local_convergence: Whether to allow messages to locally converge - i.e. if all their
                             input messages have converged then stop updating them.
   :type local_convergence: bool, optional
   :param strip_exponent: Whether to strip the exponent from the final result. If ``True``
                          then the returned result is ``(mantissa, exponent)``.
   :type strip_exponent: bool, optional
   :param info: If specified, update this dictionary with information about the
                belief propagation run.
   :type info: dict, optional
   :param progbar: Whether to show a progress bar.
   :type progbar: bool, optional