pygsti.circuits.circuitstructure
Defines the CircuitStructure class and supporting functionality.
Module Contents
Classes
Encapsulates a single "plaquette" or "submatrix" within a circuit plot. 

A plaquette whose rows and columns correspond to measurement and preparation fiducial circuits. 

A plaquette whose rows and columns correspond to fiducial pairs and whose base is a germpower. 

Encapsulates a set of circuits, along with an associated structure. 
 class pygsti.circuits.circuitstructure.CircuitPlaquette(elements, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
Encapsulates a single “plaquette” or “submatrix” within a circuit plot.
Parameters
 elementsdict
A dictionary with (i,j) keys, where i and j are row and column indices and
Circuit
values. num_rowsint, 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_colsint, 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_aliasesdict, optional
A dictionary of operation label aliases that is carried along for calls to
expand_aliases()
. circuit_ruleslist, optional
A list of (find,replace) 2tuples which specify string replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).
Create a new CircuitPlaquette.
 property circuits
 elementvec_to_array(elementvec, layout, mergeop='sum')
Form a array of values corresponding to this plaquette from an element vector.
An element vector holds individualoutcome elements (e.g. the bulk probabilities computed by a model).
Parameters
 elementvecnumpy 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.
 layoutCircuitOutcomeProbabilityArrayLayout
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 soformatted components are joined together with separating commas, and the resulting array contains string (objecttype) entries.
Returns
numpy array
 process_circuits(processor_fn, updated_aliases=None)
Create a new plaquette with circuits manipulated according to processor_fn.
Parameters
 processor_fnfunction
A function which takes a single Circuit argument and returns another (or the same) Circuit.
 updated_aliasesdict, 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
 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_filterDataSet, optional
If not None, keep only strings that are in this data set.
Returns
CircuitPlaquette
 truncate(circuits_to_keep, keep_rows_cols=False)
Remove any circuits from this plaquette that aren’t in circuits_to_keep.
Parameters
 circuits_to_keeplist or set
List of circuits to keep. If None, then a copy of this object is returned.
 keep_rows_colsbool
Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty).
Returns
CircuitPlaquette
 summary_label()
 element_label(irow, icol)
 class pygsti.circuits.circuitstructure.FiducialPairPlaquette(base, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None)
Bases:
CircuitPlaquette
A plaquette whose rows and columns correspond to measurement and preparation fiducial circuits.
Theese fiducials sandwich a “base” circuit.
Parameters
 baseCircuit
The “base” circuit of this plaquette. Typically the sequence that is sandwiched between fiducial pairs.
 fidpairslist 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_rowsint, 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_colsint, 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_aliasesdict, optional
A dictionary of operation label aliases that is carried along for calls to
expand_aliases()
. circuit_ruleslist, optional
A list of (find,replace) 2tuples which specify string replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).
Create a new FiducialPairPlaquette.
 process_circuits(processor_fn, updated_aliases=None)
Create a new plaquette with circuits manipulated according to processor_fn.
Parameters
 processor_fnfunction
A function which takes a single Circuit argument and returns another (or the same) Circuit.
 updated_aliasesdict, 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
 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_filterDataSet, optional
If not None, keep only strings that are in this data set.
Returns
CircuitPlaquette
 truncate(circuits_to_keep, keep_rows_cols=False)
Remove any circuits from this plaquette that aren’t in circuits_to_keep.
Parameters
 circuits_to_keeplist or set
List of circuits to keep. If None, then a copy of this object is returned.
 keep_rows_colsbool
Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty).
Returns
FiducialPairPlaquette
 summary_label()
 element_label(irow, icol)
 class pygsti.circuits.circuitstructure.GermFiducialPairPlaquette(germ, power, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None, circuit_rules=None)
Bases:
FiducialPairPlaquette
A plaquette whose rows and columns correspond to fiducial pairs and whose base is a germpower.
Parameters
 germCircuit
The “germ” circuit of this plaquette.
 powerint
The number of times germ is repeated to get the base circuit (that is sandwiched between different fiducial pairs).
 fidpairslist 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_rowsint, 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_colsint, 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_aliasesdict, optional
A dictionary of operation label aliases that is carried along for calls to
expand_aliases()
. circuit_ruleslist, optional
A list of (find,replace) 2tuples which specify string replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).
Create a new GermFiducialPairPlaquette.
 process_circuits(processor_fn, updated_aliases=None)
Create a new plaquette with circuits manipulated according to processor_fn.
Parameters
 processor_fnfunction
A function which takes a single Circuit argument and returns another (or the same) Circuit.
 updated_aliasesdict, 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
 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_filterDataSet, optional
If not None, keep only strings that are in this data set.
Returns
CircuitPlaquette
 truncate(circuits_to_keep, keep_rows_cols=False)
Remove any circuits from this plaquette that aren’t in circuits_to_keep.
Parameters
 circuits_to_keeplist or set
List of circuits to keep. If None, then a copy of this object is returned.
 keep_rows_colsbool
Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty).
Returns
GermFiducialPairPlaquette
 summary_label()
 class pygsti.circuits.circuitstructure.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:
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 4tuple (x, y, minor_x, minor_y) for displaying in nested color box plots, along with any aliases.
Create a CircuitList.
Parameters
 circuitslist
The list of circuits that constitutes the primary data held by this object.
 op_label_aliasesdict, optional
Dictionary of circuit metadata 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_ruleslist, optional
A list of (find,replace) 2tuples which specify circuitlabel replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).
 circuit_weightsnumpy.ndarray, optional
If not None, an array of percircuit weights (of length equal to the number of circuits) that are typically used to multiply the counts extracted for each circuit.
 namestr, optional
An optional name for this list, used for status messages.
 property plaquettes
 classmethod cast(circuits_or_structure)
Convert (if needed) an object into a circuit structure.
Parameters
 circuits_or_structurelist or CircuitList
The object to convert. If a
PlaquetteGridCircuitStructure
, then the object is simply returned. Lists of circuits (includingCircuitList
objects are converted to structures having no plaquettes.
Returns
PlaquetteGridCircuitStructure
 iter_plaquettes()
 plaquette(x, y, empty_if_missing=False)
The plaquette at (x,y).
Parameters
 xvarious
xvalue (not index)
 yvarious
yvalue (not index)
 empty_if_missingbool, optional
Whether an empty (0element) plaquette should be returned when the requested (x,y) is missing.
Returns
CircuitPlaquette
 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_keeplist
Keep only the circuits present in this list (of Circuit objects).
 xs_to_keeplist, optional
The xvalues to keep. If None, then all are kept.
 ys_to_keeplist, optional
The yvalues to keep. If None, then all are kept.
 keep_rows_colsbool
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
PlaquetteGridCircuitStructure
to have the same number of rows and columns.
Returns
PlaquetteGridCircuitStructure
 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 xvalues. E.g., if the xvalues 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 yvalues.
Parameters
 axis{‘x’, ‘y’}
Which axis to truncate along (see above).
 keep_rows_colsbool
Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty).
Returns
 list
A list of
PlaquetteGridCircuitStructure
objects (truncations of this object).
 process_circuits(processor_fn, updated_aliases=None)
Create a new plaquette with circuits manipulated according to processor_fn.
Parameters
 processor_fnfunction
A function which takes a single Circuit argument and returns another (or the same) Circuit.
 updated_aliasesdict, 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