Autodoc migration for RB

qiskit_experiments/library/__init__.py

@@ -32,9 +32,14 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :template: autosummary/experiment.rst
 
     ~randomized_benchmarking.StandardRB
     ~randomized_benchmarking.InterleavedRB
+
+.. autosummary::
+    :toctree: ../stubs/
+
     ~tomography.StateTomography
     ~tomography.ProcessTomography
     ~quantum_volume.QuantumVolume

qiskit_experiments/library/randomized_benchmarking/__init__.py

@@ -21,6 +21,7 @@
 ===========
 .. autosummary::
     :toctree: ../stubs/
+    :template: autosummary/experiment.rst
 
     StandardRB
     InterleavedRB
@@ -31,9 +32,14 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :template: autosummary/analysis.rst
 
     RBAnalysis
     InterleavedRBAnalysis
+
+.. autosummary::
+    :toctree: ../stubs/
+
     RBUtils
 """
 from .rb_experiment import StandardRB

qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py

@@ -24,14 +24,13 @@
 class InterleavedRBAnalysis(RBAnalysis):
     r"""A class to analyze interleaved randomized benchmarking experiment.
 
-    Overview
+    # section: overview
         This analysis takes only two series for standard and interleaved RB curve fitting.
         From the fit :math:`\alpha` and :math:`\alpha_c` value this analysis estimates
         the error per Clifford (EPC) of the interleaved gate.
 
         The EPC estimate is obtained using the equation
 
-
         .. math::
 
             r_{\mathcal{C}}^{\text{est}} =
@@ -52,44 +51,45 @@ class InterleavedRBAnalysis(RBAnalysis):
 
         See Ref. [1] for more details.
 
+    # section: fit_model
+        The fit is based on the following decay functions:
 
+        Fit model for standard RB
 
-    Fit Model
-        The fit is based on the following decay functions:
+        .. math::
+
+            F(x) = a \alpha^{x} + b
+
+        Fit model for interleaved RB
 
         .. math::
 
