Merge a7b5c04 into 4381020

docs/run/advanced-runtime-options.mdx

@@ -137,6 +137,8 @@ estimator = Estimator(session=backend, options=options)
 For more information and a complete list of advanced transpilation options, see the Advanced transpilation options table in the
 [Runtime compilation topic](configure-runtime-compilation#transpilation-table).
 
+<admonition type="note">V2 primitives do not support any advanced transpilation options except `skip_transpilation`.</admonition>
+
 
 ### Error mitigation
 

docs/run/configure-error-mitigation.mdx

@@ -15,6 +15,8 @@ The error mitigation techniques built in to primitives are advanced
 resilience options. To specify these options, use the `resilience_level`
 option when submitting your job.
 
+<admonition type="note">Sampler V2 does not support specifying resilience levels.</admonition>
+
 The resilience level specifies how much resilience to build against
 errors. Higher levels generate more accurate results, at the expense of
 longer processing times. Resilience levels can be used to configure the
@@ -38,13 +40,24 @@ apply vary based whether you are sampling a distribution or generating
 expectation values.
 </Admonition>
 
+<span id="resilience-table"></span>
+Resilience levels in Estimator V2: 
+
+| Resilience Level | Definition                                                                                            | Technique                                                                 |
+|------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| 0                | No mitigation                                                                                         | None                                                                      |
+| 1 [Default]      | Minimal mitigation costs: Mitigate error associated with readout errors                               | Twirled Readout Error eXtinction  (TREX) measurement twirling             |
+| 2                | Medium mitigation costs. Typically reduces bias in estimators, but is not guaranteed to be zero-bias. | Level 1 + Zero Noise Extrapolation (ZNE) and TREX gate twirling           |
+
+
+Resilience levels in V1 primitives: 
 
 | Resilience Level | Definition                                                                                            | Estimator                                                                 | Sampler                                |
 |------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|----------------------------------------|
 | 0                | No mitigation                                                                                         | None                                                                      | None                                   |
 | 1 [Default]      | Minimal mitigation costs: Mitigate error associated with readout errors                               | Twirled Readout Error eXtinction  (TREX)                                  | Matrix-free Measurement Mitigation (M3)|
 | 2                | Medium mitigation costs. Typically reduces bias in estimators, but is not guaranteed to be zero-bias. | Zero Noise Extrapolation (ZNE)                                            | -                                      |
-| 3                | Heavy mitigation with layer sampling. Theoretically expected to deliver zero-bias estimators.         | Probabilistic Error Cancellation (PEC)                                     | -                                      |
+| 3                | Heavy mitigation with layer sampling. Theoretically expected to deliver zero-bias estimators.         | Probabilistic Error Cancellation (PEC)                                    | -                                      |
 
 
 <Admonition type="info" title="Attention">
@@ -65,7 +78,95 @@ applied at each resilience level.
   runtime warning. For more information visit the [Q-CTRL documentation](https://docs.q-ctrl.com/q-ctrl-embedded).
 </Admonition>
 
-## Configure the Estimator with resilience levels
+## Configure Estimator V2 with resilience levels
+
+You can use resiliance levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings with Estimator V2.](advanced-error) 
+
+<details>
+<summary>Resilience Level 0</summary>
+
+No error mitigation is applied to the user program.
+
+
+</details>
+
+
+<details>
+<summary>Resilience Level 1</summary>
+
+Level 1 applies **readout error mitigation** and **measurement twirling** by applying a model-free technique known
+as Twirled Readout Error eXtinction (TREX). It reduces measurement error
+by diagonalizing the noise channel associated with measurement by
+randomly flipping qubits through X gates immediately before measurement. A
+rescaling term from the diagonal noise channel is learned by
+benchmarking random circuits initialized in the zero state. This allows
+the service to remove bias from expectation values that result from
+readout noise. This approach is described further in [Model-free
+readout-error mitigation for quantum expectation
+values](https://arxiv.org/abs/2012.09738).
+
+</details>
+
+
+<details>
+<summary>Resilience Level 2</summary>
+
+Level 2 applies the **error mitigation techniques included in level 1** and also applies **gate twirling** and uses the **Zero Noise Extrapolation method (ZNE)**.  Zne computes an
+expectation value of the observable for different noise factors
+(amplification stage) and then uses the measured expectation values to
+infer the ideal expectation value at the zero-noise limit (extrapolation
+stage). This approach tends to reduce errors in expectation values, but
+is not guaranteed to produce an unbiased result.
+
+
+![This image shows a graph.  The x-axis is labeled Noise amplification factor.  The y-axis is labeled Expectation value.  An upward sloping line is labeled Mitigated value.  Points near the line are noise-amplified values.  There is a horizontal line just above the X-axis labeled Exact value. ](/images/optimize/resiliance-2.png "Illustration of the ZNE method")
+
+The overhead of this method scales with the number of noise factors. The
+default settings sample the expectation value at three noise factors,
+leading to a roughly 3x overhead when employing this resilience level.
+
+In Level 2, the TREX method randomly flips qubits through X gates immediately before measurement,
+and flips the corresponding measured bit if an X gate was applied. This approach is described further in [Model-free
+readout-error mitigation for quantum expectation
+values](https://arxiv.org/abs/2012.09738).
+
+
+</details>
+
+
+### Example
+
+The `EstimatorV2` interface lets users seamlessly work with the variety of
+error mitigation methods to reduce error in expectation values of
+observables. The following code uses Zero Noise Extrapolation by simply
+setting `resilience_level 2`.
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService, Estimator, Options
+
+service = QiskitRuntimeService()
+options = Options()
+options.resilience_level = 2
+options.optimization_level = 3
+backend = service.backend("ibmq_qasm_simulator")
+
+estimator = Estimator(options=options, backend=backend)
+job = estimator.run(circuits=[psi1], observables=[H1], parameter_values=[theta1])
+psi1_H1 = job.result()
+```
+
+<Admonition type="info" title="Note">
+
+As you increase the resilience level, you will be able to use additional methods to improve the accuracy of your result. However, because the methods become more advanced with each level, they require additional sampling overhead (time) to generate more accurate expectation values. Note that higher resilience levels do not guarantee better quality. Higher levels only mean greater overhead. Each method has its strengths and weaknesses. For example, TREX (Twirled Readout Error eXtinction) is good for shallow circuits because of its readout error mitigation, whereas ZNE (Zero Noise Extrapolation) is good for deeper circuits. PEC can mitigate arbitrary errors but may not work in practice because of its large overhead.
+</Admonition>
+
+<span id="advanced-error"></span>
+## Custom error settings with Estimator V2 
+
+With Estimator V2, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, and ZNE.
+
+
+## Configure Estimator (V1) with resilience levels
 
 
 <details>
@@ -208,7 +309,7 @@ problems.
 
 </details>
 
-## Example
+### Example
 
 The Estimator interface lets users seamlessly work with the variety of
 error mitigation methods to reduce error in expectation values of
@@ -234,7 +335,9 @@ psi1_H1 = job.result()
 As you increase the resilience level, you will be able to use additional methods to improve the accuracy of your result. However, because the methods become more advanced with each level, they require additional sampling overhead (time) to generate more accurate expectation values. Note that higher resilience levels do not guarantee better quality. Higher levels only mean greater overhead. Each method has its strengths and weaknesses. For example, TREX (Twirled Readout Error eXtinction) is good for shallow circuits because of its readout error mitigation, whereas ZNE (Zero Noise Extrapolation) is good for deeper circuits. PEC can mitigate arbitrary errors but may not work in practice because of its large overhead.
 </Admonition>
 
-## Configure Sampler with resilience levels
+## Configure Sampler (V1) with resilience levels
+
+<admonition type="note">Sampler V2 does not support specifying resilience levels.</admonition>
 
 The Sampler default resilience setting (level 1) enables readout error
 mitigation to allow users to generate mitigated quasi-probability

docs/run/configure-runtime-compilation.mdx

@@ -111,6 +111,9 @@ sampler = Sampler(options=options, backend=backend)
 
 You also have the ability to tune a variety of advanced options to configure your runtime compilation strategy further. These methods can be used alongside optimization levels. They allow you to change the options of interest and let your optimization level manage the rest.
 
+<admonition type="note">V2 primitives do not support any advanced transpilation options except `skip_transpilation`.</admonition>
+
+
 | Options                                                         | Description                                                                                                                                                                  |
 | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | options.transpilation.skip\_transpilation (bool)                | Directs the service to execute the primitive query with the bare minimum about of runtime compilation necessary                                                              |