:py:mod:`cotengra.experimental.path_compressed_branchbound`
===========================================================

.. py:module:: cotengra.experimental.path_compressed_branchbound

.. autoapi-nested-parse::

   Compressed contraction path finding using branch and bound.



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

Classes
~~~~~~~

.. autoapisummary::

   cotengra.experimental.path_compressed_branchbound.CompressedExhaustive
   cotengra.experimental.path_compressed_branchbound.CompressedTreeRefiner



Functions
~~~~~~~~~

.. autoapisummary::

   cotengra.experimental.path_compressed_branchbound.do_reconfigure



.. py:class:: CompressedExhaustive(minimize, max_nodes=float('inf'), max_time=None, local_score=None, exploration_power=0.0, best_score=None, progbar=False)


   Exhaustively search all possible contraction orders for a given
   compressed bond dimension, using several forms of pruning and local
   hueristics to accelerate the search.

   :param chi: The max bond dimension of the compressed hypergraph.
   :type chi: int
   :param max_nodes: Set the maximum number of contraction steps to consider.
   :type max_nodes: int, optional
   :param max_time: Set the maximum time to spend on the search.
   :type max_time: float, optional
   :param local_score: A function that assigns a score to a potential contraction, with a
                       lower score giving more priority to explore that contraction earlier.
                       It should have signature::

                           local_score(step : int, tracker: CompressedStatsTracker) -> float

                       where ``step`` is the number of steps so far, ``tracker`` is a
                       `CompressedStatsTracker` object that tracks various properties
                       like flops and peak size.
   :type local_score: callable, optional
   :param exploration_power: If not ``0.0``, the inverse power to which the step is raised in the
                             default local score function. Higher values favor exploring more
                             promising branches early on - at the cost of increased memory. Ignored
                             if ``local_score`` is supplied.
   :type exploration_power: float, optional
   :param best_score: Manually specify an upper bound for best score found so far.
   :type best_score: float, optional
   :param progbar: If ``True``, display a progress bar.
   :type progbar: bool, optional

   .. py:property:: ssa_path


   .. py:property:: path


   .. py:method:: setup(inputs, output, size_dict)

      Set-up the optimizer with a specific contraction.


   .. py:method:: expand_node(i, j, hg, tree_map, ssa_path, tracker, high_priority=False)

      Given a current contraction node, expand it by contracting nodes
      ``i`` and ``j``.

      :param i: The nodes to contract.
      :type i: int
      :param j: The nodes to contract.
      :type j: int
      :param hg: The hypergraph to contract.
      :type hg: Hypergraph
      :param ssa_path: The contraction path so far.
      :type ssa_path: list
      :param tracker: Scoring object that tracks costs of current compressed contraction.
      :type tracker: CompressedStatsTracker
      :param high_priority: If True, the contraction will be assessed before any other normal
                            contractions.
      :type high_priority: bool, optional

      :returns: The contraction index, or None if the contraction is guaranteed to
                be worse than another contraction.
      :rtype: int or None


   .. py:method:: _update_progbar(pbar, c)


   .. py:method:: run(inputs, output, size_dict)


   .. py:method:: explore_path(path, high_priority=True, restrict=False)

      Explicitly supply a path to be added to the search space, by default
      it is added to the priority queue and will be processed first.

      :param path: A contraction path to explore.
      :type path: sequence[tuple[int]]
      :param high_priority: If ``True``, the path will be assessed before anything else,
                            regardless of cost - the default.
      :type high_priority: bool, optional
      :param restrict: If ``True``, only allow contractions in this path, so only the
                       order will be optimized.
      :type restrict: bool, optional


   .. py:method:: search(inputs, output, size_dict)

      Run and return the best ``ContractionTreeCompressed``.


   .. py:method:: __call__(inputs, output, size_dict)

      Run and return the best ``path``.



.. py:function:: do_reconfigure(tree, time, chi)


.. py:class:: CompressedTreeRefiner(trees, copt, chi, max_refine_time=8, executor=None, pre_dispatch=8, progbar=False, plot=False)


   .. py:method:: _check_score(key, tree, score=None)


   .. py:method:: _get_next_tree()


   .. py:method:: _get_next_result_seq()


   .. py:method:: _get_next_result_par(max_futures)


   .. py:method:: _process_result(tree, key, time, old, new)


   .. py:method:: refine(num_its=None, bins=30)