qiskit-community · coruscating · Feb 8, 2024 · Jan 31, 2024 · Feb 1, 2024 · Feb 1, 2024
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -74,7 +74,7 @@ When submitting a pull request for review, please ensure that:
    etc.), you've added or updated a reno release note for that change and tagged the PR
    for the changelog.
 6. If your code requires a change to dependencies, you've updated the corresponding
-   requirements file: `requirements.txt` contain core dependencies,
+   requirements file: `requirements.txt` for core dependencies,
    `requirements-extras.txt` for dependencies for optional features, and `requirements-dev.txt`
    for dependencies required for running tests and building documentation.
 
@@ -361,11 +361,48 @@ There are a few other build options available:
 
 ### Deprecation policy
 
-Qiskit Experiments is part of Qiskit and, therefore, the [Qiskit Deprecation
-Policy](https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md) fully applies here.
-Public-facing changes must come with a deprecation warning for at least three months or
-two version cycles before the old feature is removed. Deprecations can only happen on
-minor releases and not on patch releases.
+Any change to the existing package code that affects how the user interacts with the package
+should give the user clear instructions and advanced warning if the change is nontrivial.
+Qiskit Experiments's deprecation policy is based on [Qiskit's
+policy](https://github.com/Qiskit/qiskit/blob/1.0.0rc1/DEPRECATION.md) prior to its 1.0 release, but
+we impose less stringent requirements such that developers can iterate more quickly.
+Deprecations and feature removals can only happen on minor releases and not on patch releases.
+
+The deprecation policy depends on the significance of the user-facing change, which we have divided into
+three categories:
+
+A **core feature change** is one that affects how the framework functions, for example a
+change to `BaseExperiment`. The timeline for deprecating an existing core feature is as follows:
+
+* Minor release 1: An alternative path is provided. A `PendingDeprecationWarning` 
+  should be issued when the old path is used, indicating to users how to switch to
+  the new path and the release in which the old path will no longer be available. The
+  developer may choose to directly deprecate the feature and issue a `DeprecationWarning` instead,
+  in which case the release note should indicate the feature has been deprecated and how to switch
+  to the new path.
+* Minor release 2: The `PendingDeprecationWarning` becomes a `DeprecationWarning`, or the
+  `DeprecationWarning` remains in place. The release note should indicate the feature has
+  been deprecated and how to switch to the new path.
+* Minor release 3: The old feature is removed. The release note should indicate that the feature has
+  been removed and how to switch to the new path.
+
+If the three-release cycle takes fewer than three months, the feature removal must wait for more
+releases until three months has elapsed since the first issuing of the `PendingDeprecationWarning`
+or `DeprecationWarning`.
+
+A **non-core feature change** may be a change to a specific experiment class or modules such as the
+plotter. The timeline is shortened for such a change:
+
+* Minor release 1: An alternative path is provided. A `DeprecationWarning` should be issued
+  when the old path is used, indicating to users how to switch to the new path and the release
+  in which the old path will no longer be available.
+* Minor release 2: The old feature is removed. The release note should indicate that the feature has
+  been removed and how to switch to the new path.
+
+Lastly, a **minor, non-core change** could be a cosmetic change such as output file names or a
+change to helper functions that isn't directly used in the package codebase. These can be made in
+one release without a deprecation process as long as the change is clearly described in the
+release notes.
 
 #### Adding deprecation warnings
 
@@ -389,6 +426,15 @@ Utilities](https://docs.quantum.ibm.com/api/qiskit/utils) to add warnings:
       pass
 ```
 
+Note that all warnings emitted by Qiskit Experiments, including pre-deprecation and deprecation
+warnings, will cause the CI to fail, but features up for deprecation should continue to be tested
+until their removal. All such expected warnings should be caught in tests:
+
+```python
+  with self.assertWarns(DeprecationWarning):
+      # Test something deprecated here
+```
+
 ### Development cycle
 
 The development cycle for Qiskit Experiments is all handled in the open using project

diff --git a/docs/conf.py b/docs/conf.py
@@ -171,9 +171,11 @@
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", None),
     "uncertainties": ("https://pythonhosted.org/uncertainties", None),
+    "pandas": ("http://pandas.pydata.org/docs/", None),
     "qiskit_aer": ("https://qiskit.org/ecosystem/aer", None),
     "qiskit_dynamics": ("https://qiskit.org/ecosystem/dynamics/", None),
     "qiskit_ibm_runtime": ("https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/", None),
+    "qiskit_ibm_provider": ("https://docs.quantum.ibm.com/api/qiskit-ibm-provider/", None),
 }
 
 

diff --git a/docs/howtos/cloud_service.rst b/docs/howtos/cloud_service.rst
@@ -18,8 +18,8 @@ Saving
 ~~~~~~
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    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 :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` 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>`_.\
 
 You must run the experiment on a real IBM

diff --git a/docs/howtos/rerun_analysis.rst b/docs/howtos/rerun_analysis.rst
@@ -12,8 +12,8 @@ Solution
 --------
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    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 :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` 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>`_.\
 
 Once you recreate the exact experiment you ran and all of its parameters and options,

diff --git a/docs/howtos/runtime_sessions.rst b/docs/howtos/runtime_sessions.rst
@@ -11,11 +11,11 @@ Solution
 --------
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    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 :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` 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 :mod:`qiskit-ibm-runtime`, which supports sessions.
+Use the :class:`~qiskit_ibm_runtime.IBMBackend` object in :external+qiskit_ibm_runtime:doc:`index`, 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

diff --git a/docs/manuals/characterization/stark_experiment.rst b/docs/manuals/characterization/stark_experiment.rst
@@ -113,7 +113,7 @@ In a typical IBM device using the cross-resonance drive architecture,
 such channel can be identified with your backend as follows:
 
 .. note::
-    This tutorial requires the :mod:`qiskit_ibm_runtime` package to model a
+    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::

diff --git a/docs/manuals/characterization/t1.rst b/docs/manuals/characterization/t1.rst
@@ -30,7 +30,7 @@ The following code demonstrates a basic run of a :math:`T_1` experiment
 for qubit 0.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/characterization/t2ramsey.rst b/docs/manuals/characterization/t2ramsey.rst
@@ -58,7 +58,7 @@ We run the experiment on a simulated backend using Qiskit Aer with a
 pure T1/T2 relaxation noise model.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/characterization/tphi.rst b/docs/manuals/characterization/tphi.rst
@@ -21,7 +21,7 @@ From the :math:`T_1` and :math:`T_2` estimates, we compute the results for
 :math:`T_\varphi.`
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/measurement/readout_mitigation.rst b/docs/manuals/measurement/readout_mitigation.rst
@@ -31,7 +31,7 @@ This notebook demonstrates the usage of both the local and correlated
 experiments to generate the corresponding mitigators.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/measurement/restless_measurements.rst b/docs/manuals/measurement/restless_measurements.rst
@@ -59,7 +59,7 @@ observe any meaningful outcomes with fake backends since the circuit simulator
 they use always starts with the qubits in the ground state.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_ibm_runtime` package to model a
+    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::

diff --git a/docs/manuals/verification/quantum_volume.rst b/docs/manuals/verification/quantum_volume.rst
@@ -25,7 +25,7 @@ probability` > 2/3 with confidence level > 0.977 (corresponding to
 z_value = 2), and at least 100 trials have been ran.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/verification/randomized_benchmarking.rst b/docs/manuals/verification/randomized_benchmarking.rst
@@ -12,7 +12,7 @@ error estimates for the quantum device, by calculating the Error Per Clifford. S
 explanation on the RB method, which is based on Refs. [1]_ [2]_.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/manuals/verification/state_tomography.rst b/docs/manuals/verification/state_tomography.rst
@@ -8,7 +8,7 @@ of a quantum state by preparing the state many times and measuring them in a tom
 complete basis of measurement operators.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/tutorials/custom_experiment.rst b/docs/tutorials/custom_experiment.rst
@@ -558,7 +558,7 @@ output if the Pauli corresponding to that bit has a nonzero signature.
 To test our code, we first simulate a noisy backend with asymmetric readout error.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` package for simulations.
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` package for simulations.
     You can install it with ``python -m pip install qiskit-aer``.
 
 

diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst
@@ -58,7 +58,7 @@ Experiments must be run on a backend. We're going to use a simulator,
 backend, real or simulated, that you can access through Qiskit.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

diff --git a/docs/tutorials/visualization.rst b/docs/tutorials/visualization.rst
@@ -34,8 +34,8 @@ Generating and customizing a figure using a plotter
 First, we display the default figure from a :class:`.Rabi` experiment as a starting point:
 
 .. note::
-    This tutorial requires the :mod:`qiskit_dynamics`, :mod:`qiskit_aer`, and
-    :mod:`qiskit_ibm_runtime` packages to run simulations.  You can install them
+    This tutorial requires the :mod:`qiskit_dynamics`, :external+qiskit_aer:doc:`qiskit-aer <index>`, and
+    :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` packages to run simulations.  You can install them
     with ``python -m pip install qiskit-dynamics qiskit-aer qiskit-ibm-runtime``.
 
 .. jupyter-execute::

diff --git a/qiskit_experiments/data_processing/nodes.py b/qiskit_experiments/data_processing/nodes.py
@@ -740,9 +740,9 @@ def __init__(
 
         Args:
             outcome: The bitstring for which to return the probability and variance.
-            alpha_prior: A prior Beta distribution parameter ``[`alpha0, alpha1]``.
+            alpha_prior: A prior Beta distribution parameter ``[alpha0, alpha1]``.
                          If specified as float this will use the same value for
