{ "cells": [ { "cell_type": "markdown", "id": "bed19311-f71d-4d8c-9a05-1b68fa72df29", "metadata": {}, "source": [ "---\n", "title: Specify Sampler options\n", "description: Specify options when building with the Sampler primitive.\n", "---\n", "\n", "# Specify Sampler options\n", "\n" ] }, { "cell_type": "markdown", "id": "3adc856a-0fcd-47e4-94d9-22b90bddc24f", "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", " \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.4.0\n", " qiskit-ibm-runtime~=0.46.1\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "56db929d-8b84-49b2-a98b-55d33f91ea30", "metadata": {}, "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", "\n", "## Set Sampler options\n", "\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", "Additionally, you can set the `shots` value in the `run()` method, as is described in the following section.\n", "\n" ] }, { "cell_type": "markdown", "id": "3ca44016-acfe-4540-ab0e-659b9577c4eb", "metadata": {}, "source": [ "\n", "\n", "### Run() method\n", "\n", "The only values you can pass to `run()` are those defined in the interface. That is, `shots`. This overwrites any value set for `default_shots` for the current run.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "c2423fcc-7f7f-4674-af6f-fc90f4b28b17", "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 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)" ] }, { "cell_type": "markdown", "id": "4bf67f60-ce62-4b95-b70c-b15f131be46d", "metadata": {}, "source": [ "### Special cases\n", "\n" ] }, { "cell_type": "markdown", "id": "857e40a1-de1d-46f0-9db8-db55a6954f47", "metadata": {}, "source": [ "\n", "\n", "#### Shots\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", "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 `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 `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", "Example:\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "e06376f4-fcba-4d03-8cbc-c53ca02d81af", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 2, "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 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": "29451d36-d88d-4726-96d2-f3083ac9e4a9", "metadata": {}, "source": [ "\n", "\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", " 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-sampler-options#default_shots)\n", " \n", "\n", " \n", " Control dynamical decoupling error mitigation settings.\n", "\n", " [`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling)\n", "\n", " \n", " \n", " **Choices**: `True`, `False`\n", "\n", " **Default**: `False`\n", " \n", "\n", " \n", " **Choices**: `middle`, `edges`\n", "\n", " **Default**: `middle`\n", " \n", "\n", " \n", " Choices: `asap`, `alap`\n", " Default: `alap`\n", " \n", "\n", " \n", " Choices: `XX`, `XpXm`, `XY4`\n", " Default: `XX`\n", " \n", "\n", " \n", " Choices: `True`, `False`\n", " Default: `False`\n", " \n", " \n", " \n", "\n", " \n", " [`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment)\n", "\n", " \n", " \n", " List of tags.\n", "\n", " **Choices**: None\n", "\n", " **Default**: None\n", " \n", "\n", " \n", " **Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", "\n", " **Default**: WARNING\n", " \n", "\n", " \n", " **Choices**: `True`, `False`\n", "\n", " **Default**: `False`\n", " \n", " \n", " \n", "\n", " \n", " [`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution)\n", "\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", " 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", " **Choices**: `classified`, `kerneled`, `avg_kerneled`\n", "\n", " **Default**: `classified`\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", " [`max_execution_time` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#max_execution_time)\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", " **Choices**: List of directed two-qubit interactions\n", "\n", " **Default**: None, which implies no connectivity constraints (full connectivity).\n", " \n", "\n", " \n", " **Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation\n", "\n", " **Default**: None\n", " \n", "\n", " \n", " **Choices**: Integer\n", "\n", " **Default**: None\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", " **Choices**: True, False\n", "\n", " **Default**: False\n", " \n", "\n", " \n", " **Choices**: `auto`, Integer >= 1\n", "\n", " **Default**: `auto`\n", " \n", "\n", " \n", " **Choices**: `auto`, Integer >= 1\n", "\n", " **Default**: `auto`\n", " \n", "\n", " \n", " **Choices**: `active`, `active-circuit`, `active-accum`, `all`\n", "\n", " **Default**: `active-accum`\n", " \n", " \n", " \n", "\n", " \n", " Experimental options, when available.\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "80737dfd-a1c7-4b5f-b1ea-3391dcfa61b7", "metadata": {}, "source": [ "\n", "\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", " Incompatible with:\n", "\n", " * Dynamical decoupling\n", "\n", " Other notes:\n", "\n", " * Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks. Measurement twirling can only be applied to terminal measurements.\n", " * Compatible with fractional gates when using `qiskit-ibm-runtime` v0.42.0 or later.\n", " \n", "\n", " \n", " Incompatible with:\n", "\n", " * Dynamic circuits\n", " \n", "\n", " \n", " Incompatible with:\n", "\n", " * Gate twirling\n", "\n", " Compatible with dynamic circuits when using `qiskit-ibm-runtime` v0.42.0 or later.\n", " \n", "\n", " \n", " Incompatible with:\n", "\n", " * Fractional gates\n", " * Stretches\n", "\n", " Other notes:\n", "\n", " * Gate twirling can be applied to dynamic circuits, but only to gates not inside conditional blocks.\n", " * Measurement twirling can only be applied to terminal measurements.\n", " * Measurement twirling is incompatible with the [`store`](/docs/api/qiskit/circuit#store) instruction.\n", " * Does not work with non-Clifford entanglers.\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "b95e9e8e-575c-411e-8504-4ef0a00166d3", "metadata": {}, "source": [ "## Next steps\n", "\n", "\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", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "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 }