Add support executing circuits with a SamplerV2 instance (#1470)

This change adds a `sampler` argument to `BaseExperiment.run()` which
causes that `BaseSamplerV2` instance to be used to run the experiment's
circuits. Additionally, if no `sampler` is passed,
`BaseExperiment.run()` defaults to instantiating a
`qiskit_ibm_runtime.SamplerV2` object and running the circuits with
that. `qiskit_ibm_runtime.SamplerV2` can execute using IBM Quantum's
sampler primitive and can also fall back to calling `backend.run` for
backends that are not representing IBM Quantum devices. A `backend_run`
parameter is also added to `BaseExperiment.run()` which causes the old
`backend.run()` execution path to be used. For sampler execution, the
job results are translated back into the format expected from
`backend.run` so that the remaining analysis code can be used unchanged.
Some additional changes have been made to account for differences
between `backend.run` job result classes and primitive job result
classes.

---------

Co-authored-by: Will Shanks <[email protected]>

Author: dcmckayibm

docs/howtos/artifacts.rst

@@ -25,6 +25,13 @@ Viewing artifacts
 Here we run a parallel experiment consisting of two :class:`.T1` experiments in parallel and then view the output
 artifacts as a list of :class:`.ArtifactData` objects accessed by :meth:`.ExperimentData.artifacts`:
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     from qiskit_ibm_runtime.fake_provider import FakePerth

docs/howtos/runtime_sessions.rst

@@ -1,29 +1,30 @@
-Use Experiments with Runtime sessions
-=====================================
+Use Experiments with Sampler
+=============================
 
 Problem
 -------
 
-You want to run experiments in a `Runtime session
-<https://docs.quantum.ibm.com/run/sessions>`_ so that jobs can run in close temporal proximity.
+You want to run experiments with a custom :class:`qiskit.primitives.BaseSamplerV2` service. 
+A sampler can be instantiated with a backend, session or batch, which allows one to 
+run an experiment in different execution modes.
+
+.. note::
+    All jobs, by default, run using the :class:`qiskit_ibm_runtime.SamplerV2` class. When calling ``exp.run`` a 
+    :class:`qiskit_ibm_runtime.SamplerV2` object will be automatically generated to wrap the specified backend.
 
 Solution
 --------
 
-.. note::
-    This guide requires :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older ``qiskit-ibm-provider`` to :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
-    consult the `migration guide <https://docs.quantum.ibm.com/api/migration-guides/qiskit-runtime-from-provider>`_.\
-
-Use the :class:`~qiskit_ibm_runtime.IBMBackend` object in :external+qiskit_ibm_runtime:doc:`index`, which supports sessions.
+In this example, we will pass in a :class:`qiskit_ibm_runtime.SamplerV2` object to a tomography experiment.
 
-In this example, we will set the ``max_circuits`` property to an artificially low value so that the experiment will be
-split into multiple jobs that run sequentially in a single session. When running real experiments with a
-large number of circuits that can't fit in a single job, it may be helpful to follow this usage pattern:
+.. note::
+    If a sampler object is passed to :meth:`qiskit_experiments.framework.BaseExperiment.run` then the `run options 
+    <https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerExecutionOptionsV2>`_ of the 
+    sampler object are used. The execution options set by the experiment are ignored.
 
 .. jupyter-input::
 
-    from qiskit_ibm_runtime import QiskitRuntimeService
+    from qiskit_ibm_runtime import SamplerV2 as Sampler
     from qiskit_experiments.library.tomography import ProcessTomography
     from qiskit import QuantumCircuit
 
@@ -32,13 +33,14 @@ large number of circuits that can't fit in a single job, it may be helpful to fo
     qc = QuantumCircuit(1)
     qc.x(0)
 
-    backend.open_session()
+    sampler = Sampler(backed)
+    # set the shots in the sampler object
+    sampler.options.default_shots = 300
     exp = ProcessTomography(qc)
     # Artificially lower circuits per job, adjust value for your own application
     exp.set_experiment_options(max_circuits=3)
-    exp_data = exp.run(backend)
-    # This will prevent further jobs from being submitted without terminating current jobs
-    backend.close_session()
+    # pass the sampler into the experiment
+    exp_data = exp.run(sampler=sampler)
+
+
 
-Note that runtime primitives are not currently supported natively in Qiskit Experiments, so  
-the ``backend.run()`` path is required to run experiments.

docs/manuals/characterization/t1.rst

@@ -34,6 +34,13 @@ for qubit 0.
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     import numpy as np

docs/manuals/characterization/t2ramsey.rst

@@ -62,6 +62,13 @@ pure T1/T2 relaxation noise model.
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     # A T1 simulator

docs/manuals/characterization/tphi.rst

@@ -25,6 +25,13 @@ From the :math:`T_1` and :math:`T_2` estimates, we compute the results for
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     import numpy as np

docs/manuals/measurement/readout_mitigation.rst

@@ -35,6 +35,13 @@ experiments to generate the corresponding mitigators.
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     import numpy as np

docs/manuals/measurement/restless_measurements.rst

@@ -62,6 +62,13 @@ they use always starts with the qubits in the ground state.
     This tutorial requires the :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` package to model a
     backend.  You can install it with ``python -m pip install qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     from qiskit_ibm_runtime.fake_provider import FakePerth

docs/manuals/verification/quantum_volume.rst

@@ -29,6 +29,13 @@ z_value = 2), and at least 100 trials have been ran.
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     from qiskit_experiments.framework import BatchExperiment

docs/manuals/verification/randomized_benchmarking.rst

@@ -16,6 +16,13 @@ explanation on the RB method, which is based on Refs. [1]_ [2]_.
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     import numpy as np

docs/manuals/verification/state_tomography.rst

@@ -14,6 +14,13 @@ complete basis of measurement operators.
 
 We first initialize a simulator to run the experiments on.
 
+.. jupyter-execute::
+    :hide-code:
+
+    # Temporary workaround for missing support in Qiskit and qiskit-ibm-runtime
+    from qiskit_experiments.test.patching import patch_sampler_test_support
+    patch_sampler_test_support()
+
 .. jupyter-execute::
 
     from qiskit_aer import AerSimulator