Revamp options page

docs/api/migration-guides/qiskit-quantum-instance.mdx

@@ -81,7 +81,7 @@ yourself two questions:
    This question is not new. In the legacy algorithm workflow, you would set up a
    [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance) with either a real system from a provider, or a simulator.
    For this migration, this "system selection" process is translated to **where** do you import your primitives from:
-   
+
    * Using **local** statevector simulators for quick prototyping: **Reference primitives**
    * Using **local** noisy simulations for finer algorithm tuning: **Aer primitives**
    * Accessing **runtime-enabled systems** (or cloud simulators): **Qiskit Runtime primitives**
@@ -90,7 +90,7 @@ yourself two questions:
 Arguably, the `Sampler` is the closest primitive to [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance), as they
 both execute circuits and provide a result. However, with the [`qiskit.utils.QuantumInstance`](../qiskit/0.46/qiskit.utils.QuantumInstance),
 the result data was system-dependent (it could be a counts `dict`, a `numpy.array` for
-statevector simulations, and so on), while `Sampler` normalizes its `SamplerResult` to 
+statevector simulations, and so on), while `Sampler` normalizes its `SamplerResult` to
 return a [`qiskit.result.QuasiDistribution`](../qiskit/qiskit.result.QuasiDistribution) object with the resulting quasi-probability distribution.
 
 The `Estimator` provides a specific abstraction for the expectation value calculation that can replace
@@ -122,8 +122,8 @@ primitives expose a similar setting through their interface:
 | Measurement error mitigation: `measurement_error_mitigation_cls`, `cals_matrix_refresh_period`, | No | No | Sampler default > M3 (*) | No |
 | Job management: `job_callback`, `max_job_retries`, `timeout`, `wait` | Does not apply | Does not apply | Sessions, callback (**) | No |
 
