Adjust tomography doc strings to automatic template

qiskit_experiments/library/__init__.py

@@ -36,12 +36,12 @@
 
     ~randomized_benchmarking.StandardRB
     ~randomized_benchmarking.InterleavedRB
+    ~tomography.StateTomography
+    ~tomography.ProcessTomography
 
 .. autosummary::
     :toctree: ../stubs/
 
-    ~tomography.StateTomography
-    ~tomography.ProcessTomography
     ~quantum_volume.QuantumVolume
 
 .. _characterization:

qiskit_experiments/library/tomography/__init__.py

@@ -22,6 +22,7 @@
 ===========
 .. autosummary::
     :toctree: ../stubs/
+    :template: autosummary/experiment.rst
 
     StateTomography
     ProcessTomography
@@ -32,6 +33,7 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :template: autosummary/analysis.rst
 
     StateTomographyAnalysis
     ProcessTomographyAnalysis

qiskit_experiments/library/tomography/qpt_analysis.py

@@ -20,41 +20,10 @@
 class ProcessTomographyAnalysis(TomographyAnalysis):
     """Quantum state and process tomography experiment analysis.
 
-    Analysis Options
-        - **measurement_basis**
-          (:class:`~qiskit_experiments.library.tomography.basis.BaseFitterMeasurementBasis`):
-          The measurement
-          :class:`~qiskit_experiments.library.tomography.basis.BaseFitterMeasurementBasis`
-          to use for tomographic reconstruction when running a
-          :class:`~qiskit_experiments.library.tomography.StateTomography` or
-          :class:`~qiskit_experiments.library.tomography.ProcessTomography`.
-        - **preparation_basis**
-          (:class:`~qiskit_experiments.library.tomography.basis.BaseFitterPreparationBasis`):
-          The preparation
-          :class:`~qiskit_experiments.library.tomography.basis.BaseFitterPreparationBasis`
-          to use for tomographic reconstruction for
-          :class:`~qiskit_experiments.library.tomography.ProcessTomography`.
-        - **fitter** (``str`` or ``Callable``): The fitter function to use for reconstruction.
-          This can  be a string to select one of the built-in fitters, or a callable to
-          supply a custom fitter function. See the `Fitter Functions` section
-          for additional information.
-        - **rescale_positive** (``bool``): If True rescale the state returned by the fitter
-          to be positive-semidefinite. See the `PSD Rescaling` section for
-          additional information (Default: True).
-        - **rescale_trace** (``bool``): If True rescale the state returned by the fitter
-          have either trace 1 for :class:`~qiskit.quantum_info.DensityMatrix`,
-          or trace dim for :class:`~qiskit.quantum_info.Choi`.
-          matrices (Default: True).
-        - **target** (``QuantumChannel`` or ``Operator``) Set a custom target quantum
-          channel for computing the :func:~qiskit.quantum_info.process_fidelity` of the
-          fitted process against. If ``"default"`` the ideal process corresponding for
-          the input circuit will be used. If ``None`` no fidelity will be computed
-          (Default: "default").
-        - **kwargs**: will be supplied to the fitter function,
-          for documentation of available args refer to the fitter function
-          documentation.
-
-    Fitter Functions
+    # section: overview
+
+        Fitter Functions
+
         Built-in fitter functions may be selected using the following string
         labels, refer to the corresponding functions documentation for additional
         details on the fitters.
@@ -70,30 +39,44 @@ class ProcessTomographyAnalysis(TomographyAnalysis):
         * ``"cvxpy_gaussian_lstsq"``:
           :func:`~qiskit_experiments.library.tomography.fitters.cvxpy_gaussian_lstsq`
 
-        .. note::
-
-            Fitters starting with ``"cvxpy_*"`` require the optional CVXPY Python
-            package to be installed.
+        PSD Rescaling
 
-        .. warning::
-            The API for tomography fitters is still under development so may change
-            in future releases.
-
-    PSD Rescaling
         For fitters that do not constrain the reconstructed state to be
         `positive-semidefinite` (PSD) we construct the maximum-likelihood
         nearest PSD state under the assumption of Gaussian measurement noise
         using the rescaling method in Reference [1]. For fitters that already
         support PSD constraints this option can be disabled by setting
         ``rescale_positive=False``.
 
-    References
-        1. J Smolin, JM Gambetta, G Smith, Phys. Rev. Lett. 108, 070502 (2012).
-           Open access: https://arxiv.org/abs/arXiv:1106.5458
+    # section: note
+        Fitters starting with ``"cvxpy_*"`` require the optional CVXPY Python
+        package to be installed.
+
+    # section: warning
+        The API for tomography fitters is still under development so may change
+        in future releases.
+
+    # section: reference
+        .. ref_arxiv:: 1 1106.5458
+
+    # section: see_also
+        qiskit_experiments.library.tomography.tomography_analysis.TomographyAnalysis
+
     """
 
     @classmethod
     def _default_options(cls) -> Options:
