cotengra.reusable
=================

.. py:module:: cotengra.reusable


Classes
-------

.. autoapisummary::

   cotengra.reusable.ReusableOptimizer


Functions
---------

.. autoapisummary::

   cotengra.reusable.sortedtuple
   cotengra.reusable.make_hashable
   cotengra.reusable.hash_contraction_a
   cotengra.reusable.hash_contraction_b
   cotengra.reusable.hash_contraction


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

.. py:function:: sortedtuple(x)

.. py:function:: make_hashable(x)

   Make ``x`` hashable by recursively turning list into tuples and dicts
   into sorted tuples of key-value pairs.


.. py:function:: hash_contraction_a(inputs, output, size_dict)

.. py:function:: hash_contraction_b(inputs, output, size_dict)

.. py:function:: hash_contraction(inputs, output, size_dict, method='a')

   Compute a hash for a particular contraction geometry.


.. py:class:: ReusableOptimizer(*, directory=None, overwrite=False, hash_method='a', cache_only=False, directory_split='auto', **opt_kwargs)

   Bases: :py:obj:`cotengra.oe.PathOptimizer`


   Mixin class for optimizers that can be reused, caching the paths
   and other relevant information for reconstructing the full tree.

   The following methods should be implemented in the subclass:

       _get_path_relevant_opts(self)
       _get_suboptimizer(self)
       _deconstruct_tree(self, opt, tree)
       _reconstruct_tree(self, inputs, output, size_dict, con)

   :param directory: If specified use this directory as a persistent cache. If ``True`` auto
                     generate a directory in the current working directory based on the
                     options which are most likely to affect the path (see
                     `ReusableHyperOptimizer._get_path_relevant_opts`).
   :type directory: None, True, or str, optional
   :param overwrite: If ``True``, the optimizer will always run, overwriting old results in
                     the cache. This can be used to update paths without deleting the whole
                     cache. If ``'improved'`` then only overwrite if the new path is better.
   :type overwrite: bool or 'improved', optional
   :param hash_method: The method used to hash the contraction tree. The default, ``'a'``, is
                       faster hashwise but doesn't recognize when indices are permuted.
   :type hash_method: {'a', 'b', ...}, optional
   :param cache_only: If ``True``, the optimizer will only use the cache, and will raise
                      ``KeyError`` if a contraction is not found.
   :type cache_only: bool, optional
   :param directory_split: If specified, the hash will be split into two parts, the first part
                           will be used as a subdirectory, and the second part will be used as the
                           filename. This is useful for avoiding a very large flat diretory. If
                           "auto" it will check the current cache if any and guess from that.
   :type directory_split: "auto" or bool, optional
   :param opt_kwargs: Supplied to ``self._get_suboptimizer(self)``.


   .. py:attribute:: _suboptimizers


   .. py:attribute:: _suboptimizer_kwargs


   .. py:attribute:: _cache


   .. py:attribute:: overwrite
      :value: False



   .. py:attribute:: _hash_method
      :value: 'a'



   .. py:attribute:: cache_only
      :value: False



   .. py:attribute:: directory_split
      :value: 'auto'



   .. py:property:: last_opt


   .. py:method:: _get_path_relevant_opts()
      :abstractmethod:


      We only want to hash on options that affect the contraction, not
      things like `progbar`.



   .. py:method:: auto_hash_path_relevant_opts()

      Automatically hash the path relevant options used to create the
      optimizer.



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

      Hash the contraction specification, returning this and whether the
      contraction is already present as a tuple.



   .. py:property:: minimize


   .. py:method:: update_from_tree(tree, overwrite='improved')

      Explicitly add the contraction that ``tree`` represents into the
      cache. For example, if you have manually improved it via reconfing.
      If ``overwrite=False`` and the contracton is present already then do
      nothing. If ``overwrite='improved'`` then only overwrite if the new
      path is better. If ``overwrite=True`` then always overwrite.

      :param tree: The tree to add to the cache.
      :type tree: ContractionTree
      :param overwrite: If ``True`` always overwrite, if ``False`` only overwrite if the
                        contraction is missing, if ``'improved'`` only overwrite if the new
                        path is better (the default). Note that the comparison of scores
                        is based on default objective of the tree.
      :type overwrite: bool or "improved", optional



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


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


   .. py:method:: __call__(inputs, output, size_dict, memory_limit=None)


   .. py:method:: _get_suboptimizer()
      :abstractmethod:



   .. py:method:: _deconstruct_tree(opt, tree)
      :abstractmethod:



   .. py:method:: _reconstruct_tree(inputs, output, size_dict, con)
      :abstractmethod:



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


   .. py:method:: cleanup()