:py:mod:`pygsti.circuits.circuitstructure` ========================================== .. py:module:: pygsti.circuits.circuitstructure .. autoapi-nested-parse:: Defines the CircuitStructure class and supporting functionality. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.circuits.circuitstructure.CircuitPlaquette pygsti.circuits.circuitstructure.FiducialPairPlaquette pygsti.circuits.circuitstructure.GermFiducialPairPlaquette pygsti.circuits.circuitstructure.PlaquetteGridCircuitStructure .. py:class:: CircuitPlaquette(elements, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None) Bases: :py:obj:`pygsti.baseobjs.nicelyserializable.NicelySerializable` Encapsulates a single "plaquette" or "sub-matrix" within a circuit plot. Parameters ---------- elements : dict A dictionary with `(i,j)` keys, where `i` and `j` are row and column indices and :class:`Circuit` values. num_rows : int, optional The number of rows in this plaquette. If None, then this is set to one larger than the maximum row index in `elements`. num_cols : int, optional The number of columns in this plaquette. If None, then this is set to one larger than the maximum colum index in `elements`. op_label_aliases : dict, optional A dictionary of operation label aliases that is carried along for calls to :func:`expand_aliases`. circuit_rules : list, optional A list of `(find,replace)` 2-tuples which specify string replacement rules. Both `find` and `replace` are tuples of operation labels (or `Circuit` objects). Create a new CircuitPlaquette. .. py:property:: circuits .. py:attribute:: elements .. py:attribute:: circuit_rules :value: 'None' .. py:attribute:: op_label_aliases :value: 'None' .. py:attribute:: num_rows :value: 'None' .. py:attribute:: num_cols :value: 'None' .. py:method:: elementvec_to_array(elementvec, layout, mergeop='sum') Form a array of values corresponding to this plaquette 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 plaquette. This array may contain more values than are needed by this plaquette. 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, and the resulting array contains string (object-type) entries. Returns ------- numpy array .. py:method:: process_circuits(processor_fn, updated_aliases=None) Create a new plaquette with circuits manipulated according to `processor_fn`. Parameters ---------- processor_fn : function A function which takes a single Circuit argument and returns another (or the same) Circuit. updated_aliases : dict, optional Because the Label keys of an alias dictionary (maps Label -> Circuit) cannot be processed as a Circuit, one must supply a manualy processed alias dictionary. If you don't use alias dictionaries just leave this set to None. Returns ------- CircuitPlaquette .. py:method:: expand_aliases(ds_filter=None) Returns a new CircuitPlaquette with any aliases expanded. Aliases are expanded (i.e. applied) within the circuits of this plaquette. Optionally keeps only those strings which, after alias expansion, are in `ds_filter`. Parameters ---------- ds_filter : DataSet, optional If not None, keep only strings that are in this data set. Returns ------- CircuitPlaquette .. py:method:: truncate(circuits_to_keep, keep_rows_cols=False) Remove any circuits from this plaquette that aren't in `circuits_to_keep`. Parameters ---------- circuits_to_keep : list or set List of circuits to keep. If None, then a copy of this object is returned. keep_rows_cols : bool Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). Returns ------- CircuitPlaquette .. py:method:: copy() Returns a copy of this `CircuitPlaquette`. Returns ------- CircuitPlaquette .. py:method:: summary_label() .. py:method:: element_label(irow, icol) .. py:class:: FiducialPairPlaquette(base, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None) Bases: :py:obj:`CircuitPlaquette` A plaquette whose rows and columns correspond to measurement and preparation fiducial circuits. Theese fiducials sandwich a "base" circuit. Parameters ---------- base : Circuit The "base" circuit of this plaquette. Typically the sequence that is sandwiched between fiducial pairs. fidpairs : list or dict A list or dict of `(prepFiducial, effectFiducial)` tuples specifying how `elements` is generated from `base`, i.e. by `prepFiducial + base + effectFiducial`. If a dictionary, then `(i, j)` keys give the row and column indices of that fiducial pair (in the case of a list, items are placed sequentially by row. num_rows : int, optional The number of rows in this plaquette. If None, then this is set to one larger than the maximum row index in `elements`. num_cols : int, optional The number of columns in this plaquette. If None, then this is set to one larger than the maximum colum index in `elements`. op_label_aliases : dict, optional A dictionary of operation label aliases that is carried along for calls to :func:`expand_aliases`. circuit_rules : list, optional A list of `(find,replace)` 2-tuples which specify string replacement rules. Both `find` and `replace` are tuples of operation labels (or `Circuit` objects). Create a new FiducialPairPlaquette. .. py:attribute:: base .. py:attribute:: fidpairs .. py:method:: process_circuits(processor_fn, updated_aliases=None) Create a new plaquette with circuits manipulated according to `processor_fn`. Parameters ---------- processor_fn : function A function which takes a single Circuit argument and returns another (or the same) Circuit. updated_aliases : dict, optional Because the Label keys of an alias dictionary (maps Label -> Circuit) cannot be processed as a Circuit, one must supply a manualy processed alias dictionary. If you don't use alias dictionaries just leave this set to None. Returns ------- CircuitPlaquette .. py:method:: expand_aliases(ds_filter=None) Returns a new CircuitPlaquette with any aliases expanded. Aliases are expanded (i.e. applied) within the circuits of this plaquette. Optionally keeps only those strings which, after alias expansion, are in `ds_filter`. Parameters ---------- ds_filter : DataSet, optional If not None, keep only strings that are in this data set. Returns ------- CircuitPlaquette .. py:method:: truncate(circuits_to_keep, keep_rows_cols=False) Remove any circuits from this plaquette that aren't in `circuits_to_keep`. Parameters ---------- circuits_to_keep : list or set List of circuits to keep. If None, then a copy of this object is returned. keep_rows_cols : bool Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). Returns ------- FiducialPairPlaquette .. py:method:: copy() Returns a copy of this `CircuitPlaquette`. Returns ------- FiducialPairPlaquette .. py:method:: summary_label() .. py:method:: element_label(irow, icol) .. py:class:: GermFiducialPairPlaquette(germ, power, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None) Bases: :py:obj:`FiducialPairPlaquette` A plaquette whose rows and columns correspond to fiducial pairs and whose base is a germ-power. Parameters ---------- germ : Circuit The "germ" circuit of this plaquette. power : int The number of times `germ` is repeated to get the base circuit (that is sandwiched between different fiducial pairs). fidpairs : list or dict A list or dict of `(prepStr, effectStr)` tuples specifying how `elements` is generated from `base`, i.e. by `prepStr + base + effectStr`. If a dictionary, then `(i, j)` keys give the row and column indices of that fiducial pair (in the case of a list, items are placed sequentially by row. num_rows : int, optional The number of rows in this plaquette. If None, then this is set to one larger than the maximum row index in `elements`. num_cols : int, optional The number of columns in this plaquette. If None, then this is set to one larger than the maximum colum index in `elements`. op_label_aliases : dict, optional A dictionary of operation label aliases that is carried along for calls to :func:`expand_aliases`. circuit_rules : list, optional A list of `(find,replace)` 2-tuples which specify string replacement rules. Both `find` and `replace` are tuples of operation labels (or `Circuit` objects). Create a new GermFiducialPairPlaquette. .. py:attribute:: germ .. py:attribute:: power .. py:method:: process_circuits(processor_fn, updated_aliases=None) Create a new plaquette with circuits manipulated according to `processor_fn`. Parameters ---------- processor_fn : function A function which takes a single Circuit argument and returns another (or the same) Circuit. updated_aliases : dict, optional Because the Label keys of an alias dictionary (maps Label -> Circuit) cannot be processed as a Circuit, one must supply a manualy processed alias dictionary. If you don't use alias dictionaries just leave this set to None. Returns ------- CircuitPlaquette .. py:method:: expand_aliases(ds_filter=None) Returns a new CircuitPlaquette with any aliases expanded. Aliases are expanded (i.e. applied) within the circuits of this plaquette. Optionally keeps only those strings which, after alias expansion, are in `ds_filter`. Parameters ---------- ds_filter : DataSet, optional If not None, keep only strings that are in this data set. Returns ------- CircuitPlaquette .. py:method:: truncate(circuits_to_keep, keep_rows_cols=False) Remove any circuits from this plaquette that aren't in `circuits_to_keep`. Parameters ---------- circuits_to_keep : list or set List of circuits to keep. If None, then a copy of this object is returned. keep_rows_cols : bool Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). Returns ------- GermFiducialPairPlaquette .. py:method:: copy() Returns a copy of this `CircuitPlaquette`. Returns ------- GermFiducialPairPlaquette .. py:method:: summary_label() .. py:class:: PlaquetteGridCircuitStructure(plaquettes, x_values, y_values, xlabel, ylabel, additional_circuits=None, op_label_aliases=None, circuit_rules=None, circuit_weights_dict=None, additional_circuits_location='start', name=None) Bases: :py:obj:`pygsti.circuits.circuitlist.CircuitList` Encapsulates a set of circuits, along with an associated structure. By "structure", we mean the ability to index the circuits by a 4-tuple (x, y, minor_x, minor_y) for displaying in nested color box plots, along with any aliases. 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:property:: plaquettes .. py:property:: used_xs The x-values which have at least one non-empty plaquette Returns ------- list .. py:property:: used_ys The y-values which have at least one non-empty plaquette Returns ------- list .. py:attribute:: xs .. py:attribute:: ys .. py:attribute:: xlabel .. py:attribute:: ylabel .. py:method:: cast(circuits_or_structure) :classmethod: Convert (if needed) an object into a circuit structure. Parameters ---------- circuits_or_structure : list or CircuitList The object to convert. If a :class:`PlaquetteGridCircuitStructure`, then the object is simply returned. Lists of circuits (including :class:`CircuitList` objects are converted to structures having no plaquettes. Returns ------- PlaquetteGridCircuitStructure .. py:method:: iter_plaquettes() .. py:method:: plaquette(x, y, empty_if_missing=False) The plaquette at `(x,y)`. Parameters ---------- x : various x-value (not index) y : various y-value (not index) empty_if_missing : bool, optional Whether an empty (0-element) plaquette should be returned when the requested `(x,y)` is missing. Returns ------- CircuitPlaquette .. py:method:: truncate(circuits_to_keep=None, xs_to_keep=None, ys_to_keep=None, keep_rows_cols=True) Truncate this circuit structure to a subset of its current circuits. Parameters ---------- circuits_to_keep : list Keep only the circuits present in this list (of Circuit objects). xs_to_keep : list, optional The x-values to keep. If None, then all are kept. ys_to_keep : list, optional The y-values to keep. If None, then all are kept. keep_rows_cols : bool Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). By default, this is `True` because we usually want all the plaquettes of a :class:`PlaquetteGridCircuitStructure` to have the same number of rows and columns. Returns ------- PlaquetteGridCircuitStructure .. py:method:: nested_truncations(axis='x', keep_rows_cols=False) Get the nested truncations of this circuit structure along an axis. When `axis == 'x'`, a list of truncations (of this structure) that keep an incrementally larger set of all the x-values. E.g., if the x-values are `[1,2,4]`, truncations to `[1]`, `[1,2]`, and `[1,2,4]` (no truncation) would be returned. Setting `axis =='y'` gives the same behavior except using the y-values. Parameters ---------- axis : {'x', 'y'} Which axis to truncate along (see above). keep_rows_cols : bool Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). Returns ------- list A list of :class:`PlaquetteGridCircuitStructure` objects (truncations of this object). .. py:method:: process_circuits(processor_fn, updated_aliases=None) Create a new plaquette with circuits manipulated according to `processor_fn`. Parameters ---------- processor_fn : function A function which takes a single Circuit argument and returns another (or the same) Circuit. updated_aliases : dict, optional Because the Label keys of an alias dictionary (maps Label -> Circuit) cannot be processed as a Circuit, one must supply a manualy processed alias dictionary. If you don't use alias dictionaries just leave this set to None. Returns ------- PlaquetteGridCircuitStructure .. py:method:: copy() Returns a copy of this circuit structure. Returns ------- PlaquetteGridCircuitStructure