-                         ``alpha0`` and``alpha1`` (Default: 0.5).
+                         ``alpha0`` and ``alpha1`` (Default: 0.5).
             validate: If set to False the DataAction will not validate its input.
 
         Raises:

diff --git a/qiskit_experiments/framework/experiment_data.py b/qiskit_experiments/framework/experiment_data.py
@@ -2255,9 +2255,11 @@ def load(
             experiment_id: Experiment ID.
             service: the database service.
             provider: an IBMProvider required for loading job data and
-                can be used to initialize the service. In ``qiskit-ibm-runtime``,
-                this is the ``QiskitRuntimeService`` and should not be confused with
-                the experiment database service.
+                can be used to initialize the service. When using
+                :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
+                this is the :class:`~qiskit_ibm_runtime.QiskitRuntimeService` and should
+                not be confused with the experiment database service
+                :meth:`qiskit_ibm_experiment.IBMExperimentService`.
 
         Returns:
             The loaded experiment data.

diff --git a/qiskit_experiments/library/calibration/half_angle_cal.py b/qiskit_experiments/library/calibration/half_angle_cal.py
@@ -28,7 +28,7 @@
 
 
 class HalfAngleCal(BaseCalibrationExperiment, HalfAngle):
-    """Calibration version of the half-angle experiment."""
+    """Calibration version of the :class:`.HalfAngle` experiment."""
 
     def __init__(
         self,

diff --git a/qiskit_experiments/library/quantum_volume/qv_experiment.py b/qiskit_experiments/library/quantum_volume/qv_experiment.py
@@ -88,7 +88,7 @@ def __init__(
             simulation_backend: The simulator backend to use to generate
                 the expected results. the simulator must have a 'save_probabilities'
                 method. If None, the :class:`qiskit_aer.AerSimulator` simulator will be used
-                (in case :mod:`qiskit_aer` is not
+                (in case :external+qiskit_aer:doc:`qiskit-aer <index>` is not
                 installed, :class:`qiskit.quantum_info.Statevector` will be used).
         """
         super().__init__(physical_qubits, analysis=QuantumVolumeAnalysis(), backend=backend)

diff --git a/qiskit_experiments/library/randomized_benchmarking/__init__.py b/qiskit_experiments/library/randomized_benchmarking/__init__.py
@@ -37,6 +37,14 @@
     RBAnalysis
     InterleavedRBAnalysis
 
+Synthesis
+=========
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    RBDefaultCliffordSynthesis
+
 Utilities
 =========
 
@@ -52,3 +60,4 @@
 from .interleaved_rb_analysis import InterleavedRBAnalysis
 from .clifford_utils import CliffordUtils
 from .rb_utils import RBUtils
+from .clifford_synthesis import RBDefaultCliffordSynthesis
diff --git a/qiskit_experiments/library/randomized_benchmarking/clifford_synthesis.py b/qiskit_experiments/library/randomized_benchmarking/clifford_synthesis.py
@@ -60,7 +60,7 @@ def run(
 
         Returns:
             The quantum circuit representation of the Operation
-                when successful, and ``None`` otherwise.
+            when successful, and ``None`` otherwise.
 
         Raises:
             QiskitError: If basis_gates is not supplied.

diff --git a/releasenotes/config.yaml b/releasenotes/config.yaml
@@ -2,13 +2,37 @@
 encoding: utf8
 default_branch: main
 sections:
-  - [features, New Features]
+  - [features, New Features, 1]
+  - [features_expnew, New Experiments, 2]
+  - [features_explib, Experiment Library Updates, 2]
+  - [features_expclass, Experiment Class Features, 2]
+  - [features_analysis, Analysis Class Features, 2]
+  - [features_expdata, Experiment Data Features, 2]
+  - [features_curvefit, Curve Fit Features, 2]
+  - [features_calibration, Calibration Features, 2]
+  - [features_visualization, Visualization Features, 2]
   - [issues, Known Issues]
-  - [upgrade, Upgrade Notes]
+  - [upgrade, Upgrade Notes, 1]
+  - [upgrade_package, Package Upgrades, 2]
+  - [upgrade_explib, Experiment Library Upgrades, 2]
+  - [upgrade_expclass, Experiment Class Upgrades, 2]
+  - [upgrade_analysis, Analysis Class Upgrades, 2]
+  - [upgrade_expdata, Experiment Data Upgrades, 2]
+  - [upgrade_curvefit, Curve Fit Upgrades, 2]
+  - [upgrade_calibration, Calibration Upgrades, 2]
+  - [upgrade_visualization, Visualization Upgrades, 2]
   - [deprecations, Deprecation Notes]
   - [critical, Critical Issues]
   - [security, Security Issues]
   - [fixes, Bug Fixes]
+  - [fixes_package, Package Fixes, 2]
+  - [fixes_explib, Experiment Library Fixes, 2]
+  - [fixes_expclass, Experiment Class Fixes, 2]
+  - [fixes_analysis, Analysis Class Fixes, 2]
+  - [fixes_expdata, Experiment Data Fixes, 2]
+  - [fixes_curvefit, Curve Fit Fixes, 2]
+  - [fixes_calibration, Calibration Fixes, 2]
+  - [fixes_visualization, Visualization Fixes, 2]
   - [developer, API Changes for Experiment Authors]
   - [other, Other Notes]
 template: |

diff --git a/releasenotes/notes/0.4/0_3_1_release-43f09573952ce3ee.yaml b/releasenotes/notes/0.4/0_3_1_release-43f09573952ce3ee.yaml