Restore Options changes (revert #1722)

docs/guides/_toc.json

@@ -306,20 +306,23 @@
               "title": "Configure runtime options",
               "children": [
                 {
-                  "title": "Configure runtime compilation",
-                  "url": "/guides/configure-error-suppression"
+                  "title": "Introduction to options",
+                  "url": "/guides/runtime-options-overview"
                 },
                 {
-                  "title": "Configure runtime error mitigation",
-                  "url": "/guides/configure-error-mitigation"
+                  "title": "Specify options",
+                  "url": "/guides/specify-runtime-options"
+                },{
+                  "title": "Error mitigation and suppression techniques",
+                  "url": "/guides/error-mitigation-and-suppression-techniques"
                 },
                 {
-                  "title": "Advanced runtime options",
-                  "url": "/guides/runtime-options-overview"
+                  "title": "Configure error mitigation",
+                  "url": "/guides/configure-error-mitigation"
                 },
                 {
-                  "title": "Error mitigation and suppression techniques",
-                  "url": "/guides/error-mitigation-and-suppression-techniques"
+                  "title": "Configure error suppression",
+                  "url": "/guides/configure-error-suppression"
                 }
               ]
             }

docs/guides/configure-error-mitigation.mdx

@@ -3,21 +3,17 @@ title: Configure error mitigation
 description: How to configure error mitigation with Qiskit Runtime.
 ---
 
-# Configure error mitigation for Qiskit Runtime
+# Configure error mitigation
 
 Error mitigation techniques allow users to mitigate circuit errors by
 modeling the device noise at the time of execution. This typically
 results in quantum pre-processing overhead related to model training and
 classical post-processing overhead to mitigate errors in the raw results
 by using the generated model.
 
