:py:mod:`pygsti.circuits.circuitlist`
=====================================

.. py:module:: pygsti.circuits.circuitlist

.. autoapi-nested-parse::

   Defines the CircuitList class, for holding meta-data alongside a list or tuple of Circuits.






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

Classes
~~~~~~~

.. autoapisummary::

   pygsti.circuits.circuitlist.CircuitList




.. py:class:: CircuitList(circuits, op_label_aliases=None, circuit_rules=None, circuit_weights=None, name=None)


   Bases: :py:obj:`pygsti.baseobjs.nicelyserializable.NicelySerializable`

   A unmutable list (a tuple) of :class:`Circuit` objects and associated metadata.

   Parameters
   ----------
   circuits : list
       The list of circuits that constitutes the primary data held by this object.

   op_label_aliases : dict, optional
       Dictionary of circuit meta-data whose keys are operation label "aliases"
       and whose values are circuits corresponding to what that operation label
       should be expanded into before querying the dataset.  Defaults to the
       empty dictionary (no aliases defined).  e.g. op_label_aliases['Gx^3'] =
       pygsti.baseobjs.Circuit(['Gx','Gx','Gx'])

   circuit_weights : numpy.ndarray, optional
       If not None, an array of per-circuit weights (of length equal to the number of
       circuits) that are typically used to multiply the counts extracted for each circuit.

   name : str, optional
       An optional name for this list, used for status messages.

   Create a CircuitList.

   Parameters
   ----------
   circuits : list
       The list of circuits that constitutes the primary data held by this object.

   op_label_aliases : dict, optional
       Dictionary of circuit meta-data whose keys are operation label "aliases"
       and whose values are circuits corresponding to what that operation label
       should be expanded into before querying the dataset.  Defaults to the
       empty dictionary (no aliases defined).  e.g. op_label_aliases['Gx^3'] =
       pygsti.baseobjs.Circuit(['Gx','Gx','Gx'])

   circuit_rules : list, optional
       A list of `(find,replace)` 2-tuples which specify circuit-label replacement
       rules.  Both `find` and `replace` are tuples of operation labels (or `Circuit` objects).

   circuit_weights : numpy.ndarray, optional
       If not None, an array of per-circuit weights (of length equal to the number of
       circuits) that are typically used to multiply the counts extracted for each circuit.

   name : str, optional
       An optional name for this list, used for status messages.

   .. py:attribute:: op_label_aliases
      :value: 'None'

      

   .. py:attribute:: circuit_rules
      :value: 'None'

      

   .. py:attribute:: circuit_weights
      :value: 'None'

      

   .. py:attribute:: name
      :value: 'None'

      

   .. py:attribute:: uuid

      

   .. py:method:: cast(circuits)
      :classmethod:

      Convert (if needed) an object into a :class:`CircuitList`.

      Parameters
      ----------
      circuits : list or CircuitList
          The object to convert.

      Returns
      -------
      CircuitList


   .. py:method:: apply_aliases()

      Applies any operation-label aliases to this circuit list.

      Returns
      -------
      list
          A list of :class:`Circuit` objects.


   .. py:method:: truncate(circuits_to_keep)

      Builds a new circuit list containing only a given subset.

      This can be safer then just creating a new :class:`CircuitList`
      because it preserves the aliases, etc., of this list.

      Parameters
      ----------
      circuits_to_keep : list or set
          The circuits to retain in the returned circuit list.

      Returns
      -------
      CircuitList


   .. py:method:: truncate_to_dataset(dataset)

      Builds a new circuit list containing only those elements in `dataset`.

      Parameters
      ----------
      dataset : DataSet
          The dataset to check.  Aliases are applied to the circuits in
          this circuit list before they are tested.

      Returns
      -------
      CircuitList


   .. py:method:: elementvec_to_array(elementvec, layout, mergeop='sum')

      Form an array of values corresponding to this CircuitList from an element vector.

      An element vector holds individual-outcome elements (e.g. the bulk probabilities
      computed by a model).

      Parameters
      ----------
      elementvec : numpy array
          An array containting the values to use when constructing a
          matrix of values for this CircuitList. This array may contain more
          values than are needed by this CircuitList.  Indices into this array
          are given by `elindices_lookup`.

      layout : CircuitOutcomeProbabilityArrayLayout
          The layout of `elementvec`, giving the mapping between its elements and
          circuit outcomes.

      mergeop : "sum" or format string, optional
          Dictates how to combine the `elementvec` components corresponding to a single
          plaquette entry (circuit).  If "sum", the returned array contains summed
          values.  If a format string, e.g. `"%.2f"`, then the so-formatted components
          are joined together, and the resulting array contains string (object-type) entries.

      Returns
      -------
      numpy array