Add sessions how-to and update links

CONTRIBUTING.md

@@ -104,21 +104,17 @@ https://stestr.readthedocs.io/en/stable/MANUAL.html#test-selection
 If you want to run a single test module, test class, or individual test method you can
 do this faster with the `-n`/`--no-discover` option. For example, to run a module:
 ```
-tox -- -n test.python.test_examples
+tox -epy310 -- -n test.framework.test_composite
 ```
-Or to run the same module by path:
 
-```
-tox -- -n test/python/test_examples.py
-```
 To run a class:
-
 ```
-tox -- -n test.python.test_examples.TestPythonExamples
+tox -epy310 -- -n test.framework.test_composite.TestCompositeExperimentData
 ```
+
 To run a method:
 ```
-tox -- -n test.python.test_examples.TestPythonExamples.test_all_examples
+tox -epy310 -- -n test.framework.test_composite.TestCompositeExperimentData.test_composite_save_load
 ```
 
 Note that tests will fail automatically if they do not finish execution within 60 seconds.

docs/_ext/custom_styles/formatter.py

@@ -38,8 +38,7 @@ def format_header(self, lines: List[str]) -> List[str]:
     def format_overview(self, lines: List[str]) -> List[str]:
         """Format overview section."""
         format_lines = [
-            ""
-            ".. rubric:: Overview",
+            "" ".. rubric:: Overview",
             "",
         ]
         format_lines.extend(lines)
@@ -167,7 +166,7 @@ def format_analysis_opts(self, lines: List[str]) -> List[str]:
         format_lines = [
             ".. rubric:: Analysis options",
             "",
-            "These are the keyword arguments of :meth:`run` method.",
+            "These are the keyword arguments of the :meth:`run` method.",
             "",
         ]
         for line in _write_options(lines, self.indent):

docs/conf.py

@@ -174,6 +174,7 @@
     "qiskit_ibm_provider": ("https://qiskit.org/ecosystem/ibm-provider/", None),
     "qiskit_aer": ("https://qiskit.org/ecosystem/aer", None),
     "qiskit_dynamics": ("https://qiskit.org/documentation/dynamics", None),
+    "qiskit_ibm_runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None),
 }
 
 

docs/howtos/cloud_service.rst

@@ -189,11 +189,4 @@ Web interface
 
 You can also view experiment results as well as change the tags and share level at the `IBM Quantum Experiments
 pane <https://quantum-computing.ibm.com/experiments?date_interval=last-90-days&owner=me>`__
-on the cloud. The documentation below explains how to view, search, and share experiment
-data entries.
-
-See also
---------
-
-* `Experiments web interface documentation <https://quantum-computing.ibm.com/lab/docs/iql/manage/experiments/>`__ 
-
+on the cloud.

docs/howtos/runtime_sessions.rst

@@ -0,0 +1,70 @@
+Use Experiments with Runtime sessions
+=====================================
+
+Problem
+-------
+
+You want to run experiments in a `Runtime session
+<https://qiskit.org/ecosystem/ibm-runtime/sessions.html>`_ so that jobs can run in close temporal proximity.
+
+Solution
+--------
+
+There are two pathways currently supported:
+
+1. Use the :class:`~qiskit_ibm_provider.IBMBackend` object in ``qiskit-ibm-provider``, which supports sessions.
+
+.. jupyter-input::
+
+    from qiskit_ibm_provider import IBMProvider
+    from qiskit_experiments.library.tomography import ProcessTomography
+    from qiskit import QuantumCircuit
+
+    provider = IBMProvider()
+    backend = provider.get_backend("ibm_nairobi")
+    qc = QuantumCircuit(1)
+    qc.x(0)
+
+    with backend.open_session() as session:
+        tomography = ProcessTomography(qc)
+        tomography_result = tomography.run(backend)
+        tomography_result.block_for_results()
+        session.cancel()
+
+2. Use the ``qiskit-ibm-runtime`` provider. This requires extracting the circuits from the
+   experiment and running them using :meth:`qiskit_ibm_runtime.Session.run`:
+
+.. jupyter-input::
+
+    from qiskit_experiments.library import StandardRB
+    from qiskit_ibm_runtime import Session, QiskitRuntimeService
+    import numpy as np
+
+    exp = StandardRB([0], np.arange(1,800,200))
+    backend = "ibm_nairobi"
+
+    # all run options must be set before execution
+    exp.set_run_options(shots=100)
+
+    def run_jobs(session, job_circuits, run_options = None):
+        runtime_inputs={'circuits': job_circuits,
+                        'skip_transpilation': True, 
+                        **run_options}
+        jobs = session.run(program_id="circuit-runner", inputs=runtime_inputs)
+        return jobs
+
+    service = QiskitRuntimeService()
+
+    with Session(service=service, backend=backend) as session:
+        exp.backend = service.get_backend(session.backend())
+        jobs = run_jobs(session, exp._transpiled_circuits(), exp.run_options)
+        session.close()
+
+    # exp_data will be the usual experiment data object
+    exp_data = exp._initialize_experiment_data()
+    exp_data.add_jobs(jobs)
+    exp_data = exp.analysis.run(exp_data).block_for_results()
+
+Runtime primitives are not currently supported natively in Qiskit Experiments, so running jobs
+with the Runtime provider must be done with the ``circuit-runner`` program. We also turn off
+transpilation with ``skip_transpilation`` since Qiskit Experiments already transpiles the circuits.

