Introduction to options

You can use options to customize Qiskit Runtime primitives to meet your needs.

Structure

When calling the primitives, you can pass in options by using an options class or a dictionary. Commonly-used options, such as resilience_level, are at the first level. Other options are grouped into categories, such as execution. Specify the options in this format: options.option.sub-option.sub-sub-option = choice. For example: options.dynamical_decoupling.enable = True.

Defaults

If you do not specify a value for an option, it is given a special value of Unset and the server default value is used. Thus, the default value will be the same regardless of your code version.

The tables in the "Options classes summary" section on each primitive's "options" guide lists the default values.

Set options

Options can be defined before a primitive is constructed and passed to the primitive as an instance of the options class or a dictionary. The primitive makes a copy of them, which means that changing the original dictionary or options instance doesn't affect the options that the primitive owns.

Additionally, you can change the options after the primitive is constructed. Use the workflow that works best for your application.

options class

When creating an instance of the primitive class, you can pass in an instance of the options class. Those options are then applied when you use run() to perform the calculation. Specify the options in this format: options.option.sub-option.sub-sub-option = choice. For example: options.dynamical_decoupling.enable = True.

See SamplerOptions or EstimatorOptions for full details about the class.

The following example uses the Estimator primitive, but the syntax for other primitives is similar.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator
from qiskit_ibm_runtime.options import EstimatorOptions

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

options = EstimatorOptions(
    resilience_level=2,
    resilience={"zne_mitigation": True, "zne": {"noise_factors": [1, 3, 5]}},
)

# or...
options = EstimatorOptions()
options.resilience_level = 2
options.resilience.zne_mitigation = True
options.resilience.zne.noise_factors = [1, 3, 5]

estimator = Estimator(mode=backend, options=options)

Dictionary

You can specify options as a dictionary when initializing a primitive.

The following example uses the Estimator primitive, but the syntax for other primitives is similar.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

# Setting options during initialization
estimator = Estimator(
    backend,
    options={
        "resilience_level": 2,
        "resilience": {
            "zne_mitigation": True,
            "zne": {"noise_factors": [1, 3, 5]},
        },
    },
)

Update options after initialization

You can specify the options in this format: _primitive_.options.option.sub-option.sub-sub-option = choice to take advantage of auto-complete, or use the update() method to make bulk updates.

The primitive's options class (EstimatorOptions or SamplerOptions) does not need to be instantiated if you are setting options after initializing the primitive.

The following example uses the Estimator primitive, but the syntax for other primitives is similar.

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import EstimatorV2 as Estimator

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

estimator = Estimator(mode=backend)

# Setting options after initialization
# This uses auto-complete.
estimator.options.default_precision = 0.01
# This does bulk update.
estimator.options.update(
    default_precision=0.02, resilience={"zne_mitigation": True}
)

Next steps