diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 06ef6e03860..34a092feaa3 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -1,942 +1,827 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "c457f721-e66d-403e-84be-10b26863c86d", - "metadata": {}, - "source": [ - "---\n", - "title: Specify Estimator options\n", - "description: Specify options when building with the Estimator primitive.\n", - "---\n", - "\n", - "\n", - "# Specify Estimator options" - ] - }, - { - "cell_type": "markdown", - "id": "1a97b5d6-3fb2-4c33-9b95-807bb6768a84", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "{/*\n", - " DO NOT EDIT THIS CELL!!!\n", - " This cell's content is generated automatically by a script. Anything you add\n", - " here will be removed next time the notebook is run. To add new content, create\n", - " a new cell before or after this one.\n", - "*/}\n", - "\n", - "
\n", - "Package versions\n", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit[all]~=2.3.0\n", - "qiskit-ibm-runtime~=0.43.1\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "3c1e38b5-3f01-4818-943e-f52d877be6ad", - "metadata": {}, - "source": [ - "You can use options to customize the Estimator primitive. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the API references for information about the [`qiskit.primitives.BaseEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BaseEstimatorV2) and [`qiskit_aer.BaseEstimatorV2`](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.primitives.EstimatorV2.html) options.\n", - "\n", - "Notes :\n", - "\n", - "- You can see the available options and update option values during or after Estimator initialization.\n", - "- Use the `update()` method to apply changes to the `options` attribute.\n", - "- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used.\n", - "- The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary.\n", - "\n", - "\n", - "\n", - "## Set Estimator options\n", - "\n", - "You can set options when initializing Estimator, after initializing Estimator, or (for `precision` only), in the `run()` method.\n", - "\n", - "### Primitive initialization\n", - "\n", - "You can pass in an instance of the options class or a dictionary when initializing Estimator, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitive.\n", - "\n", - "#### Options class\n", - "\n", - "When creating an instance of the `EstimatorV2` class, you can pass in an instance of the options class. Those options will then be 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`\n", - "\n", - "Example:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "a20ed38a-31b7-4f0a-aed1-bd11046ab10e", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "from qiskit_ibm_runtime.options import EstimatorOptions\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "options = EstimatorOptions(\n", - " resilience_level=2,\n", - " resilience={\"zne_mitigation\": True, \"zne\": {\"noise_factors\": [1, 3, 5]}},\n", - ")\n", - "\n", - "# or...\n", - "options = EstimatorOptions()\n", - "options.resilience_level = 2\n", - "options.resilience.zne_mitigation = True\n", - "options.resilience.zne.noise_factors = [1, 3, 5]\n", - "\n", - "estimator = Estimator(mode=backend, options=options)" - ] - }, - { - "cell_type": "markdown", - "id": "dc5ba623-45f2-4abf-9478-ff83490b480c", - "metadata": {}, - "source": [ - "#### Dictionary\n", - "\n", - "You can specify options as a dictionary when initializing Estimator." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "869e4bf1-a7f9-4a66-8876-f327dcb87811", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "# Setting options during initialization\n", - "estimator = Estimator(\n", - " backend,\n", - " options={\n", - " \"resilience_level\": 2,\n", - " \"resilience\": {\n", - " \"zne_mitigation\": True,\n", - " \"zne\": {\"noise_factors\": [1, 3, 5]},\n", - " },\n", - " },\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "498899b6-3253-4348-9589-19dbbd6bc22b", - "metadata": {}, - "source": [ - "### Update options after initialization\n", - "\n", - "You can specify the options in this format: `estimator.options.option.sub-option.sub-sub-option = choice` to take advantage of auto-complete, or use the `update()` method to make bulk updates.\n", - "\n", - "The `EstimatorV2` options class ([`EstimatorOptions`](/docs/api/qiskit-ibm-runtime/options-estimator-options)) does not need to be instantiated if you are setting options after initializing the primitive." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "1cd195bb-50a5-4c64-aa0b-effb1ea621ce", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "estimator = Estimator(mode=backend)\n", - "\n", - "# Setting options after initialization\n", - "# This uses auto-complete.\n", - "estimator.options.default_precision = 0.01\n", - "# This does bulk update.\n", - "estimator.options.update(\n", - " default_precision=0.02, resilience={\"zne_mitigation\": True}\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "7cde6f7f-278e-4170-afa3-2c3fb4ec4bfa", - "metadata": {}, - "source": [ - "\n", - "### Run() method\n", - "\n", - "The only values you can pass to `run()` are those defined in the interface. That is, `precision` for Estimator. This overwrites any value set for `default_precision` for the current run." - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "id": "c0606f38-2bed-4b56-8202-708669e5ea66", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "" - ] - }, - "execution_count": 16, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "from qiskit.circuit.library import random_iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "circuit1 = random_iqp(3)\n", - "circuit1.measure_all()\n", - "circuit2 = random_iqp(3)\n", - "circuit2.measure_all()\n", - "\n", - "observable = SparsePauliOp(\"Z\" * 3)\n", - "\n", - "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=3, backend=backend\n", - ")\n", - "\n", - "transpiled1 = pass_manager.run(circuit1)\n", - "transpiled2 = pass_manager.run(circuit2)\n", - "isa_observable1 = observable.apply_layout(transpiled1.layout)\n", - "isa_observable2 = observable.apply_layout(transpiled2.layout)\n", - "\n", - "estimator = Estimator(mode=backend)\n", - "# Default precision to use if not specified in run()\n", - "estimator.options.default_precision = 0.01\n", - "# Run two circuits, requiring a precision of .02 for both.\n", - "estimator.run(\n", - " [(transpiled1, isa_observable1), (transpiled2, isa_observable2)],\n", - " precision=0.02,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "effe450a-255f-4837-a276-c8c3ea6e2db0", - "metadata": {}, - "source": [ - "### Special case: precision\n", - "\n", - "The `EstimatorV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for precision, and a precision keyword argument. These precision values are a part of the Estimator execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Estimator abstraction.\n", - "\n", - "However, if `precision` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the precision value from the options is used, most notably `default_precision`.\n", - "\n", - "Note that Estimator options contain both `default_shots` and `default_precision`. However, because gate-twirling is enabled by default, the product of `num_randomizations` and `shots_per_randomization` takes precedence over those two options.\n", - "\n", - "Specifically, for any Estimator PUB:\n", - "\n", - "1. If the PUB specifies precision, use that value.\n", - "2. If the precision keyword argument is specified in `run`, use that value.\n", - "3. If `twirling` is enabled (True by default), then the product of `num_randomizations` and `shots_per_randomization`, as specified as [`twirling` options](/docs/api/qiskit-ibm-runtime/options-twirling-options), is used.\n", - "4. If `estimator.options.default_shots` is specified, use that value to control the amount of data.\n", - "5. If `estimator.options.default_precision` is specified, use that value.\n", - "\n", - "For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used.\n", - "\n", - "\n", - "Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "bf02c107-226e-443a-ab4c-dfd3246ada2c", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "from qiskit.circuit.library import random_iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "observable = SparsePauliOp(\"Z\" * 3)\n", - "\n", - "circuit = random_iqp(3)\n", - "circuit.measure_all()\n", - "\n", - "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=3, backend=backend\n", - ")\n", - "\n", - "isa_circuit = pass_manager.run(circuit)\n", - "isa_observable = observable.apply_layout(isa_circuit.layout)\n", - "\n", - "# Setting precision during primitive initialization\n", - "estimator = Estimator(mode=backend, options={\"default_precision\": 0.05})\n", - "\n", - "# Run with precision=0.02, overwriting the default.\n", - "estimator.run(\n", - " [(isa_circuit, isa_observable1)],\n", - " precision=0.02,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "be2f096d-355a-4f5f-8729-4808a0c5791d", - "metadata": {}, - "source": [ - "\n", - "## Turn off all error mitigation and error suppression\n", - "\n", - "You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, set `resilience_level = 0`.\n", - "\n", - "Example:" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "id": "0e357659-44c4-4332-80b9-c0a9080adfbd", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import EstimatorV2 as Estimator, QiskitRuntimeService\n", - "\n", - "# Define the service. This allows you to access an IBM QPU.\n", - "service = QiskitRuntimeService()\n", - "\n", - "# Get a backend\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "# Define Estimator\n", - "estimator = Estimator(backend)\n", - "\n", - "options = estimator.options\n", - "\n", - "# Turn off all error mitigation and suppression\n", - "options.resilience_level = 0" - ] - }, - { - "cell_type": "markdown", - "id": "e64d93fc-2a2c-4e6b-a94a-fd7142858c99", - "metadata": {}, - "source": [ - "\n", - "## Available options\n", - "\n", - "The following table documents options from the latest version of `qiskit-ibm-runtime`. To see older option versions, visit the [`qiskit-ibm-runtime` API reference](/docs/api/qiskit-ibm-runtime) and select a previous version.\n", - "\n", - "\n", - "\n", - "\n", - "The total number of shots to use per circuit per configuration.\n", - "\n", - "**Choices**: Integer >= 0\n", - "\n", - "**Default**: None\n", - "\n", - "[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_shots)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "The default precision to use for any PUB or `run()` call that does not specify one.\n", - "\n", - "**Choices**: Float > 0\n", - "\n", - "**Default**: 0.015625 (1 / sqrt(4096))\n", - "\n", - "[`default_precision` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_precision)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Control dynamical decoupling error mitigation settings.\n", - "\n", - "[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling)\n", - "\n", - "\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `False`\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `middle`, `edges`\n", - "\n", - "**Default**: `middle`\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Choices: `asap`, `alap`\n", - "Default: `alap`\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Choices: `XX`, `XpXm`, `XY4`\n", - "Default: `XX`\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Choices: `True`, `False`\n", - "Default: `False`\n", - " \n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment)\n", - "\n", - "\n", - "\n", - "Callable function that receives the `Job ID` and `Job result`.\n", - "\n", - "**Choices**: None\n", - "\n", - "**Default**: None\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "List of tags.\n", - "\n", - "**Choices**: None\n", - "\n", - "**Default**: None\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", - "\n", - "**Default**: WARNING\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `False`\n", - " \n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution)\n", - "\n", - "\n", - "Whether to reset the qubits to the ground state for each shot.\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `True`\n", - " \n", - "\n", - "\n", - "\n", - "The delay between a measurement and the subsequent quantum circuit.\n", - "\n", - "**Choices**: Value in the range supplied by `backend.rep_delay_range`\n", - "\n", - "**Default**: Given by `backend.default_rep_delay`\n", - " \n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Limits how long a job can run, in seconds. See the [maximum execution time](/docs/guides/max-execution-time) guide for details.\n", - "\n", - "**Choices**: Integer number of seconds in the range [1, 10800]\n", - "\n", - "**Default**: 10800 (3 hours)\n", - " \n", - "\n", - "\n", - "\n", - "Advanced resilience options to fine tune the resilience strategy.\n", - "\n", - "[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience)\n", - "\n", - "\n", - "\n", - "Options for learning layer noise.\n", - "\n", - "[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: list[int] of 2-10 values in the range [0, 200]\n", - "\n", - "**Default**: `(0, 1, 2, 4, 16, 32)`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: None, Integer >= 1\n", - "\n", - "**Default**: `4`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer >= 1\n", - "\n", - "**Default**: `32`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer >= 1\n", - "\n", - "**Default**: `128`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]`\n", - "\n", - "**Default**: None\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `True`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "Options for measurement noise learning.\n", - "\n", - "[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer >= 1\n", - "\n", - "**Default**: `32`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer, `auto`\n", - "\n", - "**Default**: `auto`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `False`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "Probabilistic error cancellation mitigation options.\n", - "\n", - "[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `None`, Integer >= 1\n", - "\n", - "\n", - "**Default**: `100`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `auto`, float in the range [0, 1]\n", - "\n", - "**Default**: `auto`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `True`, `False`\n", - "\n", - "**Default**: `False`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea`\n", - "\n", - "**Default**: `gate_folding`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: List of floats\n", - "\n", - "**Default**: `[0, *noise_factors]`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback`\n", - "\n", - "**Default**: `(exponential, linear)`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: List of floats; each float >= 1\n", - "\n", - "**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times. See the [resilience levels](/docs/guides/estimator-noise-management#resilience) section in the Noise management topic to learn more.\n", - "\n", - "**Choices**: `0`, `1`, `2`\n", - "\n", - "**Default**: `1`\n", - "\n", - "[`resilience_level` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience_level)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer\n", - "\n", - "**Default**: None\n", - "\n", - "[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator)\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "Options to pass when simulating a backend\n", - "\n", - "[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options)\n", - "\n", - "\n", - "\n", - "**Choices**: List of basis gate names to unroll to\n", - "\n", - "**Default**: The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html)\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: List of directed two-qubit interactions\n", - "\n", - "**Default**: None, which implies no connectivity constraints (full connectivity).\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation\n", - "\n", - "**Default**: None\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: Integer\n", - "\n", - "**Default**: None\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "Twirling options\n", - "\n", - "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", - "\n", - "\n", - "\n", - "**Choices**: True, False\n", - "\n", - "**Default**: False\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: True, False\n", - "\n", - "**Default**: True\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `auto`, Integer >= 1\n", - "\n", - "**Default**: `auto`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `auto`, Integer >= 1\n", - "\n", - "**Default**: `auto`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "**Choices**: `active`, `active-circuit`, `active-accum`, `all`\n", - "\n", - "**Default**: `active-accum`\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\n", - "Experimental options, when available.\n", - "\n", - " \n", - "\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "83f4261c-fe8e-4993-ad7c-280350a970f3", - "metadata": {}, - "source": [ - "\n", - "## Feature compatibility\n", - "\n", - "Certain runtime features cannot be used together in a single job. Click the appropriate tab for a list of features that are incompatible with the selected feature:\n", - "\n", - "\n", - "\n", - " \n", - " Incompatible with:\n", - " - Gate twirling\n", - " - PEA\n", - " - PEC\n", - "\n", - " \n", - "\n", - " \n", - " Incompatible with:\n", - " - PEA\n", - " - PEC\n", - "\n", - " Might not work when using custom gates.\n", - " \n", - " \n", - " Incompatible with fractional gates or with stretches.\n", - "\n", - " Other notes:\n", - " - Measurement twirling can only be applied to terminal measurements.\n", - " - Does not work with non-Clifford entanglers.\n", - "\n", - " \n", - "\n", - " \n", - " Incompatible with:\n", - " - Fractional gates\n", - " - Gate-folding ZNE\n", - " - PEC\n", - " \n", - "\n", - " \n", - " Incompatible with:\n", - " - Fractional gates\n", - " - Gate-folding ZNE\n", - " - PEA\n", - " \n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "5e795454-5b76-40d3-94c6-bb982be58239", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Find more details about the `EstimatorV2` methods in the [Estimator API reference](/docs/api/qiskit-ibm-runtime/estimator-v2).\n", - " - Decide what [execution mode](/docs/guides/execution-modes) to run your job in.\n", - " - Learn about [noise management with Estimator](/docs/guides/estimator-noise-management).\n", - "" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c457f721-e66d-403e-84be-10b26863c86d", + "metadata": {}, + "source": [ + "---\n", + "title: Specify Estimator options\n", + "description: Specify options when building with the Estimator primitive.\n", + "---\n", + "\n", + "\n", + "# Specify Estimator options" + ] + }, + { + "cell_type": "markdown", + "id": "1a97b5d6-3fb2-4c33-9b95-807bb6768a84", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", + "\n", + "
\n", + "Package versions\n", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit[all]~=2.3.0\n", + "qiskit-ibm-runtime~=0.43.1\n", + "```\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "3c1e38b5-3f01-4818-943e-f52d877be6ad", + "metadata": {}, + "source": [ + "You can use options to customize the Estimator primitive. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the API references for information about the [`qiskit.primitives.BaseEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BaseEstimatorV2) and [`qiskit_aer.BaseEstimatorV2`](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.primitives.EstimatorV2.html) options.\n", + "\n", + "\n", + "## Set Estimator options\n", + "\n", + "You can set options when initializing Estimator, after initializing Estimator, or you can update the options after Estimator has been initialized. For instructions to use these techniques, see the [Introduction to options](/docs/guides/runtime-options-overview#options-precedence) topic.\n", + "\n", + "Additionally, you can set the `precision` value in the `run()` method, as is described in the following section." + ] + }, + { + "cell_type": "markdown", + "id": "7cde6f7f-278e-4170-afa3-2c3fb4ec4bfa", + "metadata": {}, + "source": [ + "\n", + "### Run() method\n", + "\n", + "The only values you can pass to `run()` are those defined in the interface. That is, `precision` for Estimator. This overwrites any value set for `default_precision` for the current run." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "c0606f38-2bed-4b56-8202-708669e5ea66", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", + "from qiskit.circuit.library import random_iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "circuit1 = random_iqp(3)\n", + "circuit1.measure_all()\n", + "circuit2 = random_iqp(3)\n", + "circuit2.measure_all()\n", + "\n", + "observable = SparsePauliOp(\"Z\" * 3)\n", + "\n", + "pass_manager = generate_preset_pass_manager(\n", + " optimization_level=3, backend=backend\n", + ")\n", + "\n", + "transpiled1 = pass_manager.run(circuit1)\n", + "transpiled2 = pass_manager.run(circuit2)\n", + "isa_observable1 = observable.apply_layout(transpiled1.layout)\n", + "isa_observable2 = observable.apply_layout(transpiled2.layout)\n", + "\n", + "estimator = Estimator(mode=backend)\n", + "# Default precision to use if not specified in run()\n", + "estimator.options.default_precision = 0.01\n", + "# Run two circuits, requiring a precision of .02 for both.\n", + "estimator.run(\n", + " [(transpiled1, isa_observable1), (transpiled2, isa_observable2)],\n", + " precision=0.02,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "effe450a-255f-4837-a276-c8c3ea6e2db0", + "metadata": {}, + "source": [ + "### Special case: precision\n", + "\n", + "The `EstimatorV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for precision, and a precision keyword argument. These precision values are a part of the Estimator execution interface, and are independent of the Runtime Estimator's options. They take precedence over any values specified as options in order to comply with the Estimator abstraction.\n", + "\n", + "However, if `precision` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the precision value from the options is used, most notably `default_precision`.\n", + "\n", + "Note that Estimator options contain both `default_shots` and `default_precision`. However, because gate-twirling is enabled by default, the product of `num_randomizations` and `shots_per_randomization` takes precedence over those two options.\n", + "\n", + "Specifically, for any Estimator PUB:\n", + "\n", + "1. If the PUB specifies precision, use that value.\n", + "2. If the precision keyword argument is specified in `run`, use that value.\n", + "3. If `twirling` is enabled (True by default), then the product of `num_randomizations` and `shots_per_randomization`, as specified in [`twirling` options](/docs/api/qiskit-ibm-runtime/options-twirling-options), is used.\n", + "4. If `estimator.options.default_shots` is specified, use that value to control the amount of data.\n", + "5. If `estimator.options.default_precision` is specified, use that value.\n", + "\n", + "For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used.\n", + "\n", + "\n", + "Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bf02c107-226e-443a-ab4c-dfd3246ada2c", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", + "from qiskit.circuit.library import random_iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "observable = SparsePauliOp(\"Z\" * 3)\n", + "\n", + "circuit = random_iqp(3)\n", + "circuit.measure_all()\n", + "\n", + "pass_manager = generate_preset_pass_manager(\n", + " optimization_level=3, backend=backend\n", + ")\n", + "\n", + "isa_circuit = pass_manager.run(circuit)\n", + "isa_observable = observable.apply_layout(isa_circuit.layout)\n", + "\n", + "# Setting precision during primitive initialization\n", + "estimator = Estimator(mode=backend, options={\"default_precision\": 0.05})\n", + "\n", + "# Run with precision=0.02, overwriting the default.\n", + "estimator.run(\n", + " [(isa_circuit, isa_observable1)],\n", + " precision=0.02,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "be2f096d-355a-4f5f-8729-4808a0c5791d", + "metadata": {}, + "source": [ + "\n", + "## Turn off all error mitigation and error suppression\n", + "\n", + "You can turn off all error mitigation and suppression if you are, for example, doing research on your own mitigation techniques. To accomplish this, set `resilience_level = 0`.\n", + "\n", + "Example:" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "0e357659-44c4-4332-80b9-c0a9080adfbd", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import EstimatorV2 as Estimator, QiskitRuntimeService\n", + "\n", + "# Define the service. This allows you to access an IBM QPU.\n", + "service = QiskitRuntimeService()\n", + "\n", + "# Get a backend\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "# Define Estimator\n", + "estimator = Estimator(backend)\n", + "\n", + "options = estimator.options\n", + "\n", + "# Turn off all error mitigation and suppression\n", + "options.resilience_level = 0" + ] + }, + { + "cell_type": "markdown", + "id": "e64d93fc-2a2c-4e6b-a94a-fd7142858c99", + "metadata": {}, + "source": [ + "\n", + "## Available options\n", + "\n", + "The following table documents options from the latest version of `qiskit-ibm-runtime`. To see older option versions, visit the [`qiskit-ibm-runtime` API reference](/docs/api/qiskit-ibm-runtime) and select a previous version.\n", + "\n", + "\n", + "\n", + "\n", + "The total number of shots to use per circuit per configuration.\n", + "\n", + "**Choices**: Integer >= 0\n", + "\n", + "**Default**: None\n", + "\n", + "[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_shots)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "The default precision to use for any PUB or `run()` call that does not specify one.\n", + "\n", + "**Choices**: Float > 0\n", + "\n", + "**Default**: 0.015625 (1 / sqrt(4096))\n", + "\n", + "[`default_precision` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_precision)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Control dynamical decoupling error mitigation settings.\n", + "\n", + "[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling)\n", + "\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `middle`, `edges`\n", + "\n", + "**Default**: `middle`\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Choices: `asap`, `alap`\n", + "Default: `alap`\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Choices: `XX`, `XpXm`, `XY4`\n", + "Default: `XX`\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Choices: `True`, `False`\n", + "Default: `False`\n", + " \n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment)\n", + "\n", + "\n", + "\n", + "Callable function that receives the `Job ID` and `Job result`.\n", + "\n", + "**Choices**: None\n", + "\n", + "**Default**: None\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "List of tags.\n", + "\n", + "**Choices**: None\n", + "\n", + "**Default**: None\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", + "\n", + "**Default**: WARNING\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + " \n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution)\n", + "\n", + "\n", + "Whether to reset the qubits to the ground state for each shot.\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `True`\n", + " \n", + "\n", + "\n", + "\n", + "The delay between a measurement and the subsequent quantum circuit.\n", + "\n", + "**Choices**: Value in the range supplied by `backend.rep_delay_range`\n", + "\n", + "**Default**: Given by `backend.default_rep_delay`\n", + " \n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Limits how long a job can run, in seconds. See the [maximum execution time](/docs/guides/max-execution-time) guide for details.\n", + "\n", + "**Choices**: Integer number of seconds in the range [1, 10800]\n", + "\n", + "**Default**: 10800 (3 hours)\n", + " \n", + "\n", + "\n", + "\n", + "Advanced resilience options to fine tune the resilience strategy.\n", + "\n", + "[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience)\n", + "\n", + "\n", + "\n", + "Options for learning layer noise.\n", + "\n", + "[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: list[int] of 2-10 values in the range [0, 200]\n", + "\n", + "**Default**: `(0, 1, 2, 4, 16, 32)`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: None, Integer >= 1\n", + "\n", + "**Default**: `4`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `32`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `128`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]`\n", + "\n", + "**Default**: None\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `True`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "Options for measurement noise learning.\n", + "\n", + "[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `32`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer, `auto`\n", + "\n", + "**Default**: `auto`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "Probabilistic error cancellation mitigation options.\n", + "\n", + "[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `None`, Integer >= 1\n", + "\n", + "\n", + "**Default**: `100`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `auto`, float in the range [0, 1]\n", + "\n", + "**Default**: `auto`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea`\n", + "\n", + "**Default**: `gate_folding`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: List of floats\n", + "\n", + "**Default**: `[0, *noise_factors]`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback`\n", + "\n", + "**Default**: `(exponential, linear)`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: List of floats; each float >= 1\n", + "\n", + "**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times. See the [resilience levels](/docs/guides/estimator-noise-management#resilience) section in the Noise management topic to learn more.\n", + "\n", + "**Choices**: `0`, `1`, `2`\n", + "\n", + "**Default**: `1`\n", + "\n", + "[`resilience_level` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience_level)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer\n", + "\n", + "**Default**: None\n", + "\n", + "[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator)\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "Options to pass when simulating a backend\n", + "\n", + "[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options)\n", + "\n", + "\n", + "\n", + "**Choices**: List of basis gate names to unroll to\n", + "\n", + "**Default**: The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html)\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: List of directed two-qubit interactions\n", + "\n", + "**Default**: None, which implies no connectivity constraints (full connectivity).\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation\n", + "\n", + "**Default**: None\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: Integer\n", + "\n", + "**Default**: None\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "Twirling options\n", + "\n", + "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", + "\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: False\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: True\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "**Choices**: `active`, `active-circuit`, `active-accum`, `all`\n", + "\n", + "**Default**: `active-accum`\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + " \n", + "\n", + "\n", + "\n", + "\n", + "\n", + "Experimental options, when available.\n", + "\n", + " \n", + "\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "83f4261c-fe8e-4993-ad7c-280350a970f3", + "metadata": {}, + "source": [ + "\n", + "## Feature compatibility\n", + "\n", + "Certain runtime features cannot be used together in a single job. Click the appropriate tab for a list of features that are incompatible with the selected feature:\n", + "\n", + "\n", + "\n", + " \n", + " Incompatible with:\n", + " - Gate twirling\n", + " - PEA\n", + " - PEC\n", + "\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - PEA\n", + " - PEC\n", + "\n", + " Might not work when using custom gates.\n", + " \n", + " \n", + " Incompatible with fractional gates or with stretches.\n", + "\n", + " Other notes:\n", + " - Measurement twirling can only be applied to terminal measurements.\n", + " - Does not work with non-Clifford entanglers.\n", + "\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - Fractional gates\n", + " - Gate-folding ZNE\n", + " - PEC\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - Fractional gates\n", + " - Gate-folding ZNE\n", + " - PEA\n", + " \n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "5e795454-5b76-40d3-94c6-bb982be58239", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - Review the [Introduction to options](/docs/guides/runtime-options-overview) guide.\n", + " - Find more details about the `EstimatorV2` methods in the [Estimator API reference](/docs/api/qiskit-ibm-runtime/estimator-v2).\n", + " - Decide what [execution mode](/docs/guides/execution-modes) to run your job in.\n", + " - Learn about [noise management with Estimator](/docs/guides/estimator-noise-management).\n", + "" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 620d3ffb4e4..e67f82d5322 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -24,7 +24,98 @@ The tables in the "Options classes summary" section on each primitive's "options ## Set options -Options can be defined before a primitive is constructed and passed to the primitive, which makes a copy of them. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. +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. + + +- You can see the available options during or after primitive initialization. +- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. +- The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. + + +### `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`](/docs/api/qiskit-ibm-runtime/options-sampler-options) or [`EstimatorOptions`](/docs/api/qiskit-ibm-runtime/options-estimator-options) for full details about the class. + +The following example uses the Estimator primitive, but the syntax for other primitives is similar. + +```python +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. + +```python +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`](/docs/api/qiskit-ibm-runtime/options-estimator-options) or [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options)) 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. + +```python +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 diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 4e3dfbc42f0..22e78e5ac45 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -50,125 +50,12 @@ "source": [ "You can use options to customize the Sampler primitive. This section focuses on how to specify Qiskit Runtime primitive options. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the corresponding API references for information about the [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) and [`qiskit_aer.primitives.SamplerV2`](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.primitives.SamplerV2.html) options.\n", "\n", - "\n", - "- You can see the available options and update option values during or after primitive initialization.\n", - "- Use the `update()` method to apply changes to the `options` attribute.\n", - "- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used.\n", - "- The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary.\n", - "\n", - "\n", "\n", "## Set Sampler options\n", "\n", - "You can set options when initializing the primitive, after initializing the primitive, or (for `shots` only), in the `run()` method.\n", - "\n", - "### Primitive initialization\n", - "\n", - "You can pass in an instance of the options class or a dictionary when initializing Sampler, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitive.\n", - "\n", - "#### Options class\n", - "\n", - "When creating an instance of the `SamplerV2` class, you can pass in an instance of the options class. Those options will then be 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`\n", - "\n", - "See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options) for full details about the options class." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "50938cb3-3bee-4a28-9f30-1b73b1c6a70f", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", - "from qiskit_ibm_runtime.options import SamplerOptions\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", + "You can set options when initializing Sampler, after initializing Sampler, or you can update the options after Sampler has been initialized. For instructions to use these techniques, see the [Introduction to options](/docs/guides/runtime-options-overview#options-precedence) topic.\n", "\n", - "options = SamplerOptions(\n", - " dynamical_decoupling={\"enable\": True, \"sequence_type\": \"XpXm\"},\n", - ")\n", - "\n", - "# or...\n", - "options = SamplerOptions()\n", - "options.dynamical_decoupling.enable = True\n", - "options.dynamical_decoupling.sequence_type = \"XpXm\"\n", - "\n", - "sampler = Sampler(mode=backend, options=options)" - ] - }, - { - "cell_type": "markdown", - "id": "4d30fcfc-58b7-4cb4-9e2d-6addfb25e9c2", - "metadata": {}, - "source": [ - "#### Dictionary\n", - "\n", - "You can specify options as a dictionary when initializing Sampler." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "5849c541-c779-470e-8ab0-a6d0e1a14775", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "# Setting options during primitive initialization\n", - "sampler = Sampler(\n", - " backend,\n", - " options={\n", - " \"dynamical_decoupling\": {\n", - " \"enable\": True,\n", - " \"sequence_type\": \"XpXm\",\n", - " },\n", - " },\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "2417e82a-7bca-4365-a0ab-0a1304ac3f0f", - "metadata": {}, - "source": [ - "### Update options after initialization\n", - "\n", - "You can specify the options in this format: `sampler.options.option.sub-option.sub-sub-option = choice` to take advantage of auto-complete, or use the `update()` method to make bulk updates.\n", - "\n", - "The `SamplerV2` options class ([`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options)) does not need to be instantiated if you are setting options after initializing the primitive." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "07353a3e-0226-4b68-b280-15ad51f11093", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "sampler = Sampler(mode=backend)\n", - "\n", - "# Setting options after primitive initialization\n", - "# This uses auto-complete.\n", - "sampler.options.default_shots = 4000\n", - "# This does bulk update.\n", - "sampler.options.update(\n", - " default_shots=4000,\n", - " dynamical_decoupling={\"enable\": True, \"sequence_type\": \"XpXm\"},\n", - ")" + "Additionally, you can set the `shots` value in the `run()` method, as is described in the following section." ] }, { @@ -641,7 +528,8 @@ "## Next steps\n", "\n", "\n", - " - Find more details about the `SamplerV2` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/sampler-v2).\n", + " - Review the [Introduction to options](/docs/guides/runtime-options-overview) guide.\n", + " - Find more details about the `SamplerV2` methods in the [Sampler API reference](/docs/api/qiskit-ibm-runtime/sampler-v2).\n", " - Decide what [execution mode](execution-modes) to run your job in.\n", " - Learn about [noise management with Sampler](/docs/guides/sampler-noise-management).\n", ""