pygsti.circuits.circuitstructure
Defines the CircuitStructure class and supporting functionality.
Module Contents
Classes
Encapsulates a single "plaquette" or "sub-matrix" 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 germ-power. |
|
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 “sub-matrix” 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) 2-tuples 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 individual-outcome 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 so-formatted components are joined together with separating commas, and the resulting array contains string (object-type) 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) 2-tuples 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 germ-power.
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) 2-tuples 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 4-tuple (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 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_ruleslist, 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_weightsnumpy.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.
- 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
x-value (not index)
- yvarious
y-value (not index)
- empty_if_missingbool, optional
Whether an empty (0-element) 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 x-values to keep. If None, then all are kept.
- ys_to_keeplist, optional
The y-values 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 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_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