Skip to content

Commit

Permalink
Update ZNE options docs (#2094)
Browse files Browse the repository at this point in the history 
Co-authored-by: ptristan3 <[email protected]>
  • Loading branch information
@kt474 @ptristan3
kt474 and ptristan3 authored Jan 10, 2025
1 parent 4c3684a commit e3e066b
Showing 1 changed file with 55 additions and 56 deletions.
111 changes: 55 additions & 56 deletions qiskit_ibm_runtime/options/zne_options.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://www.nature.com/articles/s41586-023-06096-3>`_) 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*,
Expand All @@ -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 <https://www.nature.com/articles/s41586-023-06096-3>`_) 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)
Expand Down

0 comments on commit e3e066b

Please sign in to comment.