docs/manuals/measurement/readout_mitigation.rst

@@ -180,4 +180,4 @@ See also
 
 * API documentation: :mod:`~qiskit_experiments.library.characterization.LocalReadoutError`, 
   :mod:`~qiskit_experiments.library.characterization.CorrelatedReadoutError`
-* Qiskit Textbook: `Measurement Error Mitigation <https://qiskit.org/textbook/ch-quantum-hardware/measurement-error-mitigation.html>`__
+* Qiskit Textbook: `Measurement Error Mitigation <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measurement-error-mitigation.ipynb>`__

docs/manuals/verification/quantum_volume.rst

@@ -8,7 +8,7 @@ that the computer successfully implements. Quantum computing systems
 with high-fidelity operations, high connectivity, large calibrated gate
 sets, and circuit rewriting toolchains are expected to have higher
 quantum volumes. See the `Qiskit
-Textbook <https://learn.qiskit.org/course/quantum-hardware/measuring-quantum-volume>`__
+Textbook <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measuring-quantum-volume.ipynb>`__
 for an explanation on the QV method, which is described in Refs. [1]_ [2]_.
 
 The Quantum Volume is determined by the largest successful circuit depth
@@ -20,8 +20,8 @@ a random permutation on the :math:`d` qubit. Then these circuits run on
 the quantum backend and on an ideal simulator (either :class:`qiskit_aer.AerSimulator`
 or :class:`qiskit.quantum_info.Statevector`).
 
-A depth :math:`d` QV circuit is successful if it has ‘mean heavy-output
-probability’ > 2/3 with confidence level > 0.977 (corresponding to
+A depth :math:`d` QV circuit is successful if it has `mean heavy-output
+probability` > 2/3 with confidence level > 0.977 (corresponding to
 z_value = 2), and at least 100 trials have been ran.
 
 .. note::
@@ -68,7 +68,7 @@ more trials may reduce the error bars to allow passing the threshold.
 
 The analysis results of the QV Experiment are:
 
--  The mean heavy output probabilities (HOP) and standard deviation
+-  The mean heavy-output probabilities (HOP) and standard deviation
 
 -  The calculated quantum volume, which will be None if the experiment
    does not pass the threshold
@@ -190,5 +190,5 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.library.quantum_volume`
-* Qiskit Textbook: `Measuring Quantum Volume <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`__
+* Qiskit Textbook: `Measuring Quantum Volume <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measuring-quantum-volume.ipynb>`__
 

docs/manuals/verification/randomized_benchmarking.rst

@@ -8,7 +8,7 @@ identity. After running the circuits, the number of shots resulting in an error
 output different from the ground state) are counted, and from this data one can infer
 error estimates for the quantum device, by calculating the Error Per Clifford. See the
 `Qiskit Textbook
-<https://learn.qiskit.org/course/quantum-hardware/randomized-benchmarking>`__ for an
+<https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/randomized-benchmarking.ipynb>`__ for an
 explanation on the RB method, which is based on Refs. [1]_ [2]_.
 
 .. jupyter-execute::
@@ -309,4 +309,4 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.library.randomized_benchmarking`
-* Qiskit Textbook: `Randomized Benchmarking <https://learn.qiskit.org/course/quantum-hardware/randomized-benchmarking>`__
+* Qiskit Textbook: `Randomized Benchmarking <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/randomized-benchmarking.ipynb>`__

