Skip to content

Commit

Permalink
0.6 release notes and deprecation policy (#1385)
Browse files Browse the repository at this point in the history
### Summary

Update the release notes and deprecation policy prior to release.

---------

Co-authored-by: Will Shanks <[email protected]>
  • Loading branch information
coruscating and wshanks authored Feb 8, 2024
1 parent a7d260a commit e8531c4
Show file tree
Hide file tree
Showing 89 changed files with 340 additions and 234 deletions.
56 changes: 50 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -379,6 +416,7 @@ Utilities](https://docs.quantum.ibm.com/api/qiskit/utils) to add warnings:
@deprecate_func(
since="0.5",
additional_msg="Use ``new_function`` instead.",
pending=True,
removal_timeline="after 0.7",
package_name="qiskit-experiments",
)
Expand All @@ -389,6 +427,12 @@ 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. For more information on how to use wrappers and test deprecated functionality,
consult [Qiskit's
policy](https://github.com/Qiskit/qiskit/blob/1.0.0rc1/DEPRECATION.md#issuing-deprecation-warnings).

### Development cycle

The development cycle for Qiskit Experiments is all handled in the open using project
Expand Down
1 change: 1 addition & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,7 @@
"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),
}


Expand Down
4 changes: 2 additions & 2 deletions docs/howtos/cloud_service.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/howtos/rerun_analysis.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions docs/howtos/runtime_sessions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/characterization/stark_experiment.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/characterization/t1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/characterization/t2ramsey.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/characterization/tphi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/measurement/readout_mitigation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/measurement/restless_measurements.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/verification/quantum_volume.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/verification/randomized_benchmarking.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/manuals/verification/state_tomography.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/custom_experiment.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.


Expand Down
31 changes: 25 additions & 6 deletions docs/tutorials/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,30 @@ cloning the repository:
The ``-e`` option will keep your installed package up to date as you make or pull new
changes.

Upgrading Qiskit Experiments
----------------------------

Qiskit Experiments version numbers are in the form ``0.X.Y``, where ``X`` is the minor version and
``Y`` is the patch version. There are two kinds of releases: minor releases, which increment the
minor version, and patch releases, which increment the patch version. New features and API
changes can only be introduced in a minor release. Patch releases contain only bug fixes and changes that do
not affect how you use the package, such as performance optimization and documentation updates.

Therefore, when you encounter a bug or unexpected behavior, it is recommended that you first check if there's a
patch release you can upgrade to under the same minor version to avoid any breaking changes. When
running ``pip``, you can specify the exact version to install:

.. code-block::
python -m pip install qiskit-experiments==0.X.Y
Before a nontrivial breaking API change is introduced in a minor release, the old feature will
undergo a deprecation process lasting two releases for a core framework change and one release
otherwise. During this process, deprecation warnings will be issued if you use the old feature that
will instruct you on how to transition to the replacement feature, if applicable. The :doc:`release
notes </release_notes>` contain full details on which features are deprecated or removed in each
release.

Running your first experiment
=============================

Expand All @@ -58,7 +82,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``.

Expand All @@ -73,11 +97,6 @@ All experiments require a ``physical_qubits`` parameter as input that specifies
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 :math:`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 :math:`T_1`
Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/visualization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
4 changes: 2 additions & 2 deletions qiskit_experiments/data_processing/nodes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
8 changes: 5 additions & 3 deletions qiskit_experiments/framework/experiment_data.py
Original file line number Diff line number Diff line change
Expand Up @@ -2271,9 +2271,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.
Expand Down
2 changes: 1 addition & 1 deletion qiskit_experiments/library/calibration/half_angle_cal.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion qiskit_experiments/library/quantum_volume/qv_experiment.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,14 @@
RBAnalysis
InterleavedRBAnalysis
Synthesis
=========
.. autosummary::
:toctree: ../stubs/
RBDefaultCliffordSynthesis
Utilities
=========
Expand All @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading

0 comments on commit e8531c4

Please sign in to comment.