diff --git a/qiskit_experiments/library/__init__.py b/qiskit_experiments/library/__init__.py index 82e492c662..2297bec910 100644 --- a/qiskit_experiments/library/__init__.py +++ b/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 diff --git a/qiskit_experiments/library/randomized_benchmarking/__init__.py b/qiskit_experiments/library/randomized_benchmarking/__init__.py index 01ffad9bc4..3b3ee177ea 100644 --- a/qiskit_experiments/library/randomized_benchmarking/__init__.py +++ b/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 diff --git a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py b/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py index cfcd9fdeef..078bc8ed1f 100644 --- a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_analysis.py +++ b/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 `_ + 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 = { diff --git a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_experiment.py b/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_experiment.py index 8542abbde5..cf3c40d7a8 100644 --- a/qiskit_experiments/library/randomized_benchmarking/interleaved_rb_experiment.py +++ b/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 `_ - - 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 diff --git a/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py b/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py index af3944a784..cba70103af 100644 --- a/qiskit_experiments/library/randomized_benchmarking/rb_analysis.py +++ b/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} diff --git a/qiskit_experiments/library/randomized_benchmarking/rb_experiment.py b/qiskit_experiments/library/randomized_benchmarking/rb_experiment.py index 2f2bdea53a..d253bc8cf4 100644 --- a/qiskit_experiments/library/randomized_benchmarking/rb_experiment.py +++ b/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 `_ - 2. Easwar Magesan, Jay M. Gambetta, and Joseph Emerson, - Characterizing Quantum Gates via Randomized Benchmarking, - `arXiv:quant-ph/1009.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 - `_ - - 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`. """