docs/tutorials/calibrations.rst

@@ -491,7 +491,7 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.calibration_management` and :mod:`~qiskit_experiments.library.calibration`
-* Qiskit Textbook: `Calibrating Qubits with Qiskit Pulse <https://qiskit.org/textbook/ch-quantum-hardware/calibrating-qubits-pulse.html>`__
+* Qiskit Textbook: `Calibrating Qubits with Qiskit Pulse <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware-pulses/calibrating-qubits-pulse.ipynb>`__
 
 
 

qiskit_experiments/framework/base_experiment.py

@@ -293,8 +293,8 @@ def job_info(self, backend: Backend = None):
 
         Args:
             backend: Optional, the backend for which to get job distribution
-            information. If not specified, the experiment must already have a
-            set backend.
+                information. If not specified, the experiment must already have a
+                set backend.
 
         Returns:
             dict: A dictionary containing information about job distribution.

qiskit_experiments/library/calibration/fine_drag_cal.py

@@ -30,7 +30,7 @@
 
 
 class FineDragCal(BaseCalibrationExperiment, FineDrag):
-    """A calibration version of the fine drag experiment."""
+    """A calibration version of the fine DRAG experiment."""
 
     def __init__(
         self,
@@ -41,7 +41,7 @@ def __init__(
         cal_parameter_name: Optional[str] = "β",
         auto_update: bool = True,
     ):
-        r"""See class :class:`FineDrag` for details.
+        r"""See class :class:`.FineDrag` for details.
 
         Note that this class implicitly assumes that the target angle of the gate
         is :math:`\pi` as seen from the default experiment options.
@@ -148,7 +148,7 @@ def update_calibrations(self, experiment_data: ExperimentData):
 
 
 class FineXDragCal(FineDragCal):
-    """Fine drag calibration of X gate."""
+    """Fine DRAG calibration of X gate."""
 
     def __init__(
         self,
@@ -158,7 +158,7 @@ def __init__(
         cal_parameter_name: Optional[str] = "β",
         auto_update: bool = True,
     ):
-        r"""see class :class:`FineDrag` for details.
+        r"""see class :class:`.FineDrag` for details.
 
         Args:
             physical_qubits: Sequence containing the qubit for which to run the
@@ -180,7 +180,7 @@ def __init__(
 
 
 class FineSXDragCal(FineDragCal):
-    """Fine drag calibration of X gate."""
+    """Fine DRAG calibration of X gate."""
 
     def __init__(
         self,
@@ -190,7 +190,7 @@ def __init__(
         cal_parameter_name: Optional[str] = "β",
         auto_update: bool = True,
     ):
-        r"""see class :class:`FineDrag` for details.
+        r"""see class :class:`.FineDrag` for details.
 
         Args:
             physical_qubits: Sequence containing the qubit for which to run the

qiskit_experiments/library/calibration/rough_drag_cal.py

@@ -102,7 +102,7 @@ def _attach_calibrations(self, circuit: QuantumCircuit):
     def update_calibrations(self, experiment_data: ExperimentData):
         """Update the beta using the value directly reported from the fit.
 
-        See :class:`DragCalAnalysis` for details on the fit.
+        See :class:`.DragCalAnalysis` for details on the fit.
         """
 
         new_beta = BaseUpdater.get_value(

qiskit_experiments/library/characterization/cr_hamiltonian.py

@@ -122,7 +122,7 @@ class CrossResonanceHamiltonian(BaseExperiment):
 
     # section: manual
         .. ref_website:: Qiskit Textbook 6.7,
-            https://qiskit.org/textbook/ch-quantum-hardware/hamiltonian-tomography.html
+            https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware-pulses/hamiltonian-tomography.ipynb
     """
 
     # Number of CR pulses. The flat top duration per pulse is divided by this number.

qiskit_experiments/library/characterization/multi_state_discrimination.py

@@ -55,7 +55,7 @@ class MultiStateDiscrimination(BaseExperiment):
 
     # section: reference
         `Qiskit Textbook\
-        <https://qiskit.org/textbook/ch-quantum-hardware/accessing_higher_energy_states.html>`_
+        <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware-pulses/accessing_higher_energy_states.ipynb>`_
 
     """
 

qiskit_experiments/library/characterization/rabi.py

@@ -50,8 +50,8 @@ class Rabi(BaseExperiment, RestlessMixin):
     # section: manual
         :ref:`Rabi Calibration`
 
-        See also `Qiskit Textbook <https://qiskit.org/textbook/ch-quantum-hardware/\
-        calibrating-qubits-pulse.html>`_
+        See also the `Qiskit Textbook
+        <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware-pulses/calibrating-qubits-pulse.ipynb>`_
         for the pulse level programming of a Rabi experiment.
 
     # section: analysis_ref

qiskit_experiments/library/quantum_volume/qv_analysis.py

@@ -34,7 +34,7 @@ class QuantumVolumeAnalysis(BaseAnalysis):
     # section: overview
         Calculate the quantum volume of the analysed system.
         The quantum volume is determined by the largest successful circuit depth.
-        A depth is successful if it has 'mean heavy-output probability' > 2/3 with confidence
+        A depth is successful if it has `mean heavy-output probability` > 2/3 with confidence
         level > 0.977 (corresponding to z_value = 2), and at least 100 trials have been ran.
         we assume the error (standard deviation) of the heavy output probability is due to a
         binomial distribution. The standard deviation for binomial distribution is
@@ -175,7 +175,7 @@ def _calc_quantum_volume(self, heavy_output_prob_exp, depth, trials):
         """
         Calc the quantum volume of the analysed system.
         quantum volume is determined by the largest successful depth.
-        A depth is successful if it has 'mean heavy-output probability' > 2/3 with confidence
+        A depth is successful if it has `mean heavy-output probability` > 2/3 with confidence
         level > 0.977 (corresponding to z_value = 2), and at least 100 trials have been ran.
         we assume the error (standard deviation) of the heavy output probability is due to a
         binomial distribution. standard deviation for binomial distribution is sqrt(np(1-p)),
@@ -187,7 +187,7 @@ def _calc_quantum_volume(self, heavy_output_prob_exp, depth, trials):
             whether the results passed the threshold,
             the confidence of the result,
             the heavy output probability for each trial,
-            the mean heavy output probability,
+            the mean heavy-output probability,
             the error of the heavy output probability,
             the depth of the circuit,
             the number of trials ran

qiskit_experiments/library/quantum_volume/qv_experiment.py

@@ -40,8 +40,8 @@ class QuantumVolume(BaseExperiment):
 
         The Quantum Volume is determined by the largest circuit depth :math:`d_{max}`,
         and equals to :math:`2^{d_{max}}`.
-        See `Qiskit Textbook
-        <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`_
+        See the `Qiskit Textbook
+        <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/measuring-quantum-volume.ipynb>`_
         for an explanation on the QV protocol.
 
         In the QV experiment we generate :class:`~qiskit.circuit.library.QuantumVolume` circuits on
@@ -50,7 +50,7 @@ class QuantumVolume(BaseExperiment):
         Then these circuits run on the quantum backend and on an ideal simulator (either
         :class:`~qiskit_aer.AerSimulator` or :class:`~qiskit.quantum_info.Statevector`).
 
-        A depth :math:`d` QV circuit is successful if it has 'mean heavy-output probability' > 2/3 with
+        A depth :math:`d` QV circuit is successful if it has `mean heavy-output probability` > 2/3 with
         confidence level > 0.977 (corresponding to z_value = 2), and at least 100 trials have been ran.
 
         See :class:`QuantumVolumeAnalysis` documentation for additional

qiskit_experiments/library/randomized_benchmarking/standard_rb.py

@@ -60,7 +60,7 @@ class StandardRB(BaseExperiment, RestlessMixin):
     Randomized Benchmarking (RB) is an efficient and robust method
     for estimating the average error rate of a set of quantum gate operations.
     See `Qiskit Textbook
-    <https://qiskit.org/textbook/ch-quantum-hardware/randomized-benchmarking.html>`_
+    <https://github.com/Qiskit/textbook/blob/main/notebooks/quantum-hardware/randomized-benchmarking.ipynb>`_
     for an explanation on the RB method.
 
     A standard RB experiment generates sequences of random Cliffords