Experiment Framework (qiskit_experiments.framework)


The experiment framework broadly defines an experiment as the execution of one or more circuits on a device, and analysis of the resulting measurement data to return one or more derived results.

The interface for running an experiment is through the Experiment classes subclassed from BaseExperiment, such as those contained in the library. The following pseudo-code illustrates the typical workflow in Qiskit Experiments for

  • 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(physical_qubits, **options)

# Run on a backend
exp_data = exp.run(backend)

# Wait for execution and analysis to finish

# Optionally save results to database

# View analysis results
for result in exp_data.analysis_results():

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 the BaseExperiment.run() method to run the experiment on a Qiskit compatible backend.

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 ExperimentData container which contains the analysis results, any figures generated during analysis, and the raw measurement data. These can each be accessed using the ExperimentData.analysis_results(), ExperimentData.figure() and ExperimentData.data() methods respectively. Additional metadata for the experiment itself can be added via ExperimentData.metadata().


Experiment Data Classes

ExperimentData([experiment, backend, ...])

Experiment data container class.

ExperimentStatus(value[, names, module, ...])

Class for experiment status enumerated type.

AnalysisStatus(value[, names, module, ...])

Class for analysis callback status enumerated type.

AnalysisResult([name, value, ...])

Class representing an analysis result for an experiment.

AnalysisResultData(name, value[, ...])

Dataclass for experiment analysis results


A table-like dataset for analysis results.

ExperimentConfig([cls, args, kwargs, ...])

Store configuration settings for an Experiment class.

AnalysisConfig([cls, args, kwargs, options, ...])

Store configuration settings for an Analysis class.

ExperimentEncoder(*[, skipkeys, ...])

JSON Encoder for Qiskit Experiments.

ExperimentDecoder(*args, **kwargs)

JSON Decoder for Qiskit Experiments.

ArtifactData(name, data[, artifact_id, ...])

A dataclass for non-analysis result payloads in ExperimentData objects.

FigureData(figure[, name, metadata])

A plot data container.

Composite Experiment Classes

CompositeExperiment(experiments, physical_qubits)

Composite Experiment base class

ParallelExperiment(experiments[, backend, ...])

Combine multiple experiments into a parallel experiment.

BatchExperiment(experiments[, backend, ...])

Combine multiple experiments into a batch experiment.

CompositeAnalysis(analyses[, ...])

Run analysis for composite experiments.

Base Classes

BaseExperiment(physical_qubits[, analysis, ...])

Abstract base class for experiments.


Abstract base class for analyzing Experiment data.

Experiment Configuration Helper Classes


Class for providing joint interface for accessing backend data

BackendTiming(backend, *[, ...])

Helper for calculating pulse and delay times for an experiment


A mixin to facilitate restless experiments.