-            F_1(x_1) &= a \alpha^{x_1} + b  \quad {\rm for standard RB} \\
-            F_2(x_2) &= a (\alpha_c \alpha)^{x_2} + b \quad {\rm for interleaved RB}
-
-    Fit Parameters
-        - :math:`a`: Height of decay curve.
-        - :math:`b`: Base line.
-        - :math:`\alpha`: Depolarizing parameter.
-        - :math:`\alpha_c`: Ratio of the depolarizing parameter of
-          interleaved RB to standard RB curve.
-
-    Initial Guesses
-        - :math:`a`: Determined by the average :math:`a` of the standard and interleaved RB.
-        - :math:`b`: Determined by the average :math:`b` of the standard and interleaved RB.
-          Usually equivalent to :math:`(1/2)**n` where :math:`n` is number of qubit.
-        - :math:`\alpha`: Determined by the slope of :math:`(y_1 - b)**(-x_1)` of the first and the
-          second data point of the standard RB.
-        - :math:`\alpha_c`: Estimate :math:`\alpha' = \alpha_c * \alpha` from the
-          interleaved RB curve, then divide this by the initial guess of :math:`\alpha`.
-
-    Bounds
-        - :math:`a`: [0, 1]
-        - :math:`b`: [0, 1]
-        - :math:`\alpha`: [0, 1]
-        - :math:`\alpha_c`: [0, 1]
-
-    References
-        1. Easwar Magesan, Jay M. Gambetta, B. R. Johnson, Colm A. Ryan, Jerry M. Chow,
-           Seth T. Merkel, Marcus P. da Silva, George A. Keefe, Mary B. Rothwell, Thomas A. Ohki,
-           Mark B. Ketchen, M. Steffen, Efficient measurement of quantum gate error by
-           interleaved randomized benchmarking,
-           `arXiv:quant-ph/1203.4550 <https://arxiv.org/pdf/1203.4550>`_
+            F(x) = a (\alpha_c \alpha)^{x_2} + b
+
+    # section: fit_parameters
+        defpar a:
+            desc: Height of decay curve.
+            init_guess: Determined by the average :math:`a` of the standard and interleaved RB.
+            bounds: [0, 1]
+        defpar b:
+            desc: Base line.
+            init_guess: Determined by the average :math:`b` of the standard and interleaved RB.
+                Usually equivalent to :math:`(1/2)^n` where :math:`n` is number of qubit.
+            bounds: [0, 1]
+        defpar \alpha:
+            desc: Depolarizing parameter.
+            init_guess: Determined by the slope of :math:`(y - b)^{-x}` of the first and the
+                second data point of the standard RB.
+            bounds: [0, 1]
+        defpar \alpha_c:
+            desc: Ratio of the depolarizing parameter of interleaved RB to standard RB curve.
+            init_guess: Estimate :math:`\alpha' = \alpha_c \alpha` from the
+                interleaved RB curve, then divide this by the initial guess of :math:`\alpha`.
+            bounds: [0, 1]
+
+    # section: reference
+        .. ref_arxiv:: 1 1203.4550
+
     """
 
     __series__ = [
@@ -117,11 +117,7 @@ class InterleavedRBAnalysis(RBAnalysis):
 
     @classmethod
     def _default_options(cls):
-        """Return default data processing options.
-
-        See :meth:`~qiskit_experiment.curve_analysis.CurveAnalysis._default_options` for
-        descriptions of analysis options.
-        """
+        """Default analysis options."""
         default_options = super()._default_options()
         default_options.p0 = {"a": None, "alpha": None, "alpha_c": None, "b": None}
         default_options.bounds = {

qiskit_experiments/library/randomized_benchmarking/interleaved_rb_experiment.py

@@ -25,9 +25,9 @@
 
 
 class InterleavedRB(StandardRB):
-    """Interleaved Randomized Benchmarking Experiment class.
+    """Interleaved randomized benchmarking experiment.
 
-    Overview
+    # section: overview
         Interleaved Randomized Benchmarking (RB) is a method
         to estimate the average error-rate of a certain quantum gate.
 
@@ -37,24 +37,9 @@ class InterleavedRB(StandardRB):
         the ground state, fits the two exponentially decaying curves, and estimates
         the interleaved gate error. See Ref. [1] for details.
 
-        See :class:`InterleavedRBAnalysis` documentation for additional
-        information on interleaved RB experiment analysis.
+    # section: reference
+        .. ref_arxiv:: 1 1203.4550
 
-    References
-        1. Easwar Magesan, Jay M. Gambetta, B. R. Johnson, Colm A. Ryan, Jerry M. Chow,
-           Seth T. Merkel, Marcus P. da Silva, George A. Keefe, Mary B. Rothwell, Thomas A. Ohki,
-           Mark B. Ketchen, M. Steffen, Efficient measurement of quantum gate error by
-           interleaved randomized benchmarking,
-           `arXiv:quant-ph/1203.4550 <https://arxiv.org/pdf/1203.4550>`_
-
-    Analysis Class
-        :class:`InterleavedRBAnalysis`
-
-    Experiment Options
-        - **lengths**: A list of RB sequences lengths.
-        - **num_samples**: Number of samples to generate for each sequence length.
-        - **interleaved_element**: The element to interleave,
-          given either as a group element or as an instruction/circuit
     """
 
     # Analysis class for experiment

qiskit_experiments/library/randomized_benchmarking/rb_analysis.py

@@ -27,34 +27,31 @@
 class RBAnalysis(curve.CurveAnalysis):
     r"""A class to analyze randomized benchmarking experiments.
 
-    Overview
+    # section: overview
         This analysis takes only single series.
         This series is fit by the exponential decay function.
         From the fit :math:`\alpha` value this analysis estimates the error per Clifford (EPC).
 
-    Fit Model
-        The fit is based on the following decay function:
-
+    # section: fit_model
         .. math::
 
             F(x) = a \alpha^x + b
 
-    Fit Parameters
-        - :math:`a`: Height of decay curve.
-        - :math:`b`: Base line.
-        - :math:`\alpha`: Depolarizing parameter. This is the fit parameter of main interest.
-
-    Initial Guesses
-        - :math:`a`: Determined by :math:`(y_0 - b) / \alpha^x_0`
-          where :math:`b` and :math:`\alpha` are initial guesses.
-        - :math:`b`: Determined by :math:`(1/2)^n` where :math:`n` is the number of qubit.
-        - :math:`\alpha`: Determined by the slope of :math:`(y - b)^{-x}` of the first and the
-          second data point.
-
-    Bounds
-        - :math:`a`: [0, 1]
-        - :math:`b`: [0, 1]
-        - :math:`\alpha`: [0, 1]
+    # section: fit_parameters
+        defpar a:
+            desc: Height of decay curve.
+            init_guess: Determined by :math:`(y - b) / \alpha^x`.
+            bounds: [0, 1]
+        defpar b:
+            desc: Base line.
+            init_guess: Determined by the average :math:`b` of the standard and interleaved RB.
+                Usually equivalent to :math:`(1/2)^n` where :math:`n` is number of qubit.
+            bounds: [0, 1]
+        defpar \alpha:
+            desc: Depolarizing parameter.
+            init_guess: Determined by the slope of :math:`(y - b)^{-x}` of the first and the
+                second data point.
+            bounds: [0, 1]
 
     """
 
