:py:mod:`pygsti.baseobjs.smartcache`
====================================

.. py:module:: pygsti.baseobjs.smartcache

.. autoapi-nested-parse::

   Defines SmartCache and supporting functions






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

Classes
~~~~~~~

.. autoapisummary::

   pygsti.baseobjs.smartcache.SmartCache



Functions
~~~~~~~~~

.. autoapisummary::

   pygsti.baseobjs.smartcache.smart_cached
   pygsti.baseobjs.smartcache.digest



Attributes
~~~~~~~~~~

.. autoapisummary::

   pygsti.baseobjs.smartcache.DIGEST_TIMES


.. py:data:: DIGEST_TIMES

   

.. py:class:: SmartCache(decorating=(None, None))


   Bases: :py:obj:`object`

   Cache object that profiles itself

   Parameters
   ----------
   decorating : tuple
       module and function being decorated by the smart cache

   Attributes
   ----------
   StaticCacheList : list
       A list of all :class:`SmartCache` instances.

   Construct a smart cache object

   Parameters
   ----------
   decorating : tuple
       module and function being decorated by the smart cache

   .. py:attribute:: StaticCacheList
      :value: '[]'

      

   .. py:attribute:: cache

      

   .. py:attribute:: outargs

      

   .. py:attribute:: ineffective

      

   .. py:attribute:: customDigests
      :value: '[]'

      

   .. py:attribute:: misses

      

   .. py:attribute:: hits

      

   .. py:attribute:: fhits

      

   .. py:attribute:: requests

      

   .. py:attribute:: ineffectiveRequests

      

   .. py:attribute:: effectiveTimes

      

   .. py:attribute:: ineffectiveTimes

      

   .. py:attribute:: hashTimes

      

   .. py:attribute:: callTimes

      

   .. py:attribute:: typesigs

      

   .. py:attribute:: saved
      :value: '0'

      

   .. py:attribute:: unpickleable

      

   .. py:method:: add_digest(custom)

      Add a "custom" digest function, used for hashing otherwise un-hashable types.

      Parameters
      ----------
      custom : function
          A hashing function, which takes two arguments: `md5` (a running MD5
          hash) and `val` (the value to be hashed).  It should call
          `md5.update` to add to the running hash, and needn't return anything.

      Returns
      -------
      None


   .. py:method:: low_overhead_cached_compute(fn, arg_vals, kwargs=None)

      Cached compute with less profiling. See :meth:`cached_compute` docstring.

      Parameters
      ----------
      fn : function
          Cached function

      arg_vals : tuple or list
          Arguments to cached function

      kwargs : dictionary
          Keyword arguments to cached function

      Returns
      -------
      key : the key used to hash the function call
      result : result of fn called with arg_vals and kwargs


   .. py:method:: cached_compute(fn, arg_vals, kwargs=None)

      Shows effectiveness of a cache

      Parameters
      ----------
      fn : function
          Cached function

      arg_vals : tuple or list
          Arguments to cached function

      kwargs : dictionary
          Keyword arguments to cached function

      Returns
      -------
      key : the key used to hash the function call
      result : result of fn called with arg_vals and kwargs


   .. py:method:: global_status(printer)
      :staticmethod:

      Show the statuses of all Cache objects

      Parameters
      ----------
      printer : VerbosityPrinter
          The printer to use for output.

      Returns
      -------
      None


   .. py:method:: avg_timedict(d)

      Given a dictionary of lists of times (`d`), returns a dict of the summed times.

      Parameters
      ----------
      d : dict
          A dictionary whose values are lists of times.

      Returns
      -------
      dict


   .. py:method:: status(printer)

      Show the status of a cache object instance

      Parameters
      ----------
      printer : VerbosityPrinter
          The printer to use for output.

      Returns
      -------
      None



.. py:function:: smart_cached(obj)

   Decorator for applying a smart cache to a single function or method.

   Parameters
   ----------
   obj : function
       function to decorate.

   Returns
   -------
   function


.. py:exception:: CustomDigestError


   Bases: :py:obj:`Exception`

   Custom Digest Exception type

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: digest(obj, custom_digests=None)

   Returns an MD5 digest of an arbitary Python object, `obj`.

   Parameters
   ----------
   obj : object
       Object to digest.

   custom_digests : list, optional
       A list of custom digest functions.  Each function should have the signature
       `digest(md5 : hashlib.md5, value)` and either digest `value` (calling `md5.update`
       or similar) or raise a :class:`CustomDigestError` to indicate it was unable to
       digest `value`.

   Returns
   -------
   MD5_digest