Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add runtime options table #1188

Merged
merged 6 commits into from
Apr 29, 2024
Merged

Add runtime options table #1188

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d67b0ff
Add options table
beckykd Apr 16, 2024
c1277d1
add ticks around code examples
beckykd Apr 16, 2024
b38e523
review comments
beckykd Apr 16, 2024
012f266
Merge branch 'main' of https://github.com/Qiskit/documentation into o…
beckykd Apr 29, 2024
8561631
link to table
beckykd Apr 29, 2024
369f9a9
Merge branch 'main' of https://github.com/Qiskit/documentation into o…
beckykd Apr 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 32 additions & 22 deletions docs/run/advanced-runtime-options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: Advanced runtime options
beckykd marked this conversation as resolved.
Show resolved Hide resolved
description: Specify options when building with Qiskit runtime primitives
description: Specify options when building with Qiskit runtime primitives
beckykd marked this conversation as resolved.
Show resolved Hide resolved

---

# Advanced Qiskit Runtime options

When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See all the available options in the [API reference](../api/qiskit-ibm-runtime/options).
When calling the primitives, you can pass in options by using an options class or a dictionary. In the options classes, commonly used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [options classes section](#options-classes) for details.

<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 system (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 primitives except Sampler V2 still optimize the input circuits. To bypass all optimization, set `optimization_level=0`.
Expand All @@ -26,10 +26,10 @@ service = QiskitRuntimeService(channel="ibm_cloud", channel_strategy="q-ctrl")
## V2 changes
Options are specified differently in the V2 primitives in these ways:

- `SamplerV2` and `EstimatorV2` now have separate options classes. You can see the available options and update option values during or after primitive initialization.
- Instead of the `set_options()` method, V2 primitive options have the `update()` method that applies changes to the `options` attribute.
- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used.
- For V2 primitives, the `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary.
- `SamplerV2` and `EstimatorV2` now have separate options classes. You can see the available options and update option values during or after primitive initialization.
- Instead of the `set_options()` method, V2 primitive options have the `update()` method that applies changes to the `options` attribute.
- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used.
- For V2 primitives, the `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary.

## Instantiate the Options class (V1)

Expand All @@ -41,7 +41,7 @@ from qiskit_ibm_runtime import Options
options = Options(optimization_level=1, environment={"log_level": "INFO"})
```

The `Options` class supports auto-complete. Once you create an instance of the `Options` class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category.
The `Options` class supports auto-complete. Once you create an instance of the `Options` class, you can use auto-complete to see what options are available. If you choose one of the categories, you can use auto-complete again to see what options are available under that category.

```python
from qiskit_ibm_runtime import Options
Expand All @@ -52,13 +52,13 @@ options.execution.shots = 2048
```
## Pass options to a primitive

### Options class
### Options class

When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example:
When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example:

<Tabs>
<TabItem value="PrimV2" label="V2 primitives">
`SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use `run()` to perform the calculation. Example:
`SamplerV2` and `EstimatorV2` have separate options classes that do not need to be instantiated. You can see the available options and update option values during or after primitive initialization. Those options will then be applied when you use `run()` to perform the calculation. Example:
beckykd marked this conversation as resolved.
Show resolved Hide resolved

```python
estimator = Estimator(backend=backend)
Expand All @@ -71,7 +71,7 @@ estimator.options.default_shots = 4000
</TabItem>

<TabItem value="PrimV1" label="V1 primitives">
When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example:
When creating an instance of the `Estimator` or `Sampler` class, you can pass in the `options` you created in the options class. Those options will then be applied when you use `run()` to perform the calculation. Example:

```python
estimator = Estimator(session=backend, options=options)
Expand All @@ -81,14 +81,14 @@ print(f">>> Metadata: {result.metadata[0]}")
</TabItem>
</Tabs>

### Primitive initialization
### Primitive initialization

You can specify options when initializing the primitive.
You can specify options when initializing the primitive.


<Tabs>
<TabItem value="PrimV2" label="V2 primitives">
```python
```python
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator

Expand All @@ -101,7 +101,7 @@ estimator = Estimator(backend, options={"resilience_level": 2})
</TabItem>

<TabItem value="PrimV1" label="V1 primitives">
```python
```python
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import Estimator

Expand All @@ -116,7 +116,7 @@ estimator = Estimator(backend, options={"resilience_level": 2})

### Run() method

You can pass in options by using the `run()` method. This overwrites the options you specified when creating the `Estimator` or `Sampler` instance for that particular execution.
You can pass in options by using the `run()` method. This overwrites the options you specified when creating the `Estimator` or `Sampler` instance for that particular execution.

<Tabs>
<TabItem value="PrimV2" label="V2 primitives">
Expand All @@ -129,7 +129,7 @@ sampler.run([circuit1, circuit2], shots=128)
</TabItem>

<TabItem value="PrimV1" label="V1 primitives">
You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the category the options are in. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid).
You can pass any options to `run()`. Because most users will only overwrite a few options at the job level, it is not necessary to specify the category the options are in. The code below, for example, specifies `shots=1024` instead of `execution={"shots": 1024}` (which is also valid).
beckykd marked this conversation as resolved.
Show resolved Hide resolved
```python
estimator = Estimator(session=backend, options=options)
result = estimator.run(circuit, observable, shots=1024).result()
Expand All @@ -148,7 +148,7 @@ For some algorithms, setting a specific number of shots is a core part of their

<Tabs>
<TabItem value="primitivesV2" label="V2 Primitives">
```python
```python
from qiskit_ibm_runtime import SamplerV2 as Sampler

# Setting shots during primitive initialization
Expand Down Expand Up @@ -224,7 +224,7 @@ estimator = Estimator(session=backend, options={"optimization_level": 1})
estimator.options.optimization_level = 1
```

To turn off all optional runtime compilation steps, you must set `optimization_level=0`. V2 primitives do not support any advanced transpilation options.
To turn off all optional runtime compilation steps, you must set `optimization_level=0`. V2 primitives do not support any advanced transpilation options.
</TabItem>

<TabItem value="PrimV1" label="V1 primitives">
Expand Down Expand Up @@ -271,7 +271,7 @@ algorithm. These methods can be set through the `resilience_level` option. For

<Tabs>
<TabItem value="PrimV2" label="Estimator V2">
With Estimator V2, you can set resilience levels 0-2 and you can also turn on and off various error mitigation settings for fine tuning.
With Estimator V2, you can set resilience levels 0-2 and you can also turn on and off various error mitigation settings for fine tuning.
beckykd marked this conversation as resolved.
Show resolved Hide resolved

```python
estimator = Estimator(backend=backend)
Expand All @@ -284,7 +284,7 @@ estimator.options.resilience.zne.noise_factors = [1, 3, 5]

<TabItem value="PrimV1" label="V1 primitives">
The method selected for each level is
different for `Sampler` and `Estimator`.
different for `Sampler` and `Estimator`.

The configuration is similar to the other options:

Expand All @@ -303,7 +303,17 @@ estimator = Estimator(session=backend, options=options)
</TabItem>
</Tabs>


<span id="options-classes"></span>
## Options classes

| Category | Description | Example |
|:-------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------:|:------------------------------------------------------|
| [Resilience](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ResilienceOptionsV2) | Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. Estimator only. | `estimator.options.resilience.measure_mitigation = True` |
| [Dynamical decoupling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.DynamicalDecouplingOptions) | Options for dynamical decoupling. | `estimator.options.dynamical_decoupling.enable = True` |
| [Execution](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) | Primitive execution options, including whether to initialize qubits and the repetition delay. | `estimator.options.execution.init_qubits = False` |
| [Twirling](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) | Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. | `estimator.options.twirling.enable_gates = True` |
| [Environment](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) | Execution environment options such as the logging level to set and job tags to add. | `estimator.options.environment.log_level = 'ERROR'` |
| [Simulator](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SimulatorOptions) | Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to local testing mode only. | `estimator.options.simulator.seed_simulator = 42` |

## Next steps

Expand Down
Loading