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

.. py:module:: pygsti.tools.slicetools

.. autoapi-nested-parse::

   Utility functions for working with Python slice objects






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


Functions
~~~~~~~~~

.. autoapisummary::

   pygsti.tools.slicetools.length
   pygsti.tools.slicetools.shift
   pygsti.tools.slicetools.intersect
   pygsti.tools.slicetools.intersect_within
   pygsti.tools.slicetools.indices
   pygsti.tools.slicetools.indices_as_array
   pygsti.tools.slicetools.list_to_slice
   pygsti.tools.slicetools.to_array
   pygsti.tools.slicetools.divide
   pygsti.tools.slicetools.slice_of_slice
   pygsti.tools.slicetools.slice_hash



.. py:function:: length(s)

   Returns the length (the number of indices) contained in a slice.

   Parameters
   ----------
   s : slice
       The slice to operate upon.

   Returns
   -------
   int


.. py:function:: shift(s, offset)

   Returns a new slice whose start and stop points are shifted by `offset`.

   Parameters
   ----------
   s : slice
       The slice to operate upon.

   offset : int
       The amount to shift the start and stop members of `s`.

   Returns
   -------
   slice


.. py:function:: intersect(s1, s2)

   Returns the intersection of two slices (which must have the same step).

   Parameters
   ----------
   s1 : slice
       First slice.

   s2 : slice
       Second slice.

   Returns
   -------
   slice


.. py:function:: intersect_within(s1, s2)

   Returns the intersection of two slices (which must have the same step).
   *and* the sub-slice of `s1` and `s2` that specifies the intersection.

   Furthermore, `s2` may be an array of indices, in which case the returned
   slices become arrays as well.

   Parameters
   ----------
   s1 : slice
       First slice.  Must have definite boundaries (start & stop
       cannot be `None`).

   s2 : slice or numpy.ndarray
       Second slice or index array.

   Returns
   -------
   intersection : slice or numpy.ndarray
       The intersection of `s1` and `s2`.

   subslice1 : slice or numpy.ndarray
       The portion of `s1` that yields `intersection`.

   subslice2 : slice or numpy.ndarray
       The portion of `s2` that yields `intersection`.


.. py:function:: indices(s, n=None)

   Returns a list of the indices specified by slice `s`.

   Parameters
   ----------
   s : slice
       The slice to operate upon.

   n : int, optional
       The number of elements in the array being indexed,
       used for computing *negative* start/stop points.

   Returns
   -------
   list of ints


.. py:function:: indices_as_array(s, n=None)

   Returns a numpy array of the indices specified by slice `s`.

   Parameters
   ----------
   s : slice
       The slice to operate upon.

   n : int, optional
       The number of elements in the array being indexed,
       used for computing *negative* start/stop points.

   Returns
   -------
   numpy ndarray array of integers


.. py:function:: list_to_slice(lst, array_ok=False, require_contiguous=True)

   Returns a slice corresponding to a given list of (integer) indices, if this is possible.

   If not, `array_ok` determines the behavior.

   Parameters
   ----------
   lst : list
       The list of integers to convert to a slice (must be contiguous
       if `require_contiguous == True`).

   array_ok : bool, optional
       If True, an integer array (of type `numpy.ndarray`) is returned
       when `lst` does not correspond to a single slice.  Otherwise,
       an AssertionError is raised.

   require_contiguous : bool, optional
       If True, then lst will only be converted to a contiguous (step=1)
       slice, otherwise either a ValueError is raised (if `array_ok`
       is False) or an array is returned.

   Returns
   -------
   numpy.ndarray or slice


.. py:function:: to_array(slc_or_list_like)

   Returns `slc_or_list_like` as an index array (an integer numpy.ndarray).

   Parameters
   ----------
   slc_or_list_like : slice or list
       A slice, list, or array.

   Returns
   -------
   numpy.ndarray


.. py:function:: divide(slc, max_len)

   Divides a slice into sub-slices based on a maximum length (for each sub-slice).

   For example:
   `divide(slice(0,10,2), 2) == [slice(0,4,2), slice(4,8,2), slice(8,10,2)]`

   Parameters
   ----------
   slc : slice
       The slice to divide

   max_len : int
       The maximum length (i.e. number of indices) allowed in a sub-slice.

   Returns
   -------
   list of slices


.. py:function:: slice_of_slice(slc, base_slc)

   A slice that is the composition of `base_slc` and `slc`.

   So that when indexing an array `a`,
   `a[slice_of_slice(slc, base_slc)] == a[base_slc][slc]`

   Parameters
   ----------
   slc : slice
       the slice to take out of `base_slc`.

   base_slc : slice
       the original "base" slice to act upon.

   Returns
   -------
   slice


.. py:function:: slice_hash(slc)