pygsti.protocols.vb

Volumetric Benchmarking Protocol objects

Module Contents

Classes

ByDepthDesign

Experiment design that holds circuits organized by depth.

BenchmarkingDesign

Experiment design that holds benchmarking data.

PeriodicMirrorCircuitDesign

Experiment design for periodic mirror-circuit benchmarking.

SummaryStatistics

A protocol that can construct "summary" quantities from raw data.

ByDepthSummaryStatistics

A protocol that computes summary statistics for data organized into by-depth circuit lists.

SummaryStatisticsResults

Summary statistics computed for a set of data.

class pygsti.protocols.vb.ByDepthDesign(depths, circuit_lists, qubit_labels=None, remove_duplicates=True)

Bases: pygsti.protocols.protocol.CircuitListsDesign

Experiment design that holds circuits organized by depth.

Parameters
  • depths (list or tuple) – A sequence of integers specifying the circuit depth associated with each element of circuit_lists.

  • circuit_lists (list or tuple) – The circuits to include in this experiment design. Each element is a list of Circuits specifying the circuits at the corresponding depth.

  • qubit_labels (tuple, optional) – The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

  • remove_duplicates (bool, optional) – Whether to remove duplicates when automatically creating all the circuits that need data.

class pygsti.protocols.vb.BenchmarkingDesign(depths, circuit_lists, ideal_outs, qubit_labels=None, remove_duplicates=False)

Bases: ByDepthDesign

Experiment design that holds benchmarking data.

By “benchmarking data” we mean definite-outcome circuits organized by depth along with their corresponding ideal outcomes.

Parameters
  • depths (list or tuple) – A sequence of integers specifying the circuit depth associated with each element of circuit_lists.

  • circuit_lists (list or tuple) – The circuits to include in this experiment design. Each element is a list of Circuits specifying the circuits at the corresponding depth.

  • ideal_outs (list or tuple) – The ideal circuit outcomes corresponding to the circuits in circuit_lists. Each element of ideal_outs is a list (with the same length as the corresponding circuits_lists element) of outcome labels.

  • qubit_labels (tuple, optional) – The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

  • remove_duplicates (bool, optional) – Whether to remove duplicates when automatically creating all the circuits that need data.

class pygsti.protocols.vb.PeriodicMirrorCircuitDesign(pspec, depths, circuits_per_depth, qubit_labels=None, clifford_compilations=None, sampler='edgegrab', samplerargs=(0.125,), localclifford=True, paulirandomize=True, fixed_versus_depth=False, descriptor='A random germ mirror circuit experiment')

Bases: BenchmarkingDesign

Experiment design for periodic mirror-circuit benchmarking.

THIS METHOD IS IN DEVELOPEMENT. DO NOT EXPECT THAT THIS FUNCTION WILL BEHAVE THE SAME IN FUTURE RELEASES OF PYGSTI! THE DOCSTRINGS SHOULD ALSO NOT BE TRUSTED – MANY (MAYBE ALL) OF THEM ARE COPIED FROM THE MIRRORBDESIGN OBJECT AND SO SOME BITS ARE WRONG OR NOT APPLICABLE.

