Experiment Framework (
This page provides useful information for developers to implement new experiments.
The experiment framework broadly defines an experiment as the execution of 1 or more circuits on a device, and analysis of the resulting measurement data to return 1 or more derived results.
The interface for running an experiment is through the Experiment classes,
such as those contained in the
The following pseudo-code illustrates the typical workflow in Qiskit Experiments
Initializing a new experiment
Running the experiment on a backend
Saving result to an online database (for compatible providers)
Viewing analysis results
# Import an experiment from qiskit_experiments.library import SomeExperiment # Initialize with desired qubits and options exp = SomeExperiment(qubits, **options) # Run on a backend exp_data = exp.run(backend) # Wait for execution and analysis to finish exp_data.block_for_results() # Optionally save results to database exp_data.save() # View analysis results for result in exp_data.analysis_results(): print(result)
The experiment class contains information for generating circuits and analysis
of results. These can typically be configured with a variety of options.
Once all options are set, you can call
BaseExperiment.run() method to run
the experiment on a Qiskit compatible
The steps of running an experiment involves generation experimental circuits
according to the options you set and submission of a job to the specified
backend. Once the job has finished executing an analysis job performs
data analysis of the experiment execution results.
The result of running an experiment is an
which contains the analysis results, any figures generated during analysis,
and the raw measurement data. These can each be accessed using the
ExperimentData.data() methods respectively.
Analysis/plotting is done in a separate child thread, so it doesn’t block the
main thread. Since matplotlib doesn’t support GUI mode in a child threads, the
figures generated during analysis need to use a non-GUI canvas. The default is
FigureCanvasSVG, but you can change it to a different
by setting the
attribute. For example, you can set
FigureCanvasAgg to use the
For experiments run through a compatible provider such as the
ExperimentData object can be saved to an online experiment
database by calling the
ExperimentData.save() method. This data can
later be retrieved by its unique
ParallelExperimentcombines all the sub experiment circuits into circuits which run the component gates in parallel on the respective qubits. The marginalization of measurement data for analysis of each sub-experiment is handled automatically. To run as a parallel experiment each sub experiment must be defined on a independent subset of device qubits.
BatchExperimentcombines the sub-experiment circuits into a single large job that runs all the circuits for each experiment in series. Filtering the batch result data for analysis for each sub-experiment is handled automatically.
Creating Custom Experiments¶
Qiskit experiments provides a framework for creating custom experiments which can be through Qiskit and stored in the online database when run through the IBMQ provider. You may use this framework to release your own module of experiments subject to the requirements of the Apache 2.0 license.
The experiment class generates the list of circuits to be executed on the backend and any corresponding metadata that is required for the analysis of measurement results.
The analysis class performs post-processing of the measurement results after execution. Analysis classes can be re-used between experiments so you can either use one of the included analysis classes if appropriate or implement your own.
To create an experiment subclass
Implement the abstract
BaseExperiment.circuits()method. This should return a list of
QuantumCircuitobjects defining the experiment payload.
BaseExperiment.__init__()method during the subclass constructor with a list of physical qubits. The length of this list must be equal to the number of qubits in each circuit and is used to map these circuits to this layout during execution. Arguments in the constructor can be overridden so that a subclass can be initialized with some experiment configuration.
Optionally the following methods can also be overridden in the subclass to allow configuring various experiment and execution options
BaseExperiment._default_experiment_options()to set default values for configurable option parameters for the experiment.
BaseExperiment._default_transpile_options()to set custom default values for the
qiskit.transpileused to transpile the generated circuits before execution.
BaseExperiment._default_run_options()to set default backend options for running the transpiled circuits on a backend.
BaseExperiment._default_analysis_options()to set default values for configurable options for the experiments analysis class. Note that these should generally be set by overriding the
BaseAnalysis._default_options()instead of this method except in the case where the experiment requires different defaults to the used analysis class.
BaseExperiment._transpiled_circuits()to override the default transpilation of circuits before execution.
BaseExperiment._metadata()to add any experiment metadata to the result data.
Furthermore, some characterization and calibration experiments can be run with restless
measurements, i.e. measurements where the qubits are not reset and circuits are executed
immediately after the previous measurement. Here, the
RestlessMixin can help
to set the appropriate run options and data processing chain.
To create an analysis subclass one only needs to implement the abstract
BaseAnalysis._run_analysis() method. This method takes a
ExperimentData container and kwarg analysis options. If any
kwargs are used the
BaseAnalysis._default_options() method should be
overriden to define default values for these options.
qiskit_experiments.data_processing module contains classes for
building data processor workflows to help with advanced analysis of
Experiment Data Classes¶
Qiskit Experiments Data container class
Class for experiment status enumerated type.
Class for job status enumerated type.
Class for analysis callback status enumerated type.
Dataclass for experiment analysis results
Store configuration settings for an Experiment
Store configuration settings for Analysis
JSON Encoder for Qiskit Experiments.
JSON Decoder for Qiskit Experiments.
Composite Experiment Classes¶
Combine multiple experiments into a parallel experiment.
Combine multiple experiments into a batch experiment.
Run analysis for composite experiments.
Abstract base class for experiments.
Abstract base class for analyzing Experiment data.
A mixin to facilitate restless experiments.