89 lines
7.5 KiB
Plaintext
89 lines
7.5 KiB
Plaintext
---
|
||
title: ZneOptions (latest version)
|
||
description: API reference for qiskit_ibm_runtime.options.ZneOptions in the latest version of qiskit-ibm-runtime
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit_ibm_runtime.options.ZneOptions
|
||
---
|
||
|
||
# ZneOptions
|
||
|
||
<Class id="qiskit_ibm_runtime.options.ZneOptions" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.33/qiskit_ibm_runtime/options/zne_options.py#L36-L188" signature="ZneOptions(*args, **kwargs)" modifiers="class">
|
||
Zero noise extrapolation mitigation options. This is only used by the V2 Estimator.
|
||
|
||
<Admonition title="Note" type="note">
|
||
Any V2 estimator is guaranteed to return data fields called `evs` and `stds` that report the desired expectation value estimates and errors, respectively. When ZNE options are enabled in the runtime estimator, additional data is returned.
|
||
|
||
In particular, suppose an input pub has observable array shape `obs_shape` and parameter values shape `par_shape`, with corresponding pub shape `shape=np.broadcast_shapes(obs_shape, par_shape)`. Then the corresponding pub result will additionally contain:
|
||
|
||
1. **pub\_result.data.evs\_extrapolated and pub\_result.data.stds\_extrapolated,**
|
||
|
||
both with shape `(*shape, num_extrapolators, num_evaluation_points)`, where `num_extrapolators` is the length of the list of `options.resilience.zne.extrapolators`, and `num_evaluation_points` is the length of the list `options.resilience.extrapolated_noise_factors`. These values provide evaluations of every extrapolator at every specified noise extrapolation value.
|
||
|
||
2. `pub_result.data.evs_noise_factors`, `pub_result.data.stds_noise_factors`, and `ensemble_stds_noise_factors` all have shape `(*shape, num_noise_factors)` where `num_noise_factors` is the length of `options.resilience.zne.noise_factors`. These values provide evaluations of the best-fit model at each of the noise amplifications. In the case of no twirling, both `*stds*` arrays will be equal, otherwise, `stds_noise_factors` is derived from the spread over twirling samples, whereas `ensemble_stds_noise_factors` assumes only shot noise and no drift.
|
||
|
||
Technical note: for single observables with multiple basis terms it might turn out that multiple extrapolation methods are used in *the same* expectation value, for example, `XX` gets linearly extrapolated but `XY` gets exponentially extrapolated in the observable `{"XX": 0.5, "XY": 0.5}`. Let’s call this a *heterogeneous fit*. The data from (2) is evaluated from heterogeneous fits by selecting the best fit for every individual distinct term, whereas data from (1) is evaluated from forced homogenous fits, one for each provided 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.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **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 [`LayerNoiseLearningOptions`](qiskit_ibm_runtime.options.LayerNoiseLearningOptions "qiskit_ibm_runtime.options.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 $f(x; A, au) = A e^{-x/ au}$, where $A = f(0; A, au)$ is the value at zero noise ($x=0$) and :math:\` au>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 $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*, [npj Quantum Inf 7, 80 (2021)](https://www.nature.com/articles/s41534-021-00404-3)
|
||
|
||
## Attributes
|
||
|
||
### amplifier
|
||
|
||
<Attribute id="qiskit_ibm_runtime.options.ZneOptions.amplifier" attributeTypeHint="UnsetType | Literal['gate_folding', 'gate_folding_front', 'gate_folding_back', 'pea']" attributeValue="Unset" />
|
||
|
||
### extrapolated\_noise\_factors
|
||
|
||
<Attribute id="qiskit_ibm_runtime.options.ZneOptions.extrapolated_noise_factors" attributeTypeHint="UnsetType | Sequence[float]" attributeValue="Unset" />
|
||
|
||
### extrapolator
|
||
|
||
<Attribute id="qiskit_ibm_runtime.options.ZneOptions.extrapolator" attributeTypeHint="UnsetType | Literal['linear', 'exponential', 'double_exponential', 'polynomial_degree_1', 'polynomial_degree_2', 'polynomial_degree_3', 'polynomial_degree_4', 'polynomial_degree_5', 'polynomial_degree_6', 'polynomial_degree_7', 'fallback'] | Sequence[Literal['linear', 'exponential', 'double_exponential', 'polynomial_degree_1', 'polynomial_degree_2', 'polynomial_degree_3', 'polynomial_degree_4', 'polynomial_degree_5', 'polynomial_degree_6', 'polynomial_degree_7', 'fallback']]" attributeValue="Unset" />
|
||
|
||
### noise\_factors
|
||
|
||
<Attribute id="qiskit_ibm_runtime.options.ZneOptions.noise_factors" attributeTypeHint="UnsetType | Sequence[float]" attributeValue="Unset" />
|
||
|
||
## Methods
|
||
</Class>
|
||
|