From a8132aaf8e9157c9af574d43dcd5472e49c253d7 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Tue, 14 Mar 2023 18:10:21 -0400 Subject: [PATCH 01/10] added `docs-nitpick` tox env also fixed broken links and bumped some package versions --- CONTRIBUTING.md | 18 +++--- docs/conf.py | 1 - docs/lint/conf.py | 57 +++++++++++++++++++ docs/manuals/benchmarking/quantum_volume.rst | 10 ++-- docs/tutorials/curve_analysis.rst | 6 +- docs/tutorials/custom_experiment.rst | 2 +- .../base_calibration_experiment.py | 10 ++-- .../database_service/__init__.py | 2 +- .../framework/base_experiment.py | 4 +- .../multi_state_discrimination.py | 3 +- .../interleaved_rb_analysis.py | 6 +- .../library/tomography/basis/base_basis.py | 12 ++-- qiskit_experiments/test/__init__.py | 3 + qiskit_experiments/visualization/__init__.py | 2 +- .../upgrade-curve-fit-4dc01b1db55ee398.yaml | 2 +- .../0.4/curve-analysis-02a702a81e014adf.yaml | 2 +- .../curve-analysis-4bcc10cf3a39a85d.yaml | 4 +- .../notes/ecr_lib-381cb18885e81abd.yaml | 2 +- ...b-3.6.0-failing-test-5a747f61a9c357b4.yaml | 4 +- .../notes/tomography-b091ce13d6983bc1.yaml | 10 ++-- requirements-dev.txt | 7 ++- tox.ini | 7 +++ 22 files changed, 120 insertions(+), 54 deletions(-) create mode 100644 docs/lint/conf.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60c55f3438..4d9d1e6596 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -227,8 +227,8 @@ should look something like: ```yaml features: - | - Introduced a new feature foo, that adds support for doing something to - ``QuantumCircuit`` objects. It can be used by using the foo function, + Introduced a new feature foo that adds support for doing something to + :class:`~qiskit.circuit.QuantumCircuit` objects. It can be used by using the foo function, for example:: from qiskit import foo @@ -236,9 +236,9 @@ features: foo(QuantumCircuit()) - | - The ``qiskit.QuantumCircuit`` module has a new method ``foo()``. This is - the equivalent of calling the ``qiskit.foo()`` to do something to your - QuantumCircuit. This is the equivalent of running ``qiskit.foo()`` on + The :class:`~qiskit.circuit.QuantumCircuit` class has a new method :meth:`.foo`. This is + the equivalent of calling :func:`qiskit.foo` to do something to your + QuantumCircuit. This is the equivalent of running :func:`qiskit.foo` on your circuit, but provides the convenience of running it natively on an object. For example:: @@ -249,11 +249,11 @@ features: deprecations: - | - The ``qiskit.bar`` module has been deprecated and will be removed in a - future release. Its sole function, ``foobar()`` has been superseded by the - ``qiskit.foo()`` function which provides similar functionality but with + The :mod:`qiskit.bar` module has been deprecated and will be removed in a + future release. Its sole function, :func:`foobar` has been superseded by the + :func:`qiskit.foo` function which provides similar functionality but with more accurate results and better performance. You should update your calls - ``qiskit.bar.foobar()`` calls to ``qiskit.foo()``. + :func:`qiskit.bar.foobar` calls to :func:`qiskit.foo`. ``` You can also look at existing release notes for more examples. diff --git a/docs/conf.py b/docs/conf.py index 1085b52310..92d0d01146 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -187,7 +187,6 @@ rst_prolog = """ .. raw:: html -


.. note:: This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being diff --git a/docs/lint/conf.py b/docs/lint/conf.py new file mode 100644 index 0000000000..bd2c6c18d9 --- /dev/null +++ b/docs/lint/conf.py @@ -0,0 +1,57 @@ +import sys, os + +# This is the configuration file to run sphinx linting for `tox -edocs-nitpick`. +# It will output warnings for each missing reference. + +sys.path.insert(0, os.path.abspath("../")) +sys.path.append(os.path.abspath("../_ext")) +sys.path.append(os.path.abspath("../../")) + +exclude_patterns = ["_build"] + +# # Set env flag so that we can doc functions that may otherwise not be loaded +# # see for example interactive visualizations in qiskit.visualization. +# os.environ["QISKIT_DOCS"] = "TRUE" + +project = "Qiskit Experiments" +nitpicky = True + +# within nit-picking build, do not refer to any intersphinx object +intersphinx_mapping = {} + +extensions = [ + "sphinx.ext.napoleon", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.extlinks", + "jupyter_sphinx", + "sphinx_autodoc_typehints", + "sphinx_design", + "sphinx.ext.intersphinx", + "nbsphinx", + "autoref", + "autodoc_experiment", + "autodoc_analysis", + "autodoc_visualization", + "jupyter_execute_custom", +] + +nbsphinx_allow_errors = True + +# Ignore these objects +nitpick_ignore_regex = [ + ("py:.*", "qiskit.*"), + ("py:.*", ".*\._.*"), + ("py:.*", "_.*"), + ("py:.*", "numpy.*"), + ("py:.*", ".*__.*"), + ("py:.*", "typing.*"), + ("py:.*", ".*Error"), + ("py:.*", "Ellipsis"), +] + +# Deprecated objects that should be ignored in the release notes +nitpick_ignore_regex += [ + ("py:class", "MplCurveDrawer"), + ("py:.*", "CliffordUtils.*"), +] diff --git a/docs/manuals/benchmarking/quantum_volume.rst b/docs/manuals/benchmarking/quantum_volume.rst index e57a192c2c..b9b9ac5fdc 100644 --- a/docs/manuals/benchmarking/quantum_volume.rst +++ b/docs/manuals/benchmarking/quantum_volume.rst @@ -53,11 +53,11 @@ backend and on an ideal simulator: - ``seed``: Seed or generator object for random number generation. If ``None`` then ``default_rng`` will be used. -- ``simulation_backend``: The simulator backend to use to generate the - expected results. the simulator must have a ``save_probabilities`` - method. If None ``AerSimulator`` simulator will be used (in case - ``AerSimulator`` is not installed ``qiskit.quantum_info.Statevector`` - will be used). +- ``simulation_backend``: The simulator backend to use to generate the expected + results. the simulator must have a ``save_probabilities`` method. If None, + :class:`~qiskit_aer.AerSimulator` will be used (in case + :class:`~qiskit_aer.AerSimulator` is not installed, + :class:`~qiskit.quantum_info.Statevector` will be used). **Note:** In some cases, 100 trials are not enough to obtain a QV greater than 1 for the specified number of qubits. In this case, adding diff --git a/docs/tutorials/curve_analysis.rst b/docs/tutorials/curve_analysis.rst index 3cfc82bd4d..58f44a6d12 100644 --- a/docs/tutorials/curve_analysis.rst +++ b/docs/tutorials/curve_analysis.rst @@ -253,9 +253,9 @@ This code will give you identical fit model to the one defined in the following ) However, note that you can also inherit other features, e.g. the algorithm to -generate initial guesses for parameters, from the :class:`AnalysisA` in the first example. +generate initial guesses for parameters, from the ``AnalysisA`` class in the first example. On the other hand, in the latter case, you need to manually copy and paste -every logic defined in the :class:`AnalysisA`. +every logic defined in ``AnalysisA``. .. _curve_analysis_workflow: @@ -268,7 +268,7 @@ This workflow is defined in the method :meth:`CurveAnalysis._run_analysis`. 1. Initialization ^^^^^^^^^^^^^^^^^ -Curve analysis calls :meth:`_initialization` method where it initializes +Curve analysis calls the :meth:`_initialization` method, where it initializes some internal states and optionally populate analysis options with the input experiment data. In some case it may train the data processor with fresh outcomes, diff --git a/docs/tutorials/custom_experiment.rst b/docs/tutorials/custom_experiment.rst index ff0ec51f10..9a6b888ffe 100644 --- a/docs/tutorials/custom_experiment.rst +++ b/docs/tutorials/custom_experiment.rst @@ -10,7 +10,7 @@ the :class:`.BaseExperiment` class. We will discuss both cases in this tutorial. In general, to subclass :class:`.BaseExperiment` class, you should: - Implement the abstract :meth:`.BaseExperiment.circuits` method. - This should return a list of :class:`~qiskit.QuantumCircuit` objects defining + This should return a list of :class:`~qiskit.circuit.QuantumCircuit` objects defining the experiment payload. - Call the :meth:`.BaseExperiment.__init__` method during the subclass diff --git a/qiskit_experiments/calibration_management/base_calibration_experiment.py b/qiskit_experiments/calibration_management/base_calibration_experiment.py index 242a0067d1..0a55c23a6d 100644 --- a/qiskit_experiments/calibration_management/base_calibration_experiment.py +++ b/qiskit_experiments/calibration_management/base_calibration_experiment.py @@ -61,14 +61,14 @@ class should be this mixin and the second class should be the characterization .. code-block:: python - RoughFrequency(BaseCalibrationExperiment, QubitSpectroscopy) + RoughFrequencyCal(BaseCalibrationExperiment, QubitSpectroscopy) - This ensures that the :meth:`run` method of :class:`.RoughFrequency` will be the + This ensures that the :meth:`run` method of :class:`.RoughFrequencyCal` will be the run method of the :class:`.BaseCalibrationExperiment` class. Furthermore, developers must explicitly call the :meth:`__init__` methods of both parent classes. Developers should strive to follow the convention that the first two arguments of - a calibration experiment are the qubit(s) and the :class:`.Calibration` instance. + a calibration experiment are the qubit(s) and the :class:`.Calibrations` instance. If the experiment uses custom schedules, which is typically the case, then developers may chose to use the :meth:`get_schedules` method when creating the @@ -133,8 +133,8 @@ def __init__( updater: The updater class that updates the Calibrations instance. Different calibration experiments will use different updaters. auto_update: If set to True (the default) then the calibrations will automatically be - updated once the experiment has run and :meth:`block_for_results()` will be called. - kwargs: Key word arguments for the characterization class. + updated once the experiment has run and :meth:`.block_for_results` will be called. + kwargs: Keyword arguments for the characterization class. """ super().__init__(*args, **kwargs) self._cals = calibrations diff --git a/qiskit_experiments/database_service/__init__.py b/qiskit_experiments/database_service/__init__.py index 1d454cf97e..24d19f2840 100644 --- a/qiskit_experiments/database_service/__init__.py +++ b/qiskit_experiments/database_service/__init__.py @@ -18,7 +18,7 @@ .. currentmodule:: qiskit_experiments.database_service This subpackage provides database-specific utility functions and exceptions which -are used with the :class:`ExperimentData` and :class:`AnalysisResult` classes. +are used with the :class:`.ExperimentData` and :class:`.AnalysisResult` classes. Exceptions diff --git a/qiskit_experiments/framework/base_experiment.py b/qiskit_experiments/framework/base_experiment.py index f261ff0066..01fe623249 100644 --- a/qiskit_experiments/framework/base_experiment.py +++ b/qiskit_experiments/framework/base_experiment.py @@ -298,12 +298,12 @@ def circuits(self) -> List[QuantumCircuit]: """Return a list of experiment circuits. Returns: - A list of :class:`QuantumCircuit`. + A list of :class:`~qiskit.circuit.QuantumCircuit`. .. note:: These circuits should be on qubits ``[0, .., N-1]`` for an *N*-qubit experiment. The circuits mapped to physical qubits - are obtained via the :meth:`transpiled_circuits` method. + are obtained via the internal :meth:`_transpiled_circuits` method. """ # NOTE: Subclasses should override this method using the `options` # values for any explicit experiment options that affect circuit diff --git a/qiskit_experiments/library/characterization/multi_state_discrimination.py b/qiskit_experiments/library/characterization/multi_state_discrimination.py index 9950e92914..f16a69b028 100644 --- a/qiskit_experiments/library/characterization/multi_state_discrimination.py +++ b/qiskit_experiments/library/characterization/multi_state_discrimination.py @@ -55,8 +55,7 @@ class MultiStateDiscrimination(BaseExperiment): :class:`MultiStateDiscriminationAnalysis` # section: reference - `Qiskit Textbook `_. + `Qiskit Textbook `_. """ diff --git a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py b/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py index bf7d29592a..266ea0703b 100644 --- a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py +++ b/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py @@ -77,12 +77,12 @@ class InterleavedRBAnalysis(curve.CurveAnalysis): bounds: [0, 1] defpar \alpha: desc: Depolarizing parameter. - init_guess: Determined by :func:`~rb_decay` with standard RB curve. + init_guess: Determined by :meth:`.rb_decay` with standard RB curve. bounds: [0, 1] defpar \alpha_c: - desc: Ratio of the depolarizing parameter of interleaved RB to standard RB curve. + desc: Ratio of the depolarizing parameter of interleaved RB to standard RB. init_guess: Determined by alpha of interleaved RB curve divided by one of - standard RB curve. Both alpha values are estimated by :func:`~rb_decay`. + standard RB curve. Both alpha values are estimated by :meth:`.rb_decay`. bounds: [0, 1] # section: reference diff --git a/qiskit_experiments/library/tomography/basis/base_basis.py b/qiskit_experiments/library/tomography/basis/base_basis.py index 0717d3db7d..0e3316a700 100644 --- a/qiskit_experiments/library/tomography/basis/base_basis.py +++ b/qiskit_experiments/library/tomography/basis/base_basis.py @@ -83,7 +83,7 @@ class PreparationBasis(BaseBasis): define a preparation basis: * The :meth:`circuit` method which returns the logical preparation - :class:`.QuantumCircuit` for basis element index on the specified + :class:`~qiskit.circuit.QuantumCircuit` for basis element index on the specified qubits. This circuit should be a logical circuit on the specified number of qubits and will be remapped to the corresponding physical qubits during transpilation. @@ -135,17 +135,17 @@ class MeasurementBasis(BaseBasis): define a preparation basis: * The :meth:`circuit` method which returns the logical measurement - :class:`.QuantumCircuit` for basis element index on the specified + :class:`~qiskit.circuit.QuantumCircuit` for basis element index on the specified physical qubits. This circuit should be a logical circuit on the specified number of qubits and will be remapped to the corresponding physical qubits during transpilation. It should include classical bits and the measure instructions for the basis measurement storing the outcome value in these bits. - * The :meth:`matrix` method which returns the POVM element corresponding - to the basis element index and measurement outcome on the specified - qubits. This should return either a :class:`.Statevector` for a PVM - element, or :class:`.DensityMatrix` for a general POVM element. + * The :meth:`matrix` method which returns the POVM element corresponding to the + basis element index and measurement outcome on the specified qubits. This should + return either a :class:`~qiskit.quantum_info.Statevector` for a PVM element, or + :class:`~qiskit.quantum_info.DensityMatrix` for a general POVM element. * The :meth:`index_shape` method which returns the shape of allowed basis indices for the specified qubits, and their values. diff --git a/qiskit_experiments/test/__init__.py b/qiskit_experiments/test/__init__.py index 651bd96e45..b2eec4a7b8 100644 --- a/qiskit_experiments/test/__init__.py +++ b/qiskit_experiments/test/__init__.py @@ -42,6 +42,8 @@ MockIQParallelBackend T2HahnBackend NoisyDelayAerBackend + PulseBackend + SingleTransmonTestBackend """ @@ -50,3 +52,4 @@ from .noisy_delay_aer_simulator import NoisyDelayAerBackend from .t2hahn_backend import T2HahnBackend from .fake_service import FakeService +from .pulse_backend import PulseBackend diff --git a/qiskit_experiments/visualization/__init__.py b/qiskit_experiments/visualization/__init__.py index 682f77bcb1..b1f91d5d32 100644 --- a/qiskit_experiments/visualization/__init__.py +++ b/qiskit_experiments/visualization/__init__.py @@ -20,7 +20,7 @@ experiment and analysis results. This includes plotter and drawer classes to plot data in :class:`.CurveAnalysis` and its subclasses. Plotters inherit from :class:`BasePlotter` and define a type of figure that may be generated from experiment -or analysis data. For example, the results from :class:`CurveAnalysis`---or any other +or analysis data. For example, the results from :class:`.CurveAnalysis`---or any other experiment where results are plotted against a single parameter (i.e., :math:`x`)---can be plotted using the :class:`CurvePlotter` class, which plots X-Y-like values. diff --git a/releasenotes/notes/0.3/upgrade-curve-fit-4dc01b1db55ee398.yaml b/releasenotes/notes/0.3/upgrade-curve-fit-4dc01b1db55ee398.yaml index 021f4954ad..b65d0fac59 100644 --- a/releasenotes/notes/0.3/upgrade-curve-fit-4dc01b1db55ee398.yaml +++ b/releasenotes/notes/0.3/upgrade-curve-fit-4dc01b1db55ee398.yaml @@ -1,7 +1,7 @@ --- upgrade: - | - The :class:`CurveAnalysis` class has been updated to use the covariance between fit + The :class:`.CurveAnalysis` class has been updated to use the covariance between fit parameters in the error propagation. This will provide more accurate standard error for your fit values. - | diff --git a/releasenotes/notes/0.4/curve-analysis-02a702a81e014adf.yaml b/releasenotes/notes/0.4/curve-analysis-02a702a81e014adf.yaml index 520a276b31..aeb70b210a 100644 --- a/releasenotes/notes/0.4/curve-analysis-02a702a81e014adf.yaml +++ b/releasenotes/notes/0.4/curve-analysis-02a702a81e014adf.yaml @@ -41,7 +41,7 @@ features: - | ``plot_options`` has been added. This was conventionally included - in the :class:`SeriesDef` dataclass, which was static and not configurable. + in the :class:`.SeriesDef` dataclass, which was static and not configurable. Now end-user can update visual representation of curves through this option. This option is a dictionary that defines three properties, for example, diff --git a/releasenotes/notes/curve-analysis-4bcc10cf3a39a85d.yaml b/releasenotes/notes/curve-analysis-4bcc10cf3a39a85d.yaml index d6ded09461..baa00db00e 100644 --- a/releasenotes/notes/curve-analysis-4bcc10cf3a39a85d.yaml +++ b/releasenotes/notes/curve-analysis-4bcc10cf3a39a85d.yaml @@ -8,13 +8,13 @@ features: and no statistical difference has been introduced with introduction of this option. deprecations: - | - Providing data_sort_key directly to the LMFIT model to instantiate :class:`CurveAnalysis` + Providing data_sort_key directly to the LMFIT model to instantiate :class:`.CurveAnalysis` has been deprecated. This option is not officially supported by the LMFIT, and thus curve analysis cannot guarantee this option is properly managed in all LMFIT model subclasses. developer: - | - To map experiment result data to a particular LMFIT model in the :class:`CurveAnalysis`, + To map experiment result data to a particular LMFIT model in the :class:`.CurveAnalysis`, an author must provide the data_subfit_map analysis option rather than directly binding data_sort_key with the target LMFIT model. The data_subfit_map option is a dictionary keyed on the model name. For example, diff --git a/releasenotes/notes/ecr_lib-381cb18885e81abd.yaml b/releasenotes/notes/ecr_lib-381cb18885e81abd.yaml index 574a34f9c0..5b0133a7ae 100644 --- a/releasenotes/notes/ecr_lib-381cb18885e81abd.yaml +++ b/releasenotes/notes/ecr_lib-381cb18885e81abd.yaml @@ -1,7 +1,7 @@ --- features: - | - A new basis gate library called :class:`EchoedCrossResonance` is been added. + A new basis gate library called :class:`.EchoedCrossResonance` is been added. upgrade: - | The :class:`.Calibrations` class has been updated to use the reference diff --git a/releasenotes/notes/fix-matplotlib-3.6.0-failing-test-5a747f61a9c357b4.yaml b/releasenotes/notes/fix-matplotlib-3.6.0-failing-test-5a747f61a9c357b4.yaml index a7f8ddd4af..15b569cfd9 100644 --- a/releasenotes/notes/fix-matplotlib-3.6.0-failing-test-5a747f61a9c357b4.yaml +++ b/releasenotes/notes/fix-matplotlib-3.6.0-failing-test-5a747f61a9c357b4.yaml @@ -1,6 +1,6 @@ --- fixes: - | - Fix a bug where :class:`CurveAnalysis` tests would fail with matplotlib 3.6.0 owing to a deprecated - function call used in :class:`MplCurveDrawer`. The new :class:`MplCurveDrawer` no-longer uses the + Fix a bug where :class:`.CurveAnalysis` tests would fail with matplotlib 3.6.0 owing to a deprecated + function call used in :class:`MplCurveDrawer`. The new :class:`MplCurveDrawer` no longer uses the deprecated function. diff --git a/releasenotes/notes/tomography-b091ce13d6983bc1.yaml b/releasenotes/notes/tomography-b091ce13d6983bc1.yaml index 2e46cde734..32a76ca022 100644 --- a/releasenotes/notes/tomography-b091ce13d6983bc1.yaml +++ b/releasenotes/notes/tomography-b091ce13d6983bc1.yaml @@ -22,12 +22,12 @@ features: - | Adds an optional ``mitigator`` kwarg to :class:`.PauliMeasurementBasis` which can be used to initialize the basis with a - :class:`.LocalReadoutMitigator` to construct a readout error mitigated + :class:`~qiskit.result.LocalReadoutMitigator` to construct a readout error mitigated basis for use with :class:`.StateTomography` and :class:`.ProcessTomography` experiments. The :class:`.LocalReadoutError` experiment can be run to obtain the - :class:`.LocalReadoutMitigator` from its analysis results. + :class:`~qiskit.result.LocalReadoutMitigator` from its analysis results. - | Adds readout error mitigated tomography experiments :class:`.MitigatedStateTomography` and :class:`.MitigatedProcessTomography`. @@ -74,7 +74,7 @@ fixes: experiments where if the input circuit contained conditional instructions with multiple classical registers the tomography measurement circuits would contain incorrect conditionals due to a bug in the - :meth:`.QuantumCircuit.compose` method. + :meth:`qiskit.circuit.QuantumCircuit.compose` method. See Issue #942 `_ for additional details. @@ -82,7 +82,7 @@ upgrade: - | Renames the ``qubits``, ``measurement_qubits``, and ``preparation_qubits`` init kwargs of :class:`~.StateTomography`, - :class:`~.ProcessTomography`, and :class:`~.TomographyExperiment` to + :class:`~.ProcessTomography`, and :class:`.TomographyExperiment` to ``physical_qubits``, ``measurement_indices`` and ``preparation_indices`` respectively. This is to make the intended use of these kwargs more clear as the measurement and preparation args refer to the index of circuit @@ -101,7 +101,7 @@ deprecations: - | Renames the ``qubits``, ``measurement_qubits``, and ``preparation_qubits`` init kwargs of :class:`~.StateTomography`, - :class:`~.ProcessTomography`, and :class:`~.TomographyExperiment` have + :class:`~.ProcessTomography`, and :class:`.TomographyExperiment` have been deprecated. They have been replaced with kwargs ``physical_qubits``, ``measurement_indices`` and ``preparation_indices`` respectively. The renamed kwargs have the same functionality as the deprecated kwargs. diff --git a/requirements-dev.txt b/requirements-dev.txt index 48296535bc..d93e4e1a38 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -5,11 +5,11 @@ pylint==2.7.1 jinja2==3.0.3 sphinx~=5.0 jupyter-sphinx>=0.4.0 -qiskit-sphinx-theme==1.11.0rc1 -sphinx-autodoc-typehints<=1.20.2 +qiskit-sphinx-theme>=1.11.0rc1 +sphinx-autodoc-typehints>=1.22.0 sphinx-design==0.3.0 pygments>=2.4 -reno>=3.4.0 +reno>=4.0.0 nbsphinx arxiv ddt>=1.6.0 @@ -21,3 +21,4 @@ pylatexenc importlib-metadata==4.13.0;python_version<'3.8' scikit-learn sphinx-copybutton +sphinxcontrib-jupyter \ No newline at end of file diff --git a/tox.ini b/tox.ini index f499f46cba..534da132ff 100644 --- a/tox.ini +++ b/tox.ini @@ -72,6 +72,13 @@ setenv = commands = sphinx-build -T --keep-going -b html {posargs} docs/ docs/_build/html +[testenv:docs-nitpick] +passenv = EXPERIMENTS_DEV_DOCS +setenv = + QISKIT_DOCS_SKIP_EXECUTE = 1 +commands = + sphinx-build -c docs/lint -n -T --keep-going -b linkcheck {posargs} docs/ docs/_build/html + [pycodestyle] max-line-length = 100 From d0263a4464722aadf414efa1e1d942fafd898692 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Tue, 14 Mar 2023 19:44:36 -0400 Subject: [PATCH 02/10] added docs lint to workflow renamed env to `docs-lint`, changed arxiv link to abstract instead of pdf, and various other fixes --- .github/workflows/main.yml | 2 ++ docs/_ext/autoref.py | 4 ++- docs/howtos/new_experimentdata.rst | 2 +- docs/lint/conf.py | 25 ++++++++++--------- .../base_calibration_experiment.py | 2 +- .../basis_gate_library.py | 10 +++++--- .../framework/composite/composite_analysis.py | 18 ++++++------- .../framework/experiment_data.py | 21 ++++++++-------- qiskit_experiments/library/__init__.py | 2 ++ .../randomized_benchmarking/rb_analysis.py | 2 +- .../library/tomography/__init__.py | 4 +++ .../library/tomography/basis/base_basis.py | 4 +-- qiskit_experiments/test/__init__.py | 2 +- ...leanup-rb-experiment-f17b6e674ae4e473.yaml | 2 +- ...sis-fixed-parameters-5915a29db1e2628b.yaml | 12 ++++----- ...riment_service_fixes-94730fd6bab83956.yaml | 2 +- ...domized_benchmarking-de55fda43765c34c.yaml | 5 ++-- tox.ini | 2 +- 18 files changed, 67 insertions(+), 54 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 4761fece4c..9a579851d4 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -72,6 +72,8 @@ jobs: run: python -m pip install -U tox - name: Run lint run: tox -elint + - name: Lint docs + run: tox -edocs-lint -- -W docs: name: docs runs-on: ubuntu-latest diff --git a/docs/_ext/autoref.py b/docs/_ext/autoref.py index 4d303d0246..5f78b23f58 100644 --- a/docs/_ext/autoref.py +++ b/docs/_ext/autoref.py @@ -30,6 +30,7 @@ class WebSite(Directive): .. ref_website:: qiskit-experiments, https://github.com/Qiskit/qiskit-experiments """ + required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True @@ -67,6 +68,7 @@ class Arxiv(Directive): If an article is not found, no journal information will be shown. """ + required_arguments = 2 optional_arguments = 0 final_argument_whitespace = False @@ -95,7 +97,7 @@ def run(self): if journal: ret_node += nodes.Text(journal) ret_node += nodes.Text(" ") - ret_node += nodes.reference(text="(open)", refuri=paper.pdf_url) + ret_node += nodes.reference(text="(open)", refuri=paper.entry_id) return [ret_node] diff --git a/docs/howtos/new_experimentdata.rst b/docs/howtos/new_experimentdata.rst index 24dcc11fd7..55b11ac270 100644 --- a/docs/howtos/new_experimentdata.rst +++ b/docs/howtos/new_experimentdata.rst @@ -84,4 +84,4 @@ first component experiment. See Also -------- -* `Saving and loading experiment data with the cloud service `_ +* :doc:`cloud_service` diff --git a/docs/lint/conf.py b/docs/lint/conf.py index bd2c6c18d9..a36c6eb385 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -1,18 +1,14 @@ -import sys, os - # This is the configuration file to run sphinx linting for `tox -edocs-nitpick`. # It will output warnings for each missing reference. +import sys, os + sys.path.insert(0, os.path.abspath("../")) sys.path.append(os.path.abspath("../_ext")) sys.path.append(os.path.abspath("../../")) exclude_patterns = ["_build"] -# # Set env flag so that we can doc functions that may otherwise not be loaded -# # see for example interactive visualizations in qiskit.visualization. -# os.environ["QISKIT_DOCS"] = "TRUE" - project = "Qiskit Experiments" nitpicky = True @@ -23,16 +19,15 @@ "sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.autosummary", - "sphinx.ext.extlinks", - "jupyter_sphinx", + "reno.sphinxext", "sphinx_autodoc_typehints", - "sphinx_design", "sphinx.ext.intersphinx", - "nbsphinx", "autoref", "autodoc_experiment", "autodoc_analysis", "autodoc_visualization", + "sphinx_design", + "jupyter_sphinx", "jupyter_execute_custom", ] @@ -41,9 +36,15 @@ # Ignore these objects nitpick_ignore_regex = [ ("py:.*", "qiskit.*"), + ("py:.*", "numpy.*"), + ("py:.*", "sklearn.*"), + ("py:.*", "scipy.*"), + ("py:.*", "datetime.*"), + ("py:.*", "IBM.*"), ("py:.*", ".*\._.*"), ("py:.*", "_.*"), - ("py:.*", "numpy.*"), + ("py:.*", "lmfit.*"), + ("py:.*", "uncertainties.*"), ("py:.*", ".*__.*"), ("py:.*", "typing.*"), ("py:.*", ".*Error"), @@ -52,6 +53,6 @@ # Deprecated objects that should be ignored in the release notes nitpick_ignore_regex += [ - ("py:class", "MplCurveDrawer"), + ("py:*", "MplCurveDrawer.*"), ("py:.*", "CliffordUtils.*"), ] diff --git a/qiskit_experiments/calibration_management/base_calibration_experiment.py b/qiskit_experiments/calibration_management/base_calibration_experiment.py index 0a55c23a6d..985f39a060 100644 --- a/qiskit_experiments/calibration_management/base_calibration_experiment.py +++ b/qiskit_experiments/calibration_management/base_calibration_experiment.py @@ -63,7 +63,7 @@ class should be this mixin and the second class should be the characterization RoughFrequencyCal(BaseCalibrationExperiment, QubitSpectroscopy) - This ensures that the :meth:`run` method of :class:`.RoughFrequencyCal` will be the + This ensures that the ``run`` method of :class:`.RoughFrequencyCal` will be the run method of the :class:`.BaseCalibrationExperiment` class. Furthermore, developers must explicitly call the :meth:`__init__` methods of both parent classes. diff --git a/qiskit_experiments/calibration_management/basis_gate_library.py b/qiskit_experiments/calibration_management/basis_gate_library.py index 20f37026bf..30782331e0 100644 --- a/qiskit_experiments/calibration_management/basis_gate_library.py +++ b/qiskit_experiments/calibration_management/basis_gate_library.py @@ -120,8 +120,9 @@ def default_values(self) -> List[DefaultCalValue]: """Return the default values for the parameters. Returns - A list of tuples is returned. These tuples are structured so that instances of - :class:`.Calibrations` can call :meth:`.add_parameter_value` on the tuples. + A list of tuples is returned. These tuples are structured so that instances + of :class:`.Calibrations` can call :meth:`.Calibrations.add_parameter_value` + on the tuples. """ @abstractmethod @@ -286,8 +287,9 @@ def default_values(self) -> List[DefaultCalValue]: """Return the default values for the parameters. Returns - A list of tuples is returned. These tuples are structured so that instances of - :class:`.Calibrations` can call :meth:`.add_parameter_value` on the tuples. + A list of tuples is returned. These tuples are structured so that instances + of :class:`.Calibrations` can call :meth:`.Calibrations.add_parameter_value` + on the tuples. """ defaults = [] for name, schedule in self.items(): diff --git a/qiskit_experiments/framework/composite/composite_analysis.py b/qiskit_experiments/framework/composite/composite_analysis.py index 2860449b11..e07e606712 100644 --- a/qiskit_experiments/framework/composite/composite_analysis.py +++ b/qiskit_experiments/framework/composite/composite_analysis.py @@ -40,15 +40,15 @@ class CompositeAnalysis(BaseAnalysis): .. note:: - If the composite :class:`ExperimentData` does not already contain - child experiment data containers for the component experiments - they will be initialized and added to the experiment data when :meth:`run` - is called on the composite data. - - When calling :meth:`run` on experiment data already containing - initialized component experiment data, any previously stored - circuit data will be cleared and replaced with the marginalized data - from the composite experiment data. + If the composite :class:`ExperimentData` does not already contain child + experiment data containers for the component experiments they will be + initialized and added to the experiment data when + :meth:`~.CompositeAnalysis.run` is called on the composite data. + + When calling :meth:`~.CompositeAnalysis.run` on experiment data already + containing initialized component experiment data, any previously stored circuit + data will be cleared and replaced with the marginalized data from the composite + experiment data. """ def __init__(self, analyses: List[BaseAnalysis], flatten_results: bool = False): diff --git a/qiskit_experiments/framework/experiment_data.py b/qiskit_experiments/framework/experiment_data.py index 1ecc4a471d..a84684e521 100644 --- a/qiskit_experiments/framework/experiment_data.py +++ b/qiskit_experiments/framework/experiment_data.py @@ -1709,21 +1709,20 @@ def status(self) -> ExperimentStatus: def job_status(self) -> JobStatus: """Return the experiment job execution status. - Possible return values for :class:`.JobStatus` are + Possible return values for :class:`qiskit.providers.jobstatus.JobStatus` are - * :attr:`~.JobStatus.ERROR` - if any job incurred an error - * :attr:`~.JobStatus.CANCELLED` - if any job is cancelled. - * :attr:`~.JobStatus.RUNNING` - if any job is still running. - * :attr:`~.JobStatus.QUEUED` - if any job is queued. - * :attr:`~.JobStatus.VALIDATING` - if any job is being validated. - * :attr:`~.JobStatus.INITIALIZING` - if any job is being initialized. - * :attr:`~.JobStatus.DONE` - if all jobs are finished. + * `ERROR`` - if any job incurred an error + * ``CANCELLED`` - if any job is cancelled. + * ``RUNNING`` - if any job is still running. + * ``QUEUED`` - if any job is queued. + * ``VALIDATING`` - if any job is being validated. + * ``INITIALIZING`` - if any job is being initialized. + * ``DONE`` - if all jobs are finished. .. note:: - If an experiment has status :attr:`~.JobStatus.ERROR` or - :attr:`~.JobStatus.CANCELLED` there may still be pending or - running jobs. In these cases it may be beneficial to call + If an experiment has status ``ERROR`` or ``CANCELLED`` there may still be + pending or running jobs. In these cases it may be beneficial to call :meth:`cancel_jobs` to terminate these remaining jobs. Returns: diff --git a/qiskit_experiments/library/__init__.py b/qiskit_experiments/library/__init__.py index 9ba3f37f39..8ddf8f848a 100644 --- a/qiskit_experiments/library/__init__.py +++ b/qiskit_experiments/library/__init__.py @@ -36,6 +36,7 @@ ~randomized_benchmarking.StandardRB ~randomized_benchmarking.InterleavedRB + ~tomography.TomographyExperiment ~tomography.StateTomography ~tomography.ProcessTomography ~tomography.MitigatedStateTomography @@ -182,6 +183,7 @@ class instance to manage parameters and pulse schedules. ) from .randomized_benchmarking import StandardRB, InterleavedRB from .tomography import ( + TomographyExperiment, StateTomography, ProcessTomography, MitigatedStateTomography, diff --git a/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py b/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py index f3a69c8fe7..b1a33fbe50 100644 --- a/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py +++ b/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py @@ -60,7 +60,7 @@ class RBAnalysis(curve.CurveAnalysis): bounds: [0, 1] defpar \alpha: desc: Depolarizing parameter. - init_guess: Determined by :func:`~rb_decay`. + init_guess: Determined by :func:`~.guess.rb_decay`. bounds: [0, 1] # section: reference diff --git a/qiskit_experiments/library/tomography/__init__.py b/qiskit_experiments/library/tomography/__init__.py index c9ebeb058b..b068970892 100644 --- a/qiskit_experiments/library/tomography/__init__.py +++ b/qiskit_experiments/library/tomography/__init__.py @@ -24,6 +24,7 @@ :toctree: ../stubs/ :template: autosummary/experiment.rst + TomographyExperiment StateTomography ProcessTomography MitigatedStateTomography @@ -37,6 +38,7 @@ :toctree: ../stubs/ :template: autosummary/analysis.rst + TomographyAnalysis StateTomographyAnalysis ProcessTomographyAnalysis MitigatedTomographyAnalysis @@ -90,10 +92,12 @@ """ # Experiment Classes +from .tomography_experiment import TomographyExperiment from .qst_experiment import StateTomography, StateTomographyAnalysis from .qpt_experiment import ProcessTomography, ProcessTomographyAnalysis from .mit_qst_experiment import MitigatedStateTomography from .mit_qpt_experiment import MitigatedProcessTomography +from .tomography_analysis import TomographyAnalysis from .mit_tomography_analysis import MitigatedTomographyAnalysis # Basis Classes diff --git a/qiskit_experiments/library/tomography/basis/base_basis.py b/qiskit_experiments/library/tomography/basis/base_basis.py index 0e3316a700..c116b713b2 100644 --- a/qiskit_experiments/library/tomography/basis/base_basis.py +++ b/qiskit_experiments/library/tomography/basis/base_basis.py @@ -94,7 +94,7 @@ class PreparationBasis(BaseBasis): * The :meth:`index_shape` method which returns the shape of allowed basis indices for the specified qubits, and their values. - * The :meth:`matrix_shape` method which returns the shape of subsystem + * The :meth:`~.PreparationBasis.matrix_shape` method which returns the shape of subsystem dimensions of the density matrix state on the specified qubits. """ @@ -150,7 +150,7 @@ class MeasurementBasis(BaseBasis): * The :meth:`index_shape` method which returns the shape of allowed basis indices for the specified qubits, and their values. - * The :meth:`matrix_shape` method which returns the shape of subsystem + * The :meth:`~.PreparationBasis.matrix_shape` method which returns the shape of subsystem dimensions of the POVM element matrices on the specified qubits. * The :meth:`outcome_shape` method which returns the shape of allowed diff --git a/qiskit_experiments/test/__init__.py b/qiskit_experiments/test/__init__.py index b2eec4a7b8..dbe7e94b9b 100644 --- a/qiskit_experiments/test/__init__.py +++ b/qiskit_experiments/test/__init__.py @@ -52,4 +52,4 @@ from .noisy_delay_aer_simulator import NoisyDelayAerBackend from .t2hahn_backend import T2HahnBackend from .fake_service import FakeService -from .pulse_backend import PulseBackend +from .pulse_backend import PulseBackend, SingleTransmonTestBackend diff --git a/releasenotes/notes/0.3/cleanup-rb-experiment-f17b6e674ae4e473.yaml b/releasenotes/notes/0.3/cleanup-rb-experiment-f17b6e674ae4e473.yaml index 2261d7b908..396aba8bc6 100644 --- a/releasenotes/notes/0.3/cleanup-rb-experiment-f17b6e674ae4e473.yaml +++ b/releasenotes/notes/0.3/cleanup-rb-experiment-f17b6e674ae4e473.yaml @@ -1,7 +1,7 @@ --- features: - | - The curve fit parameter guess function :func:`~rb_decay` has been added. + The curve fit parameter guess function :func:`~.guess.rb_decay` has been added. This improves the initial parameter estimation of randomized benchmark experiments. upgrade: - | diff --git a/releasenotes/notes/0.3/curve-analysis-fixed-parameters-5915a29db1e2628b.yaml b/releasenotes/notes/0.3/curve-analysis-fixed-parameters-5915a29db1e2628b.yaml index f0701c689d..37a182a26a 100644 --- a/releasenotes/notes/0.3/curve-analysis-fixed-parameters-5915a29db1e2628b.yaml +++ b/releasenotes/notes/0.3/curve-analysis-fixed-parameters-5915a29db1e2628b.yaml @@ -13,11 +13,11 @@ deprecations: has been deprecated. Please set `fixed_parameters` option instead. This is a python dictionary of fixed parameter values keyed on the fit parameter names. - | - Analysis class :class:`FineDragAnalysis` has been deprecated. Now you can directly - set fixed parameters to the :class:`ErrorAmplificationAnalysis` instance as an analysis option. + Analysis class ``FineDragAnalysis`` has been deprecated. Now you can directly + set fixed parameters to the :class:`.ErrorAmplificationAnalysis` instance as an analysis option. - | - Analysis class :class:`FineFrequencyAnalysis` has been deprecated. Now you can directly - set fixed parameters to the :class:`ErrorAmplificationAnalysis` instance as an analysis option. + Analysis class ``FineFrequencyAnalysis`` has been deprecated. Now you can directly + set fixed parameters to the :class:`.ErrorAmplificationAnalysis` instance as an analysis option. - | - Analysis class :class:`FineHalfAngleAnalysis` has been deprecated. Now you can directly - set fixed parameters to the :class:`ErrorAmplificationAnalysis` instance as an analysis option. + Analysis class ``FineHalfAngleAnalysis`` has been deprecated. Now you can directly + set fixed parameters to the :class:`.ErrorAmplificationAnalysis` instance as an analysis option. diff --git a/releasenotes/notes/0.3/experiment_service_fixes-94730fd6bab83956.yaml b/releasenotes/notes/0.3/experiment_service_fixes-94730fd6bab83956.yaml index fcfc369120..16e040ef60 100644 --- a/releasenotes/notes/0.3/experiment_service_fixes-94730fd6bab83956.yaml +++ b/releasenotes/notes/0.3/experiment_service_fixes-94730fd6bab83956.yaml @@ -1,6 +1,6 @@ --- fixes: - | - :meth:`.ExperimentData.save()` should now fail gracefully when experiment metadata failed to save instead of crashing. + :meth:`.ExperimentData.save` should now fail gracefully when experiment metadata failed to save instead of crashing. - | The link to the experiment entry in the database service shown after saving is now by default obtained from the service, not hard-coded. diff --git a/releasenotes/notes/0.4/randomized_benchmarking-de55fda43765c34c.yaml b/releasenotes/notes/0.4/randomized_benchmarking-de55fda43765c34c.yaml index 2942065e4b..07e9d5ebd1 100644 --- a/releasenotes/notes/0.4/randomized_benchmarking-de55fda43765c34c.yaml +++ b/releasenotes/notes/0.4/randomized_benchmarking-de55fda43765c34c.yaml @@ -1,5 +1,6 @@ --- fixes: - | - Initial guess function for the randomized benchmarking analysis :func:`.rb_decay` has been - upgraded to give accurate estimate of the decay function base. + Initial guess function for the randomized benchmarking analysis + :func:`~.guess.rb_decay` has been upgraded to give accurate estimate of the decay + function base. diff --git a/tox.ini b/tox.ini index 534da132ff..7d6df1b3d0 100644 --- a/tox.ini +++ b/tox.ini @@ -72,7 +72,7 @@ setenv = commands = sphinx-build -T --keep-going -b html {posargs} docs/ docs/_build/html -[testenv:docs-nitpick] +[testenv:docs-lint] passenv = EXPERIMENTS_DEV_DOCS setenv = QISKIT_DOCS_SKIP_EXECUTE = 1 From 8c7da162ea2f9ef74f179cec99f6c2d48914e72e Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Tue, 14 Mar 2023 20:30:53 -0400 Subject: [PATCH 03/10] fix lint --- qiskit_experiments/framework/__init__.py | 8 ++++---- qiskit_experiments/framework/experiment_data.py | 2 +- .../characterization/multi_state_discrimination.py | 3 ++- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/qiskit_experiments/framework/__init__.py b/qiskit_experiments/framework/__init__.py index e25b1db496..05f047b9a9 100644 --- a/qiskit_experiments/framework/__init__.py +++ b/qiskit_experiments/framework/__init__.py @@ -57,7 +57,7 @@ The experiment class contains information for generating circuits and analysis of results. These can typically be configured with a variety of options. -Once all options are set, you can call :meth:`BaseExperiment.run` method to run +Once all options are set, you can call the :meth:`.BaseExperiment.run` method to run the experiment on a Qiskit compatible ``backend``. The steps of running an experiment involves generation experimental circuits @@ -68,9 +68,9 @@ The result of running an experiment is an :class:`ExperimentData` container which contains the analysis results, any figures generated during analysis, and the raw measurement data. These can each be accessed using the -:meth:`ExperimentData.analysis_results`, :meth:`ExperimentData.figure` -and :meth:`ExperimentData.data` methods respectively. Additional metadata -for the experiment itself can be added via :meth:`ExperimentData.metadata`. +:meth:`.ExperimentData.analysis_results`, :meth:`.ExperimentData.figure` +and :meth:`.ExperimentData.data` methods respectively. Additional metadata +for the experiment itself can be added via :meth:`.ExperimentData.metadata`. Classes diff --git a/qiskit_experiments/framework/experiment_data.py b/qiskit_experiments/framework/experiment_data.py index a84684e521..ce859b10c8 100644 --- a/qiskit_experiments/framework/experiment_data.py +++ b/qiskit_experiments/framework/experiment_data.py @@ -1711,7 +1711,7 @@ def job_status(self) -> JobStatus: Possible return values for :class:`qiskit.providers.jobstatus.JobStatus` are - * `ERROR`` - if any job incurred an error + * ``ERROR`` - if any job incurred an error * ``CANCELLED`` - if any job is cancelled. * ``RUNNING`` - if any job is still running. * ``QUEUED`` - if any job is queued. diff --git a/qiskit_experiments/library/characterization/multi_state_discrimination.py b/qiskit_experiments/library/characterization/multi_state_discrimination.py index f16a69b028..f4e2689f7b 100644 --- a/qiskit_experiments/library/characterization/multi_state_discrimination.py +++ b/qiskit_experiments/library/characterization/multi_state_discrimination.py @@ -55,7 +55,8 @@ class MultiStateDiscrimination(BaseExperiment): :class:`MultiStateDiscriminationAnalysis` # section: reference - `Qiskit Textbook `_. + `Qiskit Textbook\ + `_ """ From 735cf213748f6ac97c914328a4d5722655a29b96 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Thu, 16 Mar 2023 11:27:28 -0400 Subject: [PATCH 04/10] add more config to `lint/conf.py` linux build is failing on the minimal conf so I'm adding more lines back in. hard to debug locally because the mac build has a different set of warnings. --- docs/conf.py | 2 -- docs/lint/conf.py | 8 ++++++++ docs/manuals/benchmarking/quantum_volume.rst | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 92d0d01146..14e55e01bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -185,8 +185,6 @@ if os.getenv("EXPERIMENTS_DEV_DOCS", None): rst_prolog = """ -.. raw:: html - .. note:: This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being diff --git a/docs/lint/conf.py b/docs/lint/conf.py index a36c6eb385..202f48e27e 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -31,7 +31,15 @@ "jupyter_execute_custom", ] +# Minimal options to let the build run successfully +autodoc_default_options = {"inherited-members": None} nbsphinx_allow_errors = True +autoclass_content = "both" +napoleon_custom_sections = [("data keys", "params_style"), ("style parameters", "params_style")] +autosummary_generate = True +autodoc_default_options = {"inherited-members": None} +numfig = True +numfig_format = {"table": "Table %s"} # Ignore these objects nitpick_ignore_regex = [ diff --git a/docs/manuals/benchmarking/quantum_volume.rst b/docs/manuals/benchmarking/quantum_volume.rst index b9b9ac5fdc..91b4a5ed84 100644 --- a/docs/manuals/benchmarking/quantum_volume.rst +++ b/docs/manuals/benchmarking/quantum_volume.rst @@ -138,7 +138,7 @@ Calculating Quantum Volume using a batch experiment Run the QV experiment with an increasing number of qubits to check what is the maximum Quantum Volume for the specific device. To reach the real system’s Quantum Volume, one must run more trials and additional -enhancements might be required (See Ref. [2] for details). +enhancements might be required (See Ref. [2]_ for details). .. jupyter-execute:: From 3e1895300f9df355c1c69df4440566640f632b4b Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Thu, 16 Mar 2023 11:37:23 -0400 Subject: [PATCH 05/10] rename benchmarking experiments to verification this syncs up the names on the manuals page and the API experiments page --- docs/conf.py | 6 +++--- docs/manuals/index.rst | 11 ++++++----- .../{benchmarking => verification}/quantum_volume.rst | 0 .../randomized_benchmarking.rst | 0 .../state_tomography.rst | 0 5 files changed, 9 insertions(+), 8 deletions(-) rename docs/manuals/{benchmarking => verification}/quantum_volume.rst (100%) rename docs/manuals/{benchmarking => verification}/randomized_benchmarking.rst (100%) rename docs/manuals/{benchmarking => verification}/state_tomography.rst (100%) diff --git a/docs/conf.py b/docs/conf.py index 14e55e01bd..8a866d4a62 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -94,11 +94,11 @@ # These should ideally be automatically generated using a custom macro to specify # chosen cells for thumbnails, like the nbsphinx-gallery tag nbsphinx_thumbnails = { - "manuals/benchmarking/quantum_volume": "_images/quantum_volume_2_0.png", + "manuals/verification/quantum_volume": "_images/quantum_volume_2_0.png", "manuals/measurement/readout_mitigation": "_images/readout_mitigation_4_0.png", - "manuals/benchmarking/randomized_benchmarking": "_images/randomized_benchmarking_3_1.png", + "manuals/verification/randomized_benchmarking": "_images/randomized_benchmarking_3_1.png", "manuals/measurement/restless_measurements": "_images/restless_shots.png", - "manuals/benchmarking/state_tomography": "_images/state_tomography_3_0.png", + "manuals/verification/state_tomography": "_images/state_tomography_3_0.png", "manuals/characterization/t1": "_images/t1_0_0.png", "manuals/characterization/t2ramsey": "_images/t2ramsey_4_0.png", "manuals/characterization/tphi": "_images/tphi_5_1.png", diff --git a/docs/manuals/index.rst b/docs/manuals/index.rst index a8117496d5..57ce747fc8 100644 --- a/docs/manuals/index.rst +++ b/docs/manuals/index.rst @@ -4,18 +4,19 @@ Experiment Manuals These experiment manuals are in-depth dives into individual experiments, their operational principles, and how to run them in Qiskit Experiments. -.. _benchmarking: +.. _verification: -Benchmarking Experiments +Verification Experiments ------------------------ -These experiments measure your device performance according to a set of defined -metrics, such as the space-time volume of circuits that can be successfully executed. +These experiments measure and verify your device performance according to a set of +defined metrics, such as the space-time volume of circuits that can be successfully +executed. .. nbgallery:: :glob: - benchmarking/* + verification/* .. _qubit characterization: diff --git a/docs/manuals/benchmarking/quantum_volume.rst b/docs/manuals/verification/quantum_volume.rst similarity index 100% rename from docs/manuals/benchmarking/quantum_volume.rst rename to docs/manuals/verification/quantum_volume.rst diff --git a/docs/manuals/benchmarking/randomized_benchmarking.rst b/docs/manuals/verification/randomized_benchmarking.rst similarity index 100% rename from docs/manuals/benchmarking/randomized_benchmarking.rst rename to docs/manuals/verification/randomized_benchmarking.rst diff --git a/docs/manuals/benchmarking/state_tomography.rst b/docs/manuals/verification/state_tomography.rst similarity index 100% rename from docs/manuals/benchmarking/state_tomography.rst rename to docs/manuals/verification/state_tomography.rst From ff4cf71f73ab6b16b712388ba3e8818cd802b8dc Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Thu, 16 Mar 2023 11:39:25 -0400 Subject: [PATCH 06/10] add even more config --- docs/lint/conf.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/lint/conf.py b/docs/lint/conf.py index 202f48e27e..220bae85c2 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -19,19 +19,31 @@ "sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.autosummary", - "reno.sphinxext", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.extlinks", + "sphinx_copybutton", + "jupyter_sphinx", "sphinx_autodoc_typehints", + "reno.sphinxext", + "sphinx_design", "sphinx.ext.intersphinx", + "nbsphinx", "autoref", "autodoc_experiment", "autodoc_analysis", "autodoc_visualization", - "sphinx_design", - "jupyter_sphinx", "jupyter_execute_custom", ] # Minimal options to let the build run successfully +nbsphinx_timeout = 360 +nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never") +nbsphinx_widgets_path = "" +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +language = "en" +add_module_names = False +modindex_common_prefix = ["qiskit_experiments."] autodoc_default_options = {"inherited-members": None} nbsphinx_allow_errors = True autoclass_content = "both" From d6cf0226de75695b337f9d82774c73207314091e Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Thu, 16 Mar 2023 13:19:41 -0400 Subject: [PATCH 07/10] put back in more config --- docs/lint/conf.py | 121 +++++++++++++++++++++++-- qiskit_experiments/library/__init__.py | 2 +- 2 files changed, 114 insertions(+), 9 deletions(-) diff --git a/docs/lint/conf.py b/docs/lint/conf.py index 220bae85c2..000ace1d27 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -1,13 +1,25 @@ # This is the configuration file to run sphinx linting for `tox -edocs-nitpick`. # It will output warnings for each missing reference. -import sys, os +import sys, os, datetime, subprocess sys.path.insert(0, os.path.abspath("../")) sys.path.append(os.path.abspath("../_ext")) sys.path.append(os.path.abspath("../../")) -exclude_patterns = ["_build"] +# Set env flag so that we can doc functions that may otherwise not be loaded +# see for example interactive visualizations in qiskit.visualization. +os.environ["QISKIT_DOCS"] = "TRUE" + +# -- Project information ----------------------------------------------------- +# The short X.Y version +version = "0.5" +# The full version, including alpha/beta/rc tags +release = "0.5.0" +project = f"Qiskit Experiments {version}" +copyright = f"2021-{datetime.date.today().year}, Qiskit Development Team" # pylint: disable=redefined-builtin +author = "Qiskit Development Team" + project = "Qiskit Experiments" nitpicky = True @@ -41,17 +53,110 @@ nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never") nbsphinx_widgets_path = "" exclude_patterns = ["_build", "**.ipynb_checkpoints"] -language = "en" -add_module_names = False -modindex_common_prefix = ["qiskit_experiments."] -autodoc_default_options = {"inherited-members": None} -nbsphinx_allow_errors = True -autoclass_content = "both" napoleon_custom_sections = [("data keys", "params_style"), ("style parameters", "params_style")] autosummary_generate = True autodoc_default_options = {"inherited-members": None} numfig = True numfig_format = {"table": "Table %s"} +language = "en" +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +pygments_style = "colorful" +add_module_names = False +modindex_common_prefix = ["qiskit_experiments."] +html_theme = "qiskit_sphinx_theme" # use the theme in subdir 'theme' +html_context = { + "analytics_enabled": True, + "expandable_sidebar": True, +} +html_last_updated_fmt = "%Y/%m/%d" +html_theme_options = { + "logo_only": True, + "display_version": True, + "prev_next_buttons_location": "bottom", + "style_external_links": True, +} +autoclass_content = "both" +intersphinx_mapping = { + "matplotlib": ("https://matplotlib.org/stable/", None), + "qiskit": ("https://qiskit.org/documentation/", None), + "uncertainties": ("https://pythonhosted.org/uncertainties", None), +} +if os.getenv("EXPERIMENTS_DEV_DOCS", None): + rst_prolog = """ +.. note:: + This is the documentation for the current state of the development branch + of Qiskit Experiments. The documentation or APIs here can change prior to being + released. +""" + + +def _get_versions(app, config): + context = config.html_context + start_version = (0, 5, 0) + proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True) + proc.check_returncode() + current_version = proc.stdout.decode("utf8") + current_version_info = current_version.split(".") + if current_version_info[0] == "0": + version_list = [ + "0.%s" % x for x in range(start_version[1], int(current_version_info[1]) + 1) + ] + else: + # TODO: When 1.0.0 add code to handle 0.x version list + version_list = [] + pass + context["version_list"] = version_list + context["version_label"] = _get_version_label(current_version) + + +def _get_version_label(current_version): + if not os.getenv("EXPERIMENTS_DEV_DOCS", None): + return release + else: + return "Development" + + +def setup(app): + app.connect("config-inited", _get_versions) + app.connect("autodoc-skip-member", maybe_skip_member) + + +# Hardcoded list of class variables to skip in autodoc to avoid warnings +# Should come up with better way to address this + +from qiskit_experiments.curve_analysis import ParameterRepr +from qiskit_experiments.curve_analysis import SeriesDef + + +def maybe_skip_member(app, what, name, obj, skip, options): + skip_names = [ + "analysis", + "set_run_options", + "data_allocation", + "labels", + "shots", + "x", + "y", + "y_err", + "name", + "filter_kwargs", + "fit_func", + "signature", + ] + skip_members = [ + ParameterRepr.repr, + ParameterRepr.unit, + SeriesDef.plot_color, + SeriesDef.plot_symbol, + SeriesDef.model_description, + SeriesDef.canvas, + ] + if not skip: + return (name in skip_names or obj in skip_members) and what == "attribute" + return skip + + +### # Ignore these objects nitpick_ignore_regex = [ diff --git a/qiskit_experiments/library/__init__.py b/qiskit_experiments/library/__init__.py index 8ddf8f848a..05791da6a9 100644 --- a/qiskit_experiments/library/__init__.py +++ b/qiskit_experiments/library/__init__.py @@ -65,7 +65,6 @@ ~characterization.FineAmplitude ~characterization.FineXAmplitude ~characterization.FineSXAmplitude - ~characterization.FineZXAmplitude ~characterization.Rabi ~characterization.EFRabi ~characterization.RamseyXY @@ -92,6 +91,7 @@ ~characterization.CrossResonanceHamiltonian ~characterization.EchoedCrossResonanceHamiltonian ~characterization.ZZRamsey + ~characterization.FineZXAmplitude .. _characterization-mitigation: From 9f9651ac116765d5433ac6355155dc8d3d0cc964 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Fri, 9 Jun 2023 16:33:31 -0400 Subject: [PATCH 08/10] remove unneeded code in lint conf --- docs/lint/conf.py | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/docs/lint/conf.py b/docs/lint/conf.py index 000ace1d27..2e2898eeed 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -90,34 +90,7 @@ """ -def _get_versions(app, config): - context = config.html_context - start_version = (0, 5, 0) - proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True) - proc.check_returncode() - current_version = proc.stdout.decode("utf8") - current_version_info = current_version.split(".") - if current_version_info[0] == "0": - version_list = [ - "0.%s" % x for x in range(start_version[1], int(current_version_info[1]) + 1) - ] - else: - # TODO: When 1.0.0 add code to handle 0.x version list - version_list = [] - pass - context["version_list"] = version_list - context["version_label"] = _get_version_label(current_version) - - -def _get_version_label(current_version): - if not os.getenv("EXPERIMENTS_DEV_DOCS", None): - return release - else: - return "Development" - - def setup(app): - app.connect("config-inited", _get_versions) app.connect("autodoc-skip-member", maybe_skip_member) From de6f4b5e80db88f7fe64165510ef964c5a23df20 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Fri, 9 Jun 2023 17:10:34 -0400 Subject: [PATCH 09/10] add `docs-lint` to contributor guide and format envs for ease of reading --- CONTRIBUTING.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 728d50509e..1f978af76f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,7 +89,7 @@ python when running. Additionally, the environment that tox sets up matches the environment more closely and it runs the tests in parallel (resulting in much faster execution). To run tests on all installed supported python versions and lint/style checks you can simply run `tox`. Or if you just want to run the tests once for a -specific python version such as 3.10: `tox -epy310`. +specific python version such as 3.10: `tox -e py310`. If you just want to run a subset of tests you can pass a selection regex to the test runner. For example, if you want to run all tests that have "dag" in the test id you can @@ -138,13 +138,13 @@ The qiskit-experiments repository uses `black` for code formatting and style and `pylint` for linting. You can run these checks locally with ``` -tox -elint +tox -e lint ``` If there is a code formatting issue identified by black you can just run ``black`` -locally to fix this (or ``tox -eblack`` which will install it and run it). +locally to fix this (or ``tox -e black`` which will install it and run it). -Because `pylint` analysis can be slow, there is also a `tox -elint-incr` target, which +Because `pylint` analysis can be slow, there is also a `tox -e lint-incr` target, which only applies `pylint` to files which have changed from the source github. On rare occasions this will miss some issues that would have been caught by checking the complete source tree, but makes up for this by being much faster (and those rare @@ -341,8 +341,9 @@ https://github.com/Qiskit-Extensions/qiskit-experiments` and `git fetch upstream There are a few other build options available: -* `tox -edocs-minimal`: build documentation without executing Jupyter code cells -* `tox -edocs-parallel`: do a full build with multiprocessing (may crash on Macs) +* `tox -e docs-minimal`: build documentation without executing Jupyter code cells +* `tox -e docs-parallel`: do a full build with multiprocessing (may crash on Macs) +* `tox -e docs-lint`: lint docs and check for broken links ### Deprecation policy From fa0371e7b1e9e4c80388d1ecb4bd66e17efc47a9 Mon Sep 17 00:00:00 2001 From: Helena Zhang Date: Fri, 9 Jun 2023 17:11:24 -0400 Subject: [PATCH 10/10] update conf and broken links also turns off nitpick mode --- docs/conf.py | 1 - docs/lint/conf.py | 13 ++++++++++--- docs/manuals/measurement/readout_mitigation.rst | 2 +- docs/manuals/verification/quantum_volume.rst | 2 +- docs/tutorials/calibrations.rst | 2 +- qiskit_experiments/framework/matplotlib.py | 2 +- .../library/characterization/cr_hamiltonian.py | 2 +- .../characterization/multi_state_discrimination.py | 2 +- qiskit_experiments/library/characterization/rabi.py | 4 ++-- .../library/quantum_volume/qv_experiment.py | 2 +- .../library/randomized_benchmarking/standard_rb.py | 2 +- .../notes/0.2/0_2_release-eef5e3ba256fc750.yaml | 2 +- tox.ini | 2 +- 13 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0570307794..4bf1adbd0d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,6 @@ import os import sys -import subprocess import datetime # -- Path setup -------------------------------------------------------------- diff --git a/docs/lint/conf.py b/docs/lint/conf.py index 2e2898eeed..e407b4c8c5 100644 --- a/docs/lint/conf.py +++ b/docs/lint/conf.py @@ -1,7 +1,7 @@ # This is the configuration file to run sphinx linting for `tox -edocs-nitpick`. # It will output warnings for each missing reference. -import sys, os, datetime, subprocess +import sys, os, datetime sys.path.insert(0, os.path.abspath("../")) sys.path.append(os.path.abspath("../_ext")) @@ -34,9 +34,7 @@ "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.extlinks", - "sphinx_copybutton", "jupyter_sphinx", - "sphinx_autodoc_typehints", "reno.sphinxext", "sphinx_design", "sphinx.ext.intersphinx", @@ -131,6 +129,14 @@ def maybe_skip_member(app, what, name, obj, skip, options): ### +linkcheck_ignore = [ + r"manuals/index.html", + "tutorials/index.html", + "howtos/index.html", + "cloud_service.html", + "apidocs/index.html", +] + # Ignore these objects nitpick_ignore_regex = [ ("py:.*", "qiskit.*"), @@ -147,6 +153,7 @@ def maybe_skip_member(app, what, name, obj, skip, options): ("py:.*", "typing.*"), ("py:.*", ".*Error"), ("py:.*", "Ellipsis"), + ("py:.*", "matplotlib.*"), ] # Deprecated objects that should be ignored in the release notes diff --git a/docs/manuals/measurement/readout_mitigation.rst b/docs/manuals/measurement/readout_mitigation.rst index a97b5e844b..a2cc8c3e8c 100644 --- a/docs/manuals/measurement/readout_mitigation.rst +++ b/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 `__ +* Qiskit Textbook: `Measurement Error Mitigation `__ diff --git a/docs/manuals/verification/quantum_volume.rst b/docs/manuals/verification/quantum_volume.rst index a4ea74e771..f15fd0ff41 100644 --- a/docs/manuals/verification/quantum_volume.rst +++ b/docs/manuals/verification/quantum_volume.rst @@ -190,5 +190,5 @@ See also -------- * API documentation: :mod:`~qiskit_experiments.library.quantum_volume` -* Qiskit Textbook: `Measuring Quantum Volume `__ +* Qiskit Textbook: `Measuring Quantum Volume `__ diff --git a/docs/tutorials/calibrations.rst b/docs/tutorials/calibrations.rst index 02dc1613be..9ff3d5ab00 100644 --- a/docs/tutorials/calibrations.rst +++ b/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 `__ +* Qiskit Textbook: `Calibrating Qubits with Qiskit Pulse `__ diff --git a/qiskit_experiments/framework/matplotlib.py b/qiskit_experiments/framework/matplotlib.py index dd98fe3652..ed43ceb493 100644 --- a/qiskit_experiments/framework/matplotlib.py +++ b/qiskit_experiments/framework/matplotlib.py @@ -19,7 +19,7 @@ default_figure_canvas = FigureCanvasSVG # pylint: disable=invalid-name """Matplotlib canvas to use when rendering a figure. This needs to be a canvas for a `non-interactive backend -`_. +https://matplotlib.org/stable/users/explain/backends.html#the-builtin-backends>`_. The default is `FigureCanvasSVG`.""" diff --git a/qiskit_experiments/library/characterization/cr_hamiltonian.py b/qiskit_experiments/library/characterization/cr_hamiltonian.py index 11aeb4bc63..34b3d1cd98 100644 --- a/qiskit_experiments/library/characterization/cr_hamiltonian.py +++ b/qiskit_experiments/library/characterization/cr_hamiltonian.py @@ -124,7 +124,7 @@ class CrossResonanceHamiltonian(BaseExperiment): # section: manual .. ref_website:: Qiskit Textbook 6.7, - https://qiskit.org/textbook/ch-quantum-hardware/hamiltonian-tomography.html + https://learn.qiskit.org/course/quantum-hardware-pulses/hamiltonian-tomography """ # Number of CR pulses. The flat top duration per pulse is divided by this number. diff --git a/qiskit_experiments/library/characterization/multi_state_discrimination.py b/qiskit_experiments/library/characterization/multi_state_discrimination.py index f4e2689f7b..9962d52b03 100644 --- a/qiskit_experiments/library/characterization/multi_state_discrimination.py +++ b/qiskit_experiments/library/characterization/multi_state_discrimination.py @@ -56,7 +56,7 @@ class MultiStateDiscrimination(BaseExperiment): # section: reference `Qiskit Textbook\ - `_ + `_ """ diff --git a/qiskit_experiments/library/characterization/rabi.py b/qiskit_experiments/library/characterization/rabi.py index 2b2d73ae10..641cedcbc1 100644 --- a/qiskit_experiments/library/characterization/rabi.py +++ b/qiskit_experiments/library/characterization/rabi.py @@ -51,8 +51,8 @@ class Rabi(BaseExperiment, RestlessMixin): # section: manual :ref:`Rabi Calibration` - See also `Qiskit Textbook `_ + See also `Qiskit Textbook + `_ for the pulse level programming of a Rabi experiment. # section: analysis_ref diff --git a/qiskit_experiments/library/quantum_volume/qv_experiment.py b/qiskit_experiments/library/quantum_volume/qv_experiment.py index 0770c2bbcf..163c0e8492 100644 --- a/qiskit_experiments/library/quantum_volume/qv_experiment.py +++ b/qiskit_experiments/library/quantum_volume/qv_experiment.py @@ -42,7 +42,7 @@ 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 - `_ + `_ for an explanation on the QV protocol. In the QV experiment we generate :class:`~qiskit.circuit.library.QuantumVolume` circuits on diff --git a/qiskit_experiments/library/randomized_benchmarking/standard_rb.py b/qiskit_experiments/library/randomized_benchmarking/standard_rb.py index 60bb8e23aa..e3718a9229 100644 --- a/qiskit_experiments/library/randomized_benchmarking/standard_rb.py +++ b/qiskit_experiments/library/randomized_benchmarking/standard_rb.py @@ -61,7 +61,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 - `_ + `_ for an explanation on the RB method. A standard RB experiment generates sequences of random Cliffords diff --git a/releasenotes/notes/0.2/0_2_release-eef5e3ba256fc750.yaml b/releasenotes/notes/0.2/0_2_release-eef5e3ba256fc750.yaml index 333fcb785d..6def023058 100644 --- a/releasenotes/notes/0.2/0_2_release-eef5e3ba256fc750.yaml +++ b/releasenotes/notes/0.2/0_2_release-eef5e3ba256fc750.yaml @@ -19,7 +19,7 @@ features: ``qiskit_experiments.framework.matplotlib.default_figure_canvas`` to the desired canvas. Note that it has to be a canvas for one of the `non-interactive backend - `_. + `_. For example, you can set ``default_figure_canvas`` to :class:`~matplotlib.backends.backend_agg.FigureCanvasAgg` to use the ``AGG`` backend. diff --git a/tox.ini b/tox.ini index 26933e24a4..13e9f718f9 100644 --- a/tox.ini +++ b/tox.ini @@ -80,7 +80,7 @@ passenv = EXPERIMENTS_DEV_DOCS setenv = QISKIT_DOCS_SKIP_EXECUTE = 1 commands = - sphinx-build -c docs/lint -n -T --keep-going -b linkcheck {posargs} docs/ docs/_build/html + sphinx-build -c docs/lint -T --keep-going -b linkcheck {posargs} docs/ docs/_build/html [pycodestyle] max-line-length = 100