Parameters
  • pspec (QubitProcessorSpec) – The QubitProcessorSpec for the device that the experiment is being generated for. The pspec is always handed to the sampler, as the first argument of the sampler function.

  • depths (list of ints) –

    The “mirror RB depths” of the circuits, which is closely related to the circuit depth. A MRB length must be an even integer, and can be zero.

    • If localclifford and paulirandomize are False, the depth of a sampled circuit = the MRB length. The first length/2 layers are all sampled independently according to the sampler specified by sampler. The remaining half of the circuit is the “inversion” circuit that is determined by the first half.

    • If paulirandomize is True and localclifford is False, the depth of a circuit is 2*length+1 with odd-indexed layers sampled according to the sampler specified by `sampler, and the the zeroth layer + the even-indexed layers consisting of random 1-qubit Pauli gates.

    • If paulirandomize and localclifford are True, the depth of a circuit is 2*length+1 + X where X is a random variable (between 0 and normally <= ~12-16) that accounts for the depth from the layer of random 1-qubit Cliffords at the start and end of the circuit.

    • If paulirandomize is False and localclifford is True, the depth of a circuit is length + X where X is a random variable (between 0 and normally <= ~12-16) that accounts for the depth from the layer of random 1-qubit Cliffords at the start and end of the circuit.

  • circuits_per_depth (int) – The number of (possibly) different MRB circuits sampled at each length.

  • qubit_labels (list, optional) – If not None, a list of the qubits that the RB circuit is to be sampled for. This should be all or a subset of the qubits in the device specified by the QubitProcessorSpec pspec. If None, it is assumed that the RB circuit should be over all the qubits. Note that the ordering of this list is the order of the ``wires’’ in the returned circuit, but is otherwise irrelevant.

  • sampler (str or function, optional) – If a string, this should be one of: {‘pairingQs’, ‘Qelimination’, ‘co2Qgates’, ‘local’}. Except for ‘local’, this corresponds to sampling layers according to the sampling function in rb.sampler named circuit_layer_by* (with * replaced by ‘sampler’). For ‘local’, this corresponds to sampling according to rb.sampler.circuit_layer_of_oneQgates [which is not a valid option for n-qubit MRB – it results in sim. 1-qubit MRB – but it is not explicitly forbidden by this function]. If sampler is a function, it should be a function that takes as the first argument a QubitProcessorSpec, and returns a random circuit layer as a list of gate Label objects. Note that the default ‘Qelimination’ is not necessarily the most useful in-built sampler, but it is the only sampler that requires no parameters beyond the QubitProcessorSpec and works for arbitrary connectivity devices. See the docstrings for each of these samplers for more information.

  • samplerargs (list, optional) – A list of arguments that are handed to the sampler function, specified by sampler. The first argument handed to the sampler is pspec and samplerargs lists the remaining arguments handed to the sampler.

  • localclifford (bool, optional) – Whether to start the circuit with uniformly random 1-qubit Cliffords and all of the qubits (compiled into the native gates of the device).

  • paulirandomize (bool, optional) – Whether to have uniformly random Pauli operators on all of the qubits before and after all of the layers in the “out” and “back” random circuits. At length 0 there is a single layer of random Pauli operators (in between two layers of 1-qubit Clifford gates if localclifford is True); at length l there are 2l+1 Pauli layers as there are

  • fixed_versus_depth (bool, optional) – <TODO description>

  • descriptor (str, optional) – A string describing the generated experiment. Stored in the returned dictionary.

classmethod from_existing_circuits(cls, circuits_and_idealouts_by_depth, qubit_labels=None, sampler='edgegrab', samplerargs=(0.125,), localclifford=True, paulirandomize=True, fixed_versus_depth=False, descriptor='A random germ mirror circuit experiment')

Create a PeriodicMirrorCircuitDesign from an existing set of sampled RB circuits.

This function serves as an alternative to the usual method of creating a mirror RB experiment design by sampling a number of circuits randomly. This function takes a list of previously-sampled random circuits and does not sampling internally.

Parameters
  • circuits_and_idealouts_by_depth (dict) – A dictionary whose keys are integer depths and whose values are lists of (circuit, ideal_outcome) 2-tuples giving each RB circuit and its ideal (correct) outcome.

  • qubit_labels (list, optional) – If not None, a list of the qubits that the RB circuit is to be sampled for. This should be all or a subset of the qubits in the device specified by the QubitProcessorSpec pspec. If None, it is assumed that the RB circuit should be over all the qubits. Note that the ordering of this list is the order of the ``wires’’ in the returned circuit, but is otherwise irrelevant.

  • sampler (str or function, optional) – If a string, this should be one of: {‘pairingQs’, ‘Qelimination’, ‘co2Qgates’, ‘local’}. Except for ‘local’, this corresponds to sampling layers according to the sampling function in rb.sampler named circuit_layer_by* (with * replaced by ‘sampler’). For ‘local’, this corresponds to sampling according to rb.sampler.circuit_layer_of_oneQgates [which is not a valid option for n-qubit MRB – it results in sim. 1-qubit MRB – but it is not explicitly forbidden by this function]. If sampler is a function, it should be a function that takes as the first argument a QubitProcessorSpec, and returns a random circuit layer as a list of gate Label objects. Note that the default ‘Qelimination’ is not necessarily the most useful in-built sampler, but it is the only sampler that requires no parameters beyond the QubitProcessorSpec and works for arbitrary connectivity devices. See the docstrings for each of these samplers for more information.

  • samplerargs (list, optional) – A list of arguments that are handed to the sampler function, specified by sampler. The first argument handed to the sampler is pspec and samplerargs lists the remaining arguments handed to the sampler.

  • localclifford (bool, optional) – Whether to start the circuit with uniformly random 1-qubit Cliffords and all of the qubits (compiled into the native gates of the device).

  • paulirandomize (bool, optional) – Whether to have uniformly random Pauli operators on all of the qubits before and after all of the layers in the “out” and “back” random circuits. At length 0 there is a single layer of random Pauli operators (in between two layers of 1-qubit Clifford gates if localclifford is True); at length l there are 2l+1 Pauli layers as there are

  • fixed_versus_depth (bool, optional) – <TODO description>

  • descriptor (str, optional) – A string describing the generated experiment. Stored in the returned dictionary.

Returns

PeriodicMirrorCircuitDesign

_init_foundation(self, depths, circuit_lists, ideal_outs, circuits_per_depth, qubit_labels, sampler, samplerargs, localclifford, paulirandomize, fixed_versus_depth, descriptor)
class pygsti.protocols.vb.SummaryStatistics(name)

Bases: pygsti.protocols.protocol.Protocol

A protocol that can construct “summary” quantities from raw data.

Parameters

name (str) – The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

summary_statistics

Static list of the categories of summary information this protocol can compute.

Type

tuple

circuit_statistics

Static list of the categories of circuit information this protocol can compute.

Type

tuple

summary_statistics = ['success_counts', 'total_counts', 'hamming_distance_counts', 'success_probabilities',...
circuit_statistics = ['two_q_gate_count', 'depth', 'idealout', 'circuit_index', 'width']
_compute_summary_statistics(self, data)

Computes all summary statistics for the given data.

Parameters

data (ProtocolData) – The data to operate on.

Returns

NamedDict

_compute_circuit_statistics(self, data)

Computes all circuit statistics for the given data.

Parameters

data (ProtocolData) – The data to operate on.

Returns

NamedDict

_compute_predicted_probs(self, data, model)

Compute the predicted success probabilities of model given data.

Parameters
Returns

NamedDict

_compute_dict(self, data, component_names, compute_fn, for_passes='all')

Executes a computation function row-by-row on the data in data and packages the results.

Parameters
  • data (ProtocolData) – The data.

  • component_names (list or tuple) – A sequence of string-valued component names which must be the keys of the dictionary returned by compute_fn.

  • compute_fn (function) – A function that computes values for each item in component_names for each row of data. This function should have signature: compute_fn(icirc : int, circ : Circuit, dsrow : _DataSetRow, idealout : OutcomeLabel) and should return a dictionary whose keys are the same as component_names.

  • for_passes ({'all', 'none', 'first'}) – UNUSED. What passes within data values are computed for.

Returns

NamedDict – A nested dictionary with indices: component-name, depth, circuit-index (the last level is a list, not a dict).

_create_depthwidth_dict(self, depths, widths, fillfn, seriestype)

Create a nested NamedDict with depht and width indices.

Parameters
  • depths (list or tuple) – The (integer) depths to use.

  • widths (list or tuple) – The (integer) widths to use.

  • fillfn (function) – A function with no arguments that is called to return a default value for each (depth, width).

  • seriestype ({"float", "int"}) – The type of values held by this nested dict.

Returns

NamedDict

_add_bootstrap_qtys(self, data_cache, num_qtys, finitecounts=True)

Adds bootstrapped “summary data”.

The bootstrap is over both the finite counts of each circuit and over the circuits at each length.

Note: only adds quantities if they’re needed.

Parameters
  • data_cache (dict) – A cache of already-existing bootstraps.

  • num_qtys (int, optional) – The number of bootstrapped data to construct.

  • finitecounts (bool, optional) – Whether finite counts should be used, i.e. whether the bootstrap samples include finite sample error with the same number of counts as the sampled data, or whether they have no finite sample error (just probabilities).

Returns

None

class pygsti.protocols.vb.ByDepthSummaryStatistics(depths='all', statistics_to_compute=('polarization',), names_to_compute=None, custom_data_src=None, name=None)

Bases: SummaryStatistics

A protocol that computes summary statistics for data organized into by-depth circuit lists.

Parameters
  • depths (list or "all", optional) – A sequence of the depths to compute summary statistics for or the special “all” value which means “all the depths in the data”. If data being processed does not contain a given value in depths, it is just ignored.

  • statistics_to_compute (tuple, optional) – A sequence of the statistic names to compute. Allowed names are: ‘success_counts’, ‘total_counts’, ‘hamming_distance_counts’, ‘success_probabilities’, ‘polarization’, ‘adjusted_success_probabilities’, ‘two_q_gate_count’, ‘depth’, ‘idealout’, ‘circuit_index’, and ‘width’.

  • names_to_compute (tuple, optional) – A sequence of user-defined names for the statistics in statistics_to_compute. If None, then the statistic names themselves are used. These names are the column names produced by calling to_dataframe on this protocol’s results, so can be useful to name the computed statistics differently from the statistic name itself to distinguish it from the same statistic run on other data, when you want to combine data frames generated from multiple ProtocolData objects.

  • custom_data_src (SuccessFailModel, optional) – An alternate source of the data counts used to compute the desired summary statistics. Currently this can only be a SuccessFailModel.

  • name (str, optional) – The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

_get_statistic_per_depth(self, statistic, data)
run(self, data, memlimit=None, comm=None, dscomparator=None)

Run this protocol on data.

Parameters
  • results (ProtocolResults or ProtocolResultsDir) – The input results.

  • memlimit (int, optional) – A rough per-processor memory limit in bytes.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator used to run this protocol in parallel.

  • dscomparator (DataComparator) – Special additional comparator object for comparing data sets.

Returns

SummaryStatisticsResults

class pygsti.protocols.vb.SummaryStatisticsResults(data, protocol_instance)

Bases: pygsti.protocols.protocol.ProtocolResults

Summary statistics computed for a set of data.

Usually the result of running a SummaryStatistics (or derived) protocol.

Parameters
  • data (ProtocolData) – The experimental data these results are generated from.

  • protocol_instance (Protocol) – The protocol that generated these results.

_my_attributes_as_nameddict(self)

Overrides base class behavior so elements of self.statistics form top-level NamedDict