pygsti.circuits.circuitstructure

Defines the CircuitStructure class and supporting functionality.

Module Contents

Classes

CircuitPlaquette

Encapsulates a single "plaquette" or "sub-matrix" within a circuit plot.

FiducialPairPlaquette

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

GermFiducialPairPlaquette

A plaquette whose rows and columns correspond to fiducial pairs and whose base is a germ-power.

PlaquetteGridCircuitStructure

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 “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 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 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 together with separating commas, and the resulting array contains string (object-type) 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 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 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 4-tuple (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) – 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

property used_xs(self)

The x-values which have at least one non-empty plaquette

Returns

list

property used_ys(self)

The y-values which have at least one non-empty 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 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 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 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 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