-(\*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, see
-[Advanced Runtime Options](../../run/advanced-runtime-options).
+(\*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, see the Qiskit Runtime options
+[overview](../../run/runtime-options-overview).
 
 (\*\*) For more information on Runtime sessions, see [About Sessions](../../run/sessions).
 

docs/api/migration-guides/qiskit-runtime-examples.mdx

@@ -60,7 +60,7 @@ service = QiskitRuntimeService()
 # Get a backend
 backend = service.least_busy(operational=True, simulator=False)
 
-# Define Estimator  
+# Define Estimator
 estimator = Estimator(backend)
 
 # Run an expectation value calculation
@@ -77,10 +77,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2
 # Run the sampler job locally using FakeManilaV2
 fake_manila = FakeManilaV2()
 
-# You can use a fixed seed to get fixed results. 
+# You can use a fixed seed to get fixed results.
 options = {"simulator": {"seed_simulator": 42}}
 
-# Define Estimator  
+# Define Estimator
 estimator = Estimator(backend=fake_manila, options=options)
 
 # Run an expectation value calculation
@@ -225,7 +225,7 @@ Output
   </TabItem>
 
   <TabItem value="legacy" label="backend.run()">
-The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls.  The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance` `run` and `transpile` methods. This degree of nesting is no longer supported, the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm. 
+The legacy workflow required additional elements and steps to compute an expectation value. The `QuantumInstance` class stored a `PassManager` and a `Backend` instance, and wrapped the conversion step to ISA circuits and `backend.run` calls.  The `CircuitSampler` class from `qiskit.opflow` wrapped the `QuantumInstance` `run` and `transpile` methods. This degree of nesting is no longer supported, the new workflow allows to access and directly manipulate all the key components of the computation (backend, pass manager, circuits and observables) at all stages of the algorithm.
 
 ``` python
 from qiskit.opflow import StateFn, PauliExpectation, CircuitSampler
@@ -256,7 +256,7 @@ expectation:  -1.065734058826613
 </Tabs>
 
 <span id="sampler-algorithm"></span>
-## Use Sampler to design an algorithm 
+## Use Sampler to design an algorithm
 
 The Sampler primitive is used to design an algorithm that samples
 circuits and extracts probability distributions.
@@ -286,7 +286,7 @@ difference is the format of the output: `backend.run()` outputs
     # Run
     result = backend.run(isa_circuits)
     ```
-    
+
     </TabItem>
 
 <TabItem value="aer" label="qiskit-aer">
@@ -334,10 +334,10 @@ from qiskit_ibm_runtime.fake_provider import FakeManilaV2
 # Run the sampler job locally using FakeManilaV2
 fake_manila = FakeManilaV2()
 
-# You can use a fixed seed to get fixed results. 
+# You can use a fixed seed to get fixed results.
 options = {"simulator": {"seed_simulator": 42}}
 
-# Define Sampler  
+# Define Sampler
 sampler = Sampler(backend=fake_manila, options=options)
 
 # Run calculation
@@ -366,7 +366,7 @@ When using the `Sampler` primitive, the circuit **must contain measurements**.
   <TabItem value="PrimV2" label="Runtime Sampler">
   ``` python
 from qiskit_ibm_runtime import SamplerV2 as Sampler
- 
+
 # Define a local backend
 from qiskit_ibm_runtime.fake_provider import FakeManilaV2
 backend = FakeManilaV2()
@@ -438,11 +438,11 @@ result = job.result()
 # Get results for the first (and only) PUB
 pub_result = result[0]
 
-# Get counts from the classical register "meas". 
+# Get counts from the classical register "meas".
 print(f" >> Meas output register counts: {pub_result.data.meas.get_counts()}")
 
->> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1} 
-```  
+>> Meas output register counts: {'0001': 210, '0010': 305, '0000': 282, '0011': 201, '0101': 2, '1010': 6, '0110': 5, '0100': 6, '1000': 3, '0111': 1, '1001': 2, '1011': 1}
+```
   </TabItem>
 
   <TabItem value="legacy" label="backend.run()">
@@ -502,7 +502,7 @@ to the following:
 <Admonition type="tip" title="Recommendations">
 - [Common use cases](qiskit-runtime-use-case)
 - [Migrate `backend.run` options to primitive options](qiskit-runtime-options)
-- [Setting execution options](../../run/advanced-runtime-options)
+- [Qiskit Runtime options overview](../../run/runtime-options-overview)
 - [Primitive execution options API reference](../qiskit-ibm-runtime/qiskit_ibm_runtime.options.Options)
 - [How to run a session](../../run/run-jobs-in-session)
 - [Qiskit Runtime local testing mode](../../verify/local-testing-mode)

docs/api/migration-guides/qiskit-runtime-options.mdx

@@ -8,7 +8,7 @@ in_page_toc_max_heading_level: 2
 
 # Migrate options
 
-All `backend.run` options are now available through the Qiskit Runtime primitives, but there are additional options available with the V2 primitives.  See the [API reference](/api/qiskit-ibm-runtime/options) for the full list of available options. See [End-to-end examples](qiskit-runtime-examples) and [Advanced Qiskit Runtime options](../../run/advanced-runtime-options) for more information about specifying V2 primitives options. 
+All `backend.run` options are now available through the Qiskit Runtime primitives, but there are additional options available with the V2 primitives.  See the [API reference](/api/qiskit-ibm-runtime/options) for the full list of available options. See [End-to-end examples](qiskit-runtime-examples) and [Qiskit Runtime options overview](../../run/runtime-options-overview) for more information about specifying V2 primitives options.
 
 | backend.run options | V2 Primitive options                                                                                                  | Notes                                                                                                                                |
 |---------------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
@@ -43,4 +43,4 @@ All `backend.run` options are now available through the Qiskit Runtime primitive
 One of the advantages of the primitives is that they abstract away the
 circuit execution setup so that algorithm developers can focus on the
 pure algorithmic components. However, sometimes, to get the most out of
-an algorithm, you might want to tune certain primitive options. For details, see [Advanced runtime options.](../../run/advanced-runtime-options)
+an algorithm, you might want to tune certain primitive options. For details, see the [Qiskit Runtime options overview.](../../run/runtime-options-overview)

docs/api/migration-guides/qiskit-runtime-use-case.mdx

@@ -7,7 +7,7 @@ description: Common use cases when migrating from backend.run to Qiskit Runtime
 This topic describes how to migrate programs with the most commonly used types of circuits.  For a full example, see [End-to-end examples.](qiskit-runtime-examples)
 
 ## Basic circuits
-The only changes when running basic circuits are how you run the job and retrieve results.  
+The only changes when running basic circuits are how you run the job and retrieve results.
 
 <Tabs>
   <TabItem value="Updated" label="Runtime primitives">
@@ -45,7 +45,7 @@ result = job.result()
 <span id="migrate-options"></span>
 ## Specifying options
 
-All options that were available with `backend.run` are available in the Qiskit Runtime primitives, but they are specified differently.  For more information, see [Migrate options](qiskit-runtime-options) and [Advanced Qiskit Runtime options.](../../run/advanced-runtime-options)
+All options that were available with `backend.run` are available in the Qiskit Runtime primitives, but they are specified differently.  For more information, see [Migrate options](qiskit-runtime-options) and the [Qiskit Runtime options overview.](../../run/runtime-options-overview)
 
 <Tabs>
   <TabItem value="Updated" label="Runtime primitives">
@@ -80,7 +80,7 @@ To migrate programs that run dynamic circuits, change the run call.
 
 <Tabs>
   <TabItem value="primitives" label="Sampler">
-    ```python  
+    ```python
 from qiskit_ibm_runtime import SamplerV2 as Sampler
 
 sampler = Sampler(backend)
@@ -92,7 +92,7 @@ print(f">>> Hardware counts: {pub_result.data.meas.get_counts()}")
   </TabItem>
 
   <TabItem value="backend" label="backend.run">
-    ```python  
+    ```python
 job = backend.run(dynamic_circ, dynamic=True)
 job.job_id()
 
@@ -154,7 +154,7 @@ theta_values = [np.pi/2, np.pi/2, np.pi/2]
 
 <Tabs>
   <TabItem value="updated" label="Runtime primitives">
-Only circuits that adhere to the Instruction Set Architecture (ISA) of a specific backend are accepted, so we must transform the circuits. 
+Only circuits that adhere to the Instruction Set Architecture (ISA) of a specific backend are accepted, so we must transform the circuits.
 
 ```python
 from qiskit_ibm_runtime import QiskitRuntimeService
@@ -185,7 +185,7 @@ job = sampler.run([(isa_circuit, theta_values)])
 result = job.result()
 # Get results for the first (and only) PUB
 pub_result = result[0]
-# Get counts from the classical register "c". 
+# Get counts from the classical register "c".
 print(f" >> Counts for the c output register: {pub_result.data.c.get_counts()}")
 ```
   </TabItem>
@@ -232,7 +232,7 @@ pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
 isa_circuit = pm.run(circuit)
 
 sampler = Sampler(backend)
-# Get the averaged IQ data. 
+# Get the averaged IQ data.
 # This is equivalent to meas_level=1, meas_return="avg" in backend.run
 sampler.options.execution.meas_type = "avg_kerneled"
 job = sampler.run([isa_circuit], shots=10)

docs/run/_toc.json

@@ -27,16 +27,16 @@
       "title": "Configure runtime options",
       "children": [
         {
-          "title": "Configure runtime compilation",
-          "url": "/run/configure-runtime-compilation"
+          "title": "Overview",
+          "url": "/run/runtime-options-overview"
         },
         {
-          "title": "Configure runtime error mitigation",
-          "url": "/run/configure-error-mitigation"
+          "title": "Configure runtime error suppression",
+          "url": "/run/configure-error-suppression"
         },
         {
-          "title": "Advanced runtime options",
-          "url": "/run/advanced-runtime-options"
+          "title": "Configure runtime error mitigation",
+          "url": "/run/configure-error-mitigation"
         },
         {
           "title": "Error mitigation and suppression techniques",

docs/run/advanced-runtime-options.mdx

@@ -325,3 +325,4 @@ estimator = Estimator(mode=backend, options=options)
     - 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.
 </Admonition>
+

docs/run/configure-error-mitigation.mdx

@@ -471,33 +471,9 @@ 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
+## Turn off all error mitigation
 
-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` and `optimization_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default.
-
-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 Quantum systems.
-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
-options.optimization_level = 0
-```
+For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section.
 
 ## Next steps
 

docs/run/configure-runtime-compilation.mdx → docs/run/configure-error-suppression.mdx

@@ -1,14 +1,14 @@
 ---
-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. (Previous topic - runtime compilation)
 
 ---
 
-# Configure runtime compilation for Qiskit Runtime
+# Configure error suppression for Qiskit Runtime
 
 Runtime compilation techniques optimize and 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.
 
-Primitives let you employ runtime compilation by choosing advanced runtime compilation options and, for Estimator V2, by setting the optimization level (`optimization_level`) option. If you don't want any processing done to minimize errors, follow the instructions in the [Turn off all error mitigation and error suppression](configure-error-mitigation#no-error-mitigation) section.
+Primitives let you employ runtime compilation by choosing advanced runtime compilation options and, for Estimator V2, by setting the optimization level (`optimization_level`) option. If you don't want any processing done to minimize errors, follow the instructions in the [Turn off all error mitigation and error suppression](runtime-options-overview#no-error-mitigation) section.
 
 <admonition type="note">Estimator V2 supports optimization levels 0 and 1 only. Sampler V2 does not support setting the optimization level.</admonition>
 
@@ -164,6 +164,9 @@ print(f">>> dynamical decoupling sequence to use: {sampler.options.dynamical_dec
   </TabItem>
 </Tabs>
 
+## Turn off all error suppression
+
+For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](runtime-options-overview#no-error-mitigation) section.
 
 ## Next steps
 

docs/run/minimize-time.mdx

@@ -12,7 +12,7 @@ There are several ways you can limit the amount of quantum time spent processing
 
 - Set limits on execution time:  You can limit how long each job or session runs.  For details, see [Maximum execution time for a Qiskit Runtime job or session](max-execution-time).
 
-- Use only the necessary settings for error suppression, error mitigation, and optimization, because higher values can cause your jobs to run longer. See [Algorithm tuning options](advanced-runtime-options), [Configure runtime compilation](configure-runtime-compilation), and [Configure error mitigation](configure-error-mitigation) for details.
+- Use only the necessary settings for error suppression, error mitigation, and optimization, because higher values can cause your jobs to run longer. See the [Qiskit Runtime options overview](runtime-options-overview), [Configure error suppression](configure-error-suppression), and [Configure error mitigation](configure-error-mitigation) for details.
 
 ## Next steps
 

docs/run/primitives-examples.mdx

@@ -766,7 +766,7 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}")
 
 <Admonition type="tip" title="Recommendations">
     - Read [Migrate to V2 primitives](/api/migration-guides/v2-primitives).
-    - [Specify advanced runtime options.](advanced-runtime-options)
+    - [Specify advanced runtime options.](runtime-options-overview)
     - Practice with primitives by working through the [Cost function lesson](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions#primitives) in IBM Quantum Learning.
     - 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.