@@ -70,10 +67,18 @@ class RBAnalysis(curve.CurveAnalysis):
 
     @classmethod
     def _default_options(cls):
-        """Return default options.
+        """Default analysis options.
+
+        Analysis Options:
+            error_dict (Dict[Tuple[Iterable[int], str], float]): Optional.
+                Error estimates for gates from the backend properties.
+            epg_1_qubit (Dict[int, Dict[str, float]]) : Optional.
+                EPG data for the 1-qubit gate involved,
+                assumed to have been obtained from previous experiments.
+                This is used to estimate the 2-qubit EPG.
+            gate_error_ratio (Dict[str, float]): An estimate for the ratios
+                between errors on different gates.
 
-        See :meth:`~qiskit_experiment.curve_analysis.CurveAnalysis._default_options` for
-        descriptions of analysis options.
         """
         default_options = super()._default_options()
         default_options.p0 = {"a": None, "alpha": None, "b": None}

qiskit_experiments/library/randomized_benchmarking/rb_experiment.py

@@ -31,9 +31,9 @@
 
 
 class StandardRB(BaseExperiment):
-    """Standard Randomized Benchmarking Experiment class.
+    """Standard randomized benchmarking experiment.
 
-    Overview
+    # section: overview
         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
@@ -44,38 +44,17 @@ class StandardRB(BaseExperiment):
         such that the unitary computed by the sequences is the identity.
         After running the sequences on a backend, it calculates the probabilities to get back to
         the ground state, fits an exponentially decaying curve, and estimates
-        the Error Per Clifford (EPC), as described in Ref. [1, 2].
-
-        See :class:`RBAnalysis` documentation for additional
-        information on RB experiment analysis.
+        the Error Per Clifford (EPC), as described in Refs. [1, 2].
 
         See :class:`RBUtils` documentation for additional information
         on estimating the Error Per Gate (EPG) for 1-qubit and 2-qubit gates,
         from 1-qubit and 2-qubit standard RB experiments, by Ref. [3].
 
-    References
-        1. Easwar Magesan, J. M. Gambetta, and Joseph Emerson,
-           Robust randomized benchmarking of quantum processes,
-           `arXiv:quant-ph/1009.3639 <https://arxiv.org/pdf/1009.3639>`_
-        2. Easwar Magesan, Jay M. Gambetta, and Joseph Emerson,
-           Characterizing Quantum Gates via Randomized Benchmarking,
-           `arXiv:quant-ph/1009.6887 <https://arxiv.org/pdf/1109.6887>`_
-        3. David C. McKay, Sarah Sheldon, John A. Smolin, Jerry M. Chow, and Jay M. Gambetta,
-           Three Qubit Randomized Benchmarking, `arXiv:quant-ph/1712.06550
-           <https://arxiv.org/pdf/1712.06550>`_
-
-    Analysis Class
-        :class:`RBAnalysis`
-
-    Experiment Options
-        - **lengths**: A list of RB sequences lengths.
-        - **num_samples**: Number of samples to generate for each sequence length.
-
-    Analysis Options
-        - **error_dict**: Optional. Error estimates for gates from the backend properties.
-        - **epg_1_qubit**: Optional. EPG data for the 1-qubit gate involved, assumed to
-          have been obtained from previous experiments. This is used to estimate the 2-qubit EPG.
-        - **gate_error_ratio**: An estimate for the ratios between errors on different gates.
+    # section: reference
+        .. ref_arxiv:: 1 1009.3639
+        .. ref_arxiv:: 2 1109.6887
+        .. ref_arxiv:: 3 1712.06550
+
     """
 
     # Analysis class for experiment
@@ -136,13 +115,22 @@ def _verify_parameters(self, lengths, num_samples):
 
     @classmethod
     def _default_experiment_options(cls):
+        """Default experiment options.
+
+        Experiment Options:
+            lengths (List[int]): A list of RB sequences lengths.
+            num_samples (int): Number of samples to generate for each sequence length.
+
+        """
         return Options(lengths=None, num_samples=None)
 
     # pylint: disable = arguments-differ
     def circuits(self, backend: Optional[Backend] = None) -> List[QuantumCircuit]:
         """Return a list of RB circuits.
+
         Args:
             backend (Backend): Optional, a backend object.
+
         Returns:
             A list of :class:`QuantumCircuit`.
         """