+        """Default analysis options
+
+        Analysis Options:
+            target (Union[str, :class:`~qiskit.quantum_info..operators.channel.quantum_channel`,
+                :class:`~qiskit.quantum_info.Operator`]): Set a custom target quantum
+                channel for computing the :func:~qiskit.quantum_info.process_fidelity` of the
+                fitted process against. If ``"default"`` the ideal process corresponding for
+                the input circuit will be used. If ``None`` no fidelity will be computed
+                (Default: "default").
+
+        """
         options = super()._default_options()
 
         options.measurement_basis = PauliMeasurementBasis()

qiskit_experiments/library/tomography/qpt_experiment.py

@@ -25,7 +25,7 @@
 class ProcessTomography(TomographyExperiment):
     """Quantum process tomography experiment.
 
-    Overview
+    # section: overview
         Quantum process tomography (QPT) is a method for experimentally
         reconstructing the quantum channel from measurement data.
 
@@ -34,51 +34,57 @@ class ProcessTomography(TomographyExperiment):
         bases. The resulting measurement data is then post-processed by a
         tomography fitter to reconstruct the quantum channel.
 
-        See :class:`TomographyAnalysis` documentation for additional
-        information on tomography experiment analysis.
-
-        .. note::
-            Performing full process tomography on an `N`-qubit circuit requires
-            running :math:`4^N 3^N` measurement circuits when using the default
-            preparation and measurement bases.
-
-    Analysis Class
-        :class:`~qiskit_experiments.library.tomography.TomographyAnalysis`.
-
-    Experiment Options
-        - **measurement_basis** (:class:`~basis.BaseTomographyMeasurementBasis`)
-          The Tomography measurement basis to use for the experiment.
-          The default basis is the :class:`~basis.PauliMeasurementBasis` which
-          performs measurements in the Pauli Z, X, Y bases for each qubit
-          measurement.
-        - **preparation_basis** (:class:`~basis.BaseTomographyPreparationBasis`)
-          The Tomography measurement basis to use for the experiment.
-          The default basis is the :class:`~basis.PauliPreparationBasis` which
-          prepares the :math:`|0\\rangle, |1\\rangle, |+\\rangle |+i\\rangle`
-          states on each prepared qubit.
-
-    Analysis Options:
-        - **measurement_basis**
-          (:class:`~basis.BaseFitterMeasurementBasis`):
-          A custom measurement basis for analysis. By default the
-          :meth:`experiment_options` measurement basis will be used.
-        - **preparation_basis**
-          (:class:`~basis.BaseFitterPreparationBasis`):
-          A custom preparation basis for analysis. By default the
-          :meth:`experiment_options` preparation basis will be used.
-        - **fitter** (``str`` or ``Callable``): The fitter function to use for
-          reconstruction.
-        - **rescale_psd** (``bool``): If True rescale the fitted state to be
-          positive-semidefinite (Default: True).
-        - **rescale_trace** (``bool``): If True rescale the state returned by the fitter
-          have either trace 1 (Default: True).
-        - **kwargs**: Additional kwargs will be supplied to the fitter function.
+    # section: note
+        Performing full process tomography on an `N`-qubit circuit requires
+        running :math:`4^N 3^N` measurement circuits when using the default
+        preparation and measurement bases.
+
+    # section: see_also
+        qiskit_experiments.library.tomography.tomography_experiment.TomographyExperiment
+
     """
 
     __analysis_class__ = ProcessTomographyAnalysis
 
+    @classmethod
+    def _default_experiment_options(cls) -> Options:
+        """Default experiment options.
+
+        Experiment Options:
+            measurement_basis (:class:`~basis.BaseTomographyMeasurementBasis`): The
+                Tomography measurement basis to use for the experiment.
+                The default basis is the :class:`~basis.PauliMeasurementBasis` which
+                performs measurements in the Pauli Z, X, Y bases for each qubit
+                measurement.
+            preparation_basis (:class:`~basis.BaseTomographyPreparationBasis`):
+                The Tomography measurement basis to use for the experiment.
+                The default basis is the :class:`~basis.PauliPreparationBasis` which
+                prepares the :math:`|0\\rangle, |1\\rangle, |+\\rangle |+i\\rangle`
+                states on each prepared qubit.
+        """
+        options = super()._default_experiment_options()
+
+        return options
+
     @classmethod
     def _default_analysis_options(cls) -> Options:
+        """Default analysis options.
+
+        Analysis Options:
+            measurement_basis (:class:`~basis.BaseFitterMeasurementBasis`): A custom measurement
+                basis for analysis. By default the :meth:`experiment_options` measurement basis
+                will be used.
+            preparation_basis (:class:`~basis.BaseFitterPreparationBasis`): A custom preparation
+                basis for analysis. By default the :meth:`experiment_options` preparation basis
+                will be used.
+            fitter (str or Callable): The fitter function to use for reconstruction.
+                rescale_psd (bool): If True rescale the fitted state to be positive-semidefinite
+                (Default: True).
+            rescale_trace (bool): If True rescale the state returned by the fitter have either
+                trace 1 (Default: True).
+            kwargs: Additional kwargs will be supplied to the fitter function.
+
+        """
         options = super()._default_analysis_options()
 
         options.measurement_basis = basis.PauliMeasurementBasis()

qiskit_experiments/library/tomography/qst_analysis.py

@@ -20,34 +20,9 @@
 class StateTomographyAnalysis(TomographyAnalysis):
     """State tomography experiment analysis.
 
-    Analysis Options
-        - **measurement_basis**
-          (:class:`~qiskit_experiments.library.tomography.basis.BaseFitterMeasurementBasis`):
-          The measurement
-          :class:`~qiskit_experiments.library.tomography.basis.BaseFitterMeasurementBasis`
-          to use for tomographic reconstruction when running a
-          :class:`~qiskit_experiments.library.tomography.StateTomography` or
-          :class:`~qiskit_experiments.library.tomography.ProcessTomography`.
-        - **fitter** (``str`` or ``Callable``): The fitter function to use for reconstruction.
-          This can  be a string to select one of the built-in fitters, or a callable to
-          supply a custom fitter function. See the `Fitter Functions` section
-          for additional information.
-        - **rescale_positive** (``bool``): If True rescale the state returned by the fitter
-          to be positive-semidefinite. See the `PSD Rescaling` section for
-          additional information (Default: True).
-        - **rescale_trace** (``bool``): If True rescale the state returned by the fitter
-          have either trace 1 for :class:`~qiskit.quantum_info.DensityMatrix`,
-          or trace dim for :class:`~qiskit.quantum_info.Choi`.
-          matrices (Default: True).
-        - **target** (``Statevector`` or ``DensityMatrix``) Set a custom target state
-          for computing the :func:`~qiskit.quantum_info.state_fidelity` of the fitted
-          state against. If ``"default"``  the ideal state prepared by the input circuit
-          will be used. If ``None`` no fidelity will be computed (Default: "default").
-        - **kwargs**: will be supplied to the fitter function,
-          for documentation of available args refer to the fitter function
-          documentation.
-
-    Fitter Functions
+    # section: overview
+        Fitter Functions
+
         Built-in fitter functions may be selected using the following string
         labels, refer to the corresponding functions documentation for additional
         details on the fitters.
@@ -63,30 +38,42 @@ class StateTomographyAnalysis(TomographyAnalysis):
         * ``"cvxpy_gaussian_lstsq"``:
           :func:`~qiskit_experiments.library.tomography.fitters.cvxpy_gaussian_lstsq`
 
-        .. note::
-
-            Fitters starting with ``"cvxpy_*"`` require the optional CVXPY Python
-            package to be installed.
+        PSD Rescaling
 
-        .. warning::
-            The API for tomography fitters is still under development so may change
-            in future releases.
-
-    PSD Rescaling
         For fitters that do not constrain the reconstructed state to be
         `positive-semidefinite` (PSD) we construct the maximum-likelihood
         nearest PSD state under the assumption of Gaussian measurement noise
         using the rescaling method in Reference [1]. For fitters that already
         support PSD constraints this option can be disabled by setting
         ``rescale_positive=False``.
 
-    References
-        1. J Smolin, JM Gambetta, G Smith, Phys. Rev. Lett. 108, 070502 (2012).
-           Open access: https://arxiv.org/abs/arXiv:1106.5458
+    # section: warning
+        The API for tomography fitters is still under development so may change
+        in future releases.
+
+    # section: note
+        Fitters starting with ``"cvxpy_*"`` require the optional CVXPY Python
+        package to be installed.
+
+    # section: reference
+        .. ref_arxiv:: 1 1106.5458
+
+    # section: see_also
+        qiskit_experiments.library.tomography.tomography_analysis.TomographyAnalysis
+
     """
 
     @classmethod
     def _default_options(cls) -> Options:
+        """Default analysis options
+
+        Analysis Options:
+            target (Union[str, :class:`~qiskit.quantum_info.DensityMatrix`,
+                :class:`~qiskit.quantum_info.StateVector`]): Set a custom target state
+                for computing the :func:`~qiskit.quantum_info.state_fidelity` of the fitted
+                state against. If ``"default"``  the ideal state prepared by the input circuit
+                will be used. If ``None`` no fidelity will be computed (Default: "default").
+        """
         options = super()._default_options()
 
         options.measurement_basis = PauliMeasurementBasis()