diff --git a/docs/guides/specify-runtime-options.ipynb b/docs/guides/specify-runtime-options.ipynb new file mode 100644 index 00000000000..625d7cb714d --- /dev/null +++ b/docs/guides/specify-runtime-options.ipynb @@ -0,0 +1,448 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "8bbb8d7d-bcd5-4092-9df1-9930c67b17bc", + "metadata": {}, + "source": [ + "# Specify options\n", + "\n", + "You can use options to customize the Estimator and Sampler primitives. 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`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options.\n", + "\n", + "Notes about specifying options in the primitives:\n", + "\n", + "- `SamplerV2` and `EstimatorV2` have separate options classes. 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", + "## Set primitive options\n", + "\n", + "You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places.\n", + "\n", + "### Primitive initialization\n", + "\n", + "You can pass in an instance of the options class or a dictionary when initializing a primitive, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitives.\n", + "\n", + "#### Options class\n", + "\n", + "When creating an instance of the `EstimatorV2` or `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", + "Example:\n", + "\n", + "`SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions))." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "4b40f0e5-2db0-4ccc-9c07-bdb71d2f5b91", + "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": "ba2f5146-2781-49da-9fa2-8a22647225d0", + "metadata": {}, + "source": [ + "#### Dictionary\n", + "\n", + "You can specify options as a dictionary when initializing the primitive." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "0ee1eaf6-c221-437f-8ff8-40ec2aa937c0", + "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 primitive 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": "fc9a759a-6d43-4372-bad2-87512d43b255", + "metadata": {}, + "source": [ + "### Update options after initialization\n", + "\n", + "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.\n", + "\n", + "The `SamplerV2` and `EstimatorV2` options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) do not need to be instantiated if you are setting options after initializing the primitive." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "71de6acf-77a5-460f-ac54-f88f7a4d2fa6", + "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 primitive initialization\n", + "# This uses auto-complete.\n", + "estimator.options.default_shots = 4000\n", + "# This does bulk update.\n", + "estimator.options.update(\n", + " default_shots=4000, resilience={\"zne_mitigation\": True}\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "fde8c5bf-d914-4806-b55e-1f33aa643204", + "metadata": {}, + "source": [ + "\n", + "### Run() method\n", + "\n", + "The only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "f2c12ead-4785-4d4f-bf4a-f015295d7083", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 1, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", + "from qiskit.circuit.library import random_iqp\n", + "from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager\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", + "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", + "\n", + "sampler = Sampler(mode=backend)\n", + "# Default shots to use if not specified in run()\n", + "sampler.options.default_shots = 500\n", + "# Sample two circuits at 128 shots each.\n", + "sampler.run([transpiled1, transpiled2], shots=128)\n", + "\n", + "# Sample two circuits with different numbers of shots.\n", + "# 100 shots is used for transpiled1 and 200 for transpiled.\n", + "sampler.run([(transpiled1, None, 100), (transpiled2, None, 200)])" + ] + }, + { + "cell_type": "markdown", + "id": "8be4bd84-9060-437a-85f4-3d996f3e581f", + "metadata": {}, + "source": [ + "### Special cases\n", + "\n", + "#### Resilience level (Estimator only)\n", + "\n", + "The resilience level is not actually an option that directly impacts the primitive query, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation.\n", + "\n", + "Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. Therefore, in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised.\n", + "\n", + "In the following example, setting the resilience level to 0 initially turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "80c10c6d-a6df-460a-bf5f-a5bac3588c1f", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "estimator = EstimatorV2(backend)\n", + "\n", + "estimator.options.default_shots = 100\n", + "estimator.options.resilience_level = 0\n", + "estimator.options.resilience.zne_mitigation = True" + ] + }, + { + "cell_type": "markdown", + "id": "52024f25-74ef-445a-9df8-d76da4ec7a32", + "metadata": {}, + "source": [ + "#### Shots (Sampler only)\n", + "\n", + "The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Sampler's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction.\n", + "\n", + "However, if `shots` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the shots value from the options is used, most notably `default_shots`.\n", + "\n", + "Finally, because the [`twirling` options](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) `num_randomizations` and `shots_per_randomization` are enabled by default, the number of shots will actually be the product of `num_randomizations` and `shots_per_randomization` if the `default_shots` value is the only way shots are specified.\n", + "\n", + "To summarize, this is the order of precedence for specifying shots in the Sampler, for any particular PUB:\n", + "\n", + "1. If the PUB specifies shots, use that value.\n", + "2. If the `shots` keyword argument is specified in `run`, use that value.\n", + "3. If `num_randomizations` and `shots_per_randomization` are specified as `twirling` options (enabled by default), shots are the product of those values.\n", + "3. If `sampler.options.default_shots` is specified, use that value.\n", + "\n", + "Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used.\n", + "\n", + "#### Precision (Estimator only)\n", + "\n", + "Precision is analogous to shots, described in the previous section, except that the Estimator options contain both `default_shots` and `default_precision`.\n", + "\n", + "Specifically, for any particular 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", + "2. If `num_randomizations` and `shots_per_randomization` are specified as [`twirling` options](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) (enabled by default), use their product to control the amount of data.\n", + "3. If `estimator.options.default_shots` is specified, use that value to control the amount of data.\n", + "4. 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", + "\n", + "\n", + "## Commonly used options\n", + "\n", + "There are many available options, but the following are the most commonly used:\n", + "\n", + "\n", + "### Shots\n", + "For some algorithms, setting a specific number of shots is a core part of their routines. Shots (or precision) can be specified in multiple places. They are prioritized as follows:\n", + "\n", + "For any Sampler PUB:\n", + "\n", + "1. Integer-valued shots contained in the PUB\n", + "2. The `run(...,shots=val)` value\n", + "3. The `options.default_shots` value\n", + "\n", + "For any Estimator PUB:\n", + "\n", + "1. Float-valued precision contained in the PUB\n", + "2. The `run(...,precision=val)` value\n", + "3. The `options.default_shots` value\n", + "4. The `options.default_precision` value\n", + "\n", + "Example:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "43ed5d23-8d2e-43a7-82a9-b563de861ab1", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", + "from qiskit.circuit.library import random_iqp\n", + "from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager\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", + "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", + "\n", + "\n", + "# Setting shots during primitive initialization\n", + "sampler = Sampler(mode=backend, options={\"default_shots\": 4096})\n", + "\n", + "# Setting options after primitive initialization\n", + "# This uses auto-complete.\n", + "sampler.options.default_shots = 2000\n", + "\n", + "# This does bulk update. The value for default_shots is overridden if you specify shots with run() or in the PUB.\n", + "sampler.options.update(\n", + " default_shots=1024, dynamical_decoupling={\"sequence_type\": \"XpXm\"}\n", + ")\n", + "\n", + "# Sample two circuits at 128 shots each.\n", + "sampler.run([transpiled1, transpiled2], shots=128)" + ] + }, + { + "cell_type": "markdown", + "id": "81196237-227f-449e-a780-c21fb328a7df", + "metadata": {}, + "source": [ + "### Maximum execution time\n", + "\n", + "The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly canceled. This value applies to single jobs, whether they are run in job, session, or batch mode.\n", + "\n", + "The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not use quantum time." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "31bd9edf-2c9e-44be-9e30-71a8415103aa", + "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", + "estimator.options.max_execution_time = 2500" + ] + }, + { + "cell_type": "markdown", + "id": "eabb08cf-e67c-452a-8aa5-d028baee77e0", + "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, for EstimatorV2, set `resilience_level = 0`. For SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default.\n", + "\n", + "Example:\n", + "\n", + "Turn off all error mitigation and suppression in Estimator." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "9fe17f58-c273-49db-b35f-f698ab44319f", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import EstimatorV2 as Estimator, QiskitRuntimeService\n", + "\n", + "# Define the service. This allows you to access 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": "9b86001b-718a-4d72-b3b5-4a67eabf0a45", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - Find more details about the `EstimatorV2` methods in the [Estimator API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2).\n", + " - Find more details about the `SamplerV2` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.SamplerV2).\n", + " - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation).\n", + " - Decide what [execution mode](execution-modes) to run your job in.\n", + "" + ] + } + ], + "metadata": { + "description": "Specify options when building with Qiskit Runtime primitives.", + "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" + }, + "title": "Specify options" + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/docs/guides/specify-runtime-options.mdx b/docs/guides/specify-runtime-options.mdx deleted file mode 100644 index 7f712c7dd2c..00000000000 --- a/docs/guides/specify-runtime-options.mdx +++ /dev/null @@ -1,269 +0,0 @@ ---- -title: Specify options -description: Specify options when building with Qiskit Runtime primitives - ---- - -# Specify options - -You can use options to customize the Estimator and Sampler primitives. 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`](/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. - -Notes about specifying options in the primitives: - -- `SamplerV2` and `EstimatorV2` have separate options classes. You can see the available options and update option values during or after primitive initialization. -- Use the `update()` method to apply 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. -- The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. - - -## Set primitive options - -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. - -### Primitive initialization - -You can pass in an instance of the options class or a dictionary when initializing a primitive, which then makes a copy of those options. Thus, changing the original dictionary or options instance doesn't affect the options owned by the primitives. - -#### Options class - -When creating an instance of the `EstimatorV2` or `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` - -Example: - -`SamplerV2` and `EstimatorV2` have separate options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)). - -```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 the primitive. - - ```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 primitive 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 `SamplerV2` and `EstimatorV2` options classes ([`EstimatorOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EstimatorOptions) and [`SamplerOptions`](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions)) do not need to be instantiated if you are setting options after initializing the primitive. -```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 primitive initialization -# This uses auto-complete. -estimator.options.default_shots = 4000 -# This does bulk update. -estimator.options.update(default_shots=4000, resilience={"zne_mitigation": True}) -``` - - -### Run() method - -The only values you can pass to `run()` are those defined in the interface. That is, `shots` for Sampler and `precision` for Estimator. This overwrites any value set for `default_shots` or `default_precision` for the current run. - -```python -from qiskit_ibm_runtime import QiskitRuntimeService -from qiskit_ibm_runtime import SamplerV2 as Sampler - -service = QiskitRuntimeService() -backend = service.least_busy(operational=True, simulator=False) - -sampler = Sampler(mode=backend) -# Default shots to use if not specified in run() -sampler.options.default_shots = 500 -# Sample two circuits at 128 shots each. -sampler.run([circuit1, circuit2], shots=128) - -# Sample two circuits with different numbers of shots. -# 100 shots is used for circuit1 and 200 for circuit2. -sampler.run([(circuit1, None, 100), (circuit2, None, 200)]) -``` - -### Special cases - -#### Resilience level (Estimator only) - -The resilience level is not actually an option that directly impacts the primitive query, but specifies a base set of curated options to build off of. In general, level 0 turns off all error mitigation, level 1 turns on options for measurement error mitigation, and level 2 turns on options for gate and measurement error mitigation. - -Any options you manually specify in addition to the resilience level are applied on top of the base set of options defined by the resilience level. Therefore, in principle, you could set the resilience level to 1, but then turn off measurement mitigation, although this is not advised. - -In the following example, setting the resilience level to 0 initially turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides the relevent setup from `estimator.options.resilience_level = 0`. - -``` python -from qiskit_ibm_runtime import EstimatorV2, QiskitRuntimeService -from qiskit import QuantumCircuit - -service = QiskitRuntimeService() -backend = service.backend("ibm_auckland") - -estimator = EstimatorV2(backend) - -estimator.options.default_shots = 100 -estimator.options.resilience_level = 0 -estimator.options.resilience.zne_mitigation = True -``` - -#### Shots (Sampler only) - -The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Sampler's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction. - -However, if `shots` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the shots value from the options is used, most notably `default_shots`. - -Finally, because the [`twirling` options](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) `num_randomizations` and `shots_per_randomization` are enabled by default, the number of shots will actually be the product of `num_randomizations` and `shots_per_randomization` if the `default_shots` value is the only way shots are specified. - -To summarize, this is the order of precedence for specifying shots in the Sampler, for any particular PUB: - -1. If the PUB specifies shots, use that value. -2. If the `shots` keyword argument is specified in `run`, use that value. -3. If `num_randomizations` and `shots_per_randomization` are specified as `twirling` options (enabled by default), shots are the product of those values. -3. If `sampler.options.default_shots` is specified, use that value. - -Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used. - -#### Precision (Estimator only) - -Precision is analogous to shots, described in the previous section, except that the Estimator options contain both `default_shots` and `default_precision`. - -Specifically, for any particular Estimator PUB: - -1. If the PUB specifies precision, use that value. -2. If the precision keyword argument is specified in `run`, use that value. -2. If `num_randomizations` and `shots_per_randomization` are specified as [`twirling` options](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.TwirlingOptions) (enabled by default), use their product to control the amount of data. -3. If `estimator.options.default_shots` is specified, use that value to control the amount of data. -4. If `estimator.options.default_precision` is specified, use that value. - -For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used. - - -Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run. - - -## Commonly used options - -There are many available options, but the following are the most commonly used: - - -### Shots -For some algorithms, setting a specific number of shots is a core part of their routines. Shots (or precision) can be specified in multiple places. They are prioritized as follows: - -For any Sampler PUB: - -1. Integer-valued shots contained in the PUB -2. The `run(...,shots=val)` value -3. The `options.default_shots` value - -For any Estimator PUB: - -1. Float-valued precision contained in the PUB -2. The `run(...,precision=val)` value -3. The `options.default_shots` value -4. The `options.default_precision` value - -Example: - -```python -from qiskit_ibm_runtime import QiskitRuntimeService -from qiskit_ibm_runtime import SamplerV2 as Sampler - -service = QiskitRuntimeService() -backend = service.least_busy(operational=True, simulator=False) - -# Setting shots during primitive initialization -sampler = Sampler(mode=backend, options={"default_shots": 4096}) - -# Setting options after primitive initialization -# This uses auto-complete. -sampler.options.default_shots=2000 - -# This does bulk update. The value for default_shots is overridden if you specify shots with run() or in the PUB. -sampler.options.update(default_shots=1024, dynamical_decoupling={"sequence_type": "XpXm"}) - -# Sample two circuits at 128 shots each. -sampler.run([circuit1, circuit2], shots=128) - ``` - -### Maximum execution time - -The maximum execution time (`max_execution_time`) limits how long a job can run. If a job exceeds this time limit, it is forcibly canceled. This value applies to single jobs, whether they are run in job, session, or batch mode. - -The value is set in seconds, based on quantum time (not wall clock time), which is the amount of time that the QPU is dedicated to processing your job. It is ignored when using local testing mode because that mode does not use quantum time. - -```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) - -estimator.options.max_execution_time = 2500 -``` - - -## 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. - -Example: - -Turn off all error mitigation and suppression in Estimator. - -```python -from qiskit_ibm_runtime import EstimatorV2 as Estimator, QiskitRuntimeService - -# Define the service. This allows you to access IBM QPU. -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 -``` - - -## Next steps - - - - Find more details about the `EstimatorV2` methods in the [Estimator API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2). - - Find more details about the `SamplerV2` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.SamplerV2). - - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). - - Decide what [execution mode](execution-modes) to run your job in. - \ No newline at end of file diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 8fa5dac40fa..c82cf48a29c 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -50,6 +50,7 @@ test-strategies.ci = { patch="qiskit-fake-provider", num_qubits=6 } test-strategies.hardware = { patch="qiskit-ibm-runtime-open" } notebooks = [ "docs/guides/debug-qiskit-runtime-jobs.ipynb", + "docs/guides/specify-runtime-options.ipynb", "docs/guides/primitive-input-output.ipynb", ]