From e3e066baec98d6cf10a732b671287e75ccf060a7 Mon Sep 17 00:00:00 2001 From: Kevin Tian Date: Fri, 10 Jan 2025 14:39:34 -0500 Subject: [PATCH] Update ZNE options docs (#2094) Co-authored-by: ptristan3 <44805021+ptristan3@users.noreply.github.com> --- qiskit_ibm_runtime/options/zne_options.py | 111 +++++++++++----------- 1 file changed, 55 insertions(+), 56 deletions(-) diff --git a/qiskit_ibm_runtime/options/zne_options.py b/qiskit_ibm_runtime/options/zne_options.py index c13b46c36..438659271 100644 --- a/qiskit_ibm_runtime/options/zne_options.py +++ b/qiskit_ibm_runtime/options/zne_options.py @@ -71,62 +71,6 @@ class ZneOptions: extrapolator. If your work requires a nuanced distinction in this regard, we presently recommend that you use single-term observables in addition to your multi-term observables. - - Args: - amplifier: Which technique to use for amplifying noise. One of: - - * `"gate_folding"` (default) uses 2-qubit gate folding to amplify noise. If the noise - factor requires amplifying only a subset of the gates, then these gates are chosen - randomly. - * `"gate_folding_front"` uses 2-qubit gate folding to amplify noise. If the noise - factor requires amplifying only a subset of the gates, then these gates are selected - from the front of the topologically ordered DAG circuit. - * `"gate_folding_back"` uses 2-qubit gate folding to amplify noise. If the noise - factor requires amplifying only a subset of the gates, then these gates are selected - from the back of the topologically ordered DAG circuit. - * `"pea"` uses a technique called Probabilistic Error Amplification (`PEA - `_) to amplify - noise. - - When this option is selected, gate twirling will always be used whether or not it has - been enabled in the options. - - In this technique, the twirled noise model of each each unique layer of - entangling gates in your ISA circuits is learned beforehand, see - :class:`~.LayerNoiseLearningOptions` for relevant learning options. Once complete, - your circuits are executed at each noise factor, where every entangling layer of - your circuits is amplified by probabilistically injecting single-qubit noise - proportional to the corresponding learned noise model. - - noise_factors: Noise factors to use for noise amplification. Default: ``(1, 1.5, 2)`` for - PEA, and ``(1, 3, 5)`` otherwise. - - extrapolated_noise_factors: Noise factors to evaluate the fit extrapolation models at. - If unset, this will default to ``[0, *noise_factors]``. This - option does not affect execution or model fitting in any way, it only determines the - points at which the ``extrapolator``\\s are evaluated to be returned in the data - fields called ``evs_extrapolated`` and ``stds_extrapolated``. - - extrapolator: Extrapolator(s) to try (in order) for extrapolating to zero noise. - The available options are: - - * ``"exponential"``, which fits the data using an exponential decaying function defined - as :math:`f(x; A, \\tau) = A e^{-x/\\tau}`, where :math:`A = f(0; A, \\tau)` is the - value at zero noise (:math:`x=0`) and :math:`\\tau>0` is a positive rate. - * ``"double_exponential"``, which uses a sum of two exponential as in Ref. 1. - * ``"polynomial_degree_(1 <= k <= 7)"``, which uses a polynomial function defined as - :math:`f(x; c_0, c_1, \\ldots, c_k) = \\sum_{i=0, k} c_i x^i`. - * ``"linear"``, which is equivalent to ``"polynomial_degree_1"``. - * ``"fallback"``, which simply returns the raw data corresponding to the lowest noise - factor (typically ``1``) without performing any sort of extrapolation. - - If more than one extrapolator is specified, the ``evs`` and ``stds`` reported in the - result's data refer to the first one, while the extrapolated values - (``evs_extrapolated`` and ``stds_extrapolated``) are sorted according to the order of - the extrapolators provided. - - Default: ``("exponential", "linear")``. - References: 1. Z. Cai, *Multi-exponential error extrapolation and combining error mitigation techniques for NISQ applications*, @@ -136,9 +80,64 @@ class ZneOptions: amplifier: Union[ UnsetType, Literal["gate_folding", "gate_folding_front", "gate_folding_back", "pea"] ] = Unset + r"""Which technique to use for amplifying noise. + + One of: + + * `"gate_folding"` (default) uses 2-qubit gate folding to amplify noise. If the noise + factor requires amplifying only a subset of the gates, then these gates are chosen + randomly. + * `"gate_folding_front"` uses 2-qubit gate folding to amplify noise. If the noise + factor requires amplifying only a subset of the gates, then these gates are selected + from the front of the topologically ordered DAG circuit. + * `"gate_folding_back"` uses 2-qubit gate folding to amplify noise. If the noise + factor requires amplifying only a subset of the gates, then these gates are selected + from the back of the topologically ordered DAG circuit. + * `"pea"` uses a technique called Probabilistic Error Amplification + (`PEA `_) to amplify noise. When this + option is selected, gate twirling will always be used whether or not it has been + enabled in the options. In this technique, the twirled noise model of each each unique + layer of entangling gates in your ISA circuits is learned beforehand, see + :class:`~.LayerNoiseLearningOptions` for relevant learning options. Once complete, + your circuits are executed at each noise factor, where every entangling layer of + your circuits is amplified by probabilistically injecting single-qubit noise + proportional to the corresponding learned noise model. + """ noise_factors: Union[UnsetType, Sequence[float]] = Unset + r""" noise_factors: Noise factors to use for noise amplification. + + Default: ``(1, 1.5, 2)`` for PEA, and ``(1, 3, 5)`` otherwise. + """ extrapolator: Union[UnsetType, ExtrapolatorType, Sequence[ExtrapolatorType]] = Unset + r"""Extrapolator(s) to try (in order) for extrapolating to zero noise. + + The available options are: + + * ``"exponential"``, which fits the data using an exponential decaying function defined + as :math:`f(x; A, \\tau) = A e^{-x/\\tau}`, where :math:`A = f(0; A, \\tau)` is the + value at zero noise (:math:`x=0`) and :math:`\\tau>0` is a positive rate. + * ``"double_exponential"``, which uses a sum of two exponential as in Ref. 1. + * ``"polynomial_degree_(1 <= k <= 7)"``, which uses a polynomial function defined as + :math:`f(x; c_0, c_1, \\ldots, c_k) = \\sum_{i=0, k} c_i x^i`. + * ``"linear"``, which is equivalent to ``"polynomial_degree_1"``. + * ``"fallback"``, which simply returns the raw data corresponding to the lowest noise + factor (typically ``1``) without performing any sort of extrapolation. + + If more than one extrapolator is specified, the ``evs`` and ``stds`` reported in the + result's data refer to the first one, while the extrapolated values + (``evs_extrapolated`` and ``stds_extrapolated``) are sorted according to the order of + the extrapolators provided. + + Default: ``("exponential", "linear")``. + """ extrapolated_noise_factors: Union[UnsetType, Sequence[float]] = Unset + r"""Noise factors to evaluate the fit extrapolation models at. + + If unset, this will default to ``[0, *noise_factors]``. This + option does not affect execution or model fitting in any way, it only determines the + points at which the ``extrapolator``\\s are evaluated to be returned in the data + fields called ``evs_extrapolated`` and ``stds_extrapolated``. + """ def _default_noise_factors(self) -> Sequence[float]: return (1, 1.5, 2, 2.5, 3) if self.amplifier == "pea" else (1, 3, 5)