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)¶
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
Encapsulates a single “plaquette” or “submatrix” within a circuit plot.
 Parameters
elements (dict) – A dictionary with (i,j) keys, where i and j are row and column indices and
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
expand_aliases()
.
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 property circuits(self)¶
 __iter__(self)¶
Iterate over (row_index, col_index, circuit) tuples.
 __len__(self)¶
 elementvec_to_matrix(self, elementvec, layout, mergeop='sum')¶
Form a matrix 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
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 soformatted components are joined together with separating commas, and the resulting array contains string (objecttype) entries.
 Returns
numpy array
 process_circuits(self, 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
 expand_aliases(self, 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
 truncate(self, 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
 copy(self)¶
Returns a copy of this CircuitPlaquette.
 Returns
CircuitPlaquette
 summary_label(self)¶
 element_label(self, irow, icol)¶
 class pygsti.circuits.circuitstructure.FiducialPairPlaquette(base, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None)¶
Bases:
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
expand_aliases()
.
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 process_circuits(self, 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
 expand_aliases(self, 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
 truncate(self, 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
 copy(self)¶
Returns a copy of this CircuitPlaquette.
 Returns
FiducialPairPlaquette
 summary_label(self)¶
 element_label(self, irow, icol)¶
 class pygsti.circuits.circuitstructure.GermFiducialPairPlaquette(germ, power, fidpairs, num_rows=None, num_cols=None, op_label_aliases=None)¶
Bases:
FiducialPairPlaquette
A plaquette whose rows and columns correspond to fiducial pairs and whose base is a germpower.
 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
expand_aliases()
.
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 process_circuits(self, 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
 expand_aliases(self, 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
 truncate(self, 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
 copy(self)¶
Returns a copy of this CircuitPlaquette.
 Returns
GermFiducialPairPlaquette
 summary_label(self)¶
 class pygsti.circuits.circuitstructure.PlaquetteGridCircuitStructure(plaquettes, x_values, y_values, xlabel, ylabel, additional_circuits=None, op_label_aliases=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.
 classmethod cast(cls, circuits_or_structure)¶
Convert (if needed) an object into a circuit structure.
 Parameters
circuits_or_structure (list or CircuitList) – The object to convert. If a
PlaquetteGridCircuitStructure
, then the object is simply returned. Lists of circuits (including :class:`CircuitList`s are converted to structures having no plaquettes. Returns
PlaquetteGridCircuitStructure
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 property plaquettes(self)¶
 iter_plaquettes(self)¶
 plaquette(self, x, y, empty_if_missing=False)¶
The plaquette at (x,y).
 Parameters
x (various) – xvalue (not index)
y (various) – yvalue (not index)
empty_if_missing (bool, optional) – Whether an empty (0element) plaquette should be returned when the requested (x,y) is missing.
 Returns
CircuitPlaquette
 property used_xs(self)¶
The xvalues which have at least one nonempty plaquette
 Returns
list
 property used_ys(self)¶
The yvalues which have at least one nonempty plaquette
 Returns
list
 truncate(self, 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 xvalues to keep. If None, then all are kept.
ys_to_keep (list, optional) – The yvalues 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
PlaquetteGridCircuitStructure
to have the same number of rows and columns.
 Returns
PlaquetteGridCircuitStructure
 nested_truncations(self, 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_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
PlaquetteGridCircuitStructure
objects (truncations of this object).
 process_circuits(self, 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
 copy(self)¶
Returns a copy of this circuit structure.
 Returns
PlaquetteGridCircuitStructure