pygsti.protocols.scarab
scarab is a software tool for creating scalable, robust benchmarks from any quantum circuit. Please see https://arxiv.org/abs/2511.02134 for more information.
Module Contents
Functions
Create a noise benchmark from transpiled Qiskit circuits. |
|
Create a full-stack benchmark from high-level Qiskit circuits. |
|
Create a subcircuit benchmark from transpiled Qiskit circuits. |
|
Create a dataframe from MCFE data and edesigns. |
- pygsti.protocols.scarab.lowlevel_mirror_benchmark(qk_circs: Dict[Any, qiskit.QuantumCircuit] | List[qiskit.QuantumCircuit], mirroring_kwargs_dict: Dict[str, Any] = {}) Tuple[pygsti.protocols.FreeformDesign, pygsti.protocols.CombinedExperimentDesign]
Create a noise benchmark from transpiled Qiskit circuits.
Parameters
- qk_circsList[qiskit.QuantumCircuit] | Dict[qiskit.QuantumCircuit]
Qiskit QuantumCircuits from which a noise benchmark is to be created. If a dictionary is provided, those keys are used. If a list is provided, default integer keys are used.
- mirroring_kwargs_dictdict, optional
dictionary of keyword arguments to be used in circuit mirroring. If an arg is not provided, a default value is used. The args are:
‘mirror_circuits_per_circ’: default 10. The number of mirror circuits of the test-exact and exact-exact varieties to be used for the process fidelity estimation of each provided Qiskit circuit.
‘num_ref_per_qubit_subset’: default 10. The number of SPAM reference circuits to use for each qubit subset that is represented among the provided Qiskit circuits.
‘rand_state’: default None. np.random.RandomState to be used for circuit mirroring.
Returns
- Tuple
- pygsti.protocols.FreeformDesign
Experiment design containing the pyGSTi conversion of all Qiskit circuits that were passed in. Does not need executed, but is needed for fidelity calculations.
- pygsti.protocols.CombinedExperimentDesign
Experiment design containing all mirror circuits that must be executed in order to perform mirror circuit fidelity estimation.
- pygsti.protocols.scarab.fullstack_mirror_benchmark(qk_circs: Dict[Any, qiskit.QuantumCircuit] | List[qiskit.QuantumCircuit], qk_backend: qiskit.providers.BackendV2 | None = None, coupling_map: qiskit.transpiler.CouplingMap | None = None, basis_gates: List[str] | None = None, transpiler_kwargs_dict: Dict[str, Any] = {}, mirroring_kwargs_dict: Dict[str, Any] = {}, num_transpilation_attempts: int = 100, return_qiskit_time: bool = False) Tuple[pygsti.protocols.FreeformDesign, pygsti.protocols.CombinedExperimentDesign]
Create a full-stack benchmark from high-level Qiskit circuits.
Parameters
- qk_circsList[qiskit.QuantumCircuit] | Dict[qiskit.QuantumCircuit]
Qiskit QuantumCircuits from which a full-stack benchmark is to be created. If a dictionary is provided, those keys are used. If a list is provided, default integer keys are used.
- qk_backendqiskit-ibm-runtime.IBMBackend, optional
IBM backend whose native gate set, connectivity, and error rates are to be targeted when doing a full-stack transpilation. Fake backends are also acceptable. If not provided, both coupling_map and basis_gates must be provided, and certain transpiler optimizations that depend on backend error rates may not be accessible.
- coupling_mapqiskit.transpiler.CouplingMap, optional
couplinp map for a target backend that must be provided if qk_backend is None. This argument is ignored if qk_backend is not None.
- basis_gateslist[str], optional
list of native gates for a target backend that must be provided if qk_backend is None. This argument is ignored if qk_backend is not None.
- transpiler_kwargs_dictdict, optional
keyword arguments that are passed to the Qiskit transpiler for full-stack transpilation. Please see the Qiskit transpiler documentation for a comprehensive list of options. If any or all of the following keys are not provided, the listed defaults are used:
‘optimization_level’: default 3 ‘approximation_degree’: default 1.0 ‘seed_transpiler’: default None
- mirroring_kwargs_dictdict, optional
dictionary of keyword arguments to be used in circuit mirroring. If an arg is not provided, a default value is used. The args are:
‘mirror_circuits_per_circ’: default 10. The number of mirror circuits of the test-exact and exact-exact varieties to be used for the process fidelity estimation of each provided Qiskit circuit.
‘num_ref_per_qubit_subset’: default 10. The number of SPAM reference circuits to use for each qubit subset that is represented among the provided Qiskit circuits.
‘rand_state’: default None. np.random.RandomState to be used for circuit mirroring.
- num_transpilation_attemptsint, optional
number of times to attempt full-stack circuit transpilation. Circuit mirroring requires that the transpilation not use ancilla qubits, which is difficult to enforce with the other transpiler options. Instead, we adopt a try-until-success strategy, which may fail if an insufficient number of attempts are allowed. Increase this number if you are having issues with the transpilation. If not provided, the default is 100 attempts.
- return_qiskit_timebool, optional
Debug flag that sets whether or not to report the time spent in the Qiskit transpiler. Qiskit transpilation is often the most costly part of benchmark creation and it can be helpful to know how much time it is consuming.
Returns
- Tuple
- pygsti.protocols.FreeformDesign
Experiment design containing the pyGSTi conversion of all Qiskit circuits that were passed in. Does not need executed, but is needed for fidelity calculations.
- pygsti.protocols.CombinedExperimentDesign
Experiment design containing all mirror circuits that must be executed in order to perform mirror circuit fidelity estimation.
- float, optional
amount of time spent in Qiskit transpiler.
- pygsti.protocols.scarab.subcircuit_mirror_benchmark(qk_circs: Dict[Any, qiskit.QuantumCircuit] | List[qiskit.QuantumCircuit], aggregate_subcircs: bool, width_depth_dict: Dict[int, List[int]], coupling_map: qiskit.transpiler.CouplingMap, instruction_durations: qiskit.transpiler.InstructionDurations, subcirc_kwargs_dict: Dict[str, Any] = {}, mirroring_kwargs_dict: Dict[str, Any] = {}) Tuple[pygsti.protocols.FreeformDesign, pygsti.protocols.CombinedExperimentDesign]
Create a subcircuit benchmark from transpiled Qiskit circuits.
Parameters
- qk_circsList[qiskit.QuantumCircuit] | Dict[qiskit.QuantumCircuit]
Qiskit QuantumCircuits from which a subcircuit benchmark is to be created. If a dictionary is provided, those keys are used. If a list is provided, default integer keys are used.
- aggregate_subcircsbool
Whether or not the provided Qiskit circuits should be used to create one combined subcircuit experiment design or kept separate. Circuit aggregration can be useful if the provided circuits are all instances of the same ‘kind’ of the circuit, e.g., all Bernstein-Vazirani circuits with different secret keys.
- width_depth_dictdict[int, list[int]]
dictionary whose keys are subcircuit widths and whose values are lists of depths to snip out for that width.
- coupling_mapstr or qiskit.transpiler.CouplingMap
coupling map for the device the Qiskit circuits were transpiled to. If ‘all-to-all’, an all-to-all coupling map is used. If ‘linear’, a linear topology is used.
- instruction_durationsqiskit.transpiler.InstructionDurations
instruction durations for each gate in the target device. These durations are needed to calculate the appropriate delay time when only idling qubits are sampled out from a full circuit layer.
- subcirc_kwargs_dictdict, optional
dictionary of keyword arguments to be used in subcircuit selection. If an arg is not provided, a default value is used. The args are:
‘num_samples_per_width_depth’: default 10. number of subcircuits to sample from each full circuit. if aggregate_subcircuits is set to True, num_samplse_per_width_depth subcircuits are drawn from each full circuit and combined into one experiment design.
‘rand_state’: default None. np.random.RandomState to be used for subcircuit selection.
- mirroring_kwargs_dictdict, optional
dictionary of keyword arguments to be used in circuit mirroring If an arg is not provided, a default value is used. The args are:
‘mirror_circuits_per_circ’: default 10. The number of mirror circuits of the test-exact and exact-exact varieties to be used for the process fidelity estimation of each provided Qiskit circuit.
‘num_ref_per_qubit_subset’: default 10. The number of SPAM reference circuits to use for each qubit subset that is represented among the provided Qiskit circuits.
‘rand_state’: default None. np.random.RandomState to be used for circuit mirroring.
Returns
- Tuple
- dict[hashable, pygsti.protocols.FreeformDesign] or pygsti.protocols.FreeformDesign
Experiment design(s) containing the pyGSTi conversion of all Qiskit circuits that were passed in. Does not need executed, but is needed for fidelity calculations. A dictionary is returned if aggregate_subcircs is False, otherwise a FreeformDesign is returned.
- dict[hashable, pygsti.protocols.CombinedExperimentDesign] or pygsti.protocols.CombinedExperimentDesign
Experiment design(s) containing all mirror circuits that must be executed in order to perform mirror circuit fidelity estimation. A dictionary is returned if aggregate_subcircs is False, otherwise a FreeformDesign is returned.
- pygsti.protocols.scarab.calculate_mirror_benchmark_results(unmirrored_design: pygsti.protocols.FreeformDesign, mirrored_data: pygsti.protocols.ProtocolData, include_dropped_gates: bool = False, bootstrap: bool = True, num_bootstraps: int = 50, rand_state: numpy.random.RandomState = None, verbose: bool = False) pygsti.protocols.VBDataFrame
Create a dataframe from MCFE data and edesigns.
Parameters
- unmirrored_design: pygsti.protocols.protocol.FreeformDesign
Edesign containing the circuits whose process fidelities are to be estimated.
- mirrored_data: pygsti.protocols.protocol.ProtocolData
Data object containing the full mirror edesign and the outcome counts for each circuit in the full mirror edesign.
- include_dropped_gates: bool
Whether to include the number of gates dropped from each subcircuit during subcircuit creation. This flag should be set to False for noise benchmark and fullstack benchmark analysis, but can be set to True for subcircuit benchmark analysis. Default is False.
- bootstrap: bool
Toggle the calculation of error bars from bootstrapped process fidelity calculations. If True, error bars are calculated. If False, error bars are not calculated.
- num_bootstraps: int
Number of samples to draw from the bootstrapped process fidelity calculations. This argument is ignored if ‘bootstrap’ is False.
- rand_state: np.random.RandomState
random state used to seed bootstrapping. If ‘bootstrap’ is set to False, this argument is ignored.
- verbose: bool
Toggle print statements with debug information. If True, print statements are turned on. If False, print statements are omitted.
Returns
- VBDataFrame
A VBDataFrame whose dataframe contains calculated MCFE values and circuit statistics.