:py:mod:`cotengra.slicer`
=========================

.. py:module:: cotengra.slicer

.. autoapi-nested-parse::

   Functionality for identifying indices to sliced.



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

Classes
~~~~~~~

.. autoapisummary::

   cotengra.slicer.ContractionCosts
   cotengra.slicer.SliceFinder




Attributes
~~~~~~~~~~

.. autoapisummary::

   cotengra.slicer.IDX_INVOLVED
   cotengra.slicer.IDX_LEGS
   cotengra.slicer.IDX_SIZE
   cotengra.slicer.IDX_FLOPS


.. py:data:: IDX_INVOLVED
   :value: 0

   

.. py:data:: IDX_LEGS
   :value: 1

   

.. py:data:: IDX_SIZE
   :value: 2

   

.. py:data:: IDX_FLOPS
   :value: 3

   

.. py:class:: ContractionCosts(contractions, size_dict, nslices=1, original_flops=None)


   A simplified struct for tracking the contraction costs of a path only.

   :param contractions: The set of individual operations that make up a full contraction path.
   :type contractions: sequence of Contraction
   :param size_dict: The sizes of the indices involved.
   :type size_dict: dict[str, int]
   :param nslices: For keeping track of the 'multiplicity' of this set of contractions if
                   part of a sliced contration where indices have been removed.
   :type nslices: int, optional

   .. py:property:: size


   .. py:property:: flops


   .. py:property:: total_flops


   .. py:property:: overhead


   .. py:attribute:: __slots__
      :value: ('size_dict', 'contractions', 'nslices', 'original_flops', '_flops', '_sizes',...

      

   .. py:method:: _set_state_from(other)

      Copy all internal structure from another ``ContractionCosts``.


   .. py:method:: copy()

      Get a copy of this ``ContractionCosts``.


   .. py:method:: from_contraction_tree(contraction_tree, **kwargs)
      :classmethod:

      Generate a set of contraction costs from a ``ContractionTree``
      object.


   .. py:method:: from_info(info, **kwargs)
      :classmethod:

      Generate a set of contraction costs from a ``PathInfo`` object.


   .. py:method:: remove(ix, inplace=False)


   .. py:method:: __repr__()

      Return repr(self).



.. py:class:: SliceFinder(tree_or_info, target_size=None, target_overhead=None, target_slices=None, temperature=0.01, minimize='flops', allow_outer=True, seed=None)


   An object to help find the best indices to slice over in order to reduce
   the memory footprint of a contraction as much as possible whilst
   introducing as little extra overhead. It searches for and stores
   ``ContractionCosts``.

   :param tree_or_info: Object describing the target full contraction to slice.
   :type tree_or_info: ContractionTree or opt_einsum.PathInfo
   :param target_size: The target number of entries in the largest tensor of the sliced
                       contraction. The search algorithm will terminate after this is reached.
   :type target_size: int, optional
   :param target_slices: The target or minimum number of 'slices' to consider - individual
                         contractions after slicing indices. The search algorithm will
                         terminate after this is breached. This is on top of the current
                         number of slices.
   :type target_slices: int, optional
   :param target_overhead: The target increase in total number of floating point operations.
                           For example, a value of  ``2.0`` will terminate the search
                           just before the cost of computing all the slices individually breaches
                           twice that of computing the original contraction all at once.
   :type target_overhead: float, optional
   :param temperature: When sampling combinations of indices, how far to randomly stray from
                       what looks like the best (local) choice.
   :type temperature: float, optional

   .. py:attribute:: plot_slicings

      

   .. py:attribute:: plot_slicings_alt

      

   .. py:method:: _maybe_default(attr, value)


   .. py:method:: best(k=None, target_size=None, target_overhead=None, target_slices=None)

      Return the best contraction slicing, subject to target filters.


   .. py:method:: trial(target_size=None, target_overhead=None, target_slices=None, temperature=None)

      A single slicing attempt, greedily select indices from the popular
      pool, subject to the score function, terminating when any of the
      target criteria are met.


   .. py:method:: search(max_repeats=16, temperature=None, target_size=None, target_overhead=None, target_slices=None)

      Repeat trial several times and return the best found so far.