Add sessions how-to and update links (#1297)

### Summary

This PR adds a sessions how-to based on the discussions in #1226. It
also updates some outdated documentation, such as the links to the
Qiskit Textbook which were all broken.

---------

Co-authored-by: Will Shanks <willshanks@us.ibm.com>

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,7 +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",
             "",
         ]
@@ -167,7 +167,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,41 @@
+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
+--------
+
+Use the :class:`~qiskit_ibm_provider.IBMBackend` object in ``qiskit-ibm-provider``, which supports sessions.
+
+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:
+
+.. 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:
+        exp = ProcessTomography(qc)
+        exp.set_experiment_options(max_circuits=3)
+        exp_data = exp.run(backend)
+        exp_data.block_for_results()
+        # Calling cancel because session.close() is not available for qiskit-ibm-provider<=0.7.2.
+        # It is safe to call cancel since block_for_results() ensures there are no outstanding jobs 
+        # still running that would be canceled.
+        session.cancel()
+
+Note that runtime primitives are not currently supported natively in Qiskit Experiments, so  
+the ``backend.run()`` path is required to run experiments.

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/data_processing/data_processor.py

@@ -48,14 +48,14 @@ class DataProcessor:
     A DataProcessor defines a sequence of operations to perform on experimental data.
     Calling an instance of DataProcessor applies this sequence on the input argument.
     A DataProcessor is created with a list of DataAction instances. Each DataAction
-    applies its _process method on the data and returns the processed data. The nodes
+    applies its ``_process`` method on the data and returns the processed data. The nodes
     in the DataProcessor may also perform data validation and some minor formatting.
     The output of one data action serves as input for the next data action.
-    DataProcessor.__call__(datum) usually takes in an entry from the data property of
+    ``DataProcessor.__call__(datum)`` usually takes in an entry from the data property of
     an ExperimentData object (i.e. a dict containing metadata and memory keys and
     possibly counts, like the Result.data property) and produces the formatted data.
-    DataProcessor.__call__(datum) extracts the data from the given datum under
-    DataProcessor._input_key (which is specified at initialization) of the given datum.
+    ``DataProcessor.__call__(datum)`` extracts the data from the given datum under
+    ``DataProcessor._input_key`` (which is specified at initialization) of the given datum.
     """
 
     def __init__(

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