:py:mod:`pygsti.tools.listtools`
================================

.. py:module:: pygsti.tools.listtools

.. autoapi-nested-parse::

   Utility functions for working with lists






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


Functions
~~~~~~~~~

.. autoapisummary::

   pygsti.tools.listtools.remove_duplicates_in_place
   pygsti.tools.listtools.remove_duplicates
   pygsti.tools.listtools.compute_occurrence_indices
   pygsti.tools.listtools.find_replace_tuple
   pygsti.tools.listtools.find_replace_tuple_list
   pygsti.tools.listtools.apply_aliases_to_circuits
   pygsti.tools.listtools.sorted_partitions
   pygsti.tools.listtools.partitions
   pygsti.tools.listtools.partition_into
   pygsti.tools.listtools.incd_product
   pygsti.tools.listtools.lists_to_tuples



.. py:function:: remove_duplicates_in_place(l, index_to_test=None)

   Remove duplicates from the list passed as an argument.

   Parameters
   ----------
   l : list
       The list to remove duplicates from.

   index_to_test : int, optional
       If not None, the index within the elements of l to test.  For
       example, if all the elements of l contain 2 tuples (x,y) then
       set index_to_test == 1 to remove tuples with duplicate y-values.

   Returns
   -------
   None


.. py:function:: remove_duplicates(l, index_to_test=None)

   Remove duplicates from the a list and return the result.

   Parameters
   ----------
   l : iterable
       The list/set to remove duplicates from.

   index_to_test : int, optional
       If not None, the index within the elements of l to test.  For
       example, if all the elements of l contain 2 tuples (x,y) then
       set index_to_test == 1 to remove tuples with duplicate y-values.

   Returns
   -------
   list
       the list after duplicates have been removed.


.. py:function:: compute_occurrence_indices(lst)

   A 0-based list of integers specifying which occurrence, i.e. enumerated duplicate, each list item is.

   For example, if `lst` = [ 'A','B','C','C','A'] then the
   returned list will be   [  0 , 0 , 0 , 1 , 1 ].  This may be useful
   when working with `DataSet` objects that have `collisionAction`
   set to "keepseparate".

   Parameters
   ----------
   lst : list
       The list to process.

   Returns
   -------
   list


.. py:function:: find_replace_tuple(t, alias_dict)

   Replace elements of t according to rules in `alias_dict`.

   Parameters
   ----------
   t : tuple or list
       The object to perform replacements upon.

   alias_dict : dictionary
       Dictionary whose keys are potential elements of `t` and whose values
       are tuples corresponding to a sub-sequence that the given element should
       be replaced with.  If None, no replacement is performed.

   Returns
   -------
   tuple


.. py:function:: find_replace_tuple_list(list_of_tuples, alias_dict)

   Applies :func:`find_replace_tuple` on each element of `list_of_tuples`.

   Parameters
   ----------
   list_of_tuples : list
       A list of tuple objects to perform replacements upon.

   alias_dict : dictionary
       Dictionary whose keys are potential elements of `t` and whose values
       are tuples corresponding to a sub-sequence that the given element should
       be replaced with.  If None, no replacement is performed.

   Returns
   -------
   list


.. py:function:: apply_aliases_to_circuits(list_of_circuits, alias_dict)

   Applies `alias_dict` to the circuits in `list_of_circuits`.

   Parameters
   ----------
   list_of_circuits : list
       A list of circuits to make replacements in.

   alias_dict : dict
       A dictionary whose keys are layer Labels (or equivalent tuples or
       strings), and whose values are Circuits or tuples of labels.

   Returns
   -------
   list


.. py:function:: sorted_partitions(n)

   Iterate over all sorted (decreasing) partitions of integer `n`.

   A partition of `n` here is defined as a list of one or more non-zero
   integers which sum to `n`.  Sorted partitions (those iterated over here)
   have their integers in decreasing order.

   Parameters
   ----------
   n : int
       The number to partition.


.. py:function:: partitions(n)

   Iterate over all partitions of integer `n`.

   A partition of `n` here is defined as a list of one or more non-zero
   integers which sum to `n`.  Every partition is iterated over exacty
   once - there are no duplicates/repetitions.

   Parameters
   ----------
   n : int
       The number to partition.


.. py:function:: partition_into(n, nbins)

   Iterate over all partitions of integer `n` into `nbins` bins.

   Here, unlike in :func:`partition`, a "partition" is allowed to contain
   zeros.  For example, (4,1,0) is a valid partition of 5 using 3 bins.  This
   function fixes the number of bins and iterates over all possible length-
   `nbins` partitions while allowing zeros.  This is equivalent to iterating
   over all usual partitions of length at most `nbins` and inserting zeros into
   all possible places for partitions of length less than `nbins`.

   Parameters
   ----------
   n : int
       The number to partition.

   nbins : int
       The fixed number of bins, equal to the length of all the
       partitions that are iterated over.


.. py:function:: incd_product(*args)

   Like `itertools.product` but returns the first modified (incremented) index along with the product tuple itself.

   Parameters
   ----------
   `*args` : iterables
       Any number of iterable things that we're taking the product of.


.. py:function:: lists_to_tuples(obj)

   Recursively replaces lists with tuples.

   Can be useful for fixing tuples that were serialized to json or mongodb.
   Recurses on lists, tuples, and dicts within `obj`.

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

   Returns
   -------
   object