-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.
+Primitives support several error mitigation techniques, including [TREX](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#measure_mitigation), [ZNE](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#zne), and [PEC](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2#pec). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details.
 
-<admonition type="note">Sampler V2 does not support specifying resilience levels. However, you can turn on or off individual error mitigation / suppression methods. See the [Custom error settings](#advanced-error) section for details.</admonition>
-
-The resilience level specifies how much resilience to build against
+Estimator V2 also supports `resilience_level`. 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
 cost/accuracy trade-off when applying error mitigation to your primitive
@@ -35,22 +31,11 @@ which levels and corresponding methods are available for each of the
 primitives.
 
 <Admonition type="info" title="Attention">
-Error mitigation is task specific so the techniques you are able to
+Error mitigation is task-specific, so the techniques you can
 apply vary based whether you are sampling a distribution or generating
 expectation values.
 </Admonition>
 
-<Admonition type="caution" title="Important">
-To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives.  See the [transpilation documentation](./transpile) for instructions to transform circuits.  Due to this change, the primitives will no longer perform layout or routing operations.  Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`.
-
-*Exception*: When you initialize the Qiskit Runtime Service with the Q-CTRL channel strategy (example below), abstract circuits are still supported.
-
-``` python
-service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl")
-```
-
-</Admonition>
-
 <span id="resilience-table"></span>
 
 <Tabs>
@@ -100,7 +85,7 @@ applied at each resilience level.
 
 ## Configure Estimator V2 with resilience levels
 
-You can use resilience levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings with Estimator V2.](#advanced-error) You cannot specify resilience levels in Sampler V2. However, you can set custom techniques individually.
+You can use resilience levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings (V2 primitives).](#advanced-error) You cannot specify resilience levels in Sampler V2. However, you can set custom techniques individually.
 
 <details>
 <summary>Resilience Level 0</summary>
@@ -139,7 +124,7 @@ 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/resilience-2.png "Illustration of the ZNE method")
+![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/resilience-2.svg "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,
@@ -156,7 +141,7 @@ values](https://arxiv.org/abs/2012.09738).
 
 The `Estimator` 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
+observables. The following code uses Zero Noise Extrapolation and readout error mitigation by simply
 setting `resilience_level 2`.
 
 ```python
@@ -170,11 +155,6 @@ backend = service.least_busy(operational=True, simulator=False)
 estimator = Estimator(backend, options={"resilience_level": 2})
 ```
 
-<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>
-
 ## Configure Estimator (V1) with resilience levels
 
 
@@ -217,7 +197,7 @@ 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/resilience-2.png "Illustration of the ZNE method")
+![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/resilience-2.svg "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,
@@ -320,7 +300,7 @@ problems.
 
 ### Example
 
-The Estimator interface lets users seamlessly work with the variety of
+The Estimator interface lets you 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`.
@@ -380,11 +360,11 @@ sampler = Sampler(backend, options=options)
 <span id="advanced-error"></span>
 ## Custom error settings (V2 primitives)
 
-With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, and ZNE.
+With the V2 primitives, you can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, PEC, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each.
 
 <Admonition type = "note" title = "Notes">
-- Not all options are available for both primitives.   See the [API reference](/api/qiskit-ibm-runtime/options) for the list of available options.
-- Dynamical decoupling is not supported when the input circuits are dynamic.
+- Not all options are available for both primitives.   See the [available options table](runtime-options-overview#options-table) for the list of available options.
+- Not all methods work together on all types of circuits.  See the [options compatibility table](runtime-options-overview#options-compatibility-table) for details.
 </Admonition>
 
 <Tabs>
@@ -471,38 +451,17 @@ job = estimator.run(circuits=[psi1], observables=[H1], parameter_values=[theta1]
 psi1_H1 = job.result()
 ```
 
-<span id="no-error-mitigation"></span>
-## Turn off all error mitigation and error suppression
-
-You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default.
+## Turn off all error mitigation
 
-Example:
-
-Turn off all error mitigation and suppression in EstimatorV2.
-
-```python
-from qiskit_ibm_runtime import EstimatorV2 as Estimator, Options, QiskitRuntimeService
-
-# Define the service.  This allows you to access IBM QPUs.
-service = QiskitRuntimeService()
-
-# Get a backend
-backend = service.least_busy(operational=True, simulator=False)
-
-# Define Estimator
-estimator = Estimator(backend)
-
-options = estimator.options
-
-# Turn off all error mitigation and suppression
-options.resilience_level = 0
-```
+For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section.
 
 ## Next steps
 
 <Admonition type="tip" title="Recommendations">
   - Walk through an example that uses error mitigation in the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum Learning.
   - Learn more about [Q-CTRL](https://docs.q-ctrl.com/q-ctrl-embedded).
-  - Learn how to transpile locally in the [Transpile](./transpile/) section.
-  - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial.
+  - Learn more about [error mitigation and error suppression techniques.](error-mitigation-and-suppression-techniques)
+  - [Configure error suppression.](configure-error-suppression)
+  - Explore other [options.](runtime-options-overview)
+  - Decide what [execution mode](execution-modes) to run your job in.
 </Admonition>

docs/guides/configure-error-suppression.mdx

@@ -1,12 +1,16 @@
 ---
-title: Configure runtime compilation
-description: How to configure runtime compilation in Qiskit Runtime.
+title: Configure error suppression
+description: How to configure error suppression in Qiskit Runtime. (Former title: Runtime compilation)
 
 ---
 
-# Configure runtime compilation for Qiskit Runtime
+# Configure error suppression
 
-Runtime compilation techniques transform your circuit to minimize errors. Runtime compilation adds some classical pre-processing overhead to your overall runtime. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.
+Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results.  This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.
+
+V2 primitives support a number of error suppression techniques, including [dynamical decoupling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions#dynamicaldecouplingoptions) and Pauli [twirling](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. In V2 primitives, you can turn on or off individual method. See the [Advanced error suppression options](#transpilation-table) section for details.
+
+Estimator V2 employs error suppression and mitigation by default. If you don't want any processing done to your input circuits follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section.
 
 <Admonition type="caution" title="Important">
 To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits and observables) before being submitted to the Qiskit Runtime primitives.  See the [transpilation documentation](./transpile) for instructions to transform circuits.  Due to this change, the primitives will no longer perform layout or routing operations.  Consequently, transpilation options referring to those tasks will no longer have any effect. By default, all V1 primitives optimize the input circuits. To bypass all optimization when using a V1 primitive, set `optimization_level=0`.
@@ -126,15 +130,16 @@ psi1_H1 = job.result()
 
 
 <span id="transpilation-table"></span>
-## Advanced runtime compilation options
+## Advanced error suppression options
 
 <Tabs>
   <TabItem value="PrimV2" label="V2 primitives">
-    In the V2 primitives, you can explicitly enable and disable individual error mitigation/suppression methods, such as dynamical decoupling.
+    In the V2 primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling.
 
-    <Admonition type = "note">
-    Dynamical decoupling is not supported when the input circuits are dynamic.
-    </Admonition>
+<Admonition type = "note" title = "Notes">
+- Not all options are available for both primitives.   See the [available options](runtime-options-overview#options-table) table for the list of available options.
+- Not all methods work together on all types of circuits.  See the [options compatibility](runtime-options-overview#options-compatibility-table) table for details.
+</Admonition>
 ```python
 
 from qiskit_ibm_runtime import QiskitRuntimeService
@@ -154,15 +159,19 @@ print(f">>> dynamical decoupling sequence to use: {sampler.options.dynamical_dec
   </TabItem>
 
   <TabItem value="PrimV1" label="V1 primitives">
-    Because all input must be ISA, options.transpilation.xxx will be ignored.
+    Because all input must be ISA, `options.transpilation.xxx` is ignored. See [Advanced runtime options](runtime-options-overview) for information.
   </TabItem>
 </Tabs>
 
+## Turn off all error suppression
+
+For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section.
 
 ## Next steps
 
 <Admonition type="tip" title="Recommendations">
-    - Try a tutorial that uses optimization levels, such as the [Variational quantum eigensolver](https://learning.quantum.ibm.com/tutorial/variational-quantum-eigensolver) tutorial.
-    - Learn how to transpile locally in the [Transpile](./transpile) section.
-    - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial.
+    - Learn more about [error mitigation and error suppression techniques.](error-mitigation-and-suppression-techniques)
+    - [Configure error mitigation.](configure-error-mitigation)
+    - Explore other [options.](runtime-options-overview)
+    - Decide what [execution mode](execution-modes) to run your job in.
 </Admonition>

docs/guides/error-mitigation-and-suppression-techniques.ipynb

@@ -256,7 +256,10 @@
     "## Next steps\n",
     "\n",
     "- Check out the [tutorial](https://learning.quantum.ibm.com/tutorial/combine-error-mitigation-options-with-the-estimator-primitive) on combining error mitigation options with the Estimator primitive.\n",
-    "- Visit the [API reference](/api/qiskit-ibm-runtime/options) to see all the options for the Qiskit Runtime primitives."
+    "- [Configure error mitigation.](configure-error-mitigation)\n",
+    "- [Configure error suppression.](configure-error-suppression)\n",
+    "- Explore other [options](runtime-options-overview) for the Qiskit Runtime primitives.\n",
+    "- Decide what [execution mode](execution-modes) to run your job in."
    ]
   }
  ],

docs/guides/execute-on-hardware.mdx

@@ -33,9 +33,10 @@ expectation values of observables corresponding to physical quantities or cost f
 * [Primitives with REST API](./primitives-rest-api)
 
 ### Configure runtime options
-* [Configure runtime compilation](./configure-error-suppression)
-* [Configure runtime error mitigation](./configure-error-mitigation)
-* [Advanced runtime options](./runtime-options-overview)
+* [Overview](./runtime-options-overview)
+* [Specify options](./specify-runtime-options)
+* [Configure error suppression](./configure-error-suppression)
+* [Configure error mitigation](./configure-error-mitigation)
 * [Error mitigation and suppression techniques](./error-mitigation-and-suppression-techniques)
 
 ### Execution modes