Qiskit Experiments is built on top of Qiskit, so we recommend that you first install Qiskit following its installation guide. Qiskit Experiments supports the same platforms as Qiskit itself and Python versions 3.8 through 3.12.
Qiskit Experiments releases can be installed via the Python package manager pip
in your shell environment:
python -m pip install qiskit-experiments
There are a number of optional packages that enable some experiments and features. If you would like to install these optional dependencies, run:
python -m pip install "qiskit-experiments[extras]"
If you want to run the most up-to-date version instead (may not be stable), you can install the latest main branch:
python -m pip install git+https://github.com/Qiskit-Extensions/qiskit-experiments.git
If you want to develop the package, you can install Qiskit Experiments from source by cloning the repository:
git clone https://github.com/Qiskit-Extensions/qiskit-experiments.git python -m pip install -e "qiskit-experiments[extras]"
The -e option will keep your installed package up to date as you make or pull new
changes.
Let's run a :class:`.T1` Experiment, which estimates the characteristic relaxation time of a qubit from the excited state to the ground state, also known as T_1, by measuring the excited state population after varying delays. First, we have to import the experiment from the Qiskit Experiments library:
.. jupyter-execute::
from qiskit_experiments.library import T1
Experiments must be run on a backend. We're going to use a simulator, :class:`~qiskit_ibm_runtime.fake_provider.FakePerth`, for this example, but you can use any backend, real or simulated, that you can access through Qiskit.
Note
This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
packages to run simulations. You can install them with python -m pip
install qiskit-aer qiskit-ibm-runtime.
.. jupyter-execute::
from qiskit_ibm_runtime.fake_provider import FakePerth
from qiskit_aer import AerSimulator
backend = AerSimulator.from_backend(FakePerth())
All experiments require a physical_qubits parameter as input that specifies which
physical qubit or qubits the circuits will be executed on. The qubits must be given as a
Python sequence (usually a tuple or a list).
Note
Since 0.5.0, using qubits instead of physical_qubits or specifying an
integer qubit index instead of a one-element sequence for a single-qubit experiment
is deprecated.
In addition, the T_1 experiment has
a second required parameter, delays, which is a list of times in seconds at which to
measure the excited state population. In this example, we'll run the T_1
experiment on qubit 0, and use the t1 backend property of this qubit to give us a
good estimate for the sweep range of the delays.
.. jupyter-execute::
import numpy as np
qubit0_t1 = FakePerth().qubit_properties(0).t1
delays = np.arange(1e-6, 3 * qubit0_t1, 3e-5)
exp = T1(physical_qubits=(0,), delays=delays)
The circuits encapsulated by the experiment can be accessed using the experiment's :meth:`~.BaseExperiment.circuits` method, which returns a list of circuits that can be run on a backend. Let's print the range of delay times we're sweeping over and draw the first and last circuits for our T_1 experiment:
.. jupyter-execute::
print(delays)
exp.circuits()[0].draw(output="mpl", style="iqp")
.. jupyter-execute::
exp.circuits()[-1].draw(output="mpl", style="iqp")
As expected, the delay block spans the full range of time values that we specified.
The :class:`.ExperimentData` class
After instantiating the experiment, we run the experiment by calling :meth:`~.BaseExperiment.run` with our backend of choice. This transpiles our experiment circuits then packages them into jobs that are run on the backend.
Note
See the how-tos for :doc:`customizing job splitting </howtos/job_splitting>` when running an experiment.
This statement returns the :class:`.ExperimentData` class containing the results of the experiment, so it's crucial that we assign the output to a data variable. We could have also provided the backend at the instantiation of the experiment, but specifying the backend at run time allows us to run the same exact experiment on different backends should we choose to do so.
.. jupyter-execute::
exp_data = exp.run(backend=backend).block_for_results()
The :meth:`~.ExperimentData.block_for_results` method is optional and is used to block execution of subsequent code until the experiment has fully completed execution and analysis. If
.. jupyter-input::
exp_data = exp.run(backend=backend)
is executed instead, the statement will finish running as soon as the jobs are
submitted, but the analysis callback won't populate exp_data with results until the
entire process has finished. In this case, there are two useful methods in the
:class:`.ExperimentData`, :meth:`~.ExperimentData.job_status` and
:meth:`~.ExperimentData.analysis_status`, that return the current status of the job and
analysis, respectively:
.. jupyter-execute::
print(exp_data.job_status())
print(exp_data.analysis_status())
Once the analysis is complete, figures are retrieved using the :meth:`~.ExperimentData.figure` method. See the :doc:`visualization module <visualization>` tutorial on how to customize figures for an experiment. For our T_1 experiment, we have a single figure showing the raw data and fit to the exponential decay model of the T_1 experiment:
.. jupyter-execute::
display(exp_data.figure(0))
The analysis results resulting from the fit are accessed with :meth:`~.ExperimentData.analysis_results`:
.. jupyter-execute::
for result in exp_data.analysis_results():
print(result)
Results can be indexed numerically (starting from 0) or using their name. Analysis results can also be
retrieved in the pandas :class:`~pandas:pandas.DataFrame` format by passing dataframe=True:
.. jupyter-execute::
exp_data.analysis_results(dataframe=True)
Note
See the :meth:`~.ExperimentData.analysis_results` API documentation for more advanced usage patterns to access subsets of analysis results.
Each analysis
result value is a UFloat object from the uncertainties package. The nominal
value and standard deviation of each value can be accessed as follows:
.. jupyter-execute::
print(exp_data.analysis_results("T1").value.nominal_value)
print(exp_data.analysis_results("T1").value.std_dev)
For further documentation on how to work with UFloats, consult the uncertainties
:external+uncertainties:doc:`user_guide`.
The curve fit data itself is contained in :meth:`~.ExperimentData.artifacts`, which are accessed
in an analogous manner. Artifacts for a standard experiment include both the curve fit data
stored in artifacts("curve_data") and information on the fit stored in artifacts("fit_summary").
Use the data attribute to access artifact data:
.. jupyter-execute::
print(exp_data.artifacts("fit_summary").data)
Note
See the :doc:`artifacts </howtos/artifacts>` how-to for more information on using artifacts.
Raw circuit output data and its associated metadata can be accessed with the
:meth:`~.ExperimentData.data` property. Data is indexed by the circuit it corresponds
to. Depending on the measurement level set in the experiment, the raw data will either
be in the key counts (level 2) or memory (level 1 IQ data).
Note
See the :doc:`data processor tutorial <data_processor>` for more information on level 1 and level 2 data.
Circuit metadata contains information set by the experiment on a circuit-by-circuit
basis; xval is used by the analysis to extract the x value for each circuit when
fitting the data.
.. jupyter-execute::
print(exp_data.data(0))
Experiments also have global associated metadata accessed by the :meth:`~.ExperimentData.metadata` property.
.. jupyter-execute::
print(exp_data.metadata)
The actual backend jobs that were executed for the experiment can be accessed with the :meth:`~.ExperimentData.jobs` method.
Note
See the how-tos for :doc:`rerunning the analysis </howtos/rerun_analysis>` for an existing experiment that finished execution.
It's often insufficient to run an experiment with only its default options. There are four types of options one can set for an experiment:
These options are passed to the experiment's :meth:`~.BaseExperiment.run` method and
then to the run() method of your specified backend. Any run option that your backend
supports can be set:
.. jupyter-execute::
from qiskit.qobj.utils import MeasLevel
exp.set_run_options(shots=1000,
meas_level=MeasLevel.CLASSIFIED)
print(f"Shots set to {exp.run_options.get('shots')}, "
"measurement level set to {exp.run_options.get('meas_level')}")
Consult the documentation of the run method of your specific backend type for valid options. For example, see :meth:`qiskit_ibm_provider.IBMBackend.run` for IBM backends.
These options are passed to the Qiskit :mod:`~qiskit.transpiler` to transpile the experiment circuits before execution:
.. jupyter-execute::
exp.set_transpile_options(scheduling_method='asap',
optimization_level=3,
basis_gates=["x", "sx", "rz"])
print(f"Transpile options are {exp.transpile_options}")
Consult the documentation of :func:`qiskit.compiler.transpile` for valid options.
These options are unique to each experiment class. Many experiment options can be set upon experiment instantiation, but can also be explicitly set via :meth:`~.BaseExperiment.set_experiment_options`:
.. jupyter-execute::
exp = T1(physical_qubits=(0,), delays=delays)
new_delays=np.arange(1e-6, 600e-6, 50e-6)
exp.set_experiment_options(delays=new_delays)
print(f"Experiment options are {exp.experiment_options}")
Consult the :doc:`API documentation </apidocs/index>` for the options of each experiment class.
These options are unique to each analysis class. Unlike the other options, analysis
options are not directly set via the experiment object but use instead a method of the
associated analysis:
.. jupyter-execute::
from qiskit_experiments.library import StandardRB
exp = StandardRB(physical_qubits=(0,),
lengths=list(range(1, 300, 30)),
seed=123,
backend=backend)
exp.analysis.set_options(gate_error_ratio=None)
Consult the :doc:`API documentation </apidocs/index>` for the options of each experiment's analysis class.
To run experiments across many qubits of the same device, we use composite experiments. A :class:`.CompositeExperiment` is a parent object that contains one or more child experiments, which may themselves be composite. There are two core types of composite experiments:
- Parallel experiments run across qubits simultaneously as set by the user. The
circuits of child experiments are combined into new circuits that map circuit gates
onto qubits in parallel. Therefore, the circuits in child experiments cannot overlap
in the
physical_qubitsparameter. The marginalization of measurement data for analysis of each child experiment is handled automatically. - Batch experiments run consecutively in time. These child circuits can overlap in qubits used.
Using parallel experiments, we can measure the T_1 of one qubit while doing a standard Randomized Benchmarking :class:`.StandardRB` experiment on other qubits simultaneously on the same device:
.. jupyter-execute::
from qiskit_experiments.framework import ParallelExperiment
child_exp1 = T1(physical_qubits=(2,), delays=delays)
child_exp2 = StandardRB(physical_qubits=(3,1), lengths=np.arange(1,100,10), num_samples=2)
parallel_exp = ParallelExperiment([child_exp1, child_exp2], flatten_results=False)
Note that when the transpile and run options are set for a composite experiment, the child experiments's options are also set to the same options recursively. Let's examine how the parallel experiment is constructed by visualizing child and parent circuits. The child experiments can be accessed via the :meth:`~.CompositeExperiment.component_experiment` method, which indexes from zero:
.. jupyter-execute::
parallel_exp.component_experiment(0).circuits()[0].draw(output="mpl", style="iqp")
.. jupyter-execute::
parallel_exp.component_experiment(1).circuits()[0].draw(output="mpl", style="iqp")
Similarly, the child analyses can be accessed via :meth:`.CompositeAnalysis.component_analysis` or via the analysis of the child experiment class:
.. jupyter-execute::
parallel_exp.component_experiment(0).analysis.set_options(plot = True)
# This should print out what we set because it's the same option
print(parallel_exp.analysis.component_analysis(0).options.get("plot"))
The circuits of all experiments assume they're acting on virtual qubits starting from index 0. In the case of a parallel experiment, the child experiment circuits are composed together and then reassigned virtual qubit indices:
.. jupyter-execute::
parallel_exp.circuits()[0].draw(output="mpl", style="iqp")
During experiment transpilation, a mapping is performed to place these circuits on the
physical layout. We can see its effects by looking at the transpiled
circuit, which is accessed via the internal method _transpiled_circuits(). After
transpilation, the :class:`.T1` experiment is correctly placed on physical qubit 2
and the :class:`.StandardRB` experiment's gates are on physical qubits 3 and 1.
.. jupyter-execute::
parallel_exp._transpiled_circuits()[0].draw(output="mpl", style="iqp")
:class:`.ParallelExperiment` and :class:`.BatchExperiment` classes can also be nested arbitrarily to make complex composite experiments.
The experiment data returned from a composite experiment contains individual analysis results for each child experiment that can be accessed using :meth:`~.ExperimentData.child_data`. By default, the parent data object does not contain analysis results.
Note
This behavior will be updated in Qiskit Experiments 0.7.
By default, all analysis results will be stored in the parent data object,
and you need to explicitly set flatten_results=False to generate child data objects.
.. jupyter-execute::
parallel_data = parallel_exp.run(backend, seed_simulator=101).block_for_results()
for i, sub_data in enumerate(parallel_data.child_data()):
print("Component experiment",i)
display(sub_data.figure(0))
for result in sub_data.analysis_results():
print(result)
If you want the parent data object to contain the analysis results instead, you can set
the flatten_results flag to true to flatten the results of all component experiments
into one level:
.. jupyter-execute::
parallel_exp = ParallelExperiment(
[T1(physical_qubits=(i,), delays=delays) for i in range(2)], flatten_results=True
)
parallel_data = parallel_exp.run(backend, seed_simulator=101).block_for_results()
parallel_data.analysis_results(dataframe=True)
Use the broadcast parameter to set analysis options to each of the child experiments.
.. jupyter-execute::
parallel_exp.analysis.set_options(plot=False, broadcast=True)
If the child experiment inherits from :class:`.CompositeExperiment` (such as :class:`.ParallelExperiment` and :class:`.BatchExperiment` classes), this process will continue to work recursively. In this instance, the analysis will not generate a figure for the child experiment after the analysis.