diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index 7a22016faa2..c9d909020b3 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -1043,7 +1043,7 @@ The qiskit-ibm-runtime `v0.41.0` release focuses on the removal of IBM Quantum P `qiskit_ibm_runtime.RuntimeJob.program_id()` is deprecated and will be replaced by `qiskit_ibm_runtime.RuntimeJob.primitive_id()`. ([1238](https://github.com/Qiskit/qiskit-ibm-runtime/pull/1238)) -* The `backend` argument in [Sampler](/docs/guides/get-started-with-primitives#3-initialize-the-qiskit-runtime-sampler) and [Estimator](/docs/guides/get-started-with-primitives#3-initialize-qiskit-runtime-estimator) has been deprecated. Please use `mode` instead. The `session` argument in [Sampler](/docs/guides/get-started-with-primitives#3-initialize-the-qiskit-runtime-sampler) and [Estimator](/docs/guides/get-started-with-primitives#3-initialize-qiskit-runtime-estimator) has also been deprecated. Please use `mode` instead. ([1556](https://github.com/Qiskit/qiskit-ibm-runtime/pull/1556)) +* The `backend` argument in [Sampler](/docs/guides/get-started-with-sampler) and [Estimator](/docs/guides/get-started-with-estimator) has been deprecated. Please use `mode` instead. The `session` argument in [Sampler](/docs/guides/get-started-with-sampler) and [Estimator](/docs/guides/get-started-with-estimator) has also been deprecated. Please use `mode` instead. ([1556](https://github.com/Qiskit/qiskit-ibm-runtime/pull/1556)) * `qiskit_ibm_runtime.QiskitRuntimeService.get_backend()` is deprecated. Please [`qiskit_ibm_runtime.QiskitRuntimeService.backend()`](qiskit-runtime-service#backend "qiskit_ibm_runtime.QiskitRuntimeService.backend") use instead. The V1 fake backends, `FakeBackend`, along with `FakeProvider` are also being deprecated in favor of the V2 fake backends and [`FakeProviderForBackendV2`](fake-provider-fake-provider-for-backend-v2 "qiskit_ibm_runtime.fake_provider.FakeProviderForBackendV2"). ([1689](https://github.com/Qiskit/qiskit-ibm-runtime/pull/1689)) @@ -1182,7 +1182,7 @@ The qiskit-ibm-runtime `v0.41.0` release focuses on the removal of IBM Quantum P ### Upgrade Notes -* Circuits that do not match the target hardware definition are no longer supported by Qiskit Runtime primitives, unless `channel_strategy="q-ctrl"` is used. See the transpilation documentation ([transpile](/docs/guides/transpile)) for instructions to transform circuits and the primitive examples ([run/primitives-examples](/docs/guides/primitives-examples)) to see this coupled with operator transformations. +* Circuits that do not match the target hardware definition are no longer supported by Qiskit Runtime primitives, unless `channel_strategy="q-ctrl"` is used. See the transpilation documentation ([transpile](/docs/guides/transpile)) for instructions to transform circuits and the primitive examples ([run/primitives-examples](/docs/guides/estimator-examples)) to see this coupled with operator transformations. @@ -1226,7 +1226,7 @@ The qiskit-ibm-runtime `v0.41.0` release focuses on the removal of IBM Quantum P ### Deprecation Notes -* Circuits that do not match the target hardware definition will no longer be supported after March 1, 2024. See the transpilation documentation ([transpile](/docs/guides/transpile)) for instructions to transform circuits and the primitive examples ([run/primitives-examples](/docs/guides/primitives-examples)) to see this coupled with operator transformations. +* Circuits that do not match the target hardware definition will no longer be supported after March 1, 2024. See the transpilation documentation ([transpile](/docs/guides/transpile)) for instructions to transform circuits and the primitive examples ([run/primitives-examples](/docs/guides/estimator-examples)) to see this coupled with operator transformations. diff --git a/docs/guides/DAG-representation.ipynb b/docs/guides/DAG-representation.ipynb index 59f97daf8b3..db2f14ace57 100644 --- a/docs/guides/DAG-representation.ipynb +++ b/docs/guides/DAG-representation.ipynb @@ -465,8 +465,8 @@ "## Next steps\n", "\n", "\n", - " - Review the guide on creating a [custom transpiler pass](./custom-transpiler-pass)\n", - " - Learn how to [Create and transpile against custom backends](./custom-backend)\n", + " - Review the guide on creating a [custom transpiler pass](/docs/guides/custom-transpiler-pass)\n", + " - Learn how to [Create and transpile against custom backends](/docs/guides/custom-backend)\n", " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n", " - Review the [DAG Circuit API documentation](/docs/api/qiskit/dagcircuit).\n", "" diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 32cbe7355dd..179721b07a7 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -226,6 +226,10 @@ "title": "Primitive inputs and outputs", "url": "/docs/guides/primitive-input-output" }, + { + "title": "Get started with the backend primitives", + "url": "/docs/guides/get-started-with-backend-primitives" + }, { "title": "Exact simulation with Qiskit SDK primitives", "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" @@ -246,6 +250,10 @@ "title": "Exact and noisy simulation with Qiskit Aer primitives", "url": "/docs/guides/simulate-with-qiskit-aer" }, + { + "title": "Exact simulation with Qiskit SDK primitives", + "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" + }, { "title": "Build noise models", "url": "/docs/guides/build-noise-models" @@ -483,51 +491,106 @@ } ] }, - { - "title": "Execute with primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/qiskit-runtime-primitives" - }, - { - "title": "Get started with primitives", - "url": "/docs/guides/get-started-with-primitives" - }, - { - "title": "Primitives examples", - "url": "/docs/guides/primitives-examples" - }, - { - "title": "Primitives with REST API", - "url": "/docs/guides/primitives-rest-api" - }, - { - "title": "Directed execution model (beta)", - "url": "/docs/guides/directed-execution-model" - }, - { - "title": "Introduction to options", - "url": "/docs/guides/runtime-options-overview" - }, - { - "title": "Specify options", - "url": "/docs/guides/specify-runtime-options" - }, - { - "title": "Local verification", - "children": [ - { - "title": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - }, - { - "title": "Debug Qiskit Runtime jobs", - "url": "/docs/guides/debug-qiskit-runtime-jobs" - } ] - } - ] - }, + { + "title": "Execute with primitives", + "children": [ + { + "title": "Introduction to primitives", + "url": "/docs/guides/qiskit-runtime-primitives" + }, + { + "title": "Directed execution model (beta)", + "url": "/docs/guides/directed-execution-model" + }, + { + "title": "Introduction to options", + "url": "/docs/guides/runtime-options-overview" + }, + { + "title": "Estimator", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-estimator" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/estimator-input-output" + }, + { + "title": "Options", + "url": "/docs/guides/estimator-options" + }, + { + "title": "Configure noise management", + "url": "/docs/guides/estimator-noise-management" + }, + { + "title": "Examples", + "url": "/docs/guides/estimator-examples" + }, + { + "title": "REST API", + "url": "/docs/guides/estimator-rest-api" + } + ] + }, + { + "title": "Sampler", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-sampler" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/sampler-input-output" + }, + { + "title": "Options", + "url": "/docs/guides/sampler-options" + }, + { + "title": "Configure noise management", + "url": "/docs/guides/sampler-noise-management" + }, + { + "title": "Examples", + "url": "/docs/guides/sampler-examples" + }, + { + "title": "REST API", + "url": "/docs/guides/sampler-rest-api" + } + ] + }, + { + "title": "Manage noise", + "children": [ + { + "title": "Overview of noise management techniques", + "url": "/docs/guides/error-mitigation-overview" + }, + { + "title": "Error mitigation and suppression", + "url": "/docs/guides/error-mitigation-and-suppression-techniques" + }, + { + "title": "Noise learning", + "url": "/docs/guides/noise-learning" + } + ] + }, + { + "title": "Debug Qiskit Runtime jobs", + "url": "/docs/guides/debug-qiskit-runtime-jobs" + }, + { + "title": "Qiskit Runtime local testing mode", + "url": "/docs/guides/local-testing-mode" + } + ] + }, { "title": "Advanced execution features", "children": [ @@ -556,6 +619,10 @@ "title": "View backend details", "url": "/docs/guides/qpu-information" }, + { + "title": "Get backend information with Qiskit", + "url": "/docs/guides/get-qpu-information" + }, { "title": "Monitoring, calibrations, and benchmarking", "url": "/docs/guides/calibration-jobs" @@ -578,31 +645,6 @@ } ] }, - { - "title": "Manage noise", - "children": [ - { - "title": "Overview of noise management techniques", - "url": "/docs/guides/error-mitigation-overview" - }, - { - "title": "Error mitigation and suppression", - "url": "/docs/guides/error-mitigation-and-suppression-techniques" - }, - { - "title": "Noise learning", - "url": "/docs/guides/noise-learning" - }, - { - "title": "Configure error mitigation", - "url": "/docs/guides/configure-error-mitigation" - }, - { - "title": "Configure error suppression", - "url": "/docs/guides/configure-error-suppression" - } - ] - }, { "title": "Manage workload execution", "children": [ diff --git a/docs/guides/ai-transpiler-passes.ipynb b/docs/guides/ai-transpiler-passes.ipynb index 331f7f78f1a..c49df68d424 100644 --- a/docs/guides/ai-transpiler-passes.ipynb +++ b/docs/guides/ai-transpiler-passes.ipynb @@ -235,11 +235,11 @@ "\n", "## Limits\n", "\n", - "Refer to the [Qiskit Transpiler Service documentation](./qiskit-transpiler-service#limits-of-the-qiskit-transpiler-service) for more information about the limits that apply to the AI-powered transpiler passes.\n", + "Refer to the [Qiskit Transpiler Service documentation](/docs/guides/qiskit-transpiler-service#limits-of-the-qiskit-transpiler-service) for more information about the limits that apply to the AI-powered transpiler passes.\n", "\n", "## Citation\n", "\n", - "If you use any AI-powered feature from the Qiskit Transpiler Service in your research, use [the recommended citation](./qiskit-transpiler-service#citation)." + "If you use any AI-powered feature from the Qiskit Transpiler Service in your research, use [the recommended citation](/docs/guides/qiskit-transpiler-service#citation)." ] } ], diff --git a/docs/guides/build-noise-models.ipynb b/docs/guides/build-noise-models.ipynb index 3b786912b0c..ba66b9a20ce 100644 --- a/docs/guides/build-noise-models.ipynb +++ b/docs/guides/build-noise-models.ipynb @@ -596,7 +596,7 @@ "source": [ "### Note on non-local qubit quantum error\n", "\n", - "`NoiseModel` does not support addition of non-local qubit quantum errors. They should be handled outside of `NoiseModel`. That suggests you should [write your own transpiler pass](./custom-transpiler-pass) (`TransformationPass`) and run the pass just before running the simulator if you need to insert your quantum errors into your circuit under your own conditions." + "`NoiseModel` does not support addition of non-local qubit quantum errors. They should be handled outside of `NoiseModel`. That suggests you should [write your own transpiler pass](/docs/guides/custom-transpiler-pass) (`TransformationPass`) and run the pass just before running the simulator if you need to insert your quantum errors into your circuit under your own conditions." ] }, { @@ -978,7 +978,7 @@ "## Next steps\n", "\n", "\n", - " - To simulate noisy circuits, see [Exact and noisy simulation with Qiskit Aer primitives](./simulate-with-qiskit-sdk-primitives).\n", + " - To simulate noisy circuits, see [Exact and noisy simulation with Qiskit Aer primitives](/docs/guides/simulate-with-qiskit-sdk-primitives).\n", " - Review the [Qiskit Aer noise module](https://qiskit.org/ecosystem/aer/apidocs/aer_noise.html) reference.\n", "" ] diff --git a/docs/guides/circuit-library.ipynb b/docs/guides/circuit-library.ipynb index 05bde9e8ae9..93715e78f85 100644 --- a/docs/guides/circuit-library.ipynb +++ b/docs/guides/circuit-library.ipynb @@ -492,7 +492,7 @@ "## Next steps\n", "\n", "\n", - " - Learn advanced methods for creating circuits in the [Construct circuits](./construct-circuits) topic.\n", + " - Learn advanced methods for creating circuits in the [Construct circuits](/docs/guides/construct-circuits) topic.\n", " - See an example of circuits being used in the [Grover's Algorithm](/docs/tutorials/grovers-algorithm) tutorial.\n", " - Review the [circuit library API](/docs/api/qiskit/circuit_library) reference.\n", "" diff --git a/docs/guides/cloud-setup-invited.mdx b/docs/guides/cloud-setup-invited.mdx index 5a43a944968..f16118ed201 100644 --- a/docs/guides/cloud-setup-invited.mdx +++ b/docs/guides/cloud-setup-invited.mdx @@ -12,7 +12,7 @@ If you do not have an invitation from an administrator to join an account that a You can run workloads on IBM® quantum processing units (QPUs) by setting up an account on IBM Cloud®. You will also need to [install and set up Qiskit and Qiskit Runtime](/docs/guides/install-qiskit#local). -Your user account is associated with one or more [instances](./instances), identified by _Cloud Resource Names_ (CRNs) that give access to IBM Quantum services. Additionally, a unique API token (also called a key) is assigned to each account, allowing for IBM Quantum access from Qiskit. For instructions to choose a specific instance, see [Connect to an instance](./instances#connect-instance). +Your user account is associated with one or more [instances](/docs/guides/instances), identified by _Cloud Resource Names_ (CRNs) that give access to IBM Quantum services. Additionally, a unique API token (also called a key) is assigned to each account, allowing for IBM Quantum access from Qiskit. For instructions to choose a specific instance, see [Connect to an instance](/docs/guides/instances#connect-instance). The [IBM Quantum Platform dashboard](https://quantum.cloud.ibm.com) and the [Instances page](https://quantum.cloud.ibm.com/instances) list the instances that you can access. diff --git a/docs/guides/compute-services.mdx b/docs/guides/compute-services.mdx index 4944db1b497..b6ee6b80417 100644 --- a/docs/guides/compute-services.mdx +++ b/docs/guides/compute-services.mdx @@ -8,9 +8,9 @@ In addition to the open-source tools of the Qiskit SDK, Qiskit addons, and other ## Qiskit Runtime -Qiskit Runtime is the cloud-based service for executing quantum computations on IBM Quantum hardware. The `qiskit-ibm-runtime` package is a client for that service, and is the successor to the Qiskit IBM Provider. The Qiskit Runtime service streamlines quantum computations and provides optimal implementations of Qiskit primitives for IBM Quantum hardware. To get started with primitives, visit the [documentation](/docs/guides/get-started-with-primitives). +Qiskit Runtime is the cloud-based service for executing quantum computations on IBM Quantum hardware. The `qiskit-ibm-runtime` package is a client for that service, and is the successor to the Qiskit IBM Provider. The Qiskit Runtime service streamlines quantum computations and provides optimal implementations of Qiskit primitives for IBM Quantum hardware. To get started with primitives, visit the [documentation](/docs/guides/primitives). -Qiskit Runtime is designed to use additional classical and quantum compute resources, including techniques such as error suppression and error mitigation, to return a higher-quality result from executing quantum circuits on quantum processors. Examples include dynamical decoupling for error suppression, and readout mitigation and zero-noise extrapolation (ZNE) for error mitigation. Learn how to configure these options on the [Configure error mitigation](/docs/guides/configure-error-mitigation) page. +Qiskit Runtime is designed to use additional classical and quantum compute resources, including techniques such as error suppression and error mitigation, to return a higher-quality result from executing quantum circuits on quantum processors. Examples include dynamical decoupling for error suppression, and readout mitigation and zero-noise extrapolation (ZNE) for error mitigation. Learn how to configure these options on the [Configure error mitigation](/docs/guides/error-mitigation-and-suppression-techniques) page. Qiskit Runtime also includes three types of execution modes for running your quantum program on IBM® hardware: [Job, Session, and Batch](/docs/guides/execution-modes), each of which have different use cases and implications for the quantum job queue. A Job is a single query to a primitive that can be run over a specified number of shots. Sessions allow you to efficiently run multiple jobs in iterative workloads on quantum computers. Batch mode allows you to submit all your jobs at once for parallel processing. Note that Open Plan users cannot submit session jobs. diff --git a/docs/guides/configure-error-mitigation.ipynb b/docs/guides/configure-error-mitigation.ipynb deleted file mode 100644 index 918ec0d93c9..00000000000 --- a/docs/guides/configure-error-mitigation.ipynb +++ /dev/null @@ -1,284 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "d59934c8-76a1-4eda-97ba-4fcfb6f15776", - "metadata": {}, - "source": [ - "---\n", - "title: Configure error mitigation\n", - "description: How to configure error mitigation with Qiskit Runtime.\n", - "---\n", - "\n", - "\n", - "# Configure error mitigation" - ] - }, - { - "cell_type": "markdown", - "id": "a13a7861", - "metadata": {}, - "source": [ - "\n", - "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "8f3a25e1-b73d-48d1-8b82-9c57095c9108", - "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", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "3f1ea669-4144-4071-a4e9-88e01056f465", - "metadata": {}, - "source": [ - "Error mitigation techniques allow users to mitigate circuit errors by\n", - "modeling the device noise at the time of execution. This typically\n", - "results in quantum pre-processing overhead related to model training and\n", - "classical post-processing overhead to mitigate errors in the raw results\n", - "by using the generated model.\n", - "\n", - "The Estimator primitive supports several error mitigation techniques, including [TREX](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#measure_mitigation), [ZNE](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#zne), [PEC](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#pec), and [PEA](/docs/api/qiskit-ibm-runtime/options-zne-options). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. When using primitives, you can turn on or off individual methods. See the [Custom error settings](#advanced-error) section for details.\n", - "\n", - "\n", - "\n", - "Sampler does not support error mitigation, but you can use the [mthree](https://qiskit.github.io/qiskit-addon-mthree/) (matrix-free measurement mitigation) package to perform error mitigation locally.\n", - "\n", - "\n", - "\n", - "Estimator also supports `resilience_level`. The resilience level specifies how much resilience to build against\n", - "errors. Higher levels generate more accurate results, at the expense of\n", - "longer processing times. Resilience levels can be used to configure the\n", - "cost/accuracy trade-off when applying error mitigation to your primitive\n", - "query. Error mitigation reduces errors (bias) in results by processing\n", - "the outputs from a collection, or ensemble, of related circuits. The\n", - "degree of error reduction depends on the method applied. The resilience\n", - "level abstracts the detailed choice of error mitigation method to allow\n", - "users to reason about the cost/accuracy trade that is appropriate to\n", - "their application.\n", - "\n", - "Given this, each level corresponds to a method or methods with\n", - "increasing level of quantum sampling overhead to enable you experiment\n", - "with different time-accuracy tradeoffs. The following table shows you\n", - "which levels and corresponding methods are available for each of the\n", - "primitives.\n", - "\n", - "\n", - "Error mitigation is task-specific, so the techniques you can\n", - "apply vary based whether you are sampling a distribution or generating\n", - "expectation values.\n", - "\n", - "\n", - "\n", - "\n", - "Estimator supports the following resilience levels. Sampler does not support resilience levels.\n", - "\n", - "| Resilience Level | Definition | Technique |\n", - "|------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|\n", - "| 0 | No mitigation | None |\n", - "| 1 [Default] | Minimal mitigation costs: Mitigate error associated with readout errors | Twirled Readout Error eXtinction (TREX) measurement twirling |\n", - "| 2 | Medium mitigation costs. Typically reduces bias in estimators, but is not guaranteed to be zero-bias. | Level 1 + Zero Noise Extrapolation (ZNE) and gate twirling\n", - "\n", - "\n", - "\n", - "\n", - "Resilience levels are currently in beta so sampling overhead and\n", - "solution quality will vary from circuit to circuit. New features,\n", - "advanced options, and management tools will be released on a rolling\n", - "basis. Specific error mitigation methods are not guaranteed to be\n", - "applied at each resilience level.\n", - "\n", - "\n", - "## Configure Estimator with resilience levels\n", - "\n", - "You can use resilience levels to specify error mitigation techniques, or you can set custom techniques individually as described in [Custom error settings](#advanced-error).\n", - "\n", - "\n", - "\n", - "\n", - "No error mitigation is applied to the user program.\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "Level 1 applies **readout error mitigation** and **measurement twirling** by applying a model-free technique known\n", - "as Twirled Readout Error eXtinction (TREX). It reduces measurement error\n", - "by diagonalizing the noise channel associated with measurement by\n", - "randomly flipping qubits through X gates immediately before measurement. A\n", - "rescaling term from the diagonal noise channel is learned by\n", - "benchmarking random circuits initialized in the zero state. This allows\n", - "the service to remove bias from expectation values that result from\n", - "readout noise. This approach is described further in [Model-free\n", - "readout-error mitigation for quantum expectation\n", - "values](https://arxiv.org/abs/2012.09738).\n", - "\n", - " \n", - "\n", - "\n", - "Level 2 applies the **error mitigation techniques included in level 1** and also applies **gate twirling** and uses the **Zero Noise Extrapolation method (ZNE)**. ZNE computes an\n", - "expectation value of the observable for different noise factors\n", - "(amplification stage) and then uses the measured expectation values to\n", - "infer the ideal expectation value at the zero-noise limit (extrapolation\n", - "stage). This approach tends to reduce errors in expectation values, but\n", - "is not guaranteed to produce an unbiased result.\n", - "\n", - "\n", - "![This image shows a graph. The x-axis is labeled Noise amplification factor. The y-axis is labeled Expectation value. An upward sloping line is labeled Mitigated value. Points near the line are noise-amplified values. There is a horizontal line just above the X-axis labeled Exact value.](/docs/images/guides/configure-error-mitigation/resilience-2.svg \"Illustration of the ZNE method\")\n", - "\n", - "The overhead of this method scales with the number of noise factors. The\n", - "default settings sample the expectation value at three noise factors,\n", - "leading to a roughly 3x overhead when employing this resilience level.\n", - "\n", - "In Level 2, the TREX method randomly flips qubits through X gates immediately before measurement,\n", - "and flips the corresponding measured bit if an X gate was applied. This approach is described further in [Model-free\n", - "readout-error mitigation for quantum expectation\n", - "values](https://arxiv.org/abs/2012.09738).\n", - "\n", - " \n", - "\n", - "\n", - "### Example\n", - "\n", - "The `EstimatorV2` interface lets users seamlessly work with the variety of\n", - "error mitigation methods to reduce error in expectation values of\n", - "observables. The following code uses Zero Noise Extrapolation and readout error mitigation by simply\n", - "setting `resilience_level 2`." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "841b526d-55b8-4125-bd2c-758d9db8dbb3", - "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(backend, options={\"resilience_level\": 2})" - ] - }, - { - "cell_type": "markdown", - "id": "c497a0e5-bcb7-4954-8096-70b4514ea498", - "metadata": {}, - "source": [ - "\n", - "## Custom error settings\n", - "\n", - "You can turn on and off individual error mitigation and suppression methods, including dynamical decoupling, gate and measurement twirling, measurement error mitigation, PEC, and ZNE. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each.\n", - "\n", - "\n", - "- Not all options are available for both primitives. See the [available options table](runtime-options-overview#options-table) for the list of available options.\n", - "- Not all methods work together on all types of circuits. See the [feature compatibility table](runtime-options-overview#options-compatibility-table) for details.\n", - "\n", - "\n", - "\n", - " \n", - " ```python\n", - "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(backend)\n", - "options = estimator.options\n", - "# Turn on gate twirling.\n", - "options.twirling.enable_gates = True\n", - "# Turn on measurement error mitigation.\n", - "options.resilience.measure_mitigation = True\n", - "\n", - "print(f\">>> gate twirling is turned on: {estimator.options.twirling.enable_gates}\")\n", - "print(f\">>> measurement error mitigation is turned on: {estimator.options.resilience.measure_mitigation}\")\n", - "```\n", - " \n", - "\n", - " \n", - "```python\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", - "\n", - "# Estimator and Sampler have different options\n", - "sampler = Sampler(backend)\n", - "options = sampler.options\n", - "\n", - "options.dynamical_decoupling.enable = True\n", - "# Turn on gate twirling. Requires qiskit_ibm_runtime 0.23.0 or later.\n", - "options.twirling.enable_gates = True\n", - "\n", - "print(f\">>> dynamical decoupling is turned on: {sampler.options.dynamical_decoupling.enable}\")\n", - "print(f\">>> gate twirling is turned on: {sampler.options.twirling.enable_gates}\")\n", - "\n", - "```\n", - " \n", - "\n", - "\n", - "## Turn off all error mitigation\n", - "\n", - "For instructions to turn off all error mitigation, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section.\n", - "\n", - "## Next steps\n", - "\n", - "\n", - " - Walk through an example that uses error mitigation in the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", - " - Learn more about [error mitigation and error suppression techniques](error-mitigation-and-suppression-techniques).\n", - " - [Configure error suppression](configure-error-suppression).\n", - " - Explore other [options](runtime-options-overview).\n", - " - Decide what [execution mode](execution-modes) to run your job in.\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/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb deleted file mode 100644 index 04c68e84e4b..00000000000 --- a/docs/guides/configure-error-suppression.ipynb +++ /dev/null @@ -1,158 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "aa4fa466-c51d-42b4-8cc5-4870b03b0a4d", - "metadata": {}, - "source": [ - "---\n", - "title: Configure error suppression\n", - "description: How to configure error suppression in Qiskit Runtime. (Former title - Runtime compilation)\n", - "---\n", - "\n", - "\n", - "# Configure error suppression" - ] - }, - { - "cell_type": "markdown", - "id": "a564e884", - "metadata": {}, - "source": [ - "\n", - "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "053b2221-0541-4867-b258-070f0a3e043f", - "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", - "\n", - "The code on this page was developed using the following requirements.\n", - "We recommend using these versions or newer.\n", - "\n", - "```\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "3f005a97-45db-4442-ab0c-ca6c986d54f8", - "metadata": {}, - "source": [ - "Error suppression refers to techniques where you use knowledge about the undesirable effects to introduce customization that can anticipate and avoid the potential impacts of those effects. These techniques often consist of altering or adding control signals to ensure that the quantum processor returns the desired results. This typically results in quantum pre-processing overhead; therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.\n", - "\n", - "Primitives support a number of error suppression techniques, including [dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options#dynamicaldecouplingoptions) and [Pauli twirling](/docs/api/qiskit-ibm-runtime/options-twirling-options). See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. When using primitives, you can turn on or off individual methods. See the [Advanced error suppression options](#transpilation-table) section for details.\n", - "\n", - "Estimator employs error suppression and mitigation by default. If you don't want any processing done to your input circuits, follow the instructions in the [Turn off all error mitigation and error suppression](specify-runtime-options#no-error-mitigation) section.\n", - "\n", - "\n", - "## Advanced error suppression options\n", - "\n", - "In the primitives, you can explicitly enable and disable individual error mitigation and suppression methods, such as dynamical decoupling.\n", - "\n", - "\n", - "- Not all options are available for both primitives. See the [available options](runtime-options-overview#options-table) table for the list of available options.\n", - "- Not all methods work together on all types of circuits. See the [feature compatibility](runtime-options-overview#options-compatibility-table) table for details.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "149509bf-86ff-4bf5-8b20-662e2e85b769", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> dynamical decoupling sequence to use: XpXm\n" - ] - } - ], - "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(backend)\n", - "\n", - "# Turn on dynamical decoupling with sequence XpXm.\n", - "sampler.options.dynamical_decoupling.enable = True\n", - "sampler.options.dynamical_decoupling.sequence_type = \"XpXm\"\n", - "\n", - "print(\n", - " f\">>> dynamical decoupling sequence to use: {sampler.options.dynamical_decoupling.sequence_type}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "b53daba1-f54d-4063-bf42-3304ab1fdb60", - "metadata": {}, - "source": [ - "\n", - "\n", - "## Turn off all error suppression\n", - "\n", - "For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](specify-runtime-options#no-error-mitigation) section.\n", - "\n", - "## Next steps\n", - "\n", - "\n", - " - Learn more about [error mitigation and error suppression techniques](error-mitigation-and-suppression-techniques).\n", - " - [Configure error mitigation](configure-error-mitigation).\n", - " - Explore other [options](runtime-options-overview).\n", - " - Decide what [execution mode](execution-modes) to run your job in.\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/construct-circuits.ipynb b/docs/guides/construct-circuits.ipynb index 62c1a2e2c12..867672eab48 100644 --- a/docs/guides/construct-circuits.ipynb +++ b/docs/guides/construct-circuits.ipynb @@ -190,7 +190,7 @@ "id": "17a82d8a-b717-44b8-b3f8-ce89e2588261", "metadata": {}, "source": [ - "The easiest way to view this information is through the [`draw`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw) method, which returns a visualization of a circuit. See [Visualize circuits](./visualize-circuits) for different ways of displaying quantum circuits." + "The easiest way to view this information is through the [`draw`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw) method, which returns a visualization of a circuit. See [Visualize circuits](/docs/guides/visualize-circuits) for different ways of displaying quantum circuits." ] }, { @@ -451,10 +451,10 @@ "\n", "## Measure qubits\n", "\n", - "Measurements are used to sample the states of individual qubits and transfer the results to a classical register. Note that if you are submitting circuits to a Sampler [primitive](/docs/guides/primitives), measurements are required. However, if circuits submitted to an Estimator primitive contain measurements, the measurements are ignored.\n", + "Measurements are used to sample the states of individual qubits and transfer the results to a classical register. Note that if you are submitting circuits to a [Sampler](/docs/guides/get-started-with-sampler) primitive, measurements are required. However, circuits submitted to an [Estimator](/docs/guides/get-started-with-estimator) primitive must not contain measurements.\n", "\n", "\n", - "Qubits can be measured using three methods: [`measure`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qiskit.circuit.QuantumCircuit.measure), [`measure_all`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) and [`measure_active`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active). To learn how to visualize measured results, see the [Visualize results](./visualize-results) page.\n", + "Qubits can be measured using three methods: [`measure`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qiskit.circuit.QuantumCircuit.measure), [`measure_all`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) and [`measure_active`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active). To learn how to visualize measured results, see the [Visualize results](/docs/guides/visualize-results) page.\n", "\n", "1. `QuantumCircuit.measure` : measures each qubit in the first argument onto the classical bit given as the second argument. This method allows full control over where the measurement result is stored.\n", "\n", diff --git a/docs/guides/custom-transpiler-pass.ipynb b/docs/guides/custom-transpiler-pass.ipynb index 9219aa8091d..64083829654 100644 --- a/docs/guides/custom-transpiler-pass.ipynb +++ b/docs/guides/custom-transpiler-pass.ipynb @@ -103,7 +103,7 @@ "source": [ "## Transpiler passes\n", "\n", - "Transpiler passes are classified either as an [`AnalysisPass`](../api/qiskit/qiskit.transpiler.AnalysisPass) or a [`TransformationPass`](../api/qiskit/qiskit.transpiler.TransformationPass). Passes in general work with the [DAG](../api/qiskit/qiskit.dagcircuit.DAGCircuit) and the `property_set`, a dictionary-like object for storing properties determined by analysis passes. Analysis passes work with both the DAG and its `property_set`. They cannot modify the DAG, but can modify the `property_set`. This contrasts with transformation passes, which do modify the DAG, and can read (but not write to) `property_set`. For example, transformation passes translate a circuit to its [ISA](./transpile#instruction-set-architecture) or perform routing passes to insert SWAP gates where needed." + "Transpiler passes are classified either as an [`AnalysisPass`](../api/qiskit/qiskit.transpiler.AnalysisPass) or a [`TransformationPass`](../api/qiskit/qiskit.transpiler.TransformationPass). Passes in general work with the [DAG](../api/qiskit/qiskit.dagcircuit.DAGCircuit) and the `property_set`, a dictionary-like object for storing properties determined by analysis passes. Analysis passes work with both the DAG and its `property_set`. They cannot modify the DAG, but can modify the `property_set`. This contrasts with transformation passes, which do modify the DAG, and can read (but not write to) `property_set`. For example, transformation passes translate a circuit to its [ISA](/docs/guides/transpile#instruction-set-architecture) or perform routing passes to insert SWAP gates where needed." ] }, { diff --git a/docs/guides/debugging-tools.mdx b/docs/guides/debugging-tools.mdx index a6e422478b6..690ed19cad1 100644 --- a/docs/guides/debugging-tools.mdx +++ b/docs/guides/debugging-tools.mdx @@ -17,19 +17,19 @@ Stabilizer circuits, also known as Clifford circuits, are a useful tool for acco For general quantum circuits, the following tools are available to test and debug your quantum programs: -- For exact simulation of small quantum circuits, you can use the reference primitives included with Qiskit. See [Exact simulation with Qiskit primitives](./simulate-with-qiskit-sdk-primitives). +- For exact simulation of small quantum circuits, you can use the reference primitives included with Qiskit. See [Exact simulation with Qiskit primitives](/docs/guides/simulate-with-qiskit-sdk-primitives). - For higher-performance simulation that can handle larger circuits, or to incorporate noise models into your simulation, use [Qiskit Aer](https://qiskit.org/ecosystem/aer/), a project that is part of the [Qiskit Ecosystem](https://qiskit.github.io/ecosystem/). See [Exact and noisy simulation with Qiskit Aer primitives](simulate-with-qiskit-aer). -- To build custom noise models, use the [`noise`](https://qiskit.org/ecosystem/aer/apidocs/aer_noise.html) module of Qiskit Aer. See [Building noise models](./build-noise-models). +- To build custom noise models, use the [`noise`](https://qiskit.org/ecosystem/aer/apidocs/aer_noise.html) module of Qiskit Aer. See [Building noise models](/docs/guides/build-noise-models). ## Hardware considerations Several factors impact how much memory quantum simulation requires, so there are no exact hardware requirements for simulation, but there are some guidelines you can follow. -- The only requirement to run Qiskit is a functioning Python environment. For details, see the [Operating system support](./install-qiskit#operating-system-support) section. +- The only requirement to run Qiskit is a functioning Python environment. For details, see the [Operating system support](/docs/guides/install-qiskit#operating-system-support) section. - Because the requirements for simulating quantum circuits scale exponentially with the number of qubits, the available hardware limits the number of qubits that can be simulated. For example, a system with 4GB RAM can simulate approximately 27 qubits. - More or less available memory will not result in more or less accurate results (assuming results are returned), although more memory might return results faster or let you simulate more qubits. -- To get the most benefit out of your hardware, use local stabilizer (Clifford) circuit simulation when possible. See [Clifford simulation with Qiskit Runtime local testing mode](local-testing-mode#clifford-simulation) or [Efficient simulation of stabilizer circuits with Qiskit Aer primitives](./simulate-stabilizer-circuits) for examples. +- To get the most benefit out of your hardware, use local stabilizer (Clifford) circuit simulation when possible. See [Clifford simulation with Qiskit Runtime local testing mode](local-testing-mode#clifford-simulation) or [Efficient simulation of stabilizer circuits with Qiskit Aer primitives](/docs/guides/simulate-stabilizer-circuits) for examples. - You can increase your computing power by following these instructions to [run with multiple GPUs, nodes, or both](https://qiskit.github.io/qiskit-aer/howtos/running_gpu.html). ## Next steps diff --git a/docs/guides/defaults-and-configuration-options.ipynb b/docs/guides/defaults-and-configuration-options.ipynb index bdb02a700d6..b315713c6af 100644 --- a/docs/guides/defaults-and-configuration-options.ipynb +++ b/docs/guides/defaults-and-configuration-options.ipynb @@ -274,8 +274,8 @@ "\n", " - Learn how to [Set the optimization level](set-optimization).\n", " - Review more [Commonly used parameters](common-parameters).\n", - " - Learn how to [Set the optimization level when using Qiskit Runtime](./runtime-options-overview).\n", - " - Visit the [Transpile with pass managers](transpile-with-pass-managers) topic.\n", + " - Learn how to [Set the optimization level when using Qiskit Runtime](/docs/guides/runtime-options-overview).\n", + " - Visit the [Transpile with pass managers](/docs/guides/transpile-with-pass-managers) topic.\n", " - For examples, see [Representing quantum computers](/docs/guides/represent-quantum-computers).\n", " - Learn [how to transpile circuits](/docs/guides/circuit-transpilation-settings) as part of the Qiskit patterns workflow using Qiskit Runtime.\n", " - Review the [Transpile API documentation](/docs/api/qiskit/transpiler).\n", diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index d3310d7f54f..784ced961f5 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -26,7 +26,7 @@ To apply error mitigation to a circuit under the framework, your workflow will t 3. Build the template circuit and samplex from the boxed circuit. -4. Run the template circuit and samplex with the [Executor](#executor-primitive) primitive, which will generate and execute the circuit variants as instructed. +4. Run the template circuit and samplex with the [Executor](#executor) primitive, which will generate and execute the circuit variants as instructed. 5. Post-process execution results. For example, you can apply post-selection, or extrapolate mitigated expectation values from the execution results. @@ -35,28 +35,23 @@ To apply error mitigation to a circuit under the framework, your workflow will t The following tools can be used together to implement an error mitigation technique in the directed execution model. + ### Samplomatic [Samplomatic](https://github.com/Qiskit/samplomatic/) is a new open-source library that supports customized sampling randomizations. It uses the [box](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#box) construct to reason about collections of circuit operations that should be treated as having a stable noise context, and uses annotations on boxes to allow you to declare and configure intents. For example, you can stratify your circuit into boxes, add a twirling annotation to each box, and specify which twirling group to use, as shown in the following figure: ![Example of using boxes and twirling annotations](/docs/images/guides/directed-execution-model/execution-model.avif) -A circuit with annotated boxes can then be used to generate a *template circuit* and a *samplex*. The output template circuit is a parameterized circuit that will be executed without further alteration (other than having different parameter values assigned to it). The samplex, which is the core type of the Samplomatic library, represents a parametric probability distribution over the parameters of the template circuit and other array-valued fields. These fields can be used to post-process data collected from executing the bound template circuit. In other words, the template circuit and samplex pair tells the Executor primitive (described below) exactly what parameters to generate and what bound circuits to run. Because these two constructs are created on the client side, you can do local inspection and sampling to verify the outputs prior to sending it for hardware execution. +A circuit with annotated boxes can then be used to generate a *template circuit* and a *samplex*. The output template circuit is a parameterized circuit that will be executed without further alteration (other than having different parameter values assigned to it). The samplex, which is the core type of the Samplomatic library, represents a parametric probability distribution over the parameters of the template circuit and other array-valued fields. These fields can be used to post-process data collected from executing the bound template circuit. In other words, the template circuit and samplex together tell the [Executor primitive](#executor) what parameters to generate and what bound circuits to run. Because these two constructs are created on the client side, you can do local inspection and sampling to verify the outputs prior to sending it for hardware execution. To simplify the process of generating annotated boxes, the Samplomatic library also provides transpiler passes that automatically group circuit instructions into annotated boxes, based on the strategies you provide. To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/samplomatic/guides/index.html) and [API reference](https://qiskit.github.io/samplomatic/) documentation. Feel free to submit feedback and report bugs in its [GitHub](https://github.com/Qiskit/samplomatic) repository. + ### Executor primitive -Executor is a new Qiskit Runtime primitive that takes the template circuit and samplex pair as the input, generates and binds parameter values according to the samplex, executes the bound circuits on the hardware, and returns the execution results and metadata. It follows the directives of the input pair and does not make any implicit decisions for you, so that the process is transparent yet performant. - -To access `Executor`, install the `executor_preview` branch from `qiskit-ibm-runtime`: - -```bash -pip install -U git+https://github.com/Qiskit/qiskit-ibm-runtime.git@executor_preview -``` -The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor API reference](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.Executor.html) for more information. In addition, the [Executor quickstart guide](https://qiskit.github.io/qiskit-ibm-runtime/guides/executor_basic.html) provides an overview and code examples. +Executor is a new Qiskit Runtime primitive that takes the (template circuit, samplex) pair as input, generates and binds parameter values according to the samplex, executes the bound circuits on the hardware, and returns the execution results and metadata. It follows the directives of the input pair and does not make any implicit decisions for you, so that the process is transparent yet performant. ### NoiseLearnerV3 diff --git a/docs/guides/error-mitigation-and-suppression-techniques.ipynb b/docs/guides/error-mitigation-and-suppression-techniques.ipynb index 154e99ccbb2..ceb8944cbdb 100644 --- a/docs/guides/error-mitigation-and-suppression-techniques.ipynb +++ b/docs/guides/error-mitigation-and-suppression-techniques.ipynb @@ -98,7 +98,7 @@ "\n", "Dynamical decoupling can be enabled by setting `enable` to `True` in the [dynamical decoupling options](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options). The `sequence_type` option can be used to pick from several different pulse sequences. The default sequence type is `\"XX\"`.\n", "\n", - "The following code cell shows how to enable dynamical decoupling for the Estimator and choose a dynamical decoupling sequence." + "The following code cell shows how to enable dynamical decoupling for Estimator and choose a dynamical decoupling sequence." ] }, { @@ -149,7 +149,7 @@ "- `num_randomizations`: The number of circuit instances to draw from the ensemble of twirled circuits.\n", "- `shots_per_randomization`: The number of shots to sample from each circuit instance.\n", "\n", - "The following code cell shows how to enable Pauli twirling and set these options for the estimator. None of these options are required to be set explicitly." + "The following code cell shows how to enable Pauli twirling and set these options for Estimator. None of these options are required to be set explicitly." ] }, { @@ -177,18 +177,24 @@ "tags": [] }, "source": [ - "## Twirled readout error extinction (TREX)\n", + "\n", + "## Twirled Readout Error eXtinction (TREX)\n", "\n", - "[Twirled readout error extinction (TREX)](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.105.032620) mitigates the effect of measurement errors for the estimation of Pauli observable expectation values.\n", - " It is based on the notion of twirled measurements, which are accomplished by randomly substituting measurement gates by a sequence of (1) a Pauli X gate, (2) a measurement, and (3) classical bit flip. Just like in standard gate twirling, this sequence is equivalent to a plain measurement in the absence of noise, as depicted in the following diagram:\n", + "[Twirled Readout Error eXtinction (TREX)](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.105.032620) mitigates the effect of measurement errors for the estimation of Pauli observable expectation values.\n", + "It is based on the notion of twirled measurements, which are accomplished by randomly substituting measurement gates by a sequence of (1) a Pauli X gate, (2) a measurement, and (3) classical bit flip. Just like in standard gate twirling, this sequence is equivalent to a plain measurement in the absence of noise, as depicted in the following diagram:\n", "\n", "![Depiction of measurement twirling](/docs/images/guides/error-mitigation-explanation/measurement_twirling.svg)\n", "\n", - "In the presence of readout error, measurement twirling has the effect of diagonalizing the readout-error transfer matrix, making it easy to invert. Estimating the readout-error transfer matrix requires executing additional calibration circuits, which introduces a small overhead.\n", + "In the presence of readout error, measurement twirling has the effect of diagonalizing the readout-error transfer matrix, making it easy to invert. A rescaling term from the diagonal noise channel is learned by\n", + "benchmarking random circuits initialized in the zero state. This allows\n", + "the service to remove bias from expectation values that result from\n", + "readout noise. Estimating the readout-error transfer matrix requires executing additional calibration circuits, which introduces a small overhead.\n", + "\n", + "### Enable ZNE by using the `measure_mitigation` option\n", "\n", "TREX can be enabled by setting `measure_mitigation` to `True` in the [Qiskit Runtime resilience options](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2) for Estimator. Options for measurement noise learning are described [here](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options). As with gate twirling, you can set the number of circuit randomizations and the number of shots per randomization.\n", "\n", - "The following code cell shows how to enable TREX and set these options for the estimator. None of these options are required to be set explicitly." + "The following code cell shows how to enable TREX and set these options for Estimator. None of these options have to be set explicitly." ] }, { @@ -204,6 +210,33 @@ "estimator.options.resilience.measure_noise_learning.shots_per_randomization = 100" ] }, + { + "cell_type": "markdown", + "id": "5a0c3f58", + "metadata": {}, + "source": [ + "### Enable TREX by using the `resilience_level` option\n", + "\n", + "You can enable TREX by setting the [resilience level](/docs/guides/estimator-noise-management#resilience) to `1`, as shown in the following example." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "de92bffd", + "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(backend, options={\"resilience_level\": 1})" + ] + }, { "attachments": {}, "cell_type": "markdown", @@ -231,13 +264,19 @@ "\n", "![Depiction of ZNE](/docs/images/guides/error-mitigation-explanation/zne.avif)\n", "\n", + "The overhead of this method scales with the number of noise factors. The\n", + "default settings sample the expectation value at three noise factors,\n", + "leading to a roughly 3x overhead.\n", + "\n", + "### Enable ZNE by using the `zne_mitigation` option\n", + "\n", "ZNE can be enabled by setting `zne_mitigation` to `True` in the [Qiskit Runtime resilience options](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2) for Estimator.\n", "The Qiskit Runtime options for ZNE are described [here](/docs/api/qiskit-ibm-runtime/options-zne-options). The following options are notable:\n", "\n", "- `noise_factors`: The noise factors to use for noise amplification.\n", "- `extrapolator`: The functional form to use for the extrapolation.\n", "\n", - "The following code cell shows how to enable ZNE and set these options for the estimator. None of these options are required to be set explicitly." + "The following code cell shows how to enable ZNE and set these options for Estimator. None of these options have to be set explicitly." ] }, { @@ -253,6 +292,33 @@ "estimator.options.resilience.zne.extrapolator = \"exponential\"" ] }, + { + "cell_type": "markdown", + "id": "600ee406", + "metadata": {}, + "source": [ + "### Enable ZNE by using the `resilience_level` option\n", + "\n", + "You can enable ZNE (along with TREX and gate twirling) by setting the [resilience level](/docs/guides/estimator-noise-management#resilience) to `2`, as shown in the following example." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7b644752", + "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(backend, options={\"resilience_level\": 2})" + ] + }, { "cell_type": "markdown", "id": "e5dcab7b", @@ -317,7 +383,7 @@ "PEC can be enabled by setting `pec_mitigation` to `True` in the [Qiskit Runtime resilience options](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2) for Estimator.\n", "The Qiskit Runtime options for PEC are described [here](/docs/api/qiskit-ibm-runtime/options-pec-options). A limit on the sampling overhead can be set using the `max_overhead` option. Note that limiting the sampling overhead can cause the precision of the result to exceed the requested precision. The default value of `max_overhead` is 100.\n", "\n", - "The following code cell shows how to enable PEC and set the `max_overhead` option for the estimator." + "The following code cell shows how to enable PEC and set the `max_overhead` option for Estimator." ] }, { @@ -340,10 +406,10 @@ "## Next steps\n", "\n", "- Check out the [tutorial](/docs/tutorials/combine-error-mitigation-techniques) on combining error mitigation options with the Estimator primitive.\n", - "- [Configure error mitigation](configure-error-mitigation).\n", - "- [Configure error suppression](configure-error-suppression).\n", - "- Explore other [options](runtime-options-overview) for the Qiskit Runtime primitives.\n", - "- Decide what [execution mode](execution-modes) to run your job in." + "- [Configure noise management with Estimator](/docs/guides/estimator-noise-management).\n", + "- [Configure noise management with Sampler](/docs/guides/sampler-noise-management).\n", + "- Explore other [options](/docs/guides/runtime-options-overview) for the Qiskit Runtime primitives.\n", + "- Decide what [execution mode](/docs/guides/execution-modes) to run your job in." ] } ], diff --git a/docs/guides/estimate-job-run-time.ipynb b/docs/guides/estimate-job-run-time.ipynb index 929554ebef5..bfe96c709c4 100644 --- a/docs/guides/estimate-job-run-time.ipynb +++ b/docs/guides/estimate-job-run-time.ipynb @@ -122,7 +122,7 @@ "\n", " - Review these tips: [Minimize job run time](minimize-time).\n", " - Set the [Maximum execution time](max-execution-time).\n", - " - Learn how to transpile locally in the [Transpile](./transpile/) section.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n", " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n", "" ] diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb new file mode 100644 index 00000000000..1151f0e835f --- /dev/null +++ b/docs/guides/estimator-examples.ipynb @@ -0,0 +1,411 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "7e51aef7-70db-4772-a53f-100af6ad6902", + "metadata": {}, + "source": [ + "---\n", + "title: Estimator examples\n", + "description: Practical examples of using the Estimator primitive in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Estimator examples" + ] + }, + { + "cell_type": "markdown", + "id": "10cf3d45-503c-41c9-b0a1-51c23e32bc5f", + "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": "3a98beb8-d1df-4daf-80ce-d51e4dc31cfa", + "metadata": {}, + "source": [ + "The examples in this section illustrate some common ways to use Estimator. Before running these examples, follow the instructions in [Install Qiskit.](install-qiskit)\n", + "\n", + "\n", + " These examples all use the primitives from Qiskit Runtime, but you could use the base primitives instead.\n", + "\n", + "\n", + "Efficiently calculate and interpret expectation values of the quantum operators required for many algorithms with Estimator. Explore uses in molecular modeling, machine learning, and complex optimization problems.\n", + "\n", + "## Run a single experiment\n", + "\n", + "Use Estimator to determine the expectation value of a single circuit-observable pair." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "6bc4a6a3-612e-4ad8-9fe3-3d56a4cb9a8f", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > Expectation value: 0.007735697018533441\n", + " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", + "\n", + "n_qubits = 50\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "mat = np.real(random_hermitian(n_qubits, seed=1234))\n", + "circuit = iqp(mat)\n", + "observable = SparsePauliOp(\"Z\" * 50)\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "isa_circuit = pm.run(circuit)\n", + "isa_observable = observable.apply_layout(isa_circuit.layout)\n", + "\n", + "estimator = Estimator(mode=backend)\n", + "job = estimator.run([(isa_circuit, isa_observable)])\n", + "result = job.result()\n", + "\n", + "print(f\" > Expectation value: {result[0].data.evs}\")\n", + "print(f\" > Metadata: {result[0].metadata}\")" + ] + }, + { + "cell_type": "markdown", + "id": "c8594feb-0516-4cca-9064-232906b980a4", + "metadata": {}, + "source": [ + "## Run multiple experiments in a single job\n", + "\n", + "Use Estimator to determine the expectation values of multiple circuit-observable pairs." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "662e73e9-8454-470a-b6aa-e84343005ca6", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Expectation values for PUB 0: 0.0185546875\n", + ">>> Standard errors for PUB 0: 0.015601139924387178\n", + ">>> Expectation values for PUB 1: -0.09142077434760362\n", + ">>> Standard errors for PUB 1: 0.03358006320017227\n", + ">>> Expectation values for PUB 2: -0.001953125\n", + ">>> Standard errors for PUB 2: 0.013875265857795725\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", + "\n", + "n_qubits = 50\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "rng = np.random.default_rng()\n", + "mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]\n", + "\n", + "pubs = []\n", + "circuits = [iqp(mat) for mat in mats]\n", + "observables = [\n", + " SparsePauliOp(\"X\" * 50),\n", + " SparsePauliOp(\"Y\" * 50),\n", + " SparsePauliOp(\"Z\" * 50),\n", + "]\n", + "\n", + "# Get ISA circuits\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "\n", + "for qc, obs in zip(circuits, observables):\n", + " isa_circuit = pm.run(qc)\n", + " isa_obs = obs.apply_layout(isa_circuit.layout)\n", + " pubs.append((isa_circuit, isa_obs))\n", + "\n", + "estimator = Estimator(backend)\n", + "job = estimator.run(pubs)\n", + "job_result = job.result()\n", + "\n", + "for idx in range(len(pubs)):\n", + " pub_result = job_result[idx]\n", + " print(f\">>> Expectation values for PUB {idx}: {pub_result.data.evs}\")\n", + " print(f\">>> Standard errors for PUB {idx}: {pub_result.data.stds}\")" + ] + }, + { + "cell_type": "markdown", + "id": "5176c806-e00d-4def-93b4-64216bf8cc64", + "metadata": {}, + "source": [ + "## Run parameterized circuits\n", + "\n", + "Use Estimator to run three experiments in a single job, leveraging parameter values to increase circuit reusability." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "3f991c86-8bcd-4d9e-bed1-a6a7ac0cabb6", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Expectation values: [[ 0.99448627 0.94805756 0.80317513 0.56626438 0.29038667 -0.02010529\n", + " -0.30613927 -0.5911369 -0.81581866 -0.94101035 -0.99303537 -0.94826483\n", + " -0.8098078 -0.59300234 -0.33287723 -0.01222899 0.29100849 0.57351886\n", + " 0.80711328 0.95531205 0.99635171]\n", + " [ 0.00808357 0.31152832 0.61663123 0.81208779 0.95178844 0.99199902\n", + " 0.9370722 0.79281158 0.56688619 0.28748488 -0.01948347 -0.31857553\n", + " -0.57434795 -0.79737154 -0.95178844 -0.99842442 -0.95427569 -0.79882244\n", + " -0.58761329 -0.27546316 0.00538905]\n", + " [-0.01906893 -0.32313549 -0.58450423 -0.8033824 -0.94930119 -0.99448627\n", + " -0.94121762 -0.80296786 -0.57186069 -0.29764116 0.02445798 0.31753918\n", + " 0.6054386 0.81644048 0.94183943 0.98681724 0.93955945 0.80027334\n", + " 0.57082434 0.29432482 -0.01513078]\n", + " [ 0.99075539 0.93375586 0.78970252 0.56688619 0.29536118 -0.00870538\n", + " -0.31401557 -0.60688949 -0.81084416 -0.94743575 -0.99344991 -0.94722848\n", + " -0.80110242 -0.57103161 -0.30075022 -0.00103636 0.30551746 0.58533331\n", + " 0.80669874 0.94142489 0.99407173]]\n", + ">>> Standard errors: [[0.00359184 0.00438386 0.00852894 0.01096216 0.00952795 0.01084166\n", + " 0.01092139 0.01112474 0.00835954 0.00493214 0.00305847 0.00505781\n", + " 0.0081545 0.00942587 0.01243794 0.01279255 0.01449143 0.01001158\n", + " 0.00686416 0.00608612 0.00306803]\n", + " [0.01380567 0.01025795 0.00809922 0.00742183 0.0050425 0.00375401\n", + " 0.00555313 0.0079511 0.01037733 0.01328277 0.01431205 0.01218068\n", + " 0.01144855 0.00865455 0.00559959 0.00383215 0.0044145 0.00880595\n", + " 0.01191713 0.01291607 0.01212646]\n", + " [0.01005963 0.00753399 0.00858187 0.00673876 0.00409901 0.0026568\n", + " 0.00439918 0.00771471 0.00939481 0.00991522 0.01046032 0.01036158\n", + " 0.00773218 0.00618488 0.00375851 0.00374272 0.0040234 0.00837196\n", + " 0.01109589 0.01055713 0.00823229]\n", + " [0.00376252 0.00513786 0.00521975 0.01071544 0.00701596 0.01081168\n", + " 0.01136338 0.01045901 0.00709637 0.00554858 0.00372386 0.00470944\n", + " 0.0063878 0.00980035 0.01048143 0.00968916 0.01234788 0.00880073\n", + " 0.00779767 0.00458181 0.00341765]]\n", + ">>> Metadata: {'shots': 10016, 'target_precision': 0.01, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "\n", + "from qiskit.circuit import QuantumCircuit, Parameter\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "# Step 1: Map classical inputs to a quantum problem\n", + "theta = Parameter(\"θ\")\n", + "\n", + "chsh_circuit = QuantumCircuit(2)\n", + "chsh_circuit.h(0)\n", + "chsh_circuit.cx(0, 1)\n", + "chsh_circuit.ry(theta, 0)\n", + "\n", + "number_of_phases = 21\n", + "phases = np.linspace(0, 2 * np.pi, number_of_phases)\n", + "individual_phases = [[ph] for ph in phases]\n", + "\n", + "ZZ = SparsePauliOp.from_list([(\"ZZ\", 1)])\n", + "ZX = SparsePauliOp.from_list([(\"ZX\", 1)])\n", + "XZ = SparsePauliOp.from_list([(\"XZ\", 1)])\n", + "XX = SparsePauliOp.from_list([(\"XX\", 1)])\n", + "ops = [ZZ, ZX, XZ, XX]\n", + "\n", + "# Step 2: Optimize problem for quantum execution.\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "chsh_isa_circuit = pm.run(chsh_circuit)\n", + "isa_observables = [\n", + " operator.apply_layout(chsh_isa_circuit.layout) for operator in ops\n", + "]\n", + "\n", + "# Step 3: Execute using Qiskit primitives.\n", + "\n", + "# Reshape observable array for broadcasting\n", + "reshaped_ops = np.fromiter(isa_observables, dtype=object)\n", + "reshaped_ops = reshaped_ops.reshape((4, 1))\n", + "\n", + "estimator = Estimator(backend, options={\"default_shots\": int(1e4)})\n", + "job = estimator.run([(chsh_isa_circuit, reshaped_ops, individual_phases)])\n", + "# Get results for the first (and only) PUB\n", + "pub_result = job.result()[0]\n", + "print(f\">>> Expectation values: {pub_result.data.evs}\")\n", + "print(f\">>> Standard errors: {pub_result.data.stds}\")\n", + "print(f\">>> Metadata: {pub_result.metadata}\")" + ] + }, + { + "cell_type": "markdown", + "id": "117454c0-c8df-48cd-8503-f4fd137d6991", + "metadata": {}, + "source": [ + "## Use batches and advanced options\n", + "\n", + "Explore the batch [execution mode](/docs/guides/execution-modes) and advanced options to optimize circuit performance on QPUs." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "f009e993-98fe-451c-96f5-738153005543", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > Expectation value: -0.04995359041431103\n", + " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", + " > Another Expectation value: 0.0\n", + " > More Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", + "from qiskit_ibm_runtime import (\n", + " QiskitRuntimeService,\n", + " Batch,\n", + " EstimatorV2 as Estimator,\n", + ")\n", + "\n", + "n_qubits = 15\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "rng = np.random.default_rng(1234)\n", + "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", + "circuit = iqp(mat)\n", + "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", + "another_circuit = iqp(mat)\n", + "observable = SparsePauliOp(\"X\" * n_qubits)\n", + "another_observable = SparsePauliOp(\"Y\" * n_qubits)\n", + "\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "isa_circuit = pm.run(circuit)\n", + "another_isa_circuit = pm.run(another_circuit)\n", + "isa_observable = observable.apply_layout(isa_circuit.layout)\n", + "another_isa_observable = another_observable.apply_layout(\n", + " another_isa_circuit.layout\n", + ")\n", + "\n", + "# The context manager automatically closes the batch.\n", + "with Batch(backend=backend) as batch:\n", + " estimator = Estimator(mode=batch)\n", + "\n", + " estimator.options.resilience_level = 1\n", + "\n", + " job = estimator.run([(isa_circuit, isa_observable)])\n", + " another_job = estimator.run(\n", + " [(another_isa_circuit, another_isa_observable)]\n", + " )\n", + " result = job.result()\n", + " another_result = another_job.result()\n", + "\n", + " # first job\n", + " print(f\" > Expectation value: {result[0].data.evs}\")\n", + " print(f\" > Metadata: {result[0].metadata}\")\n", + "\n", + " # second job\n", + " print(f\" > Another Expectation value: {another_result[0].data.evs}\")\n", + " print(f\" > More Metadata: {another_result[0].metadata}\")" + ] + }, + { + "cell_type": "markdown", + "id": "e207719d-da1b-4af2-ae63-4cb033865a1b", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - [Specify advanced runtime options](runtime-options-overview).\n", + " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum® Learning.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n", + " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n", + " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", + " - Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM® QPU.\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/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb new file mode 100644 index 00000000000..b958259e9f2 --- /dev/null +++ b/docs/guides/estimator-input-output.ipynb @@ -0,0 +1,365 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "4a99b08b-5a4e-4c2c-ba72-b932d8510bf2", + "metadata": {}, + "source": [ + "---\n", + "title: Estimator inputs and outputs\n", + "description: Understand the input and output format of the Estimator primitive\n", + "---\n", + "\n", + "\n", + "# Estimator inputs and outputs" + ] + }, + { + "cell_type": "markdown", + "id": "0f04fa5d-aae1-4a05-832b-be5e0f03f5b2", + "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": "cd5b8a3a-fc21-4eaf-923c-1576db19d569", + "metadata": {}, + "source": [ + "This page gives an overview of the inputs and outputs of the Qiskit Runtime Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure called a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." + ] + }, + { + "cell_type": "markdown", + "id": "d27b242b-5865-48cc-9052-577982a0b922", + "metadata": {}, + "source": [ + "## Inputs\n", + "\n", + "Each PUB is in this format:\n", + "\n", + "(``, ``, ``, ``),\n", + "\n", + "The optional `parameter values` can be a list or a single parameter. Elements from observables and parameter values are combined by following NumPy broadcasting rules as described in the [Primitive inputs and outputs](primitive-input-output#broadcasting-rules) topic, and one expectation value estimate is returned for each element of the broadcasted shape.\n", + "\n", + "\n", + "If the input contains measurements, they are ignored.\n", + "\n", + "\n", + "For the Estimator primitive, a PUB can contain at most four values:\n", + "- A single `QuantumCircuit`, which may contain one or more [`Parameter`](/docs/api/qiskit/qiskit.circuit.Parameter) objects\n", + "- A list of one or more observables, which specify the expectation values to estimate, arranged into an array (for example, a single observable represented as a 0-d array, a list of observables as a 1-d array, and so on). The data can be in any one of the `ObservablesArrayLike` format such as `Pauli`, `SparsePauliOp`, `PauliList`, or `str`.\n", + " \n", + " - Commuting observables **in the same PUB** are grouped together by using [this method](/docs/api/qiskit/qiskit.quantum_info.PauliList#group_qubit_wise_commuting).\n", + " - Commuting observables in different PUBs, even if they have the same circuit, are not estimated by using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB.\n", + " - To ensure that commuting observables are estimated by using the same measurement, group them within the same PUB.\n", + " \n", + "- A collection of parameter values to bind the circuit against. This can be specified as a single array-like object where the last index is over circuit `Parameter` objects or omitted (or equivalently, set to `None`) if the circuit has no `Parameter` objects.\n", + "- (Optionally) A target precision for expectation values to estimate" + ] + }, + { + "cell_type": "markdown", + "id": "6b4da5a2-093a-4069-99ba-11e2f9c1f9a1", + "metadata": {}, + "source": [ + "---\n", + "\n", + "The following code demonstrates an example set of vectorized inputs to the `Estimator` primitive and executes them on an IBM® backend as a single `RuntimeJobV2 ` object." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "f4b2c3b6-80bd-4d84-9b16-8bdb7502e06b", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.circuit import (\n", + " Parameter,\n", + " QuantumCircuit,\n", + ")\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "from qiskit_ibm_runtime import (\n", + " QiskitRuntimeService,\n", + " EstimatorV2 as Estimator,\n", + ")\n", + "\n", + "import numpy as np\n", + "\n", + "# Instantiate runtime service and get\n", + "# the least busy backend\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "# Define a circuit with two parameters.\n", + "circuit = QuantumCircuit(2)\n", + "circuit.h(0)\n", + "circuit.cx(0, 1)\n", + "circuit.ry(Parameter(\"a\"), 0)\n", + "circuit.rz(Parameter(\"b\"), 0)\n", + "circuit.cx(0, 1)\n", + "circuit.h(0)\n", + "\n", + "# Transpile the circuit\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "transpiled_circuit = pm.run(circuit)\n", + "layout = transpiled_circuit.layout\n", + "\n", + "# Now define a sweep over parameter values, the last axis of dimension 2 is\n", + "# for the two parameters \"a\" and \"b\"\n", + "params = np.vstack(\n", + " [\n", + " np.linspace(-np.pi, np.pi, 100),\n", + " np.linspace(-4 * np.pi, 4 * np.pi, 100),\n", + " ]\n", + ").T\n", + "\n", + "# Define three observables. The inner length-1 lists cause this array of\n", + "# observables to have shape (3, 1), rather than shape (3,) if they were\n", + "# omitted.\n", + "observables = [\n", + " [SparsePauliOp([\"XX\", \"IY\"], [0.5, 0.5])],\n", + " [SparsePauliOp(\"XX\")],\n", + " [SparsePauliOp(\"IY\")],\n", + "]\n", + "# Apply the same layout as the transpiled circuit.\n", + "observables = [\n", + " [observable.apply_layout(layout) for observable in observable_set]\n", + " for observable_set in observables\n", + "]\n", + "\n", + "# Estimate the expectation value for all 300 combinations of observables\n", + "# and parameter values, where the pub result will have shape (3, 100).\n", + "#\n", + "# This shape is due to our array of parameter bindings having shape\n", + "# (100, 2), combined with our array of observables having shape (3, 1).\n", + "estimator_pub = (transpiled_circuit, observables, params)\n", + "\n", + "# Instantiate the new Estimator object, then run the transpiled circuit\n", + "# using the set of parameters and observables.\n", + "estimator = Estimator(mode=backend)\n", + "job = estimator.run([estimator_pub])\n", + "result = job.result()" + ] + }, + { + "cell_type": "markdown", + "id": "246bd44d-8f3d-40b6-b1c1-795cc3533b32", + "metadata": {}, + "source": [ + "## Outputs\n", + "\n", + "After one or more PUBs are sent to a QPU for execution and a job successfully completes, the data is returned as a [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) container object accessed by calling the `RuntimeJobV2.result()` method.\n", + "\n", + "The `PrimitiveResult` contains an iterable list of [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB.\n", + "\n", + "Each element of this list corresponds to each PUB submitted to the primitive's `run()` method (for example, a job submitted with 20 PUBs will return a `PrimitiveResult` object that contains a list of 20 `PubResult` objects, one corresponding to each PUB).\n", + "\n", + "Each `PubResult` for the Estimator primitive contains at least an array of expectation values (`PubResult.data.evs`) and associated standard deviations (either `PubResult.data.stds` or `PubResult.data.ensemble_standard_error` depending on the `resilience_level` used), but can contain more data depending on the error mitigation options that were specified.\n", + "\n", + "Each `PubResult` object possesses both a `data` and a `metadata` attribute.\n", + " - The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth.\n", + " - The `DataBin` has various attributes depending on the shape or structure of the associated PUB as well as the error mitigation options specified by the primitive used to submit the job (for example, [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](/docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)).\n", + " - The `metadata` attribute contains information about the runtime and error mitigation options used (explained later in the [Result metadata](#result-metadata) section of this page).\n", + "\n", + "The following is a visual outline of the `PrimitiveResult` data structure for the Estimator output:\n", + "\n", + " ```\n", + " └── PrimitiveResult\n", + " ├── PubResult[0]\n", + " │ ├── metadata\n", + " │ └── data ## In the form of a DataBin object\n", + " │ ├── evs\n", + " │ │ └── List of estimated expectation values in the shape\n", + " | | specified by the first pub\n", + " │ └── stds\n", + " │ └── List of calculated standard deviations in the\n", + " | same shape as above\n", + " ├── PubResult[1]\n", + " | ├── metadata\n", + " | └── data ## In the form of a DataBin object\n", + " | ├── evs\n", + " | │ └── List of estimated expectation values in the shape\n", + " | | specified by the second pub\n", + " | └── stds\n", + " | └── List of calculated standard deviations in the\n", + " | same shape as above\n", + " ├── ...\n", + " ├── ...\n", + " └── ...\n", + " ```\n", + "\n", + "Put simply, a single job returns a `PrimitiveResult` object and contains a list of one or more `PubResult` objects. These `PubResult` objects then store the measurement data for each PUB that was submitted to the job.\n", + "\n", + "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "defbebd5-f09f-4596-aff0-ae88cbf2555c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The result of the submitted job had 1 PUB and has a value:\n", + " PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray(), shape=(3, 100)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})\n", + "\n", + "The associated PubResult of this job has the following data bins:\n", + " DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray(), shape=(3, 100))\n", + "\n", + "And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])\n", + "Recall that this shape is due to our array of parameter binding sets having shape (100, 2) -- where 2 is the\n", + " number of parameters in the circuit -- combined with our array of observables having shape (3, 1). \n", + "\n", + "The expectation values measured from this PUB are: \n", + "[[ 0.01951024 0.16823039 0.31511097 ... -0.2887414 -0.14410851\n", + " 0.01993466]\n", + " [ 0.02517623 0.09566969 0.15407855 ... -0.08106747 -0.02517623\n", + " 0.0448137 ]\n", + " [ 0.01384425 0.2407911 0.47614339 ... -0.49641533 -0.26304079\n", + " -0.00494438]]\n" + ] + } + ], + "source": [ + "print(\n", + " f\"The result of the submitted job had {len(result)} PUB and has a value:\\n {result}\\n\"\n", + ")\n", + "print(\n", + " f\"The associated PubResult of this job has the following data bins:\\n {result[0].data}\\n\"\n", + ")\n", + "print(f\"And this DataBin has attributes: {result[0].data.keys()}\")\n", + "print(\n", + " \"Recall that this shape is due to our array of parameter binding sets having shape (100, 2) -- where 2 is the\\n\\\n", + " number of parameters in the circuit -- combined with our array of observables having shape (3, 1). \\n\"\n", + ")\n", + "with np.printoptions(threshold=200):\n", + " print(\n", + " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", + " )" + ] + }, + { + "cell_type": "markdown", + "id": "33af7b71-0562-4bb6-8098-8ddebb206032", + "metadata": {}, + "source": [ + "#### How the Estimator primitive calculates error\n", + "\n", + "In addition to the estimate of the mean of the observables passed in the input PUBs (the `evs` field of the `DataBin`), Estimator also attempts to deliver an estimate of the error associated with those expectation values. All Estimator queries will populate the `stds` field with a quantity like the standard error of the mean for each expectation value, but some error mitigation options produce additional information, such as `ensemble_standard_error`.\n", + "\n", + "Consider a single observable $\\mathcal{O}$. In the absence of [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne), you can think of each shot of the Estimator execution as providing a point estimate of the expectation value $\\langle \\mathcal{O} \\rangle$. If the pointwise estimates are in a vector `Os`, then the value returned in `ensemble_standard_error` is equivalent to the following (in which $\\sigma_{\\mathcal{O}}$ is the [standard deviation of the expectation value](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) estimate and $N_{shots}$ is the number of shots):\n", + "\n", + "$$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{shots}} },$$\n", + "\n", + "which treats all shots as part of a single ensemble. If you requested gate [twirling](/docs/guides/error-mitigation-and-suppression-techniques#pauli-twirling) (`twirling.enable_gates = True`), you can sort the pointwise estimates of $\\langle \\mathcal{O} \\rangle$ into sets that share a common twirl. Call these sets of estimates `O_twirls`, and there are `num_randomizations` (number of twirls) of them. Then `stds` is the standard error of the mean of `O_twirls`, as in\n", + "\n", + "$$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{twirls}} },$$\n", + "\n", + "where $\\sigma_{\\mathcal{O}}$ is the standard deviation of `O_twirls` and $N_{twirls}$ is the number of twirls. When you do not enable twirling, `stds` and `ensemble_standard_error` are equal.\n", + "\n", + "If you enable ZNE, then the `stds` described above become weights in a non-linear regression to an extrapolator model. What finally gets returned in the `stds` in this case is the uncertainty of the fit model evaluated at a noise factor of zero. When there is a poor fit, or large uncertainty in the fit, the reported `stds` can become very large. When ZNE is enabled, `pub_result.data.evs_noise_factors` and `pub_result.data.stds_noise_factors` are also populated, so that you can do your own extrapolation." + ] + }, + { + "cell_type": "markdown", + "id": "cc748369-c7db-4d3d-a2a6-7973fa5c37fe", + "metadata": {}, + "source": [ + "## Result metadata\n", + "\n", + "In addition to the execution results, both the `PrimitiveResult` and `PubResult` objects contain a metadata attribute about the job that was submitted. The metadata containing information for all submitted PUBs (such as the various [runtime options](/docs/api/qiskit-ibm-runtime/options) available) can be found in the `PrimitiveResult.metatada`, while the metadata specific to each PUB is found in `PubResult.metadata`.\n", + "\n", + "\n", + "In the metadata field, primitive implementations can return any information about execution that is relevant to them, and there are no key-value pairs that are guaranteed by the base primitive. Thus, the returned metadata might be different in different primitive implementations.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "b740caa1-bbdb-421c-aae8-e389a8e55aa1", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The metadata of the PrimitiveResult is:\n", + "'dynamical_decoupling' : {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'},\n", + "'twirling' : {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'},\n", + "'resilience' : {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False},\n", + "'version' : 2,\n", + "\n", + "The metadata of the PubResult result is:\n", + "'shots' : 4096,\n", + "'target_precision' : 0.015625,\n", + "'circuit_metadata' : {},\n", + "'resilience' : {},\n", + "'num_randomizations' : 32,\n" + ] + } + ], + "source": [ + "# Print out the results metadata\n", + "print(\"The metadata of the PrimitiveResult is:\")\n", + "for key, val in result.metadata.items():\n", + " print(f\"'{key}' : {val},\")\n", + "\n", + "print(\"\\nThe metadata of the PubResult result is:\")\n", + "for key, val in result[0].metadata.items():\n", + " print(f\"'{key}' : {val},\")" + ] + } + ], + "metadata": { + "celltoolbar": "Raw Cell Format", + "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/estimator-noise-management.ipynb b/docs/guides/estimator-noise-management.ipynb new file mode 100644 index 00000000000..4246afba94c --- /dev/null +++ b/docs/guides/estimator-noise-management.ipynb @@ -0,0 +1,219 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "d59934c8-76a1-4eda-97ba-4fcfb6f15776", + "metadata": {}, + "source": [ + "---\n", + "title: Configure noise management with Estimator\n", + "description: How to configure noise management with the Qiskit Runtime Estimator primitive.\n", + "---\n", + "\n", + "# Configure noise management with Estimator" + ] + }, + { + "cell_type": "markdown", + "id": "8f3a25e1-b73d-48d1-8b82-9c57095c9108", + "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", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit-ibm-runtime~=0.45.1\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "3f1ea669-4144-4071-a4e9-88e01056f465", + "metadata": {}, + "source": [ + "There are several ways to manage noise, typically by using various error mitigation and error suppression techniques to avoid errors before they happen. These techniques usually cause pre-processing overhead. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.\n", + "\n", + "Estimator supports the following noise management techniques. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each. See the [Custom error settings](#advanced-error) section for instructions to enable these techniques.\n", + "\n", + "- [dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options#dynamicaldecouplingoptions)\n", + "- [Pauli twirling](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", + "- [PEA](/docs/api/qiskit-ibm-runtime/options-zne-options)\n", + "- [PEC](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#pec)\n", + "- [`resilience_level`](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience_level)\n", + "- [TREX](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#measure_mitigation)\n", + "- [ZNE](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2#zne)\n", + "\n", + "\n", + "## Resilience level\n", + "\n", + "The `resilience_level` specifies how much resilience to build against\n", + "errors. Higher levels generate more accurate results, at the expense of\n", + "longer processing times. Resilience levels can be used to configure the\n", + "cost/accuracy trade-off when applying noise management to your primitive\n", + "query. Noise management reduces errors (bias) in results by processing\n", + "the outputs from a collection, or ensemble, of related circuits. The\n", + "degree of error reduction depends on the method applied. The resilience\n", + "level abstracts the detailed choice of noise management method to allow\n", + "users to reason about the cost/accuracy trade that is appropriate to\n", + "their application.\n", + "\n", + "Given this, each level corresponds to a method or methods with\n", + "increasing level of quantum sampling overhead to enable you experiment\n", + "with different time-accuracy tradeoffs. The following table shows you\n", + "which levels and corresponding methods are available for each of the\n", + "primitives.\n", + "\n", + "\n", + "\n", + "| Resilience Level | Description | Technique |\n", + "|------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|\n", + "| 0 | No mitigation | None |\n", + "| 1 [Default] | Minimal mitigation costs: Mitigate error associated with readout errors | [Twirled Readout Error eXtinction (TREX)](/docs/guides/error-mitigation-and-suppression-techniques#trex) measurement twirling |\n", + "| 2 | Medium mitigation costs. Typically reduces bias in estimators, but is not guaranteed to be zero-bias. | Level 1 + [Zero Noise Extrapolation (ZNE)](/docs/guides/error-mitigation-and-suppression-techniques#zne) and gate twirling\n", + "\n", + "\n", + "\n", + "\n", + "Resilience levels are currently in beta so sampling overhead and\n", + "solution quality will vary from circuit to circuit. New features,\n", + "advanced options, and management tools will be released on a rolling\n", + "basis. Specific noise management methods are not guaranteed to be\n", + "applied at each resilience level.\n", + "\n", + "\n", + "### Configure Estimator with resilience levels\n", + "\n", + "You can use resilience levels to specify noise management techniques, or you can set custom techniques individually as described in [Custom error settings](#advanced-error).\n", + "\n", + "\n", + "Any options you manually specify in addition to the resilience level are applied in addition to 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", + "For example, setting the resilience level to 0 turns off `zne_mitigation`, but `estimator.options.resilience.zne_mitigation = True` overrides that value.\n", + "\n", + "\n", + "### Example\n", + "\n", + "The following code enables ZNE, TREX, and gate twirling by\n", + "setting `resilience_level 2`." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "841b526d-55b8-4125-bd2c-758d9db8dbb3", + "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(backend, options={\"resilience_level\": 2})" + ] + }, + { + "cell_type": "markdown", + "id": "c497a0e5-bcb7-4954-8096-70b4514ea498", + "metadata": {}, + "source": [ + "\n", + "## Custom noise management settings\n", + "\n", + "You can turn on and off individual noise management methods by using the [Estimator options](/docs/guides/estimator-options).\n", + "\n", + "\n", + "Not all options work together on all types of circuits. See the [feature compatibility table](estimator-options#options-compatibility-table) for details.\n", + "\n", + "\n", + "### Example" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "89f1827d-92a1-40a4-bd71-6d67a18f0932", + "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(backend)\n", + "options = estimator.options\n", + "# Turn on gate twirling.\n", + "options.twirling.enable_gates = True\n", + "# Turn on measurement error mitigation.\n", + "options.resilience.measure_mitigation = True\n", + "\n", + "print(\n", + " f\">>> gate twirling is turned on: {estimator.options.twirling.enable_gates}\"\n", + ")\n", + "print(\n", + " f\">>> measurement error mitigation is turned on: {estimator.options.resilience.measure_mitigation}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "0eba7825-2725-4406-82b7-3911c33957c5", + "metadata": {}, + "source": [ + "## Turn off all error mitigation\n", + "\n", + "For instructions to turn off all error mitigation see the [Turn off all error suppression and mitigation](estimator-options#no-error-mitigation) section in the Estimator options guide.\n", + "\n", + "## Next steps\n", + "\n", + "\n", + " - Walk through an example that uses error mitigation in the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", + " - Learn more about [error mitigation and error suppression techniques](error-mitigation-and-suppression-techniques).\n", + " - Explore [Estimator options](/docs/guides/estimator-options).\n", + " - Decide what [execution mode](/docs/guides/execution-modes) to run your job in.\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/estimator-options.ipynb b/docs/guides/estimator-options.ipynb new file mode 100644 index 00000000000..06ef6e03860 --- /dev/null +++ b/docs/guides/estimator-options.ipynb @@ -0,0 +1,942 @@ +{ + "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 +} diff --git a/docs/guides/estimator-rest-api.ipynb b/docs/guides/estimator-rest-api.ipynb new file mode 100644 index 00000000000..954de59e067 --- /dev/null +++ b/docs/guides/estimator-rest-api.ipynb @@ -0,0 +1,469 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0998165a-381f-4561-a79a-bf584aed9687", + "metadata": {}, + "source": [ + "---\n", + "title: Estimator with the REST API\n", + "description: How to use the Estimator primitive with the Qiskit Runtime REST API.\n", + "---\n", + "\n", + "\n", + "{/* cspell:ignore IIZII, XIZZZ, accum */}\n", + "\n", + "# Estimator with the REST API" + ] + }, + { + "cell_type": "markdown", + "id": "da948b6b-2ead-4359-aed4-b824e43ccbfb", + "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", + "```\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "3d9ef591-91fd-4a49-a065-5e2cda4d41be", + "metadata": {}, + "source": [ + "The steps in this topic describe how to run and configure workloads with the REST API, and demonstrate how to invoke them in any program of your choice.\n", + "\n", + "\n", + " This documentation utilizes the Python `requests` module to demonstrate the Qiskit Runtime REST API. However, this workflow can be executed using any language or framework that supports working with REST APIs. Refer to the [API reference documentation](/docs/api/qiskit-ibm-runtime/tags/jobs) for details.\n", + "\n", + "\n", + "## 1. Initialize the account\n", + "\n", + "Because Qiskit Runtime Estimator is a managed service, you first need to initialize your account. You can then select the device you want to use to calculate the expectation value.\n", + "\n", + "\n", + "Find details on how to initialize your account, view available backends, and invalidate tokens in this [topic](/docs/guides/cloud-setup-rest-api).\n", + "\n", + "## 2. Create a QASM circuit\n", + "\n", + "You need at least one circuit as the input to the Estimator primitive.\n", + "\n", + "Define a QASM quantum circuit. For example:\n", + "\n", + "```python\n", + "qasm_string='''\n", + "OPENQASM 3;\n", + "include \"stdgates.inc\";\n", + "qreg q[2];\n", + "creg c[2];\n", + "x q[0];\n", + "cx q[0], q[1];\n", + "c[0] = measure q[0];\n", + "c[1] = measure q[1];\n", + "'''\n", + "```\n", + "\n", + "The following code snippets assume that the `qasm_string` has been transpiled to a new string `resulting_qasm`.\n", + "\n", + "## 3. Run the quantum circuit using the Estimator V2 API\n", + "\n", + "\n", + "\n", + " The following jobs use [Qiskit Runtime V2 primitives](/docs/guides/v2-primitives). Both `SamplerV2` and `EstimatorV2` take one or more primitive unified blocs (PUBs) as the input. Each PUB is a tuple that contains one circuit and the data broadcasted to that circuit, which can be multiple observables and parameters. Each PUB returns a result.\n", + "\n", + "\n", + "\n", + "\n", + "```python\n", + "import requests\n", + "\n", + "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", + "auth_id = \"Bearer \"\n", + "crn = \"\"\n", + "backend = \"\"\n", + "\n", + "headers = {\n", + " 'Content-Type': 'application/json',\n", + " 'Authorization':auth_id,\n", + " 'Service-CRN': crn\n", + " }\n", + "\n", + "job_input = {\n", + " 'program_id': 'estimator',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [ #primitive unified blocs (PUBs) containing one circuit each.\n", + " [resulting_qasm, # QASM circuit\n", + " {\"IIZII\": 1, \"XIZZZ\": 2.3}, # Observable\n", + " None # parameter values\n", + " ]]\n", + "}}\n", + "\n", + "response = requests.post(url, headers=headers, json=job_input)\n", + "\n", + "if response.status_code == 200:\n", + " job_id = response.json().get('id')\n", + " print(\"Job created:\",response.text)\n", + "else:\n", + " print(f\"Error: {response.status_code}\")\n", + "```\n", + "\n", + "\n", + "\n", + "## 4. Check job status and get results\n", + "\n", + "Next, pass the `job_id` to the API:\n", + "\n", + "```python\n", + "response_status_singlejob= requests.get(url+'/'+job_id, headers=headers)\n", + "response_status_singlejob.json().get('state')\n", + "```\n", + "Output\n", + "\n", + "```text\n", + ">>> Job ID: 58223448-5100-4dec-a47a-942fb30edcad\n", + ">>> Job Status: JobStatus.RUNNING\n", + "```\n", + "\n", + "Get job results:\n", + "```python\n", + "response_result= requests.get(url+'/'+job_id+'/results', headers=headers)\n", + "\n", + "res_dict=response_result.json()\n", + "\n", + "estimator_result=res_dict['results']\n", + "print(estimator_result)\n", + "```\n", + "Output\n", + "```text\n", + "[{'data': {'evs': 0.7428980350102542, 'stds': 0.029884014518789213, 'ensemble_standard_error': 0.03261147170624149}, 'metadata': {'shots': 10016, 'target_precision': 0.01, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}}]\n", + "```\n", + "\n", + "## 5. Work with Runtime options\n", + "\n", + "Error mitigation techniques allow users to mitigate circuit errors by modeling the device noise at the time of execution. This typically results in quantum pre-processing overhead related to model training, and classical post-processing overhead to mitigate errors in the raw results by using the generated model.\n", + "\n", + "The error mitigation techniques built in to primitives are advanced resilience options. To specify these options, use the `resilience_level` option when submitting your job.\n", + "\n", + "The following examples demonstrate the default options for dynamical decoupling, twirling, and TREX + ZNE. Find more options and further details in the [Error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) topic.\n", + "\n", + "### TREX + ZNE\n", + "\n", + "```python\n", + "import requests\n", + "\n", + "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", + "auth_id = \"Bearer \"\n", + "crn = \"\"\n", + "backend = \"BACKEND_NAME\"\n", + "\n", + "headers = {\n", + " 'Content-Type': 'application/json',\n", + " 'Authorization':auth_id,\n", + " 'Service-CRN': crn\n", + " }\n", + "job_input = {\n", + " 'program_id': 'estimator',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [ #primitive unified blocs (PUBs) containing one circuit each\n", + " [resulting_qasm, # QASM circuit\n", + " {\"IIZII\": 1, \"XIZZZ\": 2.3}, # Observable\n", + " None # parameter values\n", + " ]]\n", + " \"options\": {\n", + " \"resilience\": {\n", + " \"measure_mitigation\": True,\n", + " \"zne_mitigation\": True,\n", + " \"zne\": {\n", + " \"extrapolator\":[\"exponential\", \"linear\"],\n", + " \"noise_factors\":[1, 3, 5],\n", + " },\n", + " },\n", + " },\n", + " }\n", + "}\n", + "\n", + "response = requests.post(url, headers=headers, json=job_input)\n", + "\n", + "if response.status_code == 200:\n", + " job_id = response.json().get('id')\n", + " print(\"Job created:\",response.text)\n", + "else:\n", + " print(f\"Error: {response.status_code}\")\n", + "```\n", + "\n", + "### Dynamical Decoupling\n", + "\n", + "```python\n", + "import requests\n", + "\n", + "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", + "auth_id = \"Bearer \"\n", + "crn = \"\"\n", + "backend = \"BACKEND_NAME\"\n", + "\n", + "headers = {\n", + " 'Content-Type': 'application/json',\n", + " 'Authorization':auth_id,\n", + " 'Service-CRN': crn\n", + " }\n", + "job_input = {\n", + " 'program_id': 'estimator',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [ #primitive unified blocs (PUBs) containing one circuit each\n", + " [resulting_qasm, # QASM circuit\n", + " {\"IIZII\": 1, \"XIZZZ\": 2.3}, # Observable\n", + " None # parameter values\n", + " ]]\n", + " \"options\": {\n", + " \"dynamical_decoupling\": {\n", + " \"enable\": True,\n", + " \"sequence_type\": 'XpXm',\n", + " \"extra_slack_distribution\": 'middle',\n", + " \"scheduling_method\": 'alap',\n", + " },\n", + " },\n", + " }\n", + "}\n", + "\n", + "response = requests.post(url, headers=headers, json=job_input)\n", + "\n", + "if response.status_code == 200:\n", + " job_id = response.json().get('id')\n", + " print(\"Job created:\",response.text)\n", + "else:\n", + " print(f\"Error: {response.status_code}\")\n", + "```\n", + "\n", + "### Twirling\n", + "\n", + "```python\n", + "import requests\n", + "\n", + "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", + "auth_id = \"Bearer \"\n", + "crn = \"\"\n", + "backend = \"BACKEND_NAME\"\n", + "\n", + "headers = {\n", + " 'Content-Type': 'application/json',\n", + " 'Authorization':auth_id,\n", + " 'Service-CRN': crn\n", + " }\n", + "job_input = {\n", + " 'program_id': 'estimator',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [ #primitive unified blocs (PUBs) containing one circuit each\n", + " [resulting_qasm, # QASM circuit\n", + " {\"IIZII\": 1, \"XIZZZ\": 2.3}, # Observable\n", + " None # parameter values\n", + " ]]\n", + " \"options\": {\n", + " \"twirling\": {\n", + " \"enable_gates\": True,\n", + " \"enable_measure\": True,\n", + " \"num_randomizations\": \"auto\",\n", + " \"shots_per_randomization\": \"auto\",\n", + " \"strategy\": \"active-accum\",\n", + " },\n", + " },\n", + " }\n", + "}\n", + "\n", + "response = requests.post(url, headers=headers, json=job_input)\n", + "\n", + "if response.status_code == 200:\n", + " job_id = response.json().get('id')\n", + " print(\"Job created:\",response.text)\n", + "else:\n", + " print(f\"Error: {response.status_code}\")\n", + "```\n", + "\n", + "## Parameterized circuits\n", + "\n", + "### 1. Initialize the account\n", + "\n", + "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the device you want to use to run your calculations on.\n", + "\n", + "\n", + "Find details on how to initialize your account, view available backends, and invalidate tokens in this [topic](/docs/guides/cloud-setup-rest-api).\n", + "\n", + "\n", + "### 2. Define parameters\n", + "\n", + "```python\n", + "import requests\n", + "import qiskit_ibm_runtime\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.qasm3 import dumps\n", + "from qiskit import QuantumCircuit\n", + "from qiskit.circuit import Parameter\n", + "from qiskit import transpile\n", + "\n", + "service = QiskitRuntimeService(channel='ibm_quantum')\n", + "backend = service.backend(\"\")\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "\n", + "theta = Parameter('theta')\n", + "phi = Parameter('phi')\n", + "parameter_values = {'theta': 1.57, 'phi': 3.14} # In case we want to pass a dictionary\n", + "```\n", + "\n", + "\n", + "### 3. Create a quantum circuit and add parameterized gates\n", + "\n", + "```python\n", + "qc = QuantumCircuit(2)\n", + "\n", + "# Add parameterized gates\n", + "qc.rx(theta, 0)\n", + "qc.ry(phi, 1)\n", + "qc.cx(0, 1)\n", + "qc.measure_all()\n", + "\n", + "# Draw the original circuit\n", + "qc.draw('mpl')\n", + "\n", + "# Get an ISA circuit\n", + "isa_circuit = pm.run(qc)\n", + "```\n", + "\n", + "### 4. Generate QASM 3 code\n", + "\n", + "```python\n", + "qasm_str = dumps(isa_circuit)\n", + "print(\"Generated QASM 3 code:\")\n", + "print(qasm_str)\n", + "```\n", + "\n", + "### 5. Run the quantum circuit using Estimator V2 API\n", + "\n", + "\n", + "```python\n", + "import requests\n", + "\n", + "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", + "auth_id = \"Bearer \"\n", + "crn = \"\"\n", + "backend = \"\"\n", + "\n", + "headers = {\n", + " 'Content-Type': 'application/json',\n", + " 'Authorization':auth_id,\n", + " 'Service-CRN': crn\n", + " }\n", + "\n", + "job_input = {\n", + " 'program_id': 'estimator',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " # Choose one option: direct parameter transfer or through a dictionary\n", + " #\"pubs\": [[qasm_str,[1,2],500]], # primitive unified blocs (PUBs) containing one circuit each.\n", + " \"pubs\": [[qasm_str,parameter_values,500]], # primitive unified blocs (PUBs) containing one circuit each.\n", + "}}\n", + "\n", + "response = requests.post(url, headers=headers, json=job_input)\n", + "\n", + "if response.status_code == 200:\n", + " job_id = response.json().get('id')\n", + " print(f\"Job created: {response.text}\")\n", + "else:\n", + " print(f\"Error: {response.status_code}\")\n", + "```\n", + "\n", + "```python\n", + "print(response.text)\n", + "```\n", + "\n", + "\n", + "### 6. Check job status and get results\n", + "\n", + "Next, pass the `job_id` to the API:\n", + "\n", + "```python\n", + "response_status_singlejob = requests.get(f\"{url}/{job_id}\", headers=headers)\n", + "response_status_singlejob.json().get('state')\n", + "```\n", + "\n", + "Output\n", + "\n", + "```text\n", + "{'status': 'Completed'}\n", + "```\n", + "\n", + "Get job results:\n", + "\n", + "```python\n", + "response_result = requests.get(f\"{url}/{job_id}/results\", headers=headers)\n", + "\n", + "res_dict=response_result.json()\n", + "\n", + "# Get results for the first PUB\n", + "counts=res_dict['results'][0]['data']['c']['samples']\n", + "\n", + "print(counts[:20])\n", + "```\n", + "\n", + "Output\n", + "\n", + "```text\n", + "['0x1', '0x2', '0x1', '0x2', '0x1', '0x2', '0x0', '0x2', '0x1', '0x1', '0x2', '0x2', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1']\n", + "```\n", + "\n", + "## Next steps\n", + "\n", + "\n", + "\n", + " - There are several ways to run workloads, depending on your needs: job mode, session mode, and batch mode. Learn how to work with session mode and batch mode in the [execution modes topic](/docs/guides/execution-modes-rest-api). Note that Open Plan users cannot submit session jobs.\n", + " - Learn how to [initialize your account](/docs/guides/cloud-setup-rest-api) with REST API.\n", + " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum® Learning.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.\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/execute-dynamic-circuits.ipynb b/docs/guides/execute-dynamic-circuits.ipynb index 6222202e513..757f0ad761c 100644 --- a/docs/guides/execute-dynamic-circuits.ipynb +++ b/docs/guides/execute-dynamic-circuits.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "add0b268-3a45-49a3-adce-cf4490fd454e", + "id": "a9095a6c-e720-4b4c-9eca-4b5234186400", "metadata": {}, "source": [ "---\n", @@ -16,7 +16,7 @@ }, { "cell_type": "markdown", - "id": "ac50b3dc-1535-4548-a457-2fc9f8964b55", + "id": "0b425be3-b17e-4e41-b393-63b0a58c054f", "metadata": { "tags": [ "version-info" @@ -46,7 +46,7 @@ }, { "cell_type": "markdown", - "id": "18d72348-b499-49be-900d-3a7d648c6955", + "id": "d59d8dd9-8c61-49ab-b43c-b34f87ebcce2", "metadata": {}, "source": [ "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements. This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n", @@ -55,7 +55,7 @@ "* [Efficient long-range entanglement](https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.5.030339) between qubits on the same chip by using shallow circuits\n", "* Efficient [sampling of IQP-like circuits](https://arxiv.org/pdf/2505.04705)\n", "\n", - "These improvements brought by dynamic circuits, however, come with trade-offs. Mid-circuit measurements and classical operations typically have longer execution time than two-qubit gates, and this increase in time might negate the benefits of reduced circuit depth. Therefore, reducing the length of mid-circuit measurement is a focus area of improvement as IBM Quantum® releases the [new version](/announcements/product-updates/2025-03-03-new-version-dynamic-circuits) of dynamic circuits. For other restrictions when using dynamic circuits, see the [Feature compatibility table](/docs/guides/runtime-options-overview#options-compatibility-table).\n", + "These improvements brought by dynamic circuits, however, come with trade-offs. Mid-circuit measurements and classical operations typically have longer execution time than two-qubit gates, and this increase in time might negate the benefits of reduced circuit depth. Therefore, reducing the length of mid-circuit measurement is a focus area of improvement as IBM Quantum® releases the [new version](/announcements/product-updates/2025-03-03-new-version-dynamic-circuits) of dynamic circuits. For other restrictions when using dynamic circuits, see the [Estimator](/docs/guides/estimator-options#options-compatibility-table) or [Sampler](/docs/guides/sampler-options#options-compatibility-table) Feature compatibility table.\n", "\n", "The [OpenQASM 3 specification](https://openqasm.com/language/classical.html#looping-and-branching) defines a number of control-flow structures, but Qiskit Runtime currently only supports the conditional `if` statement. In Qiskit SDK, this corresponds to the [if_test](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#if_test) method on [QuantumCircuit](/docs/api/qiskit/qiskit.circuit.QuantumCircuit). This method returns a [context manager](https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers) and is typically used in a `with` statement. This guide describes how to use this conditional statement.\n", "\n", @@ -66,7 +66,7 @@ }, { "cell_type": "markdown", - "id": "67b56da5-27fe-40b8-bc92-4ebdcedb3f4e", + "id": "c1f79012-05ce-4854-908b-59ca6b472508", "metadata": {}, "source": [ "## Find backends that support dynamic circuits\n", @@ -83,7 +83,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "a58871ad-aa00-4547-935b-b2d5523e1ab7", + "id": "0cd6971f-cb04-4ff9-89a8-7638fdcca0d1", "metadata": { "tags": [ "remove-cell" @@ -100,7 +100,7 @@ { "cell_type": "code", "execution_count": 2, - "id": "7ba471fd-8691-4552-8f22-4495d935e349", + "id": "517e5e4d-3f48-4c2b-9084-222ed3cd2de7", "metadata": {}, "outputs": [ { @@ -121,7 +121,7 @@ }, { "cell_type": "markdown", - "id": "134fc3cf-1541-4b56-b964-741cb0c46ceb", + "id": "5992c1cd-f28a-4f40-b3f9-09374c9f61ca", "metadata": {}, "source": [ "\n", @@ -141,7 +141,7 @@ { "cell_type": "code", "execution_count": 3, - "id": "bd89c780-e854-433d-8a01-4e23bcfbc0ba", + "id": "8b1b8786-21bd-4a9c-b868-36f497738f10", "metadata": {}, "outputs": [ { @@ -180,7 +180,7 @@ }, { "cell_type": "markdown", - "id": "0a13e866-8020-4c1e-8088-af8253ee4b50", + "id": "983e4d2b-7049-4be1-b628-eac093f96585", "metadata": {}, "source": [ "\n", @@ -193,7 +193,7 @@ }, { "cell_type": "markdown", - "id": "6fe87779-fe4d-43f8-973d-21f08b4e7862", + "id": "88942666-966d-4eb6-81b5-2a9e1265fe0a", "metadata": {}, "source": [ "## Full example\n", @@ -204,7 +204,7 @@ { "cell_type": "code", "execution_count": 4, - "id": "aa722cad-4820-4d68-817a-5fa00f4902d6", + "id": "800ddb06-3b1a-4b9e-a92e-c782e4a3d412", "metadata": {}, "outputs": [ { @@ -259,7 +259,7 @@ }, { "cell_type": "markdown", - "id": "232f55f5-4f35-4477-b66e-2a50e7956004", + "id": "e2ee6fb4-7b6d-4ee6-a625-0f92e40bd7f9", "metadata": {}, "source": [ "## Qiskit Runtime limitations\n", @@ -342,12 +342,12 @@ }, { "cell_type": "markdown", - "id": "33990aa3-3eb6-4a36-a742-d9b8ace38645", + "id": "fb3c25a4-bde2-4d34-bbd2-670091a33968", "metadata": {}, "source": [ "## Use dynamic circuits with Estimator\n", "\n", - "Since Estimator does not support dynamic circuits, you can use Sampler and build your own measurement circuits instead. Alternatively, you can use the [Executor primitive](/docs/guides/directed-execution-model#executor-primitive), which supports dynamic circuits.\n", + "Since Estimator does not support dynamic circuits, you can use [Sampler](/docs/guides/get-started-with-sampler) and build your own measurement circuits instead.\n", "\n", "To replicate Estimator's behavior, follow this process:\n", "\n", @@ -361,7 +361,17 @@ }, { "cell_type": "markdown", - "id": "37455b7e-cae4-4d05-a60b-619b9a41b362", + "id": "5adac953-3305-4383-b522-901ecbd9bd31", + "metadata": {}, + "source": [ + "## Restrictions\n", + "\n", + "Review any [Feature compatibility table](/docs/guides/estimator-options#options-compatibility-table) to understand restrictions when using dynamic circuits. Note that feature compatibility is not primitive-dependent." + ] + }, + { + "cell_type": "markdown", + "id": "b5b33172-d1b6-418c-b06d-12e4c2a75738", "metadata": {}, "source": [ "## Next steps\n", @@ -370,7 +380,6 @@ "- Learn how to implement accurate dynamic decoupling by using [stretch](/docs/guides/stretch).\n", "- Review the [classical feedforward and control flow](/docs/guides/classical-feedforward-and-control-flow) guide.\n", "- Use [circuit schedule visualization](/docs/guides/qiskit-runtime-circuit-timing) to debug and optimize your dynamic circuits.\n", - "- Review the [Feature compatibility table](/docs/guides/runtime-options-overview#options-compatibility-table) to understand restrictions when using dynamic circuits.\n", "" ] } diff --git a/docs/guides/execution-modes-rest-api.ipynb b/docs/guides/execution-modes-rest-api.ipynb index 24c1452af2f..25298e64869 100644 --- a/docs/guides/execution-modes-rest-api.ipynb +++ b/docs/guides/execution-modes-rest-api.ipynb @@ -22,7 +22,25 @@ "version-info" ] }, - "source": [] + "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", + "```\n", + "
" + ] }, { "cell_type": "markdown", @@ -37,11 +55,11 @@ "\n", "## Job mode with REST API\n", "\n", - "In job mode, a single primitive request of the Estimator or the Sampler is made without a context manager. See how to run a quantum circuit using [Estimator](primitives-rest-api#estimator-primitive-with-rest-api) and [Sampler](primitives-rest-api#sampler-primitive-with-rest-api) for some examples.\n", + "In job mode, a single primitive request of Estimator or Sampler is made without a context manager. See how to run a quantum circuit using [Estimator](/docs/guides/estimator-rest-api) and [Sampler](/docs/guides/sampler-rest-api) for some examples.\n", "\n", "## Session mode with REST API\n", "\n", - "A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources. More details about Sessions can be found in the [documentation](./execution-modes).\n", + "A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources. More details about Sessions can be found in the [documentation](/docs/guides/execution-modes).\n", "\n", "\n", "\n", @@ -116,7 +134,7 @@ "\n", "## Batch mode with REST API\n", "\n", - "Alternatively, you can submit a batch job by specifying the `mode` in the request payload. Batch mode can help shorten processing time if all jobs can be provided at the outset. Learn about batch mode in the [introduction to execution modes](./execution-modes#batch-mode) guide.\n", + "Alternatively, you can submit a batch job by specifying the `mode` in the request payload. Batch mode can help shorten processing time if all jobs can be provided at the outset. Learn about batch mode in the [introduction to execution modes](/docs/guides/execution-modes#batch-mode) guide.\n", "\n", "\n", "```python\n", @@ -278,10 +296,11 @@ "## Next steps\n", "\n", "\n", - " - Review detailed [Sampler and Estimator](primitives-rest-api) primitives examples using REST API.\n", + " - Review detailed [Sampler](/docs/guides/sampler-rest-api) primitives examples using REST API.\n", + " - Review detailed [Estimator](/docs/guides/estimator-rest-api) primitives examples using REST API.\n", " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum® Learning.\n", - " - Learn how to transpile locally in the [Transpile](./transpile) section.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.\n", "" ] } diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index 3e7ddfedfcb..cffa1fe1a9e 100644 --- a/docs/guides/execution-modes.mdx +++ b/docs/guides/execution-modes.mdx @@ -9,7 +9,7 @@ When Qiskit Runtime was introduced, users could only execute circuits as individ ## Job mode -A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify `mode=backend` when instantiating a primitive. See [Primitives examples](/docs/guides/primitives-examples) for usage. +A single primitive request made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify `mode=backend` when instantiating a primitive. See [Estimator examples](/docs/guides/estimator-examples) and [Sampler examples](/docs/guides/sampler-examples) for usage. ## Batch mode diff --git a/docs/guides/fractional-gates.ipynb b/docs/guides/fractional-gates.ipynb index 776c8ab79dd..53ac6d0fb6c 100644 --- a/docs/guides/fractional-gates.ipynb +++ b/docs/guides/fractional-gates.ipynb @@ -66,7 +66,7 @@ "Internally, these fractional gates work by directly executing an $R_{ZZ}(\\theta)$ and $R_X(\\theta)$ rotation for an arbitrary angle. Use of the $R_X(\\theta)$ gate can reduce the duration and error for single-qubit rotations of arbitrary angle by up to a factor of two. The direct execution of the $R_{ZZ}(\\theta)$ gate rotation avoids decomposition into multiple `CZGate` objects, similarly reducing a circuit's duration and error. This is especially useful for circuits that contain many single- and two-qubit rotations, such as when simulating the dynamics of a quantum system or when using a variational ansatz with many parameters.\n", "\n", "\n", - "While these types of gates are in the [library of standard gates](./circuit-library) which a `QuantumCircuit` can possess, they can only be used on specific IBM Quantum QPUs, and which must be loaded with the flag `use_fractional_gates` set to `True` (shown below). This flag will ensure that fractional gates are included in the backend's `Target` for the transpiler.\n", + "While these types of gates are in the [library of standard gates](/docs/guides/circuit-library) which a `QuantumCircuit` can possess, they can only be used on specific IBM Quantum QPUs, and which must be loaded with the flag `use_fractional_gates` set to `True` (shown below). This flag will ensure that fractional gates are included in the backend's `Target` for the transpiler.\n", "\n", "```python\n", "service = QiskitRuntimeService()\n", diff --git a/docs/guides/function-template-chemistry-workflow.ipynb b/docs/guides/function-template-chemistry-workflow.ipynb index 547034d2792..7c149ee5a77 100644 --- a/docs/guides/function-template-chemistry-workflow.ipynb +++ b/docs/guides/function-template-chemistry-workflow.ipynb @@ -93,7 +93,7 @@ "- 200,000 shots for systems with 16 - 18 molecular orbitals\n", "- 200,000 - 2,000,000 shots for systems with more than 18 molecular orbitals\n", "\n", - "The required number of shots is affected by the number of spin orbitals in the studied system and by the size of the Hilbert space corresponding to the selected active space within the studied system. Generally, instances with smaller Hilbert spaces require fewer shots. Other available LUCJ options are [circuit transpiler optimization level](https://docs.quantum.ibm.com/guides/set-optimization) and [error suppression options](https://docs.quantum.ibm.com/guides/configure-error-suppression). Note that these options also affect the required number of shots and the resulting accuracy.\n", + "The required number of shots is affected by the number of spin orbitals in the studied system and by the size of the Hilbert space corresponding to the selected active space within the studied system. Generally, instances with smaller Hilbert spaces require fewer shots. Other available LUCJ options are [circuit transpiler optimization level](https://docs.quantum.ibm.com/guides/set-optimization) and [error suppression options](https://docs.quantum.ibm.com/guides/error-mitigation-and-suppression-techniques). Note that these options also affect the required number of shots and the resulting accuracy.\n", "\n", " \n", "" @@ -699,7 +699,7 @@ "\n", "\n", "\n", - "- Review the guide on building a function template for [Hamiltonian simulation](./function-template-hamiltonian-simulation)\n", + "- Review the guide on building a function template for [Hamiltonian simulation](/docs/guides/function-template-hamiltonian-simulation)\n", "- Check out the source files for this template on [GitHub](https://github.com/qiskit-community/qiskit-function-templates/tree/main/chemistry/sqd_pcm)\n", "\n", "" diff --git a/docs/guides/get-started-with-backend-primitives.mdx b/docs/guides/get-started-with-backend-primitives.mdx new file mode 100644 index 00000000000..8b20d9ffdb1 --- /dev/null +++ b/docs/guides/get-started-with-backend-primitives.mdx @@ -0,0 +1,50 @@ +--- +title: Get started with the backend primitives +description: How to use the Qiskit Estimator and Sampler backend primitives. + +--- + +# Get started with the backend primitives + +Unlike provider-specific primitives, backend primitives are generic implementations that can be used with an arbitrary +`backend` object, as long as it implements the [`BackendV2`](/docs/api/qiskit/qiskit.providers.BackendV2) interface. Some providers implement primitives natively. See the [Qiskit Ecosystem page](https://www.ibm.com/quantum/ecosystem?tag=provider) for details. + + +## Get started with the Estimator backend primitive + +The Estimator primitive can be run with any provider by using the [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) class. However, it offers no measurement or gate error mitigation implementations "out-of-the-box", as backend primitives are designed to run locally in the user's machine. + +### Example: + +```python +from qiskit.primitives import BackendEstimatorV2 +from import QiskitProvider + +provider = QiskitProvider() +backend = provider.get_backend('backend_name') +estimator = BackendEstimatorV2(backend) +``` + + +## Get started with the Sampler backend primitive + +The Sampler primitive can be run with any provider by using [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2). However, it requires a backend that supports the `memory` option. + + +### Example: + +```python +from qiskit.primitives import BackendSamplerV2 +from import QiskitProvider + +provider = QiskitProvider() +backend = provider.get_backend('backend_name') +sampler = BackendSamplerV2(backend) +``` + +## Next steps + + + - Review the [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) API documentation. + - Review the [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) API documentation. + diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb new file mode 100644 index 00000000000..91bada46e8e --- /dev/null +++ b/docs/guides/get-started-with-estimator.ipynb @@ -0,0 +1,319 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", + "metadata": {}, + "source": [ + "---\n", + "title: Get started with the Estimator primitive\n", + "description: How to use the Estimator primitive in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Get started with the Estimator primitive" + ] + }, + { + "cell_type": "markdown", + "id": "49f269ba-e11d-4e5c-bbba-9d4a10540ad8", + "metadata": {}, + "source": [ + "The Estimator primitive computes the expectation values for one or more observables with respect to states prepared by quantum circuits. The circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.\n", + "\n", + "This primitive has several built-in [error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) techniques, including dynamical decoupling, Pauli-twirling, gate-folding ZNE, PEA, and PEC. It also supports a `resilience_level` option that allows you to easily configure the cost and accuracy tradeoff." + ] + }, + { + "cell_type": "markdown", + "id": "b7e96291-0925-4d7f-81a8-a7738549477c", + "metadata": {}, + "source": [ + "The steps in this topic describe how to set up Estimator, explore the options you can use to configure it, and invoke it in a program." + ] + }, + { + "cell_type": "markdown", + "id": "818a2b3d-3950-4a28-8e37-39959c56484b", + "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", + "\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.1\n", + "qiskit-ibm-runtime~=0.45.1\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "bafa61f0-c049-4ee6-ac76-a0ed97e67caf", + "metadata": {}, + "source": [ + "{/*Verified the v2 examples 2/29/24 - updated 10/29/24*/}\n", + "\n", + "## Steps to use the Estimator primitive\n", + "\n", + "### 1. Initialize the account\n", + "\n", + "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", + "\n", + "Follow the steps in the [Set up your IBM Cloud account](cloud-setup) if you don't already have an account.\n", + "\n", + "\n", + " To use the newly supported [fractional gates](/docs/guides/fractional-gates), set `use_fractional_gates=True` when requesting a backend from a `QiskitRuntimeService` instance. For example:\n", + " ```python\n", + " service = QiskitRuntimeService()\n", + " fractional_gate_backend = service.least_busy(use_fractional_gates=True)\n", + " ```\n", + "\n", + " This is an experimental feature and might change in the future.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "71d62ba2-b1ba-405a-b304-5bdd7ec5e11b", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "ibm_fez\n" + ] + } + ], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=127\n", + ")\n", + "\n", + "print(backend.name)" + ] + }, + { + "cell_type": "markdown", + "id": "d894fbe3-3ea8-4db0-908e-95790b560ddb", + "metadata": {}, + "source": [ + "### 2. Create a circuit and an observable\n", + "\n", + "You need at least one circuit and one observable as inputs to the Estimator primitive." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c0ad8982-d19b-46d4-8a2d-dd30357c0e52", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Observable: ['IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", + " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...', ...]\n" + ] + } + ], + "source": [ + "from qiskit.circuit.library import qaoa_ansatz\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "\n", + "entanglement = [tuple(edge) for edge in backend.coupling_map.get_edges()]\n", + "observable = SparsePauliOp.from_sparse_list(\n", + " [(\"ZZ\", [i, j], 0.5) for i, j in entanglement],\n", + " num_qubits=backend.num_qubits,\n", + ")\n", + "circuit = qaoa_ansatz(observable, reps=2)\n", + "# The circuit is parametrized, so we will define the parameter values for execution\n", + "param_values = [0.1, 0.2, 0.3, 0.4]" + ] + }, + { + "cell_type": "markdown", + "id": "84b42c6f-d80e-4cff-8e34-03affa566a97", + "metadata": {}, + "source": [ + "The circuit and observable need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). Use the transpiler to do this." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "abefc665-24a7-466e-a9ec-67cac6a50ebd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Circuit ops (ISA): OrderedDict([('rz', 4472), ('sx', 1884), ('cz', 1120)])\n" + ] + } + ], + "source": [ + "from qiskit.transpiler import generate_preset_pass_manager\n", + "\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "isa_circuit = pm.run(circuit)\n", + "isa_observable = observable.apply_layout(isa_circuit.layout)\n", + "print(f\">>> Circuit ops (ISA): {isa_circuit.count_ops()}\")" + ] + }, + { + "cell_type": "markdown", + "id": "b53e9ab3-7d87-4dd5-b362-138b24cfa73b", + "metadata": {}, + "source": [ + "### 3. Initialize Qiskit Runtime Estimator\n", + "\n", + "When you initialize Estimator, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes.](execution-modes) Note that Open Plan users cannot submit session jobs." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "961508db-e534-4fc9-970d-7babcd6c39ef", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", + "\n", + "estimator = Estimator(mode=backend)" + ] + }, + { + "cell_type": "markdown", + "id": "59b13a43-0c9f-4fdb-a379-af5115c153e1", + "metadata": {}, + "source": [ + "### 4. Invoke Estimator and get results\n", + "\n", + "Next, invoke the `run()` method to calculate expectation values for the input circuits and observables. The circuit, observable, and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "f1a60bad-cf09-4136-aa1a-4482759b3aea", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Job ID: d76cm768faus73f14eg0\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Job Status: QUEUED\n" + ] + } + ], + "source": [ + "job = estimator.run([(isa_circuit, isa_observable, param_values)])\n", + "print(f\">>> Job ID: {job.job_id()}\")\n", + "print(f\">>> Job Status: {job.status()}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "c817cce5-4686-43d2-89a1-ed0842d8ace3", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray()), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})\n", + " > Expectation value: 28.628978416256825\n", + " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" + ] + } + ], + "source": [ + "result = job.result()\n", + "print(f\">>> {result}\")\n", + "print(f\" > Expectation value: {result[0].data.evs}\")\n", + "print(f\" > Metadata: {result[0].metadata}\")" + ] + }, + { + "cell_type": "markdown", + "id": "d38dd409-e0d8-4749-bb22-58ae9a53d26a", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", + " - Review detailed [examples](/docs/guides/estimator-examples).\n", + " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n", + " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings#compare-transpiler-settings) guide.\n", + " - Learn how to [use the primitive options](runtime-options-overview).\n", + " - View the API for [Estimator](/docs/api/qiskit-ibm-runtime/options-estimator-options) options.\n", + " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\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/get-started-with-primitives.ipynb b/docs/guides/get-started-with-primitives.ipynb deleted file mode 100644 index a024e1cf23c..00000000000 --- a/docs/guides/get-started-with-primitives.ipynb +++ /dev/null @@ -1,548 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", - "metadata": {}, - "source": [ - "---\n", - "title: Get started with primitives\n", - "description: How to use the Estimator and Sampler primitives in Qiskit Runtime.\n", - "---\n", - "\n", - "\n", - "# Get started with primitives\n", - "\n", - "\n", - "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n", - "\n", - "\n", - "\n", - "\n", - "While this documentation uses the primitives from Qiskit Runtime, which allow you to use IBM® backends, the primitives can be run on any provider by using the [backend primitives](#backend) instead. Additionally, you can use the *reference* primitives to run on a local statevector simulator. See [Exact simulation with Qiskit primitives](/docs/guides/simulate-with-qiskit-sdk-primitives) for details.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "b7e96291-0925-4d7f-81a8-a7738549477c", - "metadata": {}, - "source": [ - "The steps in this topic describe how to set up primitives, explore the options you can use to configure them, and invoke them in a program.\n", - "\n", - "\n", - " To use the newly supported [fractional gates](./fractional-gates), set `use_fractional_gates=True` when requesting a backend from a `QiskitRuntimeService` instance. For example:\n", - " ```python\n", - " service = QiskitRuntimeService()\n", - " fractional_gate_backend = service.least_busy(use_fractional_gates=True)\n", - " ```\n", - "\n", - " Note that this is an experimental feature and might change in the future.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "818a2b3d-3950-4a28-8e37-39959c56484b", - "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", - "\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.1\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "bafa61f0-c049-4ee6-ac76-a0ed97e67caf", - "metadata": {}, - "source": [ - "\n", - "## Get started with Estimator\n", - "\n", - "{/*Verified the v2 examples 2/29/24 - updated 10/29/24*/}\n", - "\n", - "### 1. Initialize the account\n", - "\n", - "Because Qiskit Runtime Estimator is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", - "\n", - "Follow the steps in the [Install and set up topic](install-qiskit) if you don't already have an account." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "71d62ba2-b1ba-405a-b304-5bdd7ec5e11b", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "ibm_fez\n" - ] - } - ], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=127\n", - ")\n", - "\n", - "print(backend.name)" - ] - }, - { - "cell_type": "markdown", - "id": "d894fbe3-3ea8-4db0-908e-95790b560ddb", - "metadata": {}, - "source": [ - "### 2. Create a circuit and an observable\n", - "\n", - "You need at least one circuit and one observable as inputs to the Estimator primitive." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "c0ad8982-d19b-46d4-8a2d-dd30357c0e52", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Observable: ['IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", - " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...', ...]\n" - ] - } - ], - "source": [ - "from qiskit.circuit.library import qaoa_ansatz\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "\n", - "entanglement = [tuple(edge) for edge in backend.coupling_map.get_edges()]\n", - "observable = SparsePauliOp.from_sparse_list(\n", - " [(\"ZZ\", [i, j], 0.5) for i, j in entanglement],\n", - " num_qubits=backend.num_qubits,\n", - ")\n", - "circuit = qaoa_ansatz(observable, reps=2)\n", - "# the circuit is parametrized, so we will define the parameter values for execution\n", - "param_values = [0.1, 0.2, 0.3, 0.4]\n", - "\n", - "print(f\">>> Observable: {observable.paulis}\")" - ] - }, - { - "cell_type": "markdown", - "id": "84b42c6f-d80e-4cff-8e34-03affa566a97", - "metadata": {}, - "source": [ - "The circuit and observable need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). We'll use the transpiler to do this." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "abefc665-24a7-466e-a9ec-67cac6a50ebd", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Circuit ops (ISA): OrderedDict([('rz', 4472), ('sx', 1884), ('cz', 1120)])\n" - ] - } - ], - "source": [ - "from qiskit.transpiler import generate_preset_pass_manager\n", - "\n", - "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", - "isa_circuit = pm.run(circuit)\n", - "isa_observable = observable.apply_layout(isa_circuit.layout)\n", - "print(f\">>> Circuit ops (ISA): {isa_circuit.count_ops()}\")" - ] - }, - { - "cell_type": "markdown", - "id": "b53e9ab3-7d87-4dd5-b362-138b24cfa73b", - "metadata": {}, - "source": [ - "### 3. Initialize Qiskit Runtime Estimator\n", - "\n", - "When you initialize the Estimator, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes](execution-modes)." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "961508db-e534-4fc9-970d-7babcd6c39ef", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", - "\n", - "estimator = Estimator(mode=backend)" - ] - }, - { - "cell_type": "markdown", - "id": "59b13a43-0c9f-4fdb-a379-af5115c153e1", - "metadata": {}, - "source": [ - "### 4. Invoke the Estimator and get results\n", - "\n", - "Next, invoke the `run()` method to calculate expectation values for the input circuits and observables. The circuit, observable, and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "f1a60bad-cf09-4136-aa1a-4482759b3aea", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Job ID: d76cm768faus73f14eg0\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Job Status: QUEUED\n" - ] - } - ], - "source": [ - "job = estimator.run([(isa_circuit, isa_observable, param_values)])\n", - "print(f\">>> Job ID: {job.job_id()}\")\n", - "print(f\">>> Job Status: {job.status()}\")" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "c817cce5-4686-43d2-89a1-ed0842d8ace3", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray()), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})\n", - " > Expectation value: 28.628978416256825\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], - "source": [ - "result = job.result()\n", - "print(f\">>> {result}\")\n", - "print(f\" > Expectation value: {result[0].data.evs}\")\n", - "print(f\" > Metadata: {result[0].metadata}\")" - ] - }, - { - "cell_type": "markdown", - "id": "64e2e09f-8528-4088-897b-1529b451ab1e", - "metadata": {}, - "source": [ - "\n", - "## Get started with Sampler\n", - "\n", - "### 1. Initialize the account\n", - "\n", - "Because Qiskit Runtime Sampler is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", - "\n", - "Follow the steps in the [Install and set up topic](install-qiskit) if you don't already have an account set up." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "b40504d7-aee5-4b30-98b1-265e70bece8d", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=127\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "73374fbc-d3b6-4d2d-84c6-edf85b43ea25", - "metadata": {}, - "source": [ - "### 2. Create a circuit\n", - "\n", - "You need at least one circuit as the input to the Sampler primitive." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "dfe23a34-2ea9-48af-bd1d-c7e3185aa80c", - "metadata": {}, - "outputs": [], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import efficient_su2\n", - "\n", - "circuit = efficient_su2(127, entanglement=\"linear\")\n", - "circuit.measure_all()\n", - "# The circuit is parametrized, so we will define the parameter values for execution\n", - "param_values = np.random.rand(circuit.num_parameters)" - ] - }, - { - "cell_type": "markdown", - "id": "6cf08ef6-34d3-42e6-8cb3-391b60217289", - "metadata": {}, - "source": [ - "Use the transpiler to get an ISA circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "062bd89b-b13e-46d0-96b6-6c84b2131415", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Circuit ops (ISA): OrderedDict([('sx', 3088), ('rz', 3036), ('cz', 1089), ('measure', 127), ('barrier', 1)])\n" - ] - } - ], - "source": [ - "from qiskit.transpiler import generate_preset_pass_manager\n", - "\n", - "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", - "isa_circuit = pm.run(circuit)\n", - "print(f\">>> Circuit ops (ISA): {isa_circuit.count_ops()}\")" - ] - }, - { - "cell_type": "markdown", - "id": "cf0f2c0a-8574-45c6-a43b-1a99eac81279", - "metadata": {}, - "source": [ - "### 3. Initialize the Qiskit Runtime Sampler\n", - "\n", - "When you initialize the Sampler, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes](/docs/guides/execution-modes). Note that Open Plan users cannot submit session jobs." - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "a2b80dca-dff8-49f9-8154-e2cb0b768507", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", - "\n", - "sampler = Sampler(mode=backend)" - ] - }, - { - "cell_type": "markdown", - "id": "f35972bf-17d3-40be-852b-9e56615c7c3c", - "metadata": {}, - "source": [ - "### 4. Invoke the Sampler and get results\n", - "\n", - "Next, invoke the `run()` method to generate the output. The circuit and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples." - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "e52e6a96-dc23-4f76-8152-b54514a99dfb", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Job ID: d76cmme8faus73f14fi0\n", - ">>> Job Status: QUEUED\n" - ] - } - ], - "source": [ - "job = sampler.run([(isa_circuit, param_values)])\n", - "print(f\">>> Job ID: {job.job_id()}\")\n", - "print(f\">>> Job Status: {job.status()}\")" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "4543fac5-abdc-4440-a1a2-d32aabe135d6", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "First ten results for the 'meas' output register: ['1001101111100100101100100000100000001000110000010000011010111000000101100000110111010010100001010101011100110100100101000000011', '0000010001011111011000010001101100110010110001111010110001001000000100110111011111010011000001011100110111111010001010000000000', '0000100111000111110111110010000000101010100011110111110111000110101000100000100001000111000001110000000101000011111100100000000', '0100111111100001011101101101010010101100010001101110101010010100000011101100010100100011001000010011010101011010000000100010011', '1111000001001101001011010010000100010010010101010111001000100000100000010110111011010101000101011110001100101100011110000111110', '1100000111101011001001110010001000001000111111010101000011001000010101100001011000000100000000011010101001111110100110100010100', '1000111001100001100000111100101111100011100110101000100110001111010010111110011010010010010101010011100101001101111101000100000', '0111101010100001110000100010010100101010100010010101011010011001101100011001010000000100111010010001100011001010000000101001111', '0100001110000101111111101111010111000000000101011010100111001101001001001000101001100010101010000001001001000000100000101010101', '1101010100001000000100000110110101000000000000000100100001100100000000100000011101001100110110011100000001100111110010001011100']\n" - ] - } - ], - "source": [ - "result = job.result()\n", - "\n", - "# Get results for the first (and only) PUB\n", - "pub_result = result[0]\n", - "print(\n", - " f\"First ten results for the 'meas' output register: {pub_result.data.meas.get_bitstrings()[:10]}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "ec04840d-5fa1-4716-b585-48aa371f67d4", - "metadata": {}, - "source": [ - "\n", - "## Get started with the backend primitives\n", - "\n", - "Unlike provider-specific primitives, backend primitives are generic implementations that can be used with an arbitrary\n", - "`backend` object, as long as it implements the [`Backend`](/docs/api/qiskit/qiskit.providers.Backend) interface.\n", - "\n", - "- The Sampler primitive can be run with any provider by using [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2).\n", - "- The Estimator primitive can be run with any provider by using [`qiskit.primitives.BackendEstimatorV2`](../api/qiskit/qiskit.primitives.BackendEstimatorV2).\n", - "\n", - "Some providers implement primitives natively. See the [Qiskit Ecosystem page](https://qiskit.github.io/ecosystem#provider) for details." - ] - }, - { - "cell_type": "markdown", - "id": "9d78f323-1c58-4360-8880-59179c8a14b7", - "metadata": {}, - "source": [ - "### Example: BackendEstimator\n", - "\n", - "```python\n", - "from qiskit.primitives import BackendEstimatorV2\n", - "from import QiskitProvider\n", - "\n", - "provider = QiskitProvider()\n", - "backend = provider.get_backend('backend_name')\n", - "estimator = BackendEstimatorV2(backend)\n", - "```\n", - "\n", - "### Example: BackendSampler\n", - "\n", - "```python\n", - "from qiskit.primitives import BackendSamplerV2\n", - "from import QiskitProvider\n", - "\n", - "provider = QiskitProvider()\n", - "backend = provider.get_backend('backend_name')\n", - "sampler = BackendSamplerV2(backend)\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "e620a7b2-233d-4e0d-8a42-ee4eda3ccd8d", - "metadata": {}, - "source": [ - "### Similarities and differences between backend and Runtime primitives\n", - "\n", - "- The inputs to and outputs from [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) and [`qiskit.primitives.BackendEstimatorV2`](../api/qiskit/qiskit.primitives.BackendEstimatorV2)\n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [Primitive inputs and outputs](primitive-input-output) for details.\n", - "However, there can be differences in the fields of the returned metadata.\n", - "\n", - "- The [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) class offers no measurement or gate error mitigation implementations out-of-the-box, as\n", - "backend primitives are designed to run locally in the user's machine.\n", - "\n", - "- The [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) class requires a backend that supports the `memory` option.\n", - "\n", - "- The backend primitive interfaces expose custom [`SamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) and [`EstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) `Options` that are different from the Runtime implementations." - ] - }, - { - "cell_type": "markdown", - "id": "d38dd409-e0d8-4749-bb22-58ae9a53d26a", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", - " - Review detailed [primitives examples](/docs/guides/primitives-examples).\n", - " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", - " - Learn how to transpile locally in the [Transpile](transpile/) section.\n", - " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings#compare-transpiler-settings) guide.\n", - " - Learn how to [use the primitive options](runtime-options-overview).\n", - " - View the API for [Sampler](/docs/api/qiskit-ibm-runtime/options-sampler-options) and [Estimator](/docs/api/qiskit-ibm-runtime/options-estimator-options) options.\n", - " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\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/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb new file mode 100644 index 00000000000..f7a6072d41e --- /dev/null +++ b/docs/guides/get-started-with-sampler.ipynb @@ -0,0 +1,268 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", + "metadata": {}, + "source": [ + "---\n", + "title: Get started with the Sampler primitive\n", + "description: How to use the Sampler primitive in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Get started with the Sampler primitive" + ] + }, + { + "cell_type": "markdown", + "id": "b7e96291-0925-4d7f-81a8-a7738549477c", + "metadata": {}, + "source": [ + "The Sampler's core task is sampling the output register from the execution of one or more quantum circuits. [Dynamic circuits](/docs/guides/execute-dynamic-circuits) and parameterized circuits are accepted as input (if parametrized circuits are submitted, the parameter values must also be provided). Sampler also supports built-in dynamical decoupling and twirling for [error suppression](/docs/guides/error-mitigation-and-suppression-techniques).\n", + "\n", + "The steps in this topic describe how to set up Sampler, explore the options you can use to configure it, and invoke it in a program." + ] + }, + { + "cell_type": "markdown", + "id": "818a2b3d-3950-4a28-8e37-39959c56484b", + "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": "64e2e09f-8528-4088-897b-1529b451ab1e", + "metadata": {}, + "source": [ + "## Steps to use the Sampler primitive\n", + "### 1. Initialize the account\n", + "\n", + "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", + "\n", + "Follow the steps in the [Set up your IBM Cloud account](/docs/guides/cloud-setup) topic if you don't already have an account set up.\n", + "\n", + "\n", + " To use the newly supported [fractional gates](/docs/guides/fractional-gates), set `use_fractional_gates=True` when requesting a backend from a `QiskitRuntimeService` instance. For example:\n", + " ```python\n", + " service = QiskitRuntimeService()\n", + " fractional_gate_backend = service.least_busy(use_fractional_gates=True)\n", + " ```\n", + "\n", + " This is an experimental feature and might change in the future.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "b40504d7-aee5-4b30-98b1-265e70bece8d", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=127\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "73374fbc-d3b6-4d2d-84c6-edf85b43ea25", + "metadata": {}, + "source": [ + "### 2. Create a circuit\n", + "\n", + "You need at least one circuit as the input to the Sampler primitive." + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "dfe23a34-2ea9-48af-bd1d-c7e3185aa80c", + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import efficient_su2\n", + "\n", + "circuit = efficient_su2(127, entanglement=\"linear\")\n", + "circuit.measure_all()\n", + "# The circuit is parametrized, so we will define the parameter values for execution\n", + "param_values = np.random.rand(circuit.num_parameters)" + ] + }, + { + "cell_type": "markdown", + "id": "6cf08ef6-34d3-42e6-8cb3-391b60217289", + "metadata": {}, + "source": [ + "The circuit and observable need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). Use the transpiler to do this." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "062bd89b-b13e-46d0-96b6-6c84b2131415", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Circuit ops (ISA): OrderedDict([('sx', 3089), ('rz', 3036), ('cz', 1092), ('measure', 127), ('barrier', 1)])\n" + ] + } + ], + "source": [ + "from qiskit.transpiler import generate_preset_pass_manager\n", + "\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "isa_circuit = pm.run(circuit)\n", + "print(f\">>> Circuit ops (ISA): {isa_circuit.count_ops()}\")" + ] + }, + { + "cell_type": "markdown", + "id": "cf0f2c0a-8574-45c6-a43b-1a99eac81279", + "metadata": {}, + "source": [ + "### 3. Initialize the Qiskit Runtime Sampler\n", + "\n", + "When you initialize Sampler, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes.](execution-modes) Note that Open Plan users cannot submit session jobs." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "a2b80dca-dff8-49f9-8154-e2cb0b768507", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", + "\n", + "sampler = Sampler(mode=backend)" + ] + }, + { + "cell_type": "markdown", + "id": "f35972bf-17d3-40be-852b-9e56615c7c3c", + "metadata": {}, + "source": [ + "### 4. Invoke Sampler and get results\n", + "\n", + "Next, invoke the `run()` method to generate the output. The circuit and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "e52e6a96-dc23-4f76-8152-b54514a99dfb", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> Job ID: d5k96rsjt3vs73ds5tig\n", + ">>> Job Status: QUEUED\n" + ] + } + ], + "source": [ + "job = sampler.run([(isa_circuit, param_values)])\n", + "print(f\">>> Job ID: {job.job_id()}\")\n", + "print(f\">>> Job Status: {job.status()}\")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "4543fac5-abdc-4440-a1a2-d32aabe135d6", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "First ten results for the 'meas' output register: ['0101001101010000011001110001011000010010001100001000100110011111011110000010110001101000110011101010000100011011000110101111000', '0100111000000100110001100100000101111000111001101000110111101110110010010100001101001111001010011101010000010011000110000010001', '0101111101111111010011010101000000110100000010000010011101100011100011001100000100100001000101000000100001010101010011001101100', '1100110101111111001110010000010100101010101010001000001100100110011111010000000010001000110111010000010101100000100000110111001', '0010000001111001111010100100010111101000101000100000101100001000011100000100011010110110100011100110001001110110111101010011000', '0101110000001000100100010010100100111000010100000000010010000000010110010010000110000001110110010100000111001110100100111101100', '0100011111101001000111110011011101101101110101110001010111011101111110011101001000000001110000011110000101010000001010000100000', '0001010101011000110100000100111111100001011000111110000011000111001101010000010001001100000110000000100000110101010010101110010', '0100011010001110011110000110100101100100101001001111010100100101010100010000000010100000101010110010000000001000010101011111110', '0000011000000111000001000101111111110110101100110000001100010010011101011100001010000100011010001010001101000000000000010001001']\n" + ] + } + ], + "source": [ + "result = job.result()\n", + "\n", + "# Get results for the first (and only) PUB\n", + "pub_result = result[0]\n", + "print(\n", + " f\"First ten results for the 'meas' output register: {pub_result.data.meas.get_bitstrings()[:10]}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "d38dd409-e0d8-4749-bb22-58ae9a53d26a", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", + " - Review detailed [examples](sampler-examples).\n", + " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", + " - Learn how to transpile locally in the [Transpile](transpile/) section.\n", + " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings#compare-transpiler-settings) guide.\n", + " - Learn how to [use the primitive options](/docs/guides/runtime-options-overview).\n", + " - View the API for [Sampler](/docs/api/qiskit-ibm-runtime/options-sampler-options) options.\n", + " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\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/hello-world.ipynb b/docs/guides/hello-world.ipynb index af8adc952a7..234c0fcdf8e 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -97,10 +97,10 @@ "\n", "3. Now you can use this Python code any time you want to authenticate to the Qiskit Runtime Service:\n", " ```python\n", - " from qiskit_ibm_runtime import QiskitRuntimeService\n", + " from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", - " # Run every time you need the service\n", - " service = QiskitRuntimeService()\n", + " # Run every time you need the service\n", + " service = QiskitRuntimeService()\n", " ```\n", "\n", "If you are using a public computer or other unsecured environment, follow the [manual authentication instructions](/docs/guides/cloud-setup-untrusted) instead to keep your authentication credentials safe.\n", @@ -152,6 +152,43 @@ { "cell_type": "code", "execution_count": 1, + "id": "15f00fb9", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "# This cell is hidden from users. It hides several unnecessary warnings.\n", + "\n", + "import logging\n", + "\n", + "\n", + "class IgnoreSpecificMessages(logging.Filter):\n", + " def filter(self, record):\n", + " for text in [\n", + " \"Instance was not set\",\n", + " \"Loading default saved account\",\n", + " \"Loading instance\",\n", + " \"Instance was not set\",\n", + " \"using instance\",\n", + " ]:\n", + " if text in record.getMessage():\n", + " return False\n", + " return True\n", + "\n", + "\n", + "logger = logging.getLogger(\"qiskit_ibm_runtime\")\n", + "logger.addFilter(IgnoreSpecificMessages())\n", + "\n", + "for handler in logger.handlers:\n", + " handler.addFilter(IgnoreSpecificMessages())" + ] + }, + { + "cell_type": "code", + "execution_count": 2, "id": "930ca3b6", "metadata": { "tags": [] @@ -160,10 +197,10 @@ { "data": { "text/plain": [ - "\"Output" + "\"Output" ] }, - "execution_count": 1, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } @@ -212,14 +249,14 @@ "id": "f3ef4248-7938-44c1-85f1-edc997f0edcd", "metadata": {}, "source": [ - "When creating quantum circuits, you must also consider what type of data you want returned after execution. Qiskit provides two ways to return data: you can obtain a probability distribution for a set of qubits you choose to measure, or you can obtain the expectation value of an observable. Prepare your workload to measure your circuit in one of these two ways with [Qiskit primitives](/docs/guides/get-started-with-primitives) (explained in detail in [Step 3](#step-3-execute-using-the-quantum-primitives)).\n", + "When creating quantum circuits, you must also consider what type of data you want returned after execution. Qiskit provides two ways to return data: you can obtain sampling output for a set of qubits you choose to measure, or you can obtain the expectation value of an observable. Prepare your workload to measure your circuit in one of these two ways with Qiskit primitives (explained in detail in [Step 3](#step-3-execute-using-the-quantum-primitives)).\n", "\n", "This example measures expectation values by using the `qiskit.quantum_info` submodule, which is specified by using operators (mathematical objects used to represent an action or process that changes a quantum state). The following code cell creates six two-qubit Pauli operators: `IZ`, `IX`, `ZI`, `XI`, `ZZ`, and `XX`." ] }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 3, "id": "c57b261c-b757-4432-beab-61b526c98a41", "metadata": { "tags": [] @@ -259,17 +296,17 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 4, "id": "9a901271", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "\"Output" + "\"Output" ] }, - "execution_count": 3, + "execution_count": 4, "metadata": {}, "output_type": "execute_result" } @@ -293,12 +330,12 @@ "source": [ "### Step 3. Execute using the quantum primitives\n", "\n", - "Quantum computers can produce random results, so you usually collect a sample of the outputs by running the circuit many times. You can estimate the value of the observable by using the `Estimator` class. `Estimator` is one of two [primitives](/docs/guides/get-started-with-primitives); the other is `Sampler`, which can be used to get data from a quantum computer. These objects possess a `run()` method that executes the selection of circuits, observables, and parameters (if applicable), using a [primitive unified bloc (PUB)](/docs/guides/primitives)." + "Quantum computers can produce random results, so you usually collect a sample of the outputs by running the circuit many times. You can estimate the value of the observable by using the `Estimator` class. `Estimator` is one of two [primitives](/docs/guides/get-started-with-estimator); the other is `Sampler`, which can be used to get data from a quantum computer. These objects possess a `run()` method that executes the selection of circuits, observables, and parameters (if applicable), using a [primitive unified bloc (PUB)](/docs/guides/get-started-with-sampler)." ] }, { "cell_type": "code", - "execution_count": 4, + "execution_count": 5, "id": "62c4ca44", "metadata": { "tags": [] @@ -308,7 +345,7 @@ "name": "stdout", "output_type": "stream", "text": [ - ">>> Job ID: d76cmli3qcgc73fsqbhg\n" + ">>> Job ID: d7nriqqk4prs73dslong\n" ] } ], @@ -342,7 +379,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 6, "id": "792d2f01", "metadata": {}, "outputs": [], @@ -358,7 +395,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 7, "id": "f7339475", "metadata": { "tags": [ @@ -421,12 +458,12 @@ "\n", "The analyze step is typically where you might post-process your results using, for example, measurement error mitigation or zero noise extrapolation (ZNE). You might feed these results into another workflow for further analysis or prepare a plot of the key values and data. In general, this step is specific to your problem. For this example, plot each of the expectation values that were measured for our circuit.\n", "\n", - "The expectation values and standard deviations for the observables you specified to Estimator are accessed through the job result's `PubResult.data.evs` and `PubResult.data.stds` attributes. To obtain the results from Sampler, use the `PubResult.data.meas.get_counts()` function, which will return a `dict` of measurements in the form of bitstrings as keys and counts as their corresponding values. For more information, see [Get started with Sampler](/docs/guides/get-started-with-primitives#get-started-with-sampler)." + "The expectation values and standard deviations for the observables you specified to Estimator are accessed through the job result's `PubResult.data.evs` and `PubResult.data.stds` attributes. To obtain the results from Sampler, use the `PubResult.data.meas.get_counts()` function, which will return a `dict` of measurements in the form of bitstrings as keys and counts as their corresponding values. For more information, see [Get started with Sampler](/docs/guides/get-started-with-sampler)." ] }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 8, "id": "87143fcc", "metadata": { "tags": [] @@ -435,7 +472,7 @@ { "data": { "text/plain": [ - "\"Output" + "\"Output" ] }, "metadata": {}, @@ -466,7 +503,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 9, "id": "b8d8e086", "metadata": { "tags": [ @@ -502,7 +539,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 10, "id": "2ac02692", "metadata": {}, "outputs": [], @@ -526,7 +563,7 @@ " return qc\n", "\n", "\n", - "# Create a new circuit with a hundred qubits in the GHZ state\n", + "# Create a new circuit with 100 qubits in the GHZ state\n", "n = 100\n", "qc = get_qc_for_n_qubit_GHZ_state(n)" ] @@ -541,26 +578,15 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 16, "id": "863a4ec9", "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['ZZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZIII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZII', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZI', 'ZIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIZ']\n", - "99\n" - ] - } - ], + "outputs": [], "source": [ "# ZZII...II, ZIZI...II, ... , ZIII...IZ\n", "operator_strings = [\n", " \"Z\" + \"I\" * i + \"Z\" + \"I\" * (n - 2 - i) for i in range(n - 1)\n", "]\n", - "print(operator_strings)\n", - "print(len(operator_strings))\n", "\n", "operators = [SparsePauliOp(operator) for operator in operator_strings]" ] @@ -577,7 +603,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 12, "id": "428f05e7", "metadata": {}, "outputs": [], @@ -600,12 +626,12 @@ "source": [ "### Step 3. Execute on hardware\n", "\n", - "Submit the job and enable error suppression by using a technique to reduce errors called [dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options). The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of longer processing times. For further explanation of the options set in the following code, see [Configure error mitigation for Qiskit Runtime](/docs/guides/configure-error-mitigation)." + "Submit the job and enable error suppression by using a technique to reduce errors called [dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options). The resilience level specifies how much resilience to build against errors. Higher levels generate more accurate results, at the expense of longer processing times. For further explanation of the options set in the following code, see [Configure error mitigation for Qiskit Runtime](/docs/guides/error-mitigation-and-suppression-techniques)." ] }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "3aaa5025", "metadata": {}, "outputs": [], @@ -621,7 +647,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "b4c3d3e7-0a0f-4023-8948-1082e225f46c", "metadata": {}, "outputs": [ @@ -629,7 +655,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "d76co6fq1anc738degh0\n" + "d7nrj362jamc73boru80\n" ] } ], @@ -652,14 +678,14 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "de91ebd0", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "\"Output" + "\"Output" ] }, "metadata": {}, diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index 4f09caa12de..e75921903c3 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -37,7 +37,7 @@ "\n", "## Overview\n", "\n", - "The IBM® Circuit function takes [abstract PUBs](./primitive-input-output) as inputs, and returns mitigated expectation values as outputs. This circuit function includes an automated and customized pipeline to enable researchers to focus on algorithm and application discovery." + "The IBM® Circuit function takes [abstract PUBs](/docs/guides/primitive-input-output#pubs) as inputs, and returns mitigated expectation values as outputs. This circuit function includes an automated and customized pipeline to enable researchers to focus on algorithm and application discovery." ] }, { @@ -49,9 +49,9 @@ "\n", "After submitting your PUB, your abstract circuits and observables are automatically transpiled, executed on hardware, and post-processed to return mitigated expectation values. To do so, this combines the following tools:\n", "\n", - "- [Qiskit Transpiler Service](./qiskit-transpiler-service), including auto-selection of AI-driven and heuristic transpilation passes to translate your abstract circuits to hardware-optimized ISA circuits\n", - "- [Error suppression and mitigation required for utility-scale computation](./error-mitigation-and-suppression-techniques), including measurement and gate twirling, dynamical decoupling, Twirled Readout Error eXtinction (TREX), Zero-Noise Extrapolation (ZNE), and Probabilistic Error Amplification (PEA)\n", - "- [Qiskit Runtime Estimator](./get-started-with-primitives), to execute ISA PUBs on hardware and return mitigated expectation values\n", + "- [Qiskit Transpiler Service](/docs/guides/qiskit-transpiler-service), including auto-selection of AI-driven and heuristic transpilation passes to translate your abstract circuits to hardware-optimized ISA circuits\n", + "- [Error suppression and mitigation required for utility-scale computation](/docs/guides/error-mitigation-and-suppression-techniques), including measurement and gate twirling, dynamical decoupling, Twirled Readout Error eXtinction (TREX), Zero-Noise Extrapolation (ZNE), and Probabilistic Error Amplification (PEA)\n", + "- [Qiskit Runtime Estimator](/docs/guides/get-started-with-estimator), to execute ISA PUBs on hardware and return mitigated expectation values\n", "\n", "![IBM Circuit function](/docs/images/guides/ibm-circuit-function/ibm-circuit-function.svg)" ] @@ -155,7 +155,7 @@ "id": "eda36356", "metadata": {}, "source": [ - "The results have the same format as an [Estimator result](/docs/guides/primitive-input-output#estimator-output):" + "The results have the same format as an [Estimator result](/docs/guides/estimator-input-output):" ] }, { diff --git a/docs/guides/interoperate-qiskit-qasm2.ipynb b/docs/guides/interoperate-qiskit-qasm2.ipynb index 0283793fa49..924f5ee5f42 100644 --- a/docs/guides/interoperate-qiskit-qasm2.ipynb +++ b/docs/guides/interoperate-qiskit-qasm2.ipynb @@ -440,7 +440,7 @@ "\n", " - Learn how to generate OpenQASM code in the [IBM Quantum Composer](/docs/guides/composer) guide.\n", " - See the [OpenQASM 2 Qiskit API](/docs/api/qiskit/qasm2) reference.\n", - " - Review the [Verify your program](./debugging-tools) topic.\n", + " - Review the [Verify your program](/docs/guides/debugging-tools) topic.\n", " - Visit the [OpenQASM Live Specification](https://openqasm.com/).\n", "" ] diff --git a/docs/guides/interoperate-qiskit-qasm3.ipynb b/docs/guides/interoperate-qiskit-qasm3.ipynb index 99ba4e72533..029b3862b17 100644 --- a/docs/guides/interoperate-qiskit-qasm3.ipynb +++ b/docs/guides/interoperate-qiskit-qasm3.ipynb @@ -225,7 +225,7 @@ "\n", " - Learn how to generate OpenQASM code in the [IBM Quantum Composer](/docs/guides/composer) guide.\n", " - Review the [OpenQASM 3 Qiskit API](/docs/api/qiskit/qasm3) reference.\n", - " - Visit the [Verify your program](./debugging-tools) topic.\n", + " - Visit the [Verify your program](/docs/guides/debugging-tools) topic.\n", " - Review the [OpenQASM Live Specification](https://openqasm.com/).\n", "" ] diff --git a/docs/guides/intro-to-patterns.mdx b/docs/guides/intro-to-patterns.mdx index 30f12acb0b8..034cd85cd61 100644 --- a/docs/guides/intro-to-patterns.mdx +++ b/docs/guides/intro-to-patterns.mdx @@ -20,7 +20,7 @@ Each step is detailed in the sections below. ## Map the problem to quantum circuits and operators -This step describes how a user starts with a classical problem and figures out how to map it to a quantum computer. For example, in applications such as chemistry and quantum simulation, this step generally involves constructing a quantum circuit representing the Hamiltonian you are attempting to solve. During this step, for certain problems, it might also be desirable to specify the mapping of the problem onto qubits in the heavy-hex (or gross) lattice of IBM® hardware from the outset if the structure of the problem lends itself to optimization earlier. It is also worth considering at this point what the outcome of the particular algorithm will be in preparation for the later execute step - for example, if the desired outcome involves inferring correlation functions using Hadamard tests, you might prepare to use Sampler, whereas specifying observables would use the Estimator and could provide many error mitigation options. +This step describes how a user starts with a classical problem and figures out how to map it to a quantum computer. For example, in applications such as chemistry and quantum simulation, this step generally involves constructing a quantum circuit representing the Hamiltonian you are attempting to solve. During this step, for certain problems, it might also be desirable to specify the mapping of the problem onto qubits in the heavy-hex (or gross) lattice of IBM® hardware from the outset if the structure of the problem lends itself to optimization earlier. It is also worth considering at this point what the outcome of the particular algorithm will be in preparation for the later execute step - for example, if the desired outcome involves inferring correlation functions using Hadamard tests, you might prepare to use Sampler, whereas specifying observables would use Estimator and could provide many error mitigation options. The output of this step is normally a collection of circuits or quantum operators that can be optimized for hardware in the next step. @@ -38,7 +38,7 @@ During this step, abstract circuits must be transpiled to Instruction Set Archit This step involves running your circuits on hardware and produces the outputs of the quantum computation. The ISA circuits produced in the previous step can be executed using either a Sampler or Estimator primitive from Qiskit Runtime, initialized locally on your computer or from a cluster or other heterogeneous compute environment. These can be executed in a Batch, which allows parallel transpilation for classical computational efficiency - or a Session, which allows iterative tasks to be implemented efficiently without queuing delays. During this step, there is also the option to configure certain error suppression and mitigation techniques provided by Qiskit Runtime. -Depending on whether you are using the Sampler or Estimator primitive, the outcome of this step will be different. If using the Sampler, the output will be per-shot measurements in the form of bitstrings. If using the Estimator, the output will be expectation values of observables corresponding to physical quantities or cost functions. +Depending on whether you are using the Sampler or Estimator primitive, the outcome of this step will be different. If using Sampler, the output will be per-shot measurements in the form of bitstrings. If using Estimator, the output will be expectation values of observables corresponding to physical quantities or cost functions. ## Post-process results diff --git a/docs/guides/local-simulators.mdx b/docs/guides/local-simulators.mdx index c6a486de8ed..8c3724f0724 100644 --- a/docs/guides/local-simulators.mdx +++ b/docs/guides/local-simulators.mdx @@ -50,7 +50,7 @@ Successful quantum algorithms must be adapted to exploit the capabilities of qua Quantum simulators should be used to help develop and test programs before fine-tuning them and sending them to quantum hardware. Local simulators can do this with good performance and efficiency. Clifford circuits can be simulated very efficiently, and results can be verified, which is a useful way to gain confidence in an experiment. -Local testing mode does not have built-in error suppression or mitigation. Instead, you must specify those options explicitly. See [Configure error mitigation for Qiskit Runtime](/docs/guides/configure-error-mitigation) for details. +Local testing mode does not have built-in error suppression or mitigation. Instead, you must specify those options explicitly. See [Configure error mitigation for Qiskit Runtime](/docs/guides/error-mitigation-and-suppression-techniques) for details. ## Migrate to local simulators @@ -97,7 +97,7 @@ qc.h(0) qc.cx(0, 1) qc.measure_all() -# Run the sampler job locally using FakeManilaV2 +# Run the Sampler job locally using FakeManilaV2 fake_manila = FakeManilaV2() pm = generate_preset_pass_manager(backend=fake_manila, optimization_level=1) isa_qc = pm.run(qc) @@ -137,7 +137,7 @@ qc.h(0) qc.cx(0, 1) qc.measure_all() -# Run the sampler job locally using AerSimulator. +# Run the Sampler job locally using AerSimulator. # Session syntax is supported but ignored because local mode doesn't support sessions. aer_sim = AerSimulator() pm = generate_preset_pass_manager(backend=aer_sim, optimization_level=1) @@ -171,7 +171,7 @@ qc.measure_all() real_backend = service.backend("ibm_brisbane") aer = AerSimulator.from_backend(real_backend) -# Run the sampler job locally using AerSimulator. +# Run the Sampler job locally using AerSimulator. pm = generate_preset_pass_manager(backend=aer, optimization_level=1) isa_qc = pm.run(qc) sampler = Sampler(mode=aer) diff --git a/docs/guides/local-testing-mode.ipynb b/docs/guides/local-testing-mode.ipynb index 9959c612949..135ed9483ce 100644 --- a/docs/guides/local-testing-mode.ipynb +++ b/docs/guides/local-testing-mode.ipynb @@ -121,7 +121,7 @@ "qc.cx(0, 1)\n", "qc.measure_all()\n", "\n", - "# Run the sampler job locally using FakeManilaV2\n", + "# Run the Sampler job locally using FakeManilaV2\n", "fake_manila = FakeManilaV2()\n", "pm = generate_preset_pass_manager(backend=fake_manila, optimization_level=1)\n", "isa_qc = pm.run(qc)\n", @@ -161,7 +161,7 @@ "qc.cx(0, 1)\n", "qc.measure_all()\n", "\n", - "# Run the sampler job locally using AerSimulator.\n", + "# Run the Sampler job locally using AerSimulator.\n", "# Session syntax is supported but ignored because local mode doesn't support sessions.\n", "aer_sim = AerSimulator()\n", "pm = generate_preset_pass_manager(backend=aer_sim, optimization_level=1)\n", @@ -211,7 +211,7 @@ "real_backend = service.backend(\"ibm_fez\")\n", "aer = AerSimulator.from_backend(real_backend)\n", "\n", - "# Run the sampler job locally using AerSimulator.\n", + "# Run the Sampler job locally using AerSimulator.\n", "pm = generate_preset_pass_manager(backend=aer, optimization_level=1)\n", "isa_qc = pm.run(qc)\n", "sampler = Sampler(mode=aer)\n", @@ -270,7 +270,8 @@ "\n", "\n", " - Use the [`Neat` class](/docs/guides/debug-qiskit-runtime-jobs) to analyze the noise impact on an Estimator workload.\n", - " - Review detailed [primitives examples](/docs/guides/primitives-examples).\n", + " - Review detailed [Sampler examples](/docs/guides/sampler-examples).\n", + " - Review detailed [Estimator examples](/docs/guides/estimator-examples).\n", " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.\n", diff --git a/docs/guides/max-execution-time.ipynb b/docs/guides/max-execution-time.ipynb index a8e7ad39d6e..a595ac1aebe 100644 --- a/docs/guides/max-execution-time.ipynb +++ b/docs/guides/max-execution-time.ipynb @@ -46,7 +46,7 @@ "\n", "The `max_execution_time` value is based on _quantum time_, not wall clock time. Quantum time is the amount of time that the QPU is dedicated to processing your job.\n", "\n", - "Set the maximum execution time (in seconds) on the job options, as shown in the following example. See [Specify options](/docs/guides/specify-runtime-options) for information about setting options.\n", + "Set the maximum execution time (in seconds) on the job options, as shown in the following example. See the [Estimator options](/docs/guides/estimator-options) or [Sampler options](/docs/guides/sampler-options) guides for information about setting options.\n", "\n", "```python\n", "from qiskit_ibm_runtime import QiskitRuntimeService\n", diff --git a/docs/guides/metapackage-migration.mdx b/docs/guides/metapackage-migration.mdx index 7ef206cc0f7..5447ddce2fe 100644 --- a/docs/guides/metapackage-migration.mdx +++ b/docs/guides/metapackage-migration.mdx @@ -111,4 +111,4 @@ You may notice that the command `pip install qiskit` will no longer includes pac Before the release of the Qiskit SDK v1.0, Qiskit was comprised of many different Python distributions, such as `qiskit-terra`, the compiler core; `qiskit-aer`, the high-performance simulator; the original IBM Quantum® provider; and several now-obsolete packages providing particular exploratory algorithmic or experiment-running features. -If you want to install the packages that were previously included in the Qiskit metapackage, visit the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem) to find a range of packages to suit your needs. You can also read the [v1.0 migration guide](./qiskit-1.0-installation) for more information about how to install the new distribution. +If you want to install the packages that were previously included in the Qiskit metapackage, visit the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem) to find a range of packages to suit your needs. You can also read the [v1.0 migration guide](/docs/guides/qiskit-1.0-installation) for more information about how to install the new distribution. diff --git a/docs/guides/minimize-time.mdx b/docs/guides/minimize-time.mdx index b31795dd2d2..c6328494cd5 100644 --- a/docs/guides/minimize-time.mdx +++ b/docs/guides/minimize-time.mdx @@ -12,10 +12,10 @@ There are several ways you can limit the amount of time spent processing and run - Set limits on execution time: You can limit how long each job, batch, or session runs. For details, see [Maximum execution time for Qiskit Runtime workloads](max-execution-time). -- Use only the necessary settings for error suppression and error mitigation, because higher values can cause your jobs to run longer. See [Introduction to options](./runtime-options-overview), [Configure error suppression](./configure-error-suppression), and [Configure error mitigation](configure-error-mitigation) for details. +- Use only the necessary settings for error suppression and error mitigation, because higher values can cause your jobs to run longer. See [Introduction to options](/docs/guides/runtime-options-overview), [Configure error suppression](/docs/guides/error-mitigation-and-suppression-techniques), and [Configure error mitigation](error-mitigation-and-suppression-techniques) for details. - If you are running multiple jobs that contain the same (likely parameterized) circuits and are using an error mitigation method that requires noise models, such as PEA and PEC, consider using `NoiseLearner`. With this helper program, you can learn the noise model of a circuit once and reuse the model in subsequent Estimator queries. Note that a noise model becomes stale after a certain time, so this is only practical if there is no long delay between jobs (for example, within a session). See [Noise learning helper -](./noise-learning) for more details. +](/docs/guides/noise-learning) for more details. ## Next steps diff --git a/docs/guides/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index ae1341e081f..4b9f7ff0ca6 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -7,7 +7,7 @@ "source": [ "---\n", "title: Monitor or cancel a job\n", - "description: How to monitor or cancel a job submitted to IBM Quantum Platform or IBM Quantum on IBM Cloud\n", + "description: How to monitor or cancel a job submitted to IBM Quantum Platform\n", "---\n", "\n", "\n", @@ -64,7 +64,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "ee0318b6-0bfd-4f0b-b980-4e233a2d5d7b", "metadata": { "tags": [ @@ -112,7 +112,7 @@ "\n", "sampler_pub = (transpiled_circuit, params)\n", "\n", - "# Instantiate the new estimator object, then run the transpiled circuit\n", + "# Instantiate the new Estimator object, then run the transpiled circuit\n", "# using the set of parameters and observables.\n", "sampler = SamplerV2(mode=backend)\n", "job = sampler.run([sampler_pub], shots=4)\n", @@ -217,139 +217,7 @@ "\n", "You can cancel a job from the IBM Quantum Platform dashboard either on the Workloads page or the details page for a specific workload. On the Workloads page, click the overflow menu at the end of the row for that workload, and select Cancel. If you are on the details page for a specific workload, use the Actions dropdown at the top of the page, and select Cancel.\n", "\n", - "In Qiskit, use `job.cancel()` to cancel a job.\n", - "\n", - "\n", - "## View Sampler execution spans\n", - "\n", - "The results of [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) jobs executed in Qiskit Runtime contain execution timing information in their metadata.\n", - "This timing information can be used to place upper and lower timestamp bounds on when particular shots were executed on the QPU.\n", - "Shots are grouped into [`ExecutionSpan`](/docs/api/qiskit-ibm-runtime/execution-span-execution-span) objects, each of which indicates a start time, a stop time, and a specification of which shots were collected in the span.\n", - "\n", - "An execution span specifies which data was executed during its window by providing an [`ExecutionSpan.mask`](/docs/api/qiskit-ibm-runtime/execution-span-execution-span#mask) method. This method, given any [Primitive Unified Block (PUB)](/docs/guides/primitive-input-output) index, returns a boolean mask that is `True` for all shots executed during its window. PUBs are indexed by the order in which they were given to the Sampler run call. If, for example, a PUB has shape `(2, 3)` and was run with four shots, then the mask's shape is `(2, 3, 4)`. See the [execution_span](/docs/api/qiskit-ibm-runtime/execution-span) API page for full details.\n", - "\n", - "Example:" - ] - }, - { - "cell_type": "markdown", - "id": "ae2820bc-c762-4d2e-944c-58cbc253acbe", - "metadata": {}, - "source": [ - "To view execution span information, review the metadata of the result returned by `SamplerV2`, which comes in the form of an `ExecutionSpans` object. This object is a list-like container containing instances of subclasses of `ExecutionSpan`, such as `SliceSpan`:" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "e025fe52-f626-4ecc-bd1d-d559a6fe9cc8", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit.primitives import BitArray\n", - "\n", - "# Get the mask of the 1st PUB for the 0th span.\n", - "mask = spans[0].mask(0)\n", - "\n", - "# Decide whether the 0th shot of parameter set (1, 2) occurred in this span.\n", - "in_this_span = mask[2, 1, 0]\n", - "\n", - "# Create a new bit array containing only the PUB-1 data collected during this span.\n", - "bits = result[0].data.meas\n", - "filtered_data = BitArray(bits.array[mask], bits.num_bits)" - ] - }, - { - "cell_type": "markdown", - "id": "40538c83-3ef9-426d-9a98-6c102cf56de0", - "metadata": {}, - "source": [ - "Execution spans can be filtered to include information pertaining to specific PUBs, selected by their indices:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "71234371-5b93-42e3-add9-ce4133f9afc4", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "ExecutionSpans([DoubleSliceSpan()])" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# take the subset of spans that reference data in PUBs 0 or 2\n", - "spans.filter_by_pub([0, 2])" - ] - }, - { - "cell_type": "markdown", - "id": "c02c3b66-f131-4d47-9321-d60924bd531c", - "metadata": {}, - "source": [ - "View global information about the collection of execution spans:" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "f2c25fbb-581d-4847-a098-99f409b79fad", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Number of execution spans: 1\n", - " Start of the first span: 2025-09-09 16:31:16.320568\n", - " End of the last span: 2025-09-09 16:31:16.865858\n", - " Total duration (s): 0.54529\n" - ] - } - ], - "source": [ - "print(\"Number of execution spans:\", len(spans))\n", - "print(\" Start of the first span:\", spans.start)\n", - "print(\" End of the last span:\", spans.stop)\n", - "print(\" Total duration (s):\", spans.duration)" - ] - }, - { - "cell_type": "markdown", - "id": "f4b459b3-a79f-42a3-8853-1359fc966b8b", - "metadata": {}, - "source": [ - "Extract and inspect a particular span:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "2321f876-3c5e-4d1d-906e-d4cad55866f2", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " Start of first span: 2025-09-09 16:31:16.320568\n", - " End of first span: 2025-09-09 16:31:16.865858\n", - "#shots in first span: 24\n" - ] - } - ], - "source": [ - "spans.sort()\n", - "print(\" Start of first span:\", spans[0].start)\n", - "print(\" End of first span:\", spans[0].stop)\n", - "print(\"#shots in first span:\", spans[0].size)" + "In Qiskit, use `job.cancel()` to cancel a job." ] }, { @@ -357,14 +225,11 @@ "id": "c2abeb3d-4e4a-4c90-be59-16ec0e1be783", "metadata": {}, "source": [ - "\n", - "It is possible for time windows specified by distinct execution spans to overlap. This is not because a QPU was performing multiple executions at once, but is instead an artifact of certain classical processing that might happen concurrently with quantum execution. The guarantee being made is that the referenced data definitely occurred in the reported execution span, but not necessarily that the limits of the time window are as tight as possible.\n", - "\n", - "\n", "## Next steps\n", "\n", "\n", " - Try the [Grover's algorithm](/docs/tutorials/grovers-algorithm) tutorial.\n", + " - Learn more about [Sampler execution spans](/docs/guides/sampler-input-output#execution-spans)\n", "" ] } diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index 0d1088b0998..8dd85525ce4 100644 --- a/docs/guides/noise-learning.ipynb +++ b/docs/guides/noise-learning.ipynb @@ -49,12 +49,12 @@ "id": "cabee439-d0f2-4079-a47d-b6d96ce78332", "metadata": {}, "source": [ - "The error mitigation techniques [PEA](./error-mitigation-and-suppression-techniques#probabilistic-error-amplification-pea) and [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec) both utilize a noise learning component based on a [Pauli-Lindblad noise model](https://arxiv.org/abs/2201.09866), which is typically managed during execution after submitting one or more jobs through `qiskit-ibm-runtime` without any local access to the fitted noise model. However, as of `qiskit-ibm-runtime` 0.27.1, a [`NoiseLearner`](../api/qiskit-ibm-runtime/noise-learner) and associated [`NoiseLearnerOptions`](../api/qiskit-ibm-runtime/options-noise-learner-options) class have been created to obtain the results of these noise learning experiments. These results can then be stored locally as a `NoiseLearnerResult` and used as input in later experiments. This page provides an overview of its usage and the associated options available.\n", + "The error mitigation techniques [PEA](/docs/guides/error-mitigation-and-suppression-techniques#pea) and [PEC](/docs/guides/error-mitigation-and-suppression-techniques#pec) both utilize a noise learning component based on a [Pauli-Lindblad noise model](https://arxiv.org/abs/2201.09866), which is typically managed during execution after submitting one or more jobs through `qiskit-ibm-runtime` without any local access to the fitted noise model. However, as of `qiskit-ibm-runtime` 0.27.1, a [`NoiseLearner`](/docs/api/qiskit-ibm-runtime/noise-learner) and associated [`NoiseLearnerOptions`](/docs/api/qiskit-ibm-runtime/options-noise-learner-options) class have been created to obtain the results of these noise learning experiments. These results can then be stored locally as a `NoiseLearnerResult` and used as input in later experiments. This page provides an overview of its usage and the associated options available.\n", "\n", "\n", "## Overview\n", "\n", - "The `NoiseLearner` class performs experiments that characterize noise processes based on a Pauli-Lindblad noise model for one (or more) circuits. It possesses a `run()` method that executes the learning experiments and takes as input either a list of circuits or a [PUB](./primitive-input-output#overview-of-pubs), and returns a `NoiseLearnerResult` containing the learned noise channels and metadata about the job(s) submitted. Below is a code snippet demonstrating the usage of the helper program." + "The `NoiseLearner` class performs experiments that characterize noise processes based on a Pauli-Lindblad noise model for one (or more) circuits. It possesses a `run()` method that executes the learning experiments and takes as input either a list of circuits or a [PUB](/docs/guides/primitive-input-output), and returns a `NoiseLearnerResult` containing the learned noise channels and metadata about the job(s) submitted. Below is a code snippet demonstrating the usage of the helper program." ] }, { @@ -347,10 +347,9 @@ "## Next steps\n", "\n", "\n", - " - Read more about [configuring error mitigation](configure-error-mitigation).\n", " - Review the [EstimatorOptions API reference](/docs/api/qiskit-ibm-runtime/options-estimator-options) and [ResilienceOptionsV2 API reference](/docs/api/qiskit-ibm-runtime/options-resilience-options-v2).\n", " - Learn more about [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) that are available through Qiskit Runtime.\n", - " - Review how to [Specify options](specify-runtime-options) for the Qiskit Runtime primitives.\n", + " - Learn how to implement [Estimator noise management](/docs/guides/estimator-noise-management).\n", " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", "" ] diff --git a/docs/guides/online-lab-environments.mdx b/docs/guides/online-lab-environments.mdx index a4f11e53710..68f62034e2d 100644 --- a/docs/guides/online-lab-environments.mdx +++ b/docs/guides/online-lab-environments.mdx @@ -26,7 +26,7 @@ OVHcloud AI notebooks are not available in some regions, such as the United Stat Follow these steps to get started: -1. [Create an IBM Cloud account](./cloud-setup). +1. [Create an IBM Cloud account](/docs/guides/cloud-setup). 1. [Set up an OVHcloud account](https://help.ovhcloud.com/csm/en-account-create-ovhcloud-account?id=kb_article_view&sysparm_article=KB0043022). 2. [Create an OVH Public Cloud project](https://support.us.ovhcloud.com/hc/en-us/articles/360002245784-Creating-Your-First-Public-Cloud-Project). 6. Follow the steps in [Launch your first AI Notebook](https://help.ovhcloud.com/csm/en-public-cloud-ai-notebooks-definition?id=kb_article_view&sysparm_article=KB0048270), selecting **Qiskit** for the framework. diff --git a/docs/guides/operator-class.ipynb b/docs/guides/operator-class.ipynb index 511d787313f..6d341990945 100644 --- a/docs/guides/operator-class.ipynb +++ b/docs/guides/operator-class.ipynb @@ -48,7 +48,7 @@ "id": "eb4d8e3f-5efb-4223-a15b-d6ef541370dc", "metadata": {}, "source": [ - "This page shows how to use the [`Operator`](/docs/api/qiskit/qiskit.quantum_info.Operator) class. For a high-level overview of operator representations in Qiskit, including the `Operator` class and others, see [Overview of operator classes](./operators-overview)." + "This page shows how to use the [`Operator`](/docs/api/qiskit/qiskit.quantum_info.Operator) class. For a high-level overview of operator representations in Qiskit, including the `Operator` class and others, see [Overview of operator classes](/docs/guides/operators-overview)." ] }, { diff --git a/docs/guides/operators-overview.ipynb b/docs/guides/operators-overview.ipynb index d1f025ed15e..afe905e4370 100644 --- a/docs/guides/operators-overview.ipynb +++ b/docs/guides/operators-overview.ipynb @@ -523,9 +523,9 @@ "## Next steps\n", "\n", "\n", - " - Learn how to [specify observables in the Pauli basis](./specify-observables-pauli).\n", + " - Learn how to [specify observables in the Pauli basis](/docs/guides/specify-observables-pauli).\n", " - See an example of using operators in the [Combine error mitigation options with the Estimator primitive](/docs/tutorials/combine-error-mitigation-techniques) tutorial.\n", - " - Read more [in-depth coverage of the Operator class](./operator-class).\n", + " - Read more [in-depth coverage of the Operator class](/docs/guides/operator-class).\n", " - Explore the [Operator API](/docs/api/qiskit/qiskit.quantum_info.Operator#operator) reference.\n", "" ] diff --git a/docs/guides/primitive-input-output.ipynb b/docs/guides/primitive-input-output.ipynb index 79425c994de..8c84d1ce155 100644 --- a/docs/guides/primitive-input-output.ipynb +++ b/docs/guides/primitive-input-output.ipynb @@ -167,6 +167,7 @@ "id": "3acc54a9-ab50-4155-9c2d-c6a75dba816d", "metadata": {}, "source": [ + "\n", "### Broadcasting rules\n", "\n", "The PUBs aggregate elements from multiple arrays (observables and parameter values) by following the same broadcasting rules as NumPy. This section briefly summarizes those rules. For a detailed explanation, see the [NumPy broadcasting rules documentation](https://numpy.org/doc/stable/user/basics.broadcasting.html).\n", @@ -218,7 +219,7 @@ "\n", " - *Example 4*: (Standard nd generalization) has a 3x6 parameter value set array and two 3x1 observables array. These combine to create two 3x6 output arrays in a similar manner to the previous example.\n", "\n", - "![This image illustrates several visual representations of array broadcasting.](/docs/images/guides/primitive-input-output/broadcasting.svg \"Visual representation of broadcasting\")" + "![This image illustrates several visual representations of array broadcasting.](/docs/images/guides/primitive-input-output/broadcasting.avif \"Visual representation of broadcasting\")" ] }, { @@ -308,7 +309,8 @@ " └── PrimitiveResult\n", " ├── PubResult[0]\n", " │ ├── metadata\n", - " │ └── data ## In the form of a DataBin object, which includes data such as the following:\n", + " │ └── data ## In the form of a DataBin object,\n", + " | | ## which includes data such as the following:\n", " │ ├── evs\n", " │ │ └── List of estimated expectation values in the shape\n", " | | specified by the first pub\n", @@ -317,7 +319,8 @@ " | same shape as above\n", " ├── PubResult[1]\n", " | ├── metadata\n", - " | └── data ## In the form of a DataBin object, which includes data such as the following:\n", + " | └── data ## In the form of a DataBin object,\n", + " | | ## which includes data such as the following:\n", " | ├── evs\n", " | │ └── List of estimated expectation values in the shape\n", " | | specified by the second pub\n", diff --git a/docs/guides/primitives-examples.ipynb b/docs/guides/primitives-examples.ipynb deleted file mode 100644 index 5f547b0e9f2..00000000000 --- a/docs/guides/primitives-examples.ipynb +++ /dev/null @@ -1,707 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "1f4a2ec4-3595-4300-8f9e-092b0ef9b444", - "metadata": {}, - "source": [ - "---\n", - "title: Primitives examples\n", - "description: Practical examples of using primitives in Qiskit Runtime.\n", - "---\n", - "\n", - "\n", - "# Primitives examples" - ] - }, - { - "cell_type": "markdown", - "id": "39d61c25", - "metadata": {}, - "source": [ - "\n", - "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "b4121e48", - "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", - "\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.1\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "bae32e60", - "metadata": {}, - "source": [ - "The examples in this section illustrate some common ways to use primitives. Before running these examples, follow the instructions in [Install and set up](install-qiskit).\n", - "\n", - "\n", - " These examples all use the primitives from Qiskit Runtime, but you could use the base primitives instead.\n", - "\n", - "\n", - "## Estimator examples\n", - "\n", - "Efficiently calculate and interpret expectation values of the quantum operators required for many algorithms with Estimator. Explore uses in molecular modeling, machine learning, and complex optimization problems.\n", - "\n", - "### Run a single experiment\n", - "\n", - "Use Estimator to determine the expectation value of a single circuit-observable pair." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "24573866-7cf2-40e1-b61c-a2bdcecb759b", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > Expectation value: 0.02001953125\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", - "\n", - "n_qubits = 50\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "mat = np.real(random_hermitian(n_qubits, seed=1234))\n", - "circuit = iqp(mat)\n", - "observable = SparsePauliOp(\"Z\" * 50)\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "isa_circuit = pm.run(circuit)\n", - "isa_observable = observable.apply_layout(isa_circuit.layout)\n", - "\n", - "estimator = Estimator(mode=backend)\n", - "job = estimator.run([(isa_circuit, isa_observable)])\n", - "result = job.result()\n", - "\n", - "print(f\" > Expectation value: {result[0].data.evs}\")\n", - "print(f\" > Metadata: {result[0].metadata}\")" - ] - }, - { - "cell_type": "markdown", - "id": "63769604-ec9e-4ff3-823d-e60f4eb8a877", - "metadata": {}, - "source": [ - "### Run multiple experiments in a single job\n", - "\n", - "Use Estimator to determine the expectation values of multiple circuit-observable pairs." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "bf4668bd-aaaf-4b23-af4b-4df767bd6d1a", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Expectation values for PUB 0: 0.38653001464128844\n", - ">>> Standard errors for PUB 0: 0.38171892296606086\n", - ">>> Expectation values for PUB 1: 0.16101694915254236\n", - ">>> Standard errors for PUB 1: 0.275264141479697\n", - ">>> Expectation values for PUB 2: -0.38052095130237823\n", - ">>> Standard errors for PUB 2: 0.23890904884822026\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", - "\n", - "n_qubits = 50\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "rng = np.random.default_rng()\n", - "mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]\n", - "\n", - "pubs = []\n", - "circuits = [iqp(mat) for mat in mats]\n", - "observables = [\n", - " SparsePauliOp(\"X\" * 50),\n", - " SparsePauliOp(\"Y\" * 50),\n", - " SparsePauliOp(\"Z\" * 50),\n", - "]\n", - "\n", - "# Get ISA circuits\n", - "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", - "\n", - "for qc, obs in zip(circuits, observables):\n", - " isa_circuit = pm.run(qc)\n", - " isa_obs = obs.apply_layout(isa_circuit.layout)\n", - " pubs.append((isa_circuit, isa_obs))\n", - "\n", - "estimator = Estimator(backend)\n", - "job = estimator.run(pubs)\n", - "job_result = job.result()\n", - "\n", - "for idx in range(len(pubs)):\n", - " pub_result = job_result[idx]\n", - " print(f\">>> Expectation values for PUB {idx}: {pub_result.data.evs}\")\n", - " print(f\">>> Standard errors for PUB {idx}: {pub_result.data.stds}\")" - ] - }, - { - "cell_type": "markdown", - "id": "60bf051a-40f8-47a9-b74d-38713bc15210", - "metadata": {}, - "source": [ - "### Run parameterized circuits\n", - "\n", - "Use Estimator to run three experiments in a single job, leveraging parameter values to increase circuit reusability." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "67dc98b8-499c-44d9-ada1-6abc9d6198c0", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - ">>> Expectation values: [[ 1.14303016 1.09293387 0.91230895 0.67462992 0.3645896 0.01586382\n", - " -0.32673908 -0.66572392 -0.89950657 -1.05647491 -1.11686876 -1.05257854\n", - " -0.898115 -0.66600223 -0.36792936 -0.03590234 0.3448294 0.65292154\n", - " 0.87946805 1.08653268 1.13384584]\n", - " [ 0.00194819 0.35039566 0.69355519 0.90256801 1.0561966 1.13384584\n", - " 1.05870142 0.91091739 0.64679866 0.31449332 -0.0242132 -0.34816916\n", - " -0.6543131 -0.94459322 -1.07122549 -1.12688802 -1.07289536 -0.9003415\n", - " -0.6565396 -0.34816916 0.03423246]\n", - " [ 0.03311921 -0.2986295 -0.58584818 -0.7926345 -0.93513059 -1.00081238\n", - " -0.96407511 -0.81990914 -0.60533007 -0.31532826 0.01196745 0.29807287\n", - " 0.56386148 0.78623331 0.93485228 0.98801 0.94153178 0.8079417\n", - " 0.60338188 0.32590414 0.01085419]\n", - " [ 0.99858588 0.9462631 0.78734656 0.57165423 0.30224757 -0.04035534\n", - " -0.33314027 -0.58863131 -0.81295132 -0.96045704 -1.01918102 -0.93290409\n", - " -0.82046577 -0.57248917 -0.29946444 -0.00890601 0.31811139 0.59558912\n", - " 0.82853683 0.96574498 1.00749188]]\n", - ">>> Standard errors: [[0.01054453 0.0090488 0.01470321 0.01431899 0.01458752 0.01594555\n", - " 0.01726554 0.01424188 0.01419258 0.01067802 0.01001923 0.01251587\n", - " 0.01116998 0.01531783 0.01449673 0.01646155 0.01646433 0.01360378\n", - " 0.01122004 0.01196567 0.01024229]\n", - " [0.01445745 0.01549534 0.01358938 0.01313319 0.00988315 0.00969048\n", - " 0.01064806 0.01322978 0.01255456 0.01452464 0.01487265 0.01730187\n", - " 0.01380378 0.01469336 0.01109645 0.01090259 0.00959465 0.01011457\n", - " 0.01501227 0.01379471 0.01569855]\n", - " [0.01664737 0.015471 0.01376998 0.01327565 0.01178408 0.00932035\n", - " 0.00974169 0.01339822 0.01515222 0.01650666 0.0214757 0.01758876\n", - " 0.01600469 0.01258592 0.01263352 0.0115907 0.0100297 0.01192499\n", - " 0.01553377 0.01850343 0.01676476]\n", - " [0.0140702 0.01061445 0.01177151 0.01647518 0.01465258 0.01621293\n", - " 0.01357167 0.01093029 0.010674 0.00991755 0.01179354 0.00989959\n", - " 0.01050795 0.01555365 0.01180389 0.01547085 0.01348899 0.01383537\n", - " 0.01139017 0.01190014 0.00922421]]\n", - ">>> Metadata: {'shots': 10016, 'target_precision': 0.01, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "\n", - "from qiskit.circuit import QuantumCircuit, Parameter\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)\n", - "\n", - "# Step 1: Map classical inputs to a quantum problem\n", - "theta = Parameter(\"θ\")\n", - "\n", - "chsh_circuit = QuantumCircuit(2)\n", - "chsh_circuit.h(0)\n", - "chsh_circuit.cx(0, 1)\n", - "chsh_circuit.ry(theta, 0)\n", - "\n", - "number_of_phases = 21\n", - "phases = np.linspace(0, 2 * np.pi, number_of_phases)\n", - "individual_phases = [[ph] for ph in phases]\n", - "\n", - "ZZ = SparsePauliOp.from_list([(\"ZZ\", 1)])\n", - "ZX = SparsePauliOp.from_list([(\"ZX\", 1)])\n", - "XZ = SparsePauliOp.from_list([(\"XZ\", 1)])\n", - "XX = SparsePauliOp.from_list([(\"XX\", 1)])\n", - "ops = [ZZ, ZX, XZ, XX]\n", - "\n", - "# Step 2: Optimize problem for quantum execution.\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "chsh_isa_circuit = pm.run(chsh_circuit)\n", - "isa_observables = [\n", - " operator.apply_layout(chsh_isa_circuit.layout) for operator in ops\n", - "]\n", - "\n", - "# Step 3: Execute using Qiskit primitives.\n", - "\n", - "# Reshape observable array for broadcasting\n", - "reshaped_ops = np.fromiter(isa_observables, dtype=object)\n", - "reshaped_ops = reshaped_ops.reshape((4, 1))\n", - "\n", - "estimator = Estimator(backend, options={\"default_shots\": int(1e4)})\n", - "job = estimator.run([(chsh_isa_circuit, reshaped_ops, individual_phases)])\n", - "# Get results for the first (and only) PUB\n", - "pub_result = job.result()[0]\n", - "print(f\">>> Expectation values: {pub_result.data.evs}\")\n", - "print(f\">>> Standard errors: {pub_result.data.stds}\")\n", - "print(f\">>> Metadata: {pub_result.metadata}\")" - ] - }, - { - "cell_type": "markdown", - "id": "793f0ed1-5682-4aa3-a4a0-7baba71650f9", - "metadata": {}, - "source": [ - "### Use sessions and advanced options\n", - "\n", - "Explore sessions and advanced options to optimize circuit performance on QPUs.\n", - "\n", - "\n", - "\n", - "The following code block will return an error for Open Plan users because it uses sessions. Open Plan workloads can run only in [job mode](/docs/guides/execution-modes#job-mode) or [batch mode](/docs/guides/execution-modes#batch-mode).\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "d007b547-8546-4ca3-aee6-9a4e3a82598d", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > Expectation value: -0.001953125\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", - " > Another Expectation value: 0.38454288407163056\n", - " > More Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp, random_hermitian\n", - "from qiskit_ibm_runtime import (\n", - " QiskitRuntimeService,\n", - " Session,\n", - " EstimatorV2 as Estimator,\n", - ")\n", - "\n", - "n_qubits = 50\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "rng = np.random.default_rng(1234)\n", - "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", - "circuit = iqp(mat)\n", - "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", - "another_circuit = iqp(mat)\n", - "observable = SparsePauliOp(\"X\" * 50)\n", - "another_observable = SparsePauliOp(\"Y\" * 50)\n", - "\n", - "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", - "isa_circuit = pm.run(circuit)\n", - "another_isa_circuit = pm.run(another_circuit)\n", - "isa_observable = observable.apply_layout(isa_circuit.layout)\n", - "another_isa_observable = another_observable.apply_layout(\n", - " another_isa_circuit.layout\n", - ")\n", - "\n", - "with Session(backend=backend) as session:\n", - " estimator = Estimator(mode=session)\n", - "\n", - " estimator.options.resilience_level = 1\n", - "\n", - " job = estimator.run([(isa_circuit, isa_observable)])\n", - " another_job = estimator.run(\n", - " [(another_isa_circuit, another_isa_observable)]\n", - " )\n", - " result = job.result()\n", - " another_result = another_job.result()\n", - "\n", - " # first job\n", - " print(f\" > Expectation value: {result[0].data.evs}\")\n", - " print(f\" > Metadata: {result[0].metadata}\")\n", - "\n", - " # second job\n", - " print(f\" > Another Expectation value: {another_result[0].data.evs}\")\n", - " print(f\" > More Metadata: {another_result[0].metadata}\")" - ] - }, - { - "cell_type": "markdown", - "id": "12aea3c7-37a1-4a6b-b944-587669aa6611", - "metadata": {}, - "source": [ - "\n", - "## Sampler examples\n", - "\n", - "Generate entire error-mitigated quasi-probability distributions sampled from quantum circuit outputs. Leverage Sampler’s capabilities for search and classification algorithms like Grover’s and QVSM.\n", - "\n", - "### Run a single experiment\n", - "\n", - "Use Sampler to return the measurement outcome as bitstrings or counts of a single circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "a5a561b3-3819-4f9e-bb64-4c27267e0e96", - "metadata": { - "scrolled": true - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > First ten results: ['1111100010001110101110110001011111001000110110001000010000001100100010001000000001110001011001101011000100100100000101010000010', '0111001010111001011101001010001110100111010000111001001011010000111110011001110000010100101001100000010010000000100000011110000', '0101001010101000010000100000011001001100010110011010010000100001001100111000001000001001110101100010000011000101001000000101011', '0001100111101101010111000100010010101110101001010000001000010100000010011101100011100000101011001010111110110000000110011010000', '1100100001000111101001000010011111000010101001100101010010110100011011100001000000010001010110001001010011001001011110011101101', '1100010001010110110100100110010010001101000001000011011000011000011111101000011010110001100000000000000100000011011000110011101', '0100011101000111110110010000001011111110110100101010010010000011010000101010111001010111100010010001010101001100000001000000000', '0011001100011000000111100110000000101101100000111001001011010100000000000101011100010011010001110100100101000000000100110000000', '0011100000111011110110001001000101010001110001100010010111001101000100111101111010111000011100000010010001011000011000100100101', '1110101100000100000000001001001000101000011100101011011000001000010100000100001011000010000000000001011110011000001000100100101']\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import random_hermitian\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", - "\n", - "n_qubits = 127\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "mat = np.real(random_hermitian(n_qubits, seed=1234))\n", - "circuit = iqp(mat)\n", - "circuit.measure_all()\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "isa_circuit = pm.run(circuit)\n", - "\n", - "sampler = Sampler(backend)\n", - "job = sampler.run([isa_circuit])\n", - "result = job.result()\n", - "\n", - "# Get results for the first (and only) PUB\n", - "pub_result = result[0]\n", - "\n", - "print(f\" > First ten results: {pub_result.data.meas.get_bitstrings()[:10]}\")" - ] - }, - { - "cell_type": "markdown", - "id": "c9ea6d3c-b03f-49e2-a8de-d32e58396e02", - "metadata": {}, - "source": [ - "### Run multiple experiments in a single job\n", - "\n", - "Use Sampler to return the measurement outcome as bitstrings or counts of multiple circuits in one job." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "e4534da8-9fe3-402b-8afc-f4bd9fbed497", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > First ten results for pub 0: ['0101101010000100000100010010000110111010100110111001010000000100100100000000111101110100001001110010000000110110010011000000000', '1001011110111100100001000000100100011000011000011000001100010101100000110111111010010100000011010000110010000000000000110100101', '0011011100011101101000000110110011101110000100001100000011010001100110100011000101100101100111111000010011100100011011011011001', '0101101110010001000011110001000001011010100000111101110101010100000110000000000100011001001001001101000110101000001010100101000', '1101110010100111100011100010100011000000111100010010001000110000110101010001110001000100001110101110100111111001001001110000001', '0010010011010100101111101001110100010110010101100010111011100000101100001101000001000000101000100111101100100011100000000100100', '1000010101001100001110111111100100110110110101101010110110110101100010000010100101010100100110011100101010110111110001010100110', '0101001011000111001111100100110100011100000000111000111100111100001011100111110011000001000001001000101010111000101100001011100', '1001011011101111111010000010010110111010001110000010100010101100101001100000011001010101000001110110111000110000101010110010101', '1000110100010000111000110100011101111000111010001111100001010001011111000100100101101001110101000111010000110100101010110011001']\n", - " > First ten results for pub 1: ['1100001010111100101001000111111101110100101001010011111100100100100001000000101011010101000000101010101100010001101110010000001', '1001000011000101010101001000100010001101111001111011000000001011000010011011001100010100110000000101100000000001100000011001000', '1100000010101010111001010000011010101101100001100010100011111000110000000000000101101001000000011010000110010011100010000100000', '0001101000011100010000110010000110011111111100010100001100010000101010010010000000010000001000100100010100000000100101110001010', '1100011001010111100101001100100100000111110001100100010110101010010000000110111111000000000100000000100000001001010001011010001', '1010110000001100111100010111110001111011110001111010000010110010010001001001000101011100001100001000000001010001000100010101111', '0010001011000000010000100101010110101001111001100000011011001100001000000001110001010110000101011011100110000000010101000000000', '0001110011101110100000011001101010001000111111000000111100110010000000010101110011000100001100101110111000110100011000000011000', '0101000001101101001000111001010000001001011101000011001000000001011100000001101010010000010000101000110000000011000001000110001', '1110010001000001010001110101000100001011101000000011000100010010110010000001111000000100010100001010000000110000000000001001100']\n", - " > First ten results for pub 2: ['0100110111100000011110100101111100101010011001001000101110000100011011100101100001100000001000010110101001000000011001000010101', '1101000111110101011100000101011011001010000100100000110100100111100100011101100100101011011010100000000100000000001010010001100', '0101000111010111101111100101110101001101100010000100100111110101000010011101000101111001010010110001101000100000001110000000010', '1001100010101010011000100100101101000000000101011110100100100011100000011000011101101010011000001001000101110111000100000000000', '1101001011110111111010100101101110001110001000011000100110110011010010100101100110011001000000011101100000110000000001011000011', '1010000110101101010100000000101001011100000010110001000110000111101110000001100000011001001111110000100000011010000010001000110', '0111000000110101101111000001001010111010100001100011000000100010001000110011100000010001000000100001010000000101101001111000001', '0110000010000110001010101110001111011001100001100001001101010011011100101010001110010010000000100010111101000000001010010010010', '0100001110111110110100001100000001101010000100000000100010110001010010000100010101001011001001010110101001100101000010000000110', '1101100110100000111100011000101100101001011001000100000001001000000011100111101110101000001001000000001000100000111111010011110']\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import random_hermitian\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", - "\n", - "n_qubits = 127\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "rng = np.random.default_rng()\n", - "mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]\n", - "circuits = [iqp(mat) for mat in mats]\n", - "for circuit in circuits:\n", - " circuit.measure_all()\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "isa_circuits = pm.run(circuits)\n", - "\n", - "sampler = Sampler(mode=backend)\n", - "job = sampler.run(isa_circuits)\n", - "result = job.result()\n", - "\n", - "for idx, pub_result in enumerate(result):\n", - " print(\n", - " f\" > First ten results for pub {idx}: {pub_result.data.meas.get_bitstrings()[:10]}\"\n", - " )" - ] - }, - { - "cell_type": "markdown", - "id": "e3ce4f13-b772-4ee6-ba9d-d98da633ab5c", - "metadata": {}, - "source": [ - "### Run parameterized circuits\n", - "\n", - "Run several experiments in a single job, leveraging parameter values to increase circuit reusability." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "c63c9cb6-0650-433c-b3d6-dcde06e465e4", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " >> First ten results for the meas output register: ['0001000011110001011111011000111110100011110001101010011001110000111001101101101101011100010110011100011000101000111010101111100', '0101000000010111011010101000100110010110011000011010011100101000110100001111101110110110110100101011011000110111101111111111101', '1000001001000101000111100011100001001000111101100011001000011100100101101100011011100011100011010101001110100011000010001100111', '0001010100100101010000011110111011101010100101111111000011110010110000000001110110000000011011111100001010011111111111001000111', '1100011010110111010011110000101110110010101001001000100111010111111100001101101000010010000100000000001010010000011100100110000', '0100110000000111101100100010001110010100000101001010001000100111111011101110011001011110100010000000001111100100111000010101111', '1000110100000101010011011011110011001010001001001001110000011010010010001111110011100000000011110000001111000011011111111010111', '0001101010010101111000010100110110110001100111100100101010010011100110101000100111010110110000110010001101000100101010111100001', '1100010000011011010000100111100010000000110001010001001100100010111100000111001100010000010000110000000100010100000010001110110', '0000010000001101001000100101000010110010001101100011010000011001010001110011111100001111000100001100001001110110110100101101000']\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import real_amplitudes\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", - "\n", - "n_qubits = 127\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "# Step 1: Map classical inputs to a quantum problem\n", - "circuit = real_amplitudes(num_qubits=n_qubits, reps=2)\n", - "circuit.measure_all()\n", - "\n", - "# Define three sets of parameters for the circuit\n", - "rng = np.random.default_rng(1234)\n", - "parameter_values = [\n", - " rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)\n", - "]\n", - "\n", - "# Step 2: Optimize problem for quantum execution.\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "isa_circuit = pm.run(circuit)\n", - "\n", - "# Step 3: Execute using Qiskit primitives.\n", - "sampler = Sampler(backend)\n", - "job = sampler.run([(isa_circuit, parameter_values)])\n", - "result = job.result()\n", - "# Get results for the first (and only) PUB\n", - "pub_result = result[0]\n", - "# Get counts from the classical register \"meas\".\n", - "print(\n", - " f\" >> First ten results for the meas output register: {pub_result.data.meas.get_bitstrings()[:10]}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "a8b00d2a-3c5d-4670-9774-d39cdb262552", - "metadata": {}, - "source": [ - "### Use sessions and advanced options\n", - "\n", - "Explore sessions and advanced options to optimize circuit performance on QPUs.\n", - "\n", - "\n", - "\n", - "The following code block will return an error for users on the Open Plan, because it uses sessions. Workloads on the Open Plan can run only in [job mode](/docs/guides/execution-modes#job-mode) or [batch mode](/docs/guides/execution-modes#batch-mode).\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "881fdac4-973b-4cef-a3da-c011d326ff54", - "metadata": { - "scrolled": true - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > The first ten measurement results of job 1: ['1100100101010110001101011100100000000000001101010001100111001011000000110111000001010001000000001101100100000100000101011100101', '0011111000001111010100111010010001000010010001010100100111010000000110011100011011000000111010000000100100000100100011001101001', '0001001111110011010001010010100001000110110000101111010010100100100111010010000001110010110100011000010100000001110000111101111', '1110110110100011011101110111000011011101000101110010000001111010001010110010010100010001001101000110110000110100101001011101100', '1010110101000010000010001011101010000000100001011100101101110100100101010010001101001001000010100110001100110000111011111010001', '0111111010101011011100001010110110011100011101101110010100100001000000000100000110000110100110001000000101100000100110000011000', '0011101011101110001001010100111001000011100000010010101010001100000101000000000100001100001011110100100000011100010010010001010', '0100011101010000011100110111110011111010001110011110000100000101000110000011100101011011010110000101110100100100000001111110000', '1010000000011101000010011000100011001010111101011101010100101000100000110010111110011000101011100100000000011101110001011011000', '0001001011101110010001001010110010101010110000000100110000000110100000100101100001001001011001010000000010000011000010000101001']\n" - ] - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import iqp\n", - "from qiskit.quantum_info import random_hermitian\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime import Session, SamplerV2 as Sampler\n", - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "n_qubits = 127\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=n_qubits\n", - ")\n", - "\n", - "rng = np.random.default_rng(1234)\n", - "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", - "circuit = iqp(mat)\n", - "circuit.measure_all()\n", - "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", - "another_circuit = iqp(mat)\n", - "another_circuit.measure_all()\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "isa_circuit = pm.run(circuit)\n", - "another_isa_circuit = pm.run(another_circuit)\n", - "\n", - "with Session(backend=backend) as session:\n", - " sampler = Sampler(mode=session)\n", - " job = sampler.run([isa_circuit])\n", - " another_job = sampler.run([another_isa_circuit])\n", - " result = job.result()\n", - " another_result = another_job.result()\n", - "\n", - "# first job\n", - "\n", - "print(\n", - " f\" > The first ten measurement results of job 1: {result[0].data.meas.get_bitstrings()[:10]}\"\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "40fe2a06-edfc-41a8-9054-7f31ab93a00c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > The first ten measurement results of job 2: ['1110010001111100001001110100000111101100100100001010011010000100111001101111000001000000101101000001010001001001000100000110000', '1000000000100001011100100010101111010111001001100100101001011110110110000101010001100100100000011011001101001000000010010000001', '1100101100010100011011000010001010111011000001100010110101001010000010000000010010000111110001000010010011101010101000010010000', '0100101111001101100111000000001100100011001011011110010101001000101000000000001100001010010101000110100101100000011000011000000', '0111010010100001011011100010001011011100101001111011101011000000000100010001000100100010110101011010101100000010010000010111000', '0100010010000100101100001100011001101100110010100000101010010100100011100000000100001001000101111000100010001100100000010000011', '0011001101001001011011000101101101100000110111111110100000000101101110110001001000100001011111010001011100101010000100010000000', '1100101100000000111110010010000000011101010110110110000011000010100010000001110110010001100010000110001010000000000000101100000', '1000011001011100111101000011100100001100111101101011010011010110011011110110001111111000100100010010001100001001100001011000101', '0000101100000110001000010110111010011100010101011011001001010000101110100010101110000011010000010110011101000000101001010000000']\n" - ] - } - ], - "source": [ - "# second job\n", - "print(\n", - " \" > The first ten measurement results of job 2:\",\n", - " another_result[0].data.meas.get_bitstrings()[:10],\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "551e1894-a12a-4f6c-8347-020fdc9db74e", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - [Specify advanced runtime options](runtime-options-overview).\n", - " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", - " - Learn how to transpile locally in the [Transpile](./transpile/) section.\n", - " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n", - " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", - " - Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM® QPU.\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/primitives-rest-api.ipynb b/docs/guides/primitives-rest-api.ipynb deleted file mode 100644 index 7b44c264689..00000000000 --- a/docs/guides/primitives-rest-api.ipynb +++ /dev/null @@ -1,1132 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "0998165a-381f-4561-a79a-bf584aed9687", - "metadata": {}, - "source": [ - "---\n", - "title: Primitives with REST API\n", - "description: How to use the Sampler and Estimator primitives with Qiskit Runtime REST API.\n", - "---\n", - "\n", - "\n", - "{/* cspell:ignore IIZII, XIZZZ, accum, WQVY, urlencoded */}\n", - "\n", - "# Primitives with REST API" - ] - }, - { - "cell_type": "markdown", - "id": "da948b6b-2ead-4359-aed4-b824e43ccbfb", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] - }, - { - "cell_type": "markdown", - "id": "95673fe9-23fa-44a0-a9a5-aa968b146b30", - "metadata": {}, - "source": [ - "The steps in this topic describe how to run and configure primitive workloads with the Qiskit Runtime REST API, and demonstrate how to invoke them in any program of your choice.\n", - "\n", - "\n", - " This documentation utilizes the Python `requests` module to demonstrate the Qiskit Runtime REST API. However, this workflow can be executed using any language or framework that supports working with REST APIs. Refer to the [API reference documentation](/docs/api/qiskit-ibm-runtime/tags/jobs) for details.\n", - "\n", - "\n", - "\n", - "## Estimator primitive with REST API\n", - "\n", - "### 1. Initialize the account\n", - "\n", - "Because Qiskit Runtime Estimator is a managed service, you first need to initialize your account. You can then select the device you want to use to calculate the expectation value.\n", - "\n", - "You will also need a bearer token. This is a short-lived token (different from an API key) which is used to authenticate requests to the REST API. To generate one, call the [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-api#create-api-key) as shown in the following sample request:\n", - "\n", - "\n", - "\n", - " \n", - " ```bash\n", - " curl -X POST 'https://iam.cloud.ibm.com/identity/token' \\\n", - " -H 'Content-Type: application/x-www-form-urlencoded' \\\n", - " -d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'\n", - " ```\n", - " Expected Response\n", - " ```text\n", - " {\n", - " \"access_token\": \"eyJhbGciOiJIUz......sgrKIi8hdFs\",\n", - " \"refresh_token\": \"SPrXw5tBE3......KBQ+luWQVY=\",\n", - " \"token_type\": \"Bearer\",\n", - " \"expires_in\": 3600,\n", - " \"expiration\": 1473188353\n", - " }\n", - " ```\n", - " \n", - "\n", - " \n", - " ```python\n", - " # Use 'service' to invoke operations.\n", - " import requests\n", - " import json\n", - "\n", - " url = 'https://iam.cloud.ibm.com/identity/token'\n", - " api_key = 'MY_APIKEY'\n", - " headers = {\n", - " 'Content-Type': 'application/x-www-form-urlencoded',\n", - " }\n", - " data = f'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={api_key}'\n", - " response = requests.post(url, headers=headers, data=data)\n", - "\n", - " # Bearer token to authorize requests to the REST API\n", - " bearer_token = response.json()['access_token']\n", - " ```\n", - " \n", - "\n", - "\n", - "For other details on how to initialize your account, view available backends, and validate tokens, read this [topic](/docs/guides/cloud-setup-rest-api).\n", - "\n", - "### 2. Create a QASM circuit\n", - "\n", - "You need at least one circuit as the input to the Estimator primitive.\n", - "\n", - "Define a QASM quantum circuit. For example:" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "14f31039-6726-47f2-91f2-c99644a9f8b1", - "metadata": {}, - "outputs": [], - "source": [ - "qasm_string = \"\"\"\n", - "OPENQASM 3.0;\n", - "include \"stdgates.inc\";\n", - "bit[2] meas;\n", - "rz(pi/2) $1;\n", - "sx $1;\n", - "rz(pi) $1;\n", - "x $2;\n", - "cz $2, $1;\n", - "sx $1;\n", - "rz(pi/2) $1;\n", - "\"\"\"" - ] - }, - { - "cell_type": "markdown", - "id": "5a7c5586-4fe6-4205-b35d-1a4a8a9df13d", - "metadata": {}, - "source": [ - "### 3. Run the quantum circuit using the Estimator V2 API\n", - "You'll need to replace `auth_id`, `crn`, and `backend` with the appropriate values.\n", - "\n", - "```python\n", - "\n", - "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", - "auth_id = \"Bearer \"\n", - "crn = \"\"\n", - "backend = \"\"\n", - "```" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "7d9988ed-69da-4102-b43e-8fda4176543b", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Code hidden from users to collect authentication credentials\n", - "import requests\n", - "import time\n", - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "url = \"https://quantum.cloud.ibm.com/api/v1/jobs\"\n", - "service = QiskitRuntimeService()\n", - "crn = service.active_account()[\"instance\"]\n", - "token = service.active_account()[\"token\"]\n", - "backend = service.least_busy().name\n", - "\n", - "header = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n", - "data = \"grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=\" + token\n", - "\n", - "response = requests.post(\n", - " \"https://iam.cloud.ibm.com/identity/token\", headers=header, data=data\n", - ")\n", - "auth_id = \"Bearer \" + response.json()[\"access_token\"]\n", - "\n", - "\n", - "def wait_for_results(url, job_id, headers):\n", - " timeout = 600\n", - " start_time = time.time()\n", - " job_status = requests.get(url + \"/\" + job_id, headers=headers)\n", - " status = job_status.json().get(\"state\")[\"status\"]\n", - " while status != \"Completed\":\n", - " if time.time() - start_time > timeout:\n", - " break\n", - " time.sleep(10)\n", - " job_status = requests.get(url + \"/\" + job_id, headers=headers)\n", - " status = job_status.json().get(\"state\")[\"status\"]" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "80a40f86-ba8e-4520-8127-eaf64d51b331", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Job created: {\"id\":\"d6147q3traac73bef6f0\",\"backend\":\"ibm_pittsburgh\"}\n" - ] - } - ], - "source": [ - "headers = {\n", - " \"Content-Type\": \"application/json\",\n", - " \"Authorization\": auth_id,\n", - " \"Service-CRN\": crn,\n", - "}\n", - "\n", - "job_input = {\n", - " \"program_id\": \"estimator\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"version\": \"2\",\n", - " \"pubs\": [ # primitive unified blocs (PUBs) containing one circuit each.\n", - " [\n", - " qasm_string, # QASM circuit\n", - " {\"IZI\": 1, \"IXI\": 2.3}, # Observable\n", - " None, # parameter values\n", - " ]\n", - " ],\n", - " },\n", - "}\n", - "\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "markdown", - "id": "f4f6b217-ed78-4a56-8329-aa0387215b6f", - "metadata": {}, - "source": [ - "### 4. Check job status and get results\n", - "\n", - "Next, pass the `job_id` to the API:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "625431da-32b8-4517-823b-ab2c86ddbd9d", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'status': 'Queued'}" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "response_status_singlejob = requests.get(url + \"/\" + job_id, headers=headers)\n", - "response_status_singlejob.json().get(\"state\")" - ] - }, - { - "cell_type": "markdown", - "id": "3814b809-3012-4498-adc8-efa1f1f5c959", - "metadata": {}, - "source": [ - "Once the job has completed, get job results:" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "b233f6ef-2e16-4084-b6e3-f51368089300", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Hide this cell for testing\n", - "\n", - "wait_for_results(url, job_id, headers)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "cb892f6f-755f-4d3d-aa7c-58192f34bd09", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "[{'data': {'evs': -0.9374102500618965, 'stds': 0.030982815700848845, 'ensemble_standard_error': 0.03686001673650654}, 'metadata': {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}}]\n" - ] - } - ], - "source": [ - "response_result = requests.get(\n", - " url + \"/\" + job_id + \"/results\", headers=headers\n", - ")\n", - "\n", - "res_dict = response_result.json()\n", - "\n", - "estimator_result = res_dict[\"results\"]\n", - "print(estimator_result)" - ] - }, - { - "cell_type": "markdown", - "id": "9b00a981-26d6-4526-998b-e13a16a515f2", - "metadata": {}, - "source": [ - "### 5. Work with Runtime options\n", - "\n", - "Error mitigation techniques allow users to mitigate circuit errors by modeling the device noise at the time of execution. This typically results in quantum pre-processing overhead related to model training, and classical post-processing overhead to mitigate errors in the raw results by using the generated model.\n", - "\n", - "The error mitigation techniques built in to primitives are advanced resilience options. To specify these options, use the `resilience_level` option when submitting your job.\n", - "\n", - "The following examples demonstrate the default options for dynamical decoupling, twirling, and TREX + ZNE. Find more options and further details in the [Error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) topic.\n", - "\n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "245d1cab-dd0f-4eff-a27f-a65e529a7fde", - "metadata": { - "tags": [ - "id-zne-options" - ] - }, - "outputs": [], - "source": [ - "job_input = {\n", - " \"program_id\": \"estimator\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [ # primitive unified blocs (PUBs) containing one circuit each.\n", - " [\n", - " qasm_string, # QASM circuit\n", - " {\"IZI\": 1, \"IXI\": 2.3}, # Observable\n", - " None, # parameter values\n", - " ]\n", - " ],\n", - " \"version\": \"2\",\n", - " \"options\": {\n", - " \"resilience\": {\n", - " \"measure_mitigation\": True,\n", - " \"zne_mitigation\": True,\n", - " \"zne\": {\n", - " \"extrapolator\": [\"exponential\", \"linear\"],\n", - " \"noise_factors\": [1, 3, 5],\n", - " },\n", - " },\n", - " },\n", - " },\n", - "}\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e8b41557-bebb-4ada-979a-f187eea07b4d", - "metadata": { - "tags": [ - "id-dd-estimator-options" - ] - }, - "outputs": [], - "source": [ - "job_input = {\n", - " \"program_id\": \"estimator\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [ # primitive unified blocs (PUBs) containing one circuit each.\n", - " [\n", - " qasm_string, # QASM circuit\n", - " {\"IZI\": 1, \"IXI\": 2.3}, # Observable\n", - " None, # parameter values\n", - " ]\n", - " ],\n", - " \"version\": \"2\",\n", - " \"options\": {\n", - " \"dynamical_decoupling\": {\n", - " \"enable\": True,\n", - " \"sequence_type\": \"XpXm\",\n", - " \"extra_slack_distribution\": \"middle\",\n", - " \"scheduling_method\": \"alap\",\n", - " },\n", - " },\n", - " },\n", - "}\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "839fe813-ff5f-4f86-abb6-0b58dc5fdb7e", - "metadata": { - "tags": [ - "id-twirling-estimator-options" - ] - }, - "outputs": [], - "source": [ - "job_input = {\n", - " \"program_id\": \"estimator\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [ # primitive unified blocs (PUBs) containing one circuit each.\n", - " [\n", - " qasm_string, # QASM circuit\n", - " {\"IZI\": 1, \"IXI\": 2.3}, # Observable\n", - " None, # parameter values\n", - " ]\n", - " ],\n", - " \"version\": \"2\",\n", - " \"options\": {\n", - " \"twirling\": {\n", - " \"enable_gates\": True,\n", - " \"enable_measure\": True,\n", - " \"num_randomizations\": \"auto\",\n", - " \"shots_per_randomization\": \"auto\",\n", - " \"strategy\": \"active-accum\",\n", - " },\n", - " },\n", - " },\n", - "}\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "66ed7e3f-1cb7-437a-bf87-1afd29e099c5", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Cancel job immediately after since the example doesn't use it\n", - "job = service.job(job_id)\n", - "job.cancel()" - ] - }, - { - "cell_type": "markdown", - "id": "5e27e5f9-f65c-4fc3-bb04-d36be4cdf982", - "metadata": {}, - "source": [ - "\n", - "## Sampler primitive with REST API\n", - "\n", - "### 1. Initialize the account\n", - "\n", - "Because Qiskit Runtime Sampler is a managed service, you first need to initialize your account. You can then select the device you want to use to run your calculations on.\n", - "\n", - "You will also need a bearer token, which can be generated using the [instructions above](#1-initialize-the-account). You can also find more information about generating bearer tokens in the [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-api#create-api-key) documentation.\n", - "\n", - "For other details on how to initialize your account, view available backends, and validate tokens, read this [topic](/docs/guides/cloud-setup-rest-api).\n", - "\n", - "\n", - "### 2. Create a QASM circuit\n", - "\n", - "You need at least one circuit as the input to the Sampler primitive.\n", - "\n", - "\n", - "Define a QASM quantum circuit:" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "b450d383-c708-4555-8c11-ec2480a5dd37", - "metadata": {}, - "outputs": [], - "source": [ - "qasm_string = \"\"\"\n", - "OPENQASM 3.0;\n", - "include \"stdgates.inc\";\n", - "bit[2] meas;\n", - "rz(pi/2) $1;\n", - "sx $1;\n", - "rz(pi) $1;\n", - "x $2;\n", - "cz $2, $1;\n", - "sx $1;\n", - "rz(pi/2) $1;\n", - "meas[0] = measure $1;\n", - "meas[1] = measure $2;\n", - "\"\"\"" - ] - }, - { - "cell_type": "markdown", - "id": "d5a41639-0087-4c1a-90dc-d3a1821cc7a7", - "metadata": {}, - "source": [ - "### 3. Run the quantum circuit using Sampler V2 API\n", - "\n", - "\n", - "\n", - " The jobs below use [Qiskit Runtime V2 primitives](/docs/guides/v2-primitives). Both `SamplerV2` and `EstimatorV2` take one or more primitive unified blocs (PUBs) as the input. Each PUB is a tuple that contains one circuit and the data broadcasted to that circuit, which can be multiple observables and parameters. Each PUB returns a result.\n", - "\n", - "\n", - "You'll need to replace `auth_id`, `crn`, and `backend` with the appropriate values.\n", - "\n", - "```python\n", - "\n", - "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", - "auth_id = \"Bearer \"\n", - "crn = \"\"\n", - "backend = \"\"\n", - "```" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "61bccee0-e7e2-4306-8bc9-d8f3f81460dd", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Job created: {\"id\":\"d6147vio8gvs73f0h130\",\"backend\":\"ibm_pittsburgh\"}\n" - ] - } - ], - "source": [ - "headers = {\n", - " \"Content-Type\": \"application/json\",\n", - " \"Authorization\": auth_id,\n", - " \"Service-CRN\": crn,\n", - "}\n", - "job_input = {\n", - " \"program_id\": \"sampler\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [\n", - " [qasm_string],\n", - " [qasm_string, None, 500],\n", - " ], # primitive unified blocs (PUBs) containing one circuit each.\n", - " \"version\": \"2\",\n", - " },\n", - "}\n", - "\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "3e853562-281f-4be5-b7d7-2d4513572d43", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Cancel job immediately after since the example doesn't use it\n", - "job = service.job(job_id)\n", - "job.cancel()" - ] - }, - { - "cell_type": "markdown", - "id": "0ef29434-69c2-4d30-9038-fd79e510f719", - "metadata": {}, - "source": [ - "### 4. Check job status and get results\n", - "\n", - "Next, pass the `job_id` to the API:" - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "ed6b98fc-be32-4d09-a9e9-2a403e14fe2e", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'status': 'Queued'}" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "response_status_singlejob = requests.get(url + \"/\" + job_id, headers=headers)\n", - "response_status_singlejob.json().get(\"state\")" - ] - }, - { - "cell_type": "markdown", - "id": "50f15367-d1df-4dc1-86e9-870e105ad033", - "metadata": {}, - "source": [ - "Once the job has completed, get job results:" - ] - }, - { - "cell_type": "code", - "execution_count": 12, - "id": "ecaf22cd-3bda-4eec-8e66-e4435cdcff38", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Hide this cell\n", - "\n", - "wait_for_results(url, job_id, headers)" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "eb522845-88a6-4b51-adda-33e63ba159e5", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x2', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3', '0x3']\n" - ] - } - ], - "source": [ - "response_result = requests.get(\n", - " url + \"/\" + job_id + \"/results\", headers=headers\n", - ")\n", - "\n", - "res_dict = response_result.json()\n", - "\n", - "# Get results for the first PUB\n", - "counts = res_dict[\"results\"][0][\"data\"][\"meas\"][\"samples\"]\n", - "\n", - "print(counts[:20])" - ] - }, - { - "cell_type": "markdown", - "id": "07b7df2e-82fe-498e-8a27-3a96bf26c23c", - "metadata": {}, - "source": [ - "### 5. Work with Runtime options\n", - "\n", - "Error mitigation techniques allow users to mitigate circuit errors by modeling the device noise at the time of execution. This typically results in quantum pre-processing overhead related to model training, and classical post-processing overhead to mitigate errors in the raw results by using the generated model.\n", - "\n", - "The error mitigation techniques built in to primitives are advanced resilience options. To specify these options, use the `resilience_level` option when submitting your job.\n", - "Sampler V2 does not support specifying resilience levels. However, you can turn on or off individual error mitigation / suppression methods.\n", - "\n", - "The following examples demonstrate the default options for dynamical decoupling and twirling. Find more options and further details in the [Error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) topic.\n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - " \n", - "\n", - "\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0ffa3726-c490-431d-ae93-c5cd5b11293b", - "metadata": { - "tags": [ - "id-dd-options" - ] - }, - "outputs": [], - "source": [ - "headers = {\n", - " \"Content-Type\": \"application/json\",\n", - " \"Authorization\": auth_id,\n", - " \"Service-CRN\": crn,\n", - "}\n", - "job_input = {\n", - " \"program_id\": \"sampler\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [\n", - " [qasm_string]\n", - " ], # primitive unified blocs (PUBs) containing one circuit each.\n", - " \"version\": \"2\",\n", - " \"options\": {\n", - " \"dynamical_decoupling\": {\n", - " \"enable\": True,\n", - " \"sequence_type\": \"XpXm\",\n", - " \"extra_slack_distribution\": \"middle\",\n", - " \"scheduling_method\": \"alap\",\n", - " },\n", - " },\n", - " },\n", - "}\n", - "\n", - "\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "e5d00fb6-a4a2-422c-a26b-6958a37cfa4e", - "metadata": { - "tags": [ - "id-twirling-options" - ] - }, - "outputs": [], - "source": [ - "headers = {\n", - " \"Content-Type\": \"application/json\",\n", - " \"Authorization\": auth_id,\n", - " \"Service-CRN\": crn,\n", - "}\n", - "job_input = {\n", - " \"program_id\": \"sampler\",\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [\n", - " [qasm_string]\n", - " ], # primitive unified blocs (PUBs) containing one circuit each.\n", - " \"version\": \"2\",\n", - " \"options\": {\n", - " \"twirling\": {\n", - " \"enable_gates\": True,\n", - " \"enable_measure\": True,\n", - " \"num_randomizations\": \"auto\",\n", - " \"shots_per_randomization\": \"auto\",\n", - " \"strategy\": \"active-accum\",\n", - " },\n", - " },\n", - " },\n", - "}\n", - "\n", - "\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(\"Job created:\", response.text)\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d3ab882b-0945-4f7f-a9dd-c781cacaba7a", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Cancel job immediately after since the example doesn't use it\n", - "job = service.job(job_id)\n", - "job.cancel()" - ] - }, - { - "cell_type": "markdown", - "id": "b4575de0-b2bf-45a8-98d7-5e370b45bca5", - "metadata": {}, - "source": [ - "\n", - "## Sampler primitive with REST API and parameterized circuits\n", - "\n", - "\n", - "### 1. Initialize the account\n", - "\n", - "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the device you want to use to run your calculations on.\n", - "\n", - "\n", - "Find details on how to initialize your account, view available backends, and invalidate tokens in this [topic](/docs/guides/cloud-setup-rest-api).\n", - "\n", - "\n", - "### 2. Define parameters" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ce185ac5-506f-4b55-8da7-e689c127d76c", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.qasm3 import dumps\n", - "from qiskit import QuantumCircuit\n", - "from qiskit.circuit import Parameter\n", - "\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy()\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "\n", - "theta = Parameter(\"theta\")\n", - "phi = Parameter(\"phi\")\n", - "parameter_values = {\n", - " \"theta\": 1.57,\n", - " \"phi\": 3.14,\n", - "} # In case we want to pass a dictionary" - ] - }, - { - "cell_type": "markdown", - "id": "1b888602-3155-4fdf-ba39-9b4961498958", - "metadata": {}, - "source": [ - "### 3. Create a quantum circuit and add parameterized gates" - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "id": "de811bfe-7836-44b1-affe-353c94a93069", - "metadata": {}, - "outputs": [], - "source": [ - "qc = QuantumCircuit(2)\n", - "\n", - "# Add parameterized gates\n", - "qc.rx(theta, 0)\n", - "qc.ry(phi, 1)\n", - "qc.cx(0, 1)\n", - "qc.measure_all()\n", - "\n", - "# Draw the original circuit\n", - "qc.draw(\"mpl\")\n", - "\n", - "# Get an ISA circuit\n", - "isa_circuit = pm.run(qc)" - ] - }, - { - "cell_type": "markdown", - "id": "a2aa333f-a0da-440d-9519-6f2d69758ffe", - "metadata": {}, - "source": [ - "### 4. Generate QASM 3 code" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "id": "60e1a8b0-5f22-412a-bd7d-afc7c5c67382", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Generated QASM 3 code:\n", - "OPENQASM 3.0;\n", - "include \"stdgates.inc\";\n", - "input float[64] phi;\n", - "input float[64] theta;\n", - "bit[2] meas;\n", - "rz(pi/2) $0;\n", - "sx $0;\n", - "rz(pi + theta) $0;\n", - "sx $0;\n", - "rz(5*pi/2) $0;\n", - "sx $1;\n", - "rz(pi + phi) $1;\n", - "rz(-pi/2) $1;\n", - "sx $1;\n", - "cz $0, $1;\n", - "rz(pi/2) $1;\n", - "sx $1;\n", - "rz(pi/2) $1;\n", - "barrier $0, $1;\n", - "meas[0] = measure $0;\n", - "meas[1] = measure $1;\n", - "\n" - ] - } - ], - "source": [ - "qasm_str = dumps(isa_circuit)\n", - "print(\"Generated QASM 3 code:\")\n", - "print(qasm_str)" - ] - }, - { - "cell_type": "markdown", - "id": "3978ce10-3867-45e8-a75e-90812ce6deaa", - "metadata": {}, - "source": [ - "### 5. Run the quantum circuit using Sampler V2 API\n", - "\n", - "\n", - "\n", - " The following jobs use Qiskit Runtime V2 [primitives](/docs/guides/primitives). Both [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) and [`EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2) take one or more [primitive unified blocs (PUBs)](/docs/guides/primitive-input-output#pubs) as the input. Each PUB is a tuple that contains one circuit and the data broadcasted to that circuit, which can be multiple observables and parameters. Each PUB returns a result.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "id": "2948dd67-1e7c-4bed-9fb7-074781dc0482", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Job created: {\"id\":\"d614873traac73bef6tg\",\"backend\":\"ibm_pittsburgh\"}\n" - ] - } - ], - "source": [ - "headers = {\n", - " \"Content-Type\": \"application/json\",\n", - " \"Authorization\": auth_id,\n", - " \"Service-CRN\": crn,\n", - "}\n", - "\n", - "job_input = {\n", - " \"program_id\": \"sampler\",\n", - " \"backend\": backend.name,\n", - " \"params\": {\n", - " # Choose one option: direct parameter transfer or through a dictionary\n", - " # \"pubs\": [[qasm_str,[1,2],500]], # primitive unified blocs (PUBs) containing one circuit each.\n", - " \"pubs\": [\n", - " [qasm_str, parameter_values, 500]\n", - " ], # primitive unified blocs (PUBs) containing one circuit each.\n", - " \"version\": \"2\",\n", - " },\n", - "}\n", - "\n", - "response = requests.post(url, headers=headers, json=job_input)\n", - "\n", - "if response.status_code == 200:\n", - " job_id = response.json().get(\"id\")\n", - " print(f\"Job created: {response.text}\")\n", - "else:\n", - " print(f\"Error: {response.status_code}\")" - ] - }, - { - "cell_type": "markdown", - "id": "a46a1ec4-4b1d-4ab0-aaef-d390de1bc96e", - "metadata": {}, - "source": [ - "### 6. Check job status and get results\n", - "Next, pass the `job_id` to the API:" - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "id": "e124546a-bf89-4ab8-91ca-927af5db3a31", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "{'status': 'Queued'}" - ] - }, - "execution_count": 19, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "response_status_singlejob = requests.get(f\"{url}/{job_id}\", headers=headers)\n", - "response_status_singlejob.json().get(\"state\")" - ] - }, - { - "cell_type": "markdown", - "id": "a05d7d8b-e588-4cb6-8faa-4c89226e3df7", - "metadata": {}, - "source": [ - "Once the job has completed, get job results:" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "id": "5ca0bc8c-72ac-41b8-ad74-c1226167035a", - "metadata": { - "tags": [ - "remove-cell" - ] - }, - "outputs": [], - "source": [ - "# Hide this cell\n", - "\n", - "wait_for_results(url, job_id, headers)" - ] - }, - { - "cell_type": "code", - "execution_count": 21, - "id": "31bf7e5d-bbe7-482c-acbb-377d970dafd6", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "['0x1', '0x2', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x2', '0x1', '0x1', '0x1', '0x1', '0x2', '0x2', '0x2', '0x2', '0x2', '0x2', '0x1']\n" - ] - } - ], - "source": [ - "response_result = requests.get(f\"{url}/{job_id}/results\", headers=headers)\n", - "\n", - "res_dict = response_result.json()\n", - "\n", - "# Get results for the first PUB\n", - "counts = res_dict[\"results\"][0][\"data\"][\"meas\"][\"samples\"]\n", - "\n", - "print(counts[:20])" - ] - }, - { - "cell_type": "markdown", - "id": "3d9ef591-91fd-4a49-a065-5e2cda4d41be", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "\n", - " - There are several ways to run workloads, depending on your needs: job mode, session mode, and batch mode. Learn how to work with session mode and batch mode in the [execution modes topic](/docs/guides/execution-modes-rest-api). Note that Open Plan users cannot submit session jobs.\n", - " - Learn how to [initialize your account](/docs/guides/cloud-setup-rest-api) with REST API.\n", - " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", - " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", - " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.\n", - " - [Migrate to the Qiskit Runtime V2 primitives](/docs/guides/v2-primitives).\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/primitives.ipynb b/docs/guides/primitives.ipynb index a7aa9d1c19b..8a1328619de 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -90,7 +90,7 @@ "\n", "## Primitive definition and implementations\n", "\n", - "There are two types of Qiskit primitives: the base classes, and their implementations. The Qiskit primitives are defined by open-source primitive base classes that live in the Qiskit SDK (in the [`qiskit.primitives`](/docs/api/qiskit/primitives) module). Providers (such as Qiskit Runtime) can use these base classes to derive their own Sampler and Estimator implementations. Most users will interact with provider implementations, not the base primitives.\n", + "There are two types of Qiskit primitives: the base classes, and their implementations. The Estimator and Sampler primitives are defined by open-source primitive base classes that live in the Qiskit SDK (in the [`qiskit.primitives`](/docs/api/qiskit/primitives) module). Providers (such as Qiskit Runtime) can use these base classes to derive their own Sampler and Estimator implementations. Most users will interact with provider implementations, not the base primitives.\n", "\n", "### Base classes\n", "\n", @@ -107,11 +107,17 @@ "\n", "These are implementations of the primitives base classes:\n", "\n", - "- The [Qiskit Runtime primitives](/docs/guides/qiskit-runtime-primitives), [`EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2) and [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2), provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service. This implementation of the base primitives is used to access IBM Quantum® hardware. They are accessed through Qiskit Runtime.\n", + "- The [Qiskit Runtime primitives](/docs/guides/qiskit-runtime-primitives), [`EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2) and [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2), provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service. This implementation of the base primitives is used to access IBM Quantum® hardware.\n", "\n", - "- [`StatevectorEstimator`](/docs/api/qiskit/qiskit.primitives.StatevectorEstimator) and [`StatevectorSampler`](/docs/api/qiskit/qiskit.primitives.StatevectorSampler#statevectorsampler) - Reference implementations of the primitives that use the simulator built into Qiskit. They are built with the Qiskit [`quantum_info`](/docs/api/qiskit/quantum_info#quantum-information) module, producing results based on ideal statevector simulations. They are accessed through Qiskit.\n", + "- [`StatevectorEstimator`](/docs/api/qiskit/qiskit.primitives.StatevectorEstimator) and [`StatevectorSampler`](/docs/api/qiskit/qiskit.primitives.StatevectorSampler#statevectorsampler) - Reference implementations of the primitives that use the simulator built into Qiskit. They are built with the Qiskit [`quantum_info`](/docs/api/qiskit/quantum_info#quantum-information) module, producing results based on ideal statevector simulations. They are accessed through Qiskit. See [Exact simulation with Qiskit primitives](/docs/guides/simulate-with-qiskit-sdk-primitives) for usage details.\n", "\n", - "- [`BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) and [`BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) - You can use these classes to “wrap” any quantum computing resource into a primitive. This lets you write primitive-style code for providers that don’t yet have a primitives-based interface. These classes can be used just like the regular Sampler and Estimator, except they should be initialized with an additional `backend` argument for selecting which quantum computer to run on. They are accessed by using Qiskit.\n", + "- [`BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) and [`BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) - You can use these classes to “wrap” any quantum computing resource into a primitive. This lets you write primitive-style code for providers that don’t yet have a primitives-based interface. These classes can be used just like the regular Sampler and Estimator, except they should be initialized with an additional `backend` argument for selecting which quantum computer to run on. They are accessed by using Qiskit. See the [backend primitives](/docs/guides/get-started-with-backend-primitives) guide for more information.\n", + "\n", + "## Options\n", + "\n", + "You can pass options to primitives to customize them to meet your needs. While the interface of the primitives' `run()` method is common across all implementations, their options are not. Consult the API references for a specific primitive implementation to learn about the options it supports.\n", + "\n", + "For example, refer to the [Estimator options](/docs/guides/estimator-options) and [Sampler options](/docs/guides/sampler-options) topics to learn about options for the Qiskit Runtime primitives, or see the [Qiskit Aer API references](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) for the Qiskit Aer primitives options.\n", "\n", "## Benefits of Qiskit primitives\n", "\n", diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 6203305b7d4..9cf8dd8fa99 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -90,7 +90,7 @@ "\n", "![Visualization of the error suppression pipeline](/docs/images/guides/qctrl-performance-management/error_suppression.svg)\n", "\n", - "The function offers two primitives, Sampler and Estimator, and the inputs and outputs of both extend the implemented spec for [Qiskit Runtime V2 primitives](/docs/guides/primitive-input-output)." + "The function offers two primitives, Sampler and Estimator, and the inputs and outputs of both extend the implemented spec for [Qiskit Runtime V2 primitives](/docs/guides/primitive-input-output#pubs)." ] }, { @@ -309,7 +309,7 @@ "metadata": {}, "outputs": [], "source": [ - "# Run the circuit using the estimator\n", + "# Run the circuit using Estimator\n", "qctrl_estimator_job = perf_mgmt.run(\n", " primitive=\"estimator\",\n", " pubs=estimator_pubs,\n", @@ -370,7 +370,7 @@ "id": "7375fcad", "metadata": {}, "source": [ - "The results have the same format as an [Estimator result](/docs/guides/primitive-input-output#estimator-output):" + "The results have the same format as an [Estimator result](/docs/guides/estimator-input-output):" ] }, { @@ -477,12 +477,12 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": null, "id": "2595df84", "metadata": {}, "outputs": [], "source": [ - "# Run the circuit using the sampler\n", + "# Run the circuit using Sampler\n", "qctrl_sampler_job = perf_mgmt.run(\n", " primitive=\"sampler\",\n", " pubs=sampler_pubs,\n", diff --git a/docs/guides/qasm-feature-table.mdx b/docs/guides/qasm-feature-table.mdx index fc977bda411..d83d3fb9b31 100644 --- a/docs/guides/qasm-feature-table.mdx +++ b/docs/guides/qasm-feature-table.mdx @@ -157,6 +157,6 @@ This includes features that cannot be loaded by Qiskit SDK from OpenQASM 3. - Learn how to generate OpenQASM code using [IBM Quantum Composer](/docs/guides/composer). - See the [OpenQASM 3 Qiskit API](/docs/api/qiskit/qasm3) reference. - See the [OpenQASM 2 Qiskit API](/docs/api/qiskit/qasm2) reference. - - Review the [Verify your program](./debugging-tools) topic. + - Review the [Verify your program](/docs/guides/debugging-tools) topic. - Visit the [OpenQASM Live Specification](https://openqasm.com/). diff --git a/docs/guides/qiskit-1.0-features.mdx b/docs/guides/qiskit-1.0-features.mdx index 077f26e3100..9f04a1bb943 100644 --- a/docs/guides/qiskit-1.0-features.mdx +++ b/docs/guides/qiskit-1.0-features.mdx @@ -335,7 +335,7 @@ sampler_v2 = StatevectorSampler() 1. `Sampler and Estimator`: The new V2 primitives are designed to accept **vectorized inputs**, where single circuits can be grouped with array-valued specifications. That is, one circuit can be executed - for arrays of `n` parameter sets, `n` observables, or both (in the case of the estimator). Each group is called a **primitive unified bloc (pub)**, and can be represented as a tuple: `(1 x circuit, [n x observables], [n x parameters])`. The V1 interface didn't allow for the same flexibility. Instead, the number of input circuits had to match the number of observables and + for arrays of `n` parameter sets, `n` observables, or both (in the case of Estimator). Each group is called a **primitive unified bloc (pub)**, and can be represented as a tuple: `(1 x circuit, [n x observables], [n x parameters])`. The V1 interface didn't allow for the same flexibility. Instead, the number of input circuits had to match the number of observables and parameter sets, as shown in the following examples (select a tab to see each example): @@ -409,7 +409,7 @@ sampler_v2 = StatevectorSampler() returns measurement outcome samples in the form of **bitstrings** or **counts**, instead of the quasi-probability distributions from the V1 interface. The bitstrings show the measurement outcomes, preserving the shot - order in which they were measured. The V2 sampler result objects organize + order in which they were measured. The V2 Sampler result objects organize data in terms of their input circuits' classical register names, for compatibility with dynamic circuits. @@ -436,7 +436,7 @@ sampler_v2 = StatevectorSampler() ```python - # Run using V1 sampler + # Run using V1 Sampler result = sampler_v1.run(circuit).result() quasi_dist = result.quasi_dists[0] print(f"The quasi-probability distribution is: {quasi_dist}") @@ -445,7 +445,7 @@ sampler_v2 = StatevectorSampler() The quasi-probability distribution is: {0: 0.5, 3: 0.5} ``` ```python - # Run using V2 sampler + # Run using V2 Sampler result = sampler_v2.run([circuit]).result() # Access result data for pub 0 data_pub = result[0].data diff --git a/docs/guides/qiskit-1.0-installation.mdx b/docs/guides/qiskit-1.0-installation.mdx index 60d94408a3e..cbbb8023438 100644 --- a/docs/guides/qiskit-1.0-installation.mdx +++ b/docs/guides/qiskit-1.0-installation.mdx @@ -21,7 +21,7 @@ This guide is divided into the following sections. You only need to review the * If you develop or maintain a package that depends on Qiskit, read the [For developers](#for-developers) section. * If you encounter problems installing or importing Qiskit 1.0, review the [Troubleshooting](#troubleshooting) section. -If you are interested in understanding the old package structure and why it changed, review the [overview of the breaking package changes](./metapackage-migration). +If you are interested in understanding the old package structure and why it changed, review the [overview of the breaking package changes](/docs/guides/metapackage-migration). ## For users diff --git a/docs/guides/qiskit-code-assistant-jupyterlab.mdx b/docs/guides/qiskit-code-assistant-jupyterlab.mdx index dac3575b473..28555ca1cf3 100644 --- a/docs/guides/qiskit-code-assistant-jupyterlab.mdx +++ b/docs/guides/qiskit-code-assistant-jupyterlab.mdx @@ -129,5 +129,5 @@ The code for this extension is publicly available and open source. Check it out ## Next steps -See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/configure-error-suppression), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). +See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/error-mitigation-and-suppression-techniques), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). diff --git a/docs/guides/qiskit-code-assistant-vscode.mdx b/docs/guides/qiskit-code-assistant-vscode.mdx index 1695978ef2e..f8054fc3d67 100644 --- a/docs/guides/qiskit-code-assistant-vscode.mdx +++ b/docs/guides/qiskit-code-assistant-vscode.mdx @@ -111,5 +111,5 @@ The code for this official extension is publicly available and open source. Chec ## Next steps -See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/configure-error-suppression), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). +See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/error-mitigation-and-suppression-techniques), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). diff --git a/docs/guides/qiskit-code-assistant.mdx b/docs/guides/qiskit-code-assistant.mdx index e2509d1c834..b365d1ee8fa 100644 --- a/docs/guides/qiskit-code-assistant.mdx +++ b/docs/guides/qiskit-code-assistant.mdx @@ -80,5 +80,5 @@ Eprint = {arXiv:2508.20907}, - Install and use the official [JupyterLab](/docs/guides/qiskit-code-assistant-jupyterlab) or [VS Code](/docs/guides/qiskit-code-assistant-vscode) extensions. - - See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/configure-error-suppression), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). + - See examples to use Qiskit Code Assistant for [circuits](/docs/guides/circuit-library), [configuring error suppression](/docs/guides/error-mitigation-and-suppression-techniques), and [transpiling with pass managers](/docs/guides/transpile-with-pass-managers). diff --git a/docs/guides/qiskit-function-templates.mdx b/docs/guides/qiskit-function-templates.mdx index a2dd9ffcf45..3ee0027d10a 100644 --- a/docs/guides/qiskit-function-templates.mdx +++ b/docs/guides/qiskit-function-templates.mdx @@ -6,7 +6,7 @@ description: Learn how to use and build Qiskit Function templates. # Introduction to Qiskit Function templates -[Qiskit Function templates](https://github.com/qiskit-community/qiskit-function-templates) are an open-source collection of realistic code examples that give you access to some of the latest research workflows that leverage tools like the Qiskit SDK and [Qiskit addons](/docs/guides/addons). These pre-built workflows take information from practical experiments and package them in a way that you can customize and reuse in your own research so that you don't have to build from scratch. All templates are readily deployable to [Qiskit Serverless](./serverless) where you can easily leverage classical compute as part of your workflow. +[Qiskit Function templates](https://github.com/qiskit-community/qiskit-function-templates) are an open-source collection of realistic code examples that give you access to some of the latest research workflows that leverage tools like the Qiskit SDK and [Qiskit addons](/docs/guides/addons). These pre-built workflows take information from practical experiments and package them in a way that you can customize and reuse in your own research so that you don't have to build from scratch. All templates are readily deployable to [Qiskit Serverless](/docs/guides/serverless) where you can easily leverage classical compute as part of your workflow. There are two types of templates: @@ -18,23 +18,23 @@ There are two types of templates: Qiskit Function template implementations are organized by application area. Currently included in the collection is a physics template for Hamiltonian simulation using the [AQC-Tensor Qiskit addon](https://qiskit.github.io/qiskit-addon-aqc-tensor/) and a chemistry template for electronic structure with the implicit solvent model using the [SQD Qiskit addon](/docs/guides/qiskit-addons-sqd). Resources to get started with these two templates are available at the following links: -- Electronic structure simulation with implicit solvent model: [template source files](https://github.com/qiskit-community/qiskit-function-templates/tree/main/chemistry/sqd_pcm) and [guide](./function-template-chemistry-workflow) -- Hamiltonian simulation: [template source files](https://github.com/qiskit-community/qiskit-function-templates/tree/main/physics/hamiltonian_simulation) and [guide](./function-template-hamiltonian-simulation) +- Electronic structure simulation with implicit solvent model: [template source files](https://github.com/qiskit-community/qiskit-function-templates/tree/main/chemistry/sqd_pcm) and [guide](/docs/guides/function-template-chemistry-workflow) +- Hamiltonian simulation: [template source files](https://github.com/qiskit-community/qiskit-function-templates/tree/main/physics/hamiltonian_simulation) and [guide](/docs/guides/function-template-hamiltonian-simulation) ## Base templates The *base templates* are references for developing your own original Qiskit Function. They are designed to help you kickstart the development process by illustrating best practices in interface development, code formatting, I/O handling, error messages, checkpoints, unit testing, and more. The repository is exposed as a [GitHub template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) so that the CI/CD implementation can be easily extended. -There are currently two templates: a [circuit function template](https://github.com/qiskit-community/qiskit-function-templates/blob/main/base_templates/circuit_function_template.py) and an [application function template](https://github.com/qiskit-community/qiskit-function-templates/blob/main/base_templates/application_function_template.py). The circuit function template is built similarly to the [IBM Circuit Function](./ibm-circuit-function) and the application function template illustrates how to structure a typical application workflow. +There are currently two templates: a [circuit function template](https://github.com/qiskit-community/qiskit-function-templates/blob/main/base_templates/circuit_function_template.py) and an [application function template](https://github.com/qiskit-community/qiskit-function-templates/blob/main/base_templates/application_function_template.py). The circuit function template is built similarly to the [IBM Circuit function](/docs/guides/ibm-circuit-function) and the application function template illustrates how to structure a typical application workflow. ## Next steps -- Review the guide on building a function template for [Hamiltonian simulation](./function-template-hamiltonian-simulation) -- Read through the guide on deploying the function template for a [chemistry workflow](./function-template-chemistry-workflow) +- Review the guide on building a function template for [Hamiltonian simulation](/docs/guides/function-template-hamiltonian-simulation) +- Read through the guide on deploying the function template for a [chemistry workflow](/docs/guides/function-template-chemistry-workflow) - Check out the [Qiskit Function templates repository](https://github.com/qiskit-community/qiskit-function-templates) on GitHub. diff --git a/docs/guides/qiskit-runtime-circuit-timing.ipynb b/docs/guides/qiskit-runtime-circuit-timing.ipynb index aca481eaa82..1ef090ca2f8 100644 --- a/docs/guides/qiskit-runtime-circuit-timing.ipynb +++ b/docs/guides/qiskit-runtime-circuit-timing.ipynb @@ -165,7 +165,7 @@ "\n", "### Visualize the timings\n", "\n", - "With `qiskit-ibm-runtime` v0.43.0 or later, you can visualize circuit timings. To visualize the timings, you first need to convert the result metadata to `fig` by using the [`draw_circuit_schedule_timing` method](https://github.com/Qiskit/qiskit-ibm-runtime/blob/3d1bf1e1d49e5123841639fce259859c90ce9314/qiskit_ibm_runtime/visualization/draw_circuit_schedule_timings.py#L26). This method returns a `plotly` figure, which you can display directly, save to a file, or both. For more information about the `plotly` commands to use, see [`fig.show()`](https://plotly.com/python-api-reference/generated/plotly.io.show.html) and [`fig.write_image(\"\")`.](https://plotly.com/python-api-reference/generated/plotly.io.write_image.html)" + "With `qiskit-ibm-runtime` v0.43.0 or later, you can visualize circuit timings. To visualize the timings, you first need to convert the result metadata to `fig` by using the [`draw_circuit_schedule_timing` method](https://github.com/Qiskit/qiskit-ibm-runtime/blob/3d1bf1e1d49e5123841639fce259859c90ce9314/qiskit_ibm_runtime/visualization/draw_circuit_schedule_timings.py#L26). This method returns a `plotly` figure, which you can display directly, save to a file, or both. For more information about the `plotly` commands to use, see [`fig.show()`](https://plotly.com/python-api-reference/generated/plotly.io.show.html) and [`fig.write_image(\"\")`](https://plotly.com/python-api-reference/generated/plotly.io.write_image.html)." ] }, { diff --git a/docs/guides/qiskit-runtime-primitives.ipynb b/docs/guides/qiskit-runtime-primitives.ipynb deleted file mode 100644 index aa4459ab1ed..00000000000 --- a/docs/guides/qiskit-runtime-primitives.ipynb +++ /dev/null @@ -1,150 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "b560356f-3bff-423c-81be-12f4e5bffc13", - "metadata": {}, - "source": [ - "---\n", - "title: Introduction to primitives\n", - "description: Introduction to primitives in Qiskit Runtime, and an explanation of available primitives\n", - "---\n", - "\n", - "\n", - "# Introduction to primitives" - ] - }, - { - "cell_type": "markdown", - "id": "d6212b2b-78d4-4439-9715-679c6fda8843", - "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", - "\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", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "44551679-f0d8-4fc0-b9c2-6d92ae0d8ee6", - "metadata": {}, - "source": [ - "\n", - "The beta release of a new execution model is now available. The directed execution model provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information.\n", - "\n", - "\n", - "Primitives were created to simplify the most common tasks for quantum computers. Namely, sampling quantum states and calculating expectation values. The Qiskit Runtime primitives ([`EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2) and [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2)) are implementations of the Qiskit [primitives base classes](/docs/guides/primitives). They provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service and are used to access IBM Quantum® hardware.\n", - "\n", - "\n", - "### Estimator\n", - "\n", - "The Estimator primitive computes the expectation values for one or more observables with respect to states prepared by quantum circuits. The circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.\n", - "\n", - "The input is an array of [PUBs](/docs/guides/primitive-input-output#pubs). Each PUB is in the format:\n", - "\n", - "(``, ``, ``, ``),\n", - "\n", - "where the optional `parameter values` can be a list or a single parameter. Elements from observables and parameter values are combined by following NumPy broadcasting rules as described in the [Primitive inputs and outputs](primitive-input-output#broadcasting-rules) topic.\n", - "\n", - "\n", - "If the input contains measurements, they are ignored.\n", - "\n", - "\n", - "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult), with both data and metadata. The data contains at least an array of expectation values (`PubResult.data.evs`) and associated standard deviations (either `PubResult.data.stds` or `PubResult.data.ensemble_standard_error` depending on the `resilience_level` used), but can contain more data depending on the error mitigation options that were specified.\n", - "\n", - "#### How the Estimator calculates error\n", - "\n", - "In addition to the estimate of the mean of the observables passed in the input PUBs (the `evs` field of the `DataBin`), the Estimator also attempts to deliver an estimate of the error associated with those expectation values. All estimator queries will populate the `stds` field with a quantity like the standard error of the mean for each expectation value, but some error mitigation options produce additional information, such as `ensemble_standard_error`.\n", - "\n", - "Consider a single observable $\\mathcal{O}$. In the absence of [ZNE](/docs/guides/error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne), you can think of each shot of the Estimator execution as providing a point estimate of the expectation value $\\langle \\mathcal{O} \\rangle$. If the pointwise estimates are in a vector `Os`, then the value returned in `ensemble_standard_error` is equivalent to the following (in which $\\sigma_{\\mathcal{O}}$ is the [standard deviation of the expectation value](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2) estimate and $N_{shots}$ is the number of shots):\n", - "\n", - "$$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{shots}} },$$\n", - "\n", - "which treats all shots as part of a single ensemble. If you requested gate [twirling](/docs/guides/error-mitigation-and-suppression-techniques#pauli-twirling) (`twirling.enable_gates = True`), you can sort the pointwise estimates of $\\langle \\mathcal{O} \\rangle$ into sets that share a common twirl. Call these sets of estimates `O_twirls`, and there are `num_randomizations` (number of twirls) of them. Then `stds` is the standard error of the mean of `O_twirls`, as in\n", - "\n", - "$$\\frac{ \\sigma_{\\mathcal{O}} }{ \\sqrt{N_{twirls}} },$$\n", - "\n", - "where $\\sigma_{\\mathcal{O}}$ is the standard deviation of `O_twirls` and $N_{twirls}$ is the number of twirls. When you do not enable twirling, `stds` and `ensemble_standard_error` are equal.\n", - "\n", - "If you enable ZNE, then the `stds` described above become weights in a non-linear regression to an extrapolator model. What finally gets returned in the `stds` in this case is the uncertainty of the fit model evaluated at a noise factor of zero. When there is a poor fit, or large uncertainty in the fit, the reported `stds` can become very large. When ZNE is enabled, `pub_result.data.evs_noise_factors` and `pub_result.data.stds_noise_factors` are also populated, so that you can do your own extrapolation." - ] - }, - { - "cell_type": "markdown", - "id": "0885436c-28e5-43c8-9721-150054ca626f", - "metadata": {}, - "source": [ - "\n", - "### Sampler\n", - "\n", - "The Sampler's core task is sampling the output register from the execution of one or more quantum circuits. The input circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.\n", - "\n", - "The input is one or more [PUBs,](/docs/guides/primitive-input-output#pubs) in the format:\n", - "\n", - "(``, ``, ``),\n", - "\n", - "where there can be multiple `parameter values` items, and each item can be either an array or a single parameter, depending on the chosen circuit. Additionally, the input must contain measurements.\n", - "\n", - "The output is counts or per-shot measurements, as [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) objects, without weights. The result class, however, has methods to return weighted samples, such as counts. See [Primitive inputs and outputs](primitive-input-output#broadcasting-rules) for full details. The Sampler result metadata also includes execution timing information called the [_execution span_](monitor-job#execution-spans)." - ] - }, - { - "cell_type": "markdown", - "id": "3e3d0d20-e63b-4d39-8a2d-6fed5727e28c", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Learn about the [Qiskit primitives](/docs/guides/primitives) that the Qiskit Runtime primitives are based on.\n", - " - Read [Get started with primitives](/docs/guides/get-started-with-primitives) to implement primitives in your work.\n", - " - Review detailed [primitives examples](/docs/guides/primitives-examples).\n", - " - See [Primitive inputs and outputs](primitive-input-output#broadcasting-rules) for detailed information.\n", - " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", - " - See the [EstimatorV2 API reference](/docs/api/qiskit-ibm-runtime/estimator-v2) and [SamplerV2 API reference](/docs/api/qiskit-ibm-runtime/sampler-v2).\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/qiskit-runtime-primitives.mdx b/docs/guides/qiskit-runtime-primitives.mdx new file mode 100644 index 00000000000..41af1832708 --- /dev/null +++ b/docs/guides/qiskit-runtime-primitives.mdx @@ -0,0 +1,40 @@ +--- +title: Introduction to primitives +description: Introduction to primitives in Qiskit Runtime, and an explanation of available primitives +--- + +# Introduction to primitives + +Primitives were created to simplify the most common tasks for quantum computers: namely, sampling quantum states and calculating expectation values. The first Qiskit Runtime primitives ([`EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2) and [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2)) are implementations of the Qiskit [primitives base classes](/docs/guides/primitives). They provide a more sophisticated implementation (for example, by including error mitigation) as a cloud-based service and are used to access IBM Quantum® hardware. + +The newest Qiskit Runtime primitive, [Executor](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.Executor.html) (which is in beta), provides a lower-level interface that gives more visibility and control without sacrificing performance. + + + + + + + + +## Next steps + + + - Learn about the [Qiskit primitives](/docs/guides/primitives) that the Qiskit Runtime primitives are based on. + - Review detailed [Estimator](/docs/guides/estimator-examples) or [Sampler](/docs/guides/sampler-examples) examples. + - See the input and output details for [Estimator](/docs/guides/estimator-input-output) or [Sampler](/docs/guides/sampler-input-output). + - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning. + - See the [EstimatorV2 API reference](/docs/api/qiskit-ibm-runtime/estimator-v2) and [SamplerV2 API reference](/docs/api/qiskit-ibm-runtime/sampler-v2). + - Read [Migrate to V2 primitives](/docs/guides/v2-primitives). + \ No newline at end of file diff --git a/docs/guides/repetition-rate-execution.ipynb b/docs/guides/repetition-rate-execution.ipynb index 0b8dace4cab..b75b6357054 100644 --- a/docs/guides/repetition-rate-execution.ipynb +++ b/docs/guides/repetition-rate-execution.ipynb @@ -108,7 +108,8 @@ "\n", "\n", " - Try an example in the [Quantum approximate optimization algorithm (QAOA)](/docs/tutorials/quantum-approximate-optimization-algorithm) tutorial.\n", - " - Review how to [get started with primitives](/docs/guides/get-started-with-primitives).\n", + " - Review how to [get started with Estimator](/docs/guides/get-started-with-estimator).\n", + " - Review how to [get started with Sampler](/docs/guides/get-started-with-sampler).\n", "" ] } diff --git a/docs/guides/run-jobs-batch.ipynb b/docs/guides/run-jobs-batch.ipynb index 9b1f88b3946..a03e711575a 100644 --- a/docs/guides/run-jobs-batch.ipynb +++ b/docs/guides/run-jobs-batch.ipynb @@ -58,7 +58,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "340d9d45-9ec0-473f-bf17-9dc7eb0804ed", "metadata": {}, "outputs": [], @@ -90,7 +90,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "id": "02e53d53-3410-4e07-9c02-c582b97e15e1", "metadata": {}, "outputs": [], @@ -115,7 +115,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "id": "fe96e5dd-8237-458d-8657-dd0f71c65f8a", "metadata": {}, "outputs": [], @@ -361,9 +361,9 @@ "## Next steps\n", "\n", "\n", - " - Try an example in the [Combine error mitigation options with the estimator primitive](/docs/tutorials/combine-error-mitigation-techniques) tutorial.\n", + " - Try an example in the [Combine error mitigation options with the Estimator primitive](/docs/tutorials/combine-error-mitigation-techniques) tutorial.\n", " - Review the [Batch API](/docs/api/qiskit-ibm-runtime/batch#batch) reference.\n", - " - Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM QPU.\n", + " - Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM® QPU.\n", " - Review [execution modes FAQs](/docs/guides/execution-modes-faq).\n", "" ] diff --git a/docs/guides/run-jobs-session.ipynb b/docs/guides/run-jobs-session.ipynb index 3e75b1a638f..af894cd2a8d 100644 --- a/docs/guides/run-jobs-session.ipynb +++ b/docs/guides/run-jobs-session.ipynb @@ -58,12 +58,12 @@ "\n", "## Set up to use sessions\n", "\n", - "Before starting a session, you must [set up Qiskit Runtime](./install-qiskit) and initialize it as a service:" + "Before starting a session, you must [set up Qiskit Runtime](/docs/guides/install-qiskit) and initialize it as a service:" ] }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "117d0471-1f98-489c-906f-8aab836cd877", "metadata": {}, "outputs": [], @@ -103,7 +103,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "id": "2694bd4c-2011-4671-9625-3e7e941dd381", "metadata": {}, "outputs": [], @@ -132,7 +132,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "id": "192e5e57-2f9d-4f8e-b3e7-1dd31907e8a6", "metadata": {}, "outputs": [], diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 466f3d6b5d5..620d3ffb4e4 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -1,902 +1,35 @@ --- title: Introduction to options description: Available options for building with Qiskit Runtime primitives -in_page_toc_min_heading_level: 2 +in_page_toc_min_heading_level: 1 in_page_toc_max_heading_level: 2 --- # Introduction to options - You can pass options to primitives to customize them to meet your needs. This section focuses on 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`](/docs/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options. - -## Overview + You can use options to customize Qiskit Runtime primitives to meet your needs. -### Structure +## Structure -When calling the primitives, you can pass in options by using an options class or a dictionary. Commonly-used options, such as `resilience_level`, are at the first level. Other options are grouped into different categories, such as `execution`. See the [Set primitive options](/docs/guides/specify-runtime-options#pass-options) section for full details. +When calling the primitives, you can pass in options by using an options class or a dictionary. Commonly-used options, such as `resilience_level`, are at the first level. Other options are grouped into categories, such as `execution`. Specify the options in this format: `options.option.sub-option.sub-sub-option = choice`. For example: `options.dynamical_decoupling.enable = True`. -### Defaults +## Defaults If you do not specify a value for an option, it is given a special value of `Unset` and the server default value is used. Thus, the default value will be the same regardless of your code version. -The tables in the [Options classes summary](#options-classes) section lists the default values. +The tables in the "Options classes summary" section on each primitive's "options" guide lists the default values. ## Set options -Options can be defined before a primitive is constructed and passed to the primitive, which makes a copy of them. This can be done either as a nested dictionary, or by using the options classes. Additionally, after the primitive is constructed, its options can be changed. Use the workflow that works best for your application. See [Specify options](specify-runtime-options) for full details. - - -## Options classes summary - - - - - [Dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options): Options for dynamical decoupling. - - [Environment](/docs/api/qiskit-ibm-runtime/options-environment-options): Execution environment options, such as the logging level to set and job tags to add. - - [Execution](/docs/api/qiskit-ibm-runtime/options-execution-options-v2): Primitive execution options, including whether to initialize qubits and the repetition delay. - - [Resilience](/docs/api/qiskit-ibm-runtime//options-resilience-options-v2): Advanced options for configuring error mitigation methods such as measurement error mitigation, ZNE, and PEC. - - [Simulator](/docs/api/qiskit-ibm-runtime/options-simulator-options): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to [local testing mode](/docs/guides/local-testing-mode) only. - - [Twirling](/docs/api/qiskit-ibm-runtime/options-twirling-options): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - - - - - [Dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options): Options for dynamical decoupling. - - [Environment](/docs/api/qiskit-ibm-runtime/options-environment-options): Execution environment options, such as the logging level to set and job tags to add. - - [Execution](/docs/api/qiskit-ibm-runtime/options-execution-options-v2): Primitive execution options, including whether to initialize qubits and the repetition delay. - - [Simulator](/docs/api/qiskit-ibm-runtime/options-simulator-options): Simulator options, such as the basis gates, simulator seed, and coupling map. Applies to [local testing mode](/docs/guides/local-testing-mode) only. - - [Twirling](/docs/api/qiskit-ibm-runtime/options-twirling-options): Twirling options, such as whether to apply two-qubit gate twirling and the number of shots to run for each random sample. - - - - - -## Available options - -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. - - - - - - -The total number of shots to use per circuit per configuration. - -**Choices**: Integer >= 0 - -**Default**: None - -[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_shots) - - - - - -The default precision to use for any PUB or `run()` call that does not specify one. - -**Choices**: Float > 0 - -**Default**: 0.015625 (1 / sqrt(4096)) - -[`default_precision` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_precision) - - - - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling) - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - -**Choices**: `middle`, `edges` - -**Default**: `middle` - - - - - -Choices: `asap`, `alap` -Default: `alap` - - - - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` - - - - - -Choices: `True`, `False` -Default: `False` - - - - - - - - - - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment) - - - -Callable function that receives the `Job ID` and `Job result`. - -**Choices**: None - -**Default**: None - - - - - -List of tags. - -**Choices**: None - -**Default**: None - - - - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING - - - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - - - - - - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution) - - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` - - - - -The delay between a measurement and the subsequent quantum circuit. - -**Choices**: Value in the range supplied by `backend.rep_delay_range` - -**Default**: Given by `backend.default_rep_delay` - - - - - - - - - -**Choices**: Integer number of seconds in the range [1, 10800] - -**Default**: 10800 (3 hours) - -[`max_execution_time` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#max_execution_time) - - - - -Advanced resilience options to fine tune the resilience strategy. - -[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience) - - - -Options for learning layer noise. - -[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options) - - - - - -**Choices**: list[int] of 2-10 values in the range [0, 200] - -**Default**: `(0, 1, 2, 4, 16, 32)` - - - - - - - -**Choices**: None, Integer >= 1 - -**Default**: `4` - - - - - - - -**Choices**: Integer >= 1 - -**Default**: `32` - - - - - - - -**Choices**: Integer >= 1 - -**Default**: `128` - - - - - - - -**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]` - -**Default**: None - - - - - - - -**Choices**: `True`, `False` - -**Default**: `True` - - - - - - - -Options for measurement noise learning. - -[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options) - - - - - -**Choices**: Integer >= 1 - -**Default**: `32` - - - - - - - -**Choices**: Integer, `auto` - -**Default**: `auto` - - - - - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - - - -Probabilistic error cancellation mitigation options. - -[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options) - - - - - -**Choices**: `None`, Integer >= 1 - - -**Default**: `100` - - - - - - - -**Choices**: `auto`, float in the range [0, 1] - -**Default**: `auto` - - - - - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - - - -[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options) - - - - - -**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea` - -**Default**: `gate_folding` - - - - - - - -**Choices**: List of floats - -**Default**: `[0, *noise_factors]` - - - - - - - -**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback` - -**Default**: `(exponential, linear)` - - - - - - - -**Choices**: List of floats; each float >= 1 - -**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise - - - - - - - - - - - - -How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times. - -**Choices**: `0`, `1`, `2` - -**Default**: `1` - -[`resilience_level` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience_level) - - - - - -**Choices**: Integer - -**Default**: None - -[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator) - - - - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) - - - -**Choices**: List of basis gate names to unroll to - -**Default**: The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) - - - - - - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - - - - - - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - - - - - - - -**Choices**: Integer - -**Default**: None - - - - - - - - - - - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) - - - -**Choices**: True, False - -**Default**: False - - - - - - - -**Choices**: True, False - -**Default**: True - - - - - - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - - - - - - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - - - - - - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - - - - - - - - - - - - -Experimental options, when available. - - - - - - - - - - - - - -The total number of shots to use per circuit per configuration. - -**Choices**: Integer >= 0 - -**Default**: None - -[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#default_shots) - - - - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - -**Choices**: `middle`, `edges` - -**Default**: `middle` - - - - - -Choices: `asap`, `alap` -Default: `alap` - - - - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` - - - - - -Choices: `True`, `False` -Default: `False` - - - - - - - - - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) - - - -List of tags. - -**Choices**: None - -**Default**: None - - - - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING - - - - - -**Choices**: `True`, `False` - -**Default**: `False` - - - - - - - - - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) - - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` - - - - -The delay between a measurement and the subsequent quantum circuit. - -**Choices**: Value in the range supplied by `backend.rep_delay_range` - -**Default**: Given by `backend.default_rep_delay` - - - - - -**Choices**: `classified`, `kerneled`, `avg_kerneled` - -**Default**: `classified` - - - - - - - - - -**Choices**: Integer number of seconds in the range [1, 10800] - -**Default**: 10800 (3 hours) - -[`max_execution_time` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#max_execution_time) - - - - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) - - - -**Choices**: List of basis gate names to unroll to - -**Default**: The set of all basis gates supported by [Qiskit Aer simulator](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.AerSimulator.html) - - - - - - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - - - - - - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - - - - - - - -**Choices**: Integer - -**Default**: None - - - - - - - - - - - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) - - - -**Choices**: True, False - -**Default**: False - - - - - - - -**Choices**: True, False - -**Default**: False - - - - - - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - - - - - - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - - - - - - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - - - - - - - - - - - - -Experimental options, when available. - - - - - - - - - - - - -## Feature compatibility - -Due to differences in the device compilation process, 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: - - - - Incompatible with: - - Gate-folding ZNE - - PEA - - PEC - - Dynamical decoupling - - Other notes: - - 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. - - Compatible with fractional gates when using `qiskit-ibm-runtime` v0.42.0 or later. - - - - Incompatible with dynamic circuits. - - - - - Incompatible with: - - Gate twirling - - PEA - - PEC - - Compatible with dynamic circuits when using `qiskit-ibm-runtime` v0.42.0 or later. - - - - - Incompatible with: - - Dynamic circuits - - PEA - - PEC - - Might not work when using custom gates. - - - Incompatible with fractional gates or with stretches. - - Other notes: - - 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. - - Does not work with non-Clifford entanglers. - - - - - Incompatible with: - - Dynamic circuits - - Fractional gates - - Gate-folding ZNE - - PEC - - - - Incompatible with: - - Dynamic circuits - - Fractional gates - - Gate-folding ZNE - - PEA - - - +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. ## Next steps - - Find more details about the `EstimatorV2` methods in the [Estimator API reference](/docs/api/qiskit-ibm-runtime/estimator-v2). - - Find more details about the `SamplerV2` methods in the [Sampler API reference](/docs/api/qiskit-ibm-runtime/sampler-v2). - - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](configure-error-mitigation). - - Learn how to [specify options](specify-runtime-options). + - Find details about how to configure [error suppression](error-mitigation-and-suppression-techniques) and [error mitigation](error-mitigation-and-suppression-techniques). + - Learn more about [Estimator options](/docs/guides/estimator-options). + - Learn more about [Sampler options](/docs/guides/sampler-options). diff --git a/docs/guides/sampler-examples.ipynb b/docs/guides/sampler-examples.ipynb new file mode 100644 index 00000000000..3aff3c22a89 --- /dev/null +++ b/docs/guides/sampler-examples.ipynb @@ -0,0 +1,357 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0be36083-7bf5-48b7-9241-7979d6853d0c", + "metadata": {}, + "source": [ + "---\n", + "title: Sampler examples\n", + "description: Practical examples of using the Sampler primitive in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Sampler examples" + ] + }, + { + "cell_type": "markdown", + "id": "ef0ce9e6-eee0-4b4b-a068-52e8cbd69115", + "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": "ab973ab2-72aa-4a57-9132-b46002738489", + "metadata": {}, + "source": [ + "Generate entire error-mitigated quasi-probability distributions sampled from quantum circuit outputs. Leverage Sampler’s capabilities for search and classification algorithms like Grover’s and QVSM.\n", + "\n", + "## Run a single experiment\n", + "\n", + "Use Sampler to return the measurement outcome as bitstrings or counts of a single circuit." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "fffb9af3-e122-4ca9-93e3-79edd6112ff8", + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > First ten results: ['0101110000110001001111000101001111000110110100011000100101011101110011010010010101000110000111101010101000001010000100100000100', '0100010101111101010000100010011100110001010000011000000010001100010111000011001010000100100000100000000010000000010010101011110', '1101010111111111100010000011101010101010100100011001000000001001110010001000000010000010000101000111000100010010000001111000010', '1001110001100001001101111010111100000100010110010001001100111000110010111000001010001000000000000000100101101001110010101000110', '0001000000011011000011000111001000000000100110110011111110110100110000101010100010000010101011011000101011101000100000110000011', '1011100010011111010000001110110000111101000001110010011001100011111010001100100000110001000010001010110011100010000111000111010', '1101110000011000001011011000001111001110010111111111100100010001110100000010000001011000110000000011010011110100101001101000010', '0110100000110011000011001000110110110001000100100001111010001101000001010111000000101010101000001110100100001010110001000100101', '1000011010011011001111010010100000001110010010100000011010000110011010100000111000010010100111000001100101100010110010101001010', '1011011100111001010010101001000111000001110011110011001111010100100011101111011101011000000111011010000011100011010000001000000']\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import random_hermitian\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", + "\n", + "n_qubits = 127\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "mat = np.real(random_hermitian(n_qubits, seed=1234))\n", + "circuit = iqp(mat)\n", + "circuit.measure_all()\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "isa_circuit = pm.run(circuit)\n", + "\n", + "sampler = Sampler(backend)\n", + "job = sampler.run([isa_circuit])\n", + "result = job.result()\n", + "\n", + "# Get results for the first (and only) PUB\n", + "pub_result = result[0]\n", + "\n", + "print(f\" > First ten results: {pub_result.data.meas.get_bitstrings()[:10]}\")" + ] + }, + { + "cell_type": "markdown", + "id": "6b1cd3d9-8487-4889-9cd6-638a13fc7127", + "metadata": {}, + "source": [ + "## Run multiple experiments in a single job\n", + "\n", + "Use Sampler to return the measurement outcome as bitstrings or counts of multiple circuits in one job." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "4f68f509-7965-41f7-9f5e-7922a45ba22d", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > First ten results for pub 0: ['1000000101000100010111001010101010000001001010101011011001011110001000000110110101010000010000000000110001001000011111110000001', '1111101011011011110001011000001100001101100001000101111011101110000101111010001011111010001001000010111001110111000010001011010', '1100100101110010000110101011110010111001101010001101100010110100110110000110110010001110001000001010011100001000011011000111010', '1100010010000100100010110100011010011001010101101101101001100001001110011001011011111100011100100001000101010000111101110001101', '0011101011101100010011111001001110000101100110000110000001111000011010011110000110100000110011011000000010110001010000111000100', '0110101101110000010110100100010011000100100010000010010010110001111111110000101011000100010000000100100100110011010111101110111', '1101011000111100011000010110000010001100101011000001110010110001111101010101011110110010000100011101000001010110010101000000100', '0000101010010100000010111110111000001011000000001011000110100010110011111000110110010110011010111101001011000000001101001110110', '1100101000110001000011111110010001011000010110010101101000000101011110000100011011111011011010001001110011011101001101010100000', '0110011000101110101001010100110010101000010111100001000111011000110101011010010101110011001010101000001001001000110010100010101']\n", + " > First ten results for pub 1: ['1100100001011010010100000110101010100111101100110000100001011000100010001101010101101110000011010010011000010000010001000001000', '1100000011000000100110011000000110010000011111000000001010000101000010011001000001010000001000001010001000110010111000010000000', '0010000111101000111010101010101001010000001110100001011011100011000111000000010101001000010101001100000010100010011000000000010', '0010100100001000011100001010011000001010000010001000000001011100001010001110010110111101101000001101010101000000000011000100110', '0101101000011110111000100010000000101110100001010101110010001100001100001000111111110101001010100110000000010011111111000000010', '0101010111000000001110100110100011010111000111110100010010010001011010001000101001100001100110001001001000010010000011100100000', '0110010000001110111010010100010010010011010010110101001110010010001001101010111000010000000100011001001000001111010001100010010', '1100001100101011011010000110111110001101010100010100101100111000010000101101101010111011111011101100000000110000100101001000101', '0000111100001000000101101001010111110100011011011101101111000000001010001001100010110000100000000001010100110001001100110010000', '0100100001001011110000110001100001111011111100000001010111011011100010110111101110101111101010100101000000110111000110000000000']\n", + " > First ten results for pub 2: ['1000010100111010101010111110101000110101010001111110011110011001010100001100100000000001000111111011001101100001001110011101100', '1110100000111000000000110110010100000011110000011110000110100010000100001100010101101001100100010111000010100101011000001000000', '1000010111011000000001110111010101000111111010010011110100001010000000111111100100001111111101010100001001011100111101010000010', '0000111011110110010011100111001010001000011010010110010010101000101110011100000010000101011000101001001001000100111101010100100', '0100000100111101110000101111011000100111101011101110100001000001000010101111100100000111010001101001100001100011011110101101100', '0100001000110101010010010100100110000100001010100001110001110101010011000111100111001001100000010100110111010111010100010100100', '0011111000010001101100000110111001000000100111110100001100001100010010010101011000000111011011111010100010000100100000100000000', '1000010010101100110110110110100010100000111001101011110100001000011000001000000110010001001011100100000000100000000000000000000', '0001011100010011111110011110000001000000010100111111000000101010000011011110110000110001010010000010010001000101110001111100010', '1111010100011100010010010110000101110000010001100101011111001100010111100001011001000001011010111011100001000001100000000000110']\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import random_hermitian\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", + "\n", + "n_qubits = 127\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "rng = np.random.default_rng()\n", + "mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]\n", + "circuits = [iqp(mat) for mat in mats]\n", + "for circuit in circuits:\n", + " circuit.measure_all()\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "isa_circuits = pm.run(circuits)\n", + "\n", + "sampler = Sampler(mode=backend)\n", + "job = sampler.run(isa_circuits)\n", + "result = job.result()\n", + "\n", + "for idx, pub_result in enumerate(result):\n", + " print(\n", + " f\" > First five results for pub {idx}: {pub_result.data.meas.get_bitstrings()[:5]}\"\n", + " )" + ] + }, + { + "cell_type": "markdown", + "id": "f6298621-8160-4e8b-8f43-316c5e388dd0", + "metadata": {}, + "source": [ + "## Run parameterized circuits\n", + "\n", + "Run several experiments in a single job, leveraging parameter values to increase circuit reusability." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "b8633a12-3cbc-42a2-85db-4ea1a2d7bda7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " >> First ten results for the meas output register: ['1100011011100001011000001001000001111110000001011100011110011100111110000111000100011100001111100010010111110001001111011000101', '1100011101010101010000100110110110010001100101011101001011101010111110000111110100000011111010101101011101101101001111011110011', '0000000011000011001101001000111110001100010010011011001111000101000000001111111101101011100111010110111101010111011001010001011', '0101010001101110100010001100111001011101101100001000100001011101110100001000011011001011110101000110010001001010011011100011101', '0110101110000010110000001000010101100010010001001001101000010100110001011111110001000001100110010001011111001010011001001000101', '0111011111110111010111100110101000010100101000001010001001011111010010100111110110000011100001100000110000111000011011100000000', '0110100111001000100100110110010001011110000000110111000011110000100111001000100110011100100001100000101111111100010111100111001', '0101101111010110000000001000010110100101001100001101110010101111010110001010000111010010001111000000011001001001111100111010110', '0100000110010101111011110111000010001101011110010000110010001111001101010010000011111100100101101000010000111100111010000000110', '0011110110011011000110000100100110111000000010010101111011111000111001100011110100001100010100100001110101110100011100110001100']\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import real_amplitudes\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n", + "\n", + "n_qubits = 127\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "# Step 1: Map classical inputs to a quantum problem\n", + "circuit = real_amplitudes(num_qubits=n_qubits, reps=2)\n", + "circuit.measure_all()\n", + "\n", + "# Define three sets of parameters for the circuit\n", + "rng = np.random.default_rng(1234)\n", + "parameter_values = [\n", + " rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)\n", + "]\n", + "\n", + "# Step 2: Optimize problem for quantum execution.\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "isa_circuit = pm.run(circuit)\n", + "\n", + "# Step 3: Execute using Qiskit primitives.\n", + "sampler = Sampler(backend)\n", + "job = sampler.run([(isa_circuit, parameter_values)])\n", + "result = job.result()\n", + "# Get results for the first (and only) PUB\n", + "pub_result = result[0]\n", + "# Get counts from the classical register \"meas\".\n", + "print(\n", + " f\" >> First five results for the meas output register: {pub_result.data.meas.get_bitstrings()[:5]}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "06bf761a-e9b7-47ca-911e-01b126090466", + "metadata": {}, + "source": [ + "## Use batches and advanced options\n", + "\n", + "Explore the batch [execution mode](/docs/guides/execution-modes) and advanced options to optimize circuit performance on QPUs." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "536ac5b5-00cf-42bf-a114-28144008d744", + "metadata": { + "scrolled": true + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > The first five measurement results of job 1: ['1001111000111001100010010111000111101101000000101000010010101001110000000010001110010001011000100100000101010010000001001000010', '0000010000001101010100011001001011011010000110000100011000000000011000010111101100010101011100100101000110011000110000000000011', '0001100011110010110100110010111001001110101100100010011001100100111000110011000100000000100001001001100100101010110010000111101', '1000100111000111010011111010010111011001100000001001101010100001101010010110100100001010000000101110100010000000100110001100000', '1011011111101100000001001010111100001001111010000000001011001000011010000101110000101010101011000110110011010011011000010000001']\n" + ] + } + ], + "source": [ + "import numpy as np\n", + "from qiskit.circuit.library import iqp\n", + "from qiskit.quantum_info import random_hermitian\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "n_qubits = 127\n", + "\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=n_qubits\n", + ")\n", + "\n", + "rng = np.random.default_rng(1234)\n", + "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", + "circuit = iqp(mat)\n", + "circuit.measure_all()\n", + "mat = np.real(random_hermitian(n_qubits, seed=rng))\n", + "another_circuit = iqp(mat)\n", + "another_circuit.measure_all()\n", + "\n", + "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", + "isa_circuit = pm.run(circuit)\n", + "another_isa_circuit = pm.run(another_circuit)\n", + "\n", + "# The context manager automatically closes the batch.\n", + "with Batch(backend=backend) as batch:\n", + " sampler = Sampler(mode=batch)\n", + " job = sampler.run([isa_circuit])\n", + " another_job = sampler.run([another_isa_circuit])\n", + " result = job.result()\n", + " another_result = another_job.result()\n", + "\n", + "# first job\n", + "\n", + "print(\n", + " f\" > The first five measurement results of job 1: {result[0].data.meas.get_bitstrings()[:5]}\"\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "44b4c746-232b-4876-87c4-002cf6d11db7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " > The first five measurement results of job 2: ['1100111000010110001000101110100001011010101100101001111000100100010101111111001000000000000000110000001100110001001000000010000', '0011010001111000001011011010011000110010101111001100000000011110011011110010010011010000000010010011001011001110010001000100100', '0101001001101010011010011000001001010000001111001100001001011100110001001001001110100001101000000101000001000011000000000110100', '0100010010100000101000001001100010000110100111010000101010010110111111110010000011001110000001100000001011000000000100000000001', '1101000000001110110101011000011111111101011101100010000001011010010001110100001010001010010110100010000010100011000000010100100']\n" + ] + } + ], + "source": [ + "# second job\n", + "print(\n", + " \" > The first five measurement results of job 2:\",\n", + " another_result[0].data.meas.get_bitstrings()[:5],\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "d5c423e4-7586-4fdf-8452-3c62a705c955", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - [Specify advanced runtime options](runtime-options-overview).\n", + " - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n", + " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings) guide.\n", + " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", + " - Understand the [Job limits](/docs/guides/job-limits) when sending a job to an IBM® QPU.\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/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb new file mode 100644 index 00000000000..24db97dcd0f --- /dev/null +++ b/docs/guides/sampler-input-output.ipynb @@ -0,0 +1,702 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a9b93ac2-c4fc-41cb-a50a-90bd04c33925", + "metadata": {}, + "source": [ + "---\n", + "title: Sampler inputs and outputs\n", + "description: Understand the input and output format of Sampler primitives\n", + "---\n", + "\n", + "\n", + "# Sampler inputs and outputs" + ] + }, + { + "cell_type": "markdown", + "id": "0968eebe-d9a2-49c0-b3cb-608b4c51f43a", + "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": "4ca46213-798b-4b71-9abb-32edc17d9c51", + "metadata": {}, + "source": [ + "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitive, which executes workloads on IBM Quantum® compute resources. Sampler lets you efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**](/docs/guides/primitive-input-output#pubs). They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the Sampler primitive, which executes the defined workload as a job. Then, after the job has completed, the results are returned in a format that is dependent on both the PUBs used as well as the runtime options specified from the primitive." + ] + }, + { + "cell_type": "markdown", + "id": "d8943823-a8b8-4249-b038-2521cb5b9936", + "metadata": {}, + "source": [ + "## Inputs\n", + "\n", + "Each PUB is in the format:\n", + "\n", + "(``, ``, ``),\n", + "\n", + "There can be multiple `parameter values` items, and each item can be either an array or a single parameter, depending on the chosen circuit. Additionally, the input must contain measurements.\n", + "\n", + "For the Sampler primitive, a PUB can contain at most three values:\n", + "- A single `QuantumCircuit`, which may contain one or more [`Parameter`](/docs/api/qiskit/qiskit.circuit.Parameter) objects\n", + " *Note: These circuits should also include measurement instructions for each of the qubits to be sampled.*\n", + "- A collection of parameter values to bind the circuit against $\\theta_k$ (only needed if any `Parameter` objects are used that must be bound at runtime)\n", + "- (Optionally) a number of shots to measure the circuit with" + ] + }, + { + "cell_type": "markdown", + "id": "52df53ff-1cf8-448e-9fc5-a199acc2c5a6", + "metadata": {}, + "source": [ + "---\n", + "\n", + "The following code demonstrates an example set of vectorized inputs to the `Sampler` primitive and executes them on an IBM® backend as a single `RuntimeJobV2 ` object." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "02d5aad4-6939-4b77-9358-12610fcb1376", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.circuit import (\n", + " Parameter,\n", + " QuantumCircuit,\n", + " ClassicalRegister,\n", + " QuantumRegister,\n", + ")\n", + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit.quantum_info import SparsePauliOp\n", + "from qiskit.primitives.containers import BitArray\n", + "\n", + "from qiskit_ibm_runtime import (\n", + " QiskitRuntimeService,\n", + " SamplerV2 as Sampler,\n", + ")\n", + "\n", + "import numpy as np\n", + "\n", + "# Instantiate runtime service and get\n", + "# the least busy backend\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(operational=True, simulator=False)\n", + "\n", + "# Define a circuit with two parameters.\n", + "circuit = QuantumCircuit(2)\n", + "circuit.h(0)\n", + "circuit.cx(0, 1)\n", + "circuit.ry(Parameter(\"a\"), 0)\n", + "circuit.rz(Parameter(\"b\"), 0)\n", + "circuit.cx(0, 1)\n", + "circuit.h(0)\n", + "circuit.measure_all()\n", + "\n", + "# Transpile the circuit\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "transpiled_circuit = pm.run(circuit)\n", + "layout = transpiled_circuit.layout\n", + "\n", + "# Now define a sweep over parameter values, the last axis of dimension 2 is\n", + "# for the two parameters \"a\" and \"b\"\n", + "params = np.vstack(\n", + " [\n", + " np.linspace(-np.pi, np.pi, 100),\n", + " np.linspace(-4 * np.pi, 4 * np.pi, 100),\n", + " ]\n", + ").T\n", + "\n", + "sampler_pub = (transpiled_circuit, params)\n", + "\n", + "# Instantiate the new Sampler object, then run the transpiled circuit\n", + "# using the set of parameters and observables.\n", + "sampler = Sampler(mode=backend)\n", + "job = sampler.run([sampler_pub])\n", + "result = job.result()" + ] + }, + { + "cell_type": "markdown", + "id": "595fe657-1c7b-4423-9917-5b5f094ac1d4", + "metadata": {}, + "source": [ + "## Outputs\n", + "\n", + "After one or more PUBs are sent to a QPU for execution and a job successfully completes, the data is returned as a [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) container object accessed by calling the `RuntimeJobV2.result()` method. The `PrimitiveResult` contains an iterable list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult) objects that contain the execution results for each PUB. These data are samples of the circuit output.\n", + "\n", + "Each element of this list corresponds to a PUB submitted to the primitive's `run()` method (for example, a job submitted with 20 PUBs will return a `PrimitiveResult` object that contains a list of 20 `SamplerPubResult` objects, one corresponding to each PUB).\n", + "\n", + "Each `SamplerPubResult` object possesses both a `data` and a `metadata` attribute.\n", + " - The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. The data bins are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", + " - The `BitArray` class is a container for ordered shot data. It stores the sampled bitstrings as bytes inside a two-dimensional array. The left-most axis of this array runs over ordered shots, while the right-most axis runs over bytes.\n", + " - The `metadata` attribute contains information about the runtime options used (explained later in the [Result metadata](#result-metadata) section of this page).\n", + "\n", + "\n", + "The following is a visual outline of the `PrimitiveResult` data structure:\n", + "\n", + "```\n", + " └── PrimitiveResult\n", + " ├── SamplerPubResult[0]\n", + " │ ├── metadata\n", + " │ └── data ## In the form of a DataBin object\n", + " │ ├── NAME_OF_CLASSICAL_REGISTER\n", + " │ │ └── BitArray of count data (default is 'meas')\n", + " | |\n", + " │ └── NAME_OF_ANOTHER_CLASSICAL_REGISTER\n", + " │ └── BitArray of count data (exists only if more than one\n", + " | ClassicalRegister was specified in the circuit)\n", + " ├── SamplerPubResult[1]\n", + " | ├── metadata\n", + " | └── data ## In the form of a DataBin object\n", + " | └── NAME_OF_CLASSICAL_REGISTER\n", + " | └── BitArray of count data for second pub\n", + " ├── ...\n", + " ├── ...\n", + " └── ...\n", + "```\n", + "\n", + "Put simply, a single job returns a [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object and contains a list of one or more [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult) objects. These `SamplerPubResult` objects then store the measurement data for each PUB that was submitted to the job.\n", + "\n", + "As a first example, let us look at the following ten-qubit circuit:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "4b4c4f1d-d4d8-4b74-a2e3-147f150e4f7c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Databin: DataBin(meas=BitArray())\n", + "\n", + "BitArray: BitArray()\n", + "\n", + "The shape of register `meas` is (4096, 2).\n", + "\n", + "The bytes in register `alpha`, shot by shot:\n", + "[[ 3 255]\n", + " [ 3 255]\n", + " [ 2 0]\n", + " ...\n", + " [ 0 0]\n", + " [ 0 0]\n", + " [ 3 255]]\n", + "\n" + ] + } + ], + "source": [ + "# generate a ten-qubit GHZ circuit\n", + "circuit = QuantumCircuit(10)\n", + "circuit.h(0)\n", + "circuit.cx(range(0, 9), range(1, 10))\n", + "\n", + "# append measurements with the `measure_all` method\n", + "circuit.measure_all()\n", + "\n", + "# transpile the circuit\n", + "transpiled_circuit = pm.run(circuit)\n", + "\n", + "# run the Sampler job and retrieve the results\n", + "sampler = Sampler(mode=backend)\n", + "job = sampler.run([transpiled_circuit])\n", + "result = job.result()\n", + "\n", + "# the data bin contains one BitArray\n", + "data = result[0].data\n", + "print(f\"Databin: {data}\\n\")\n", + "\n", + "# to access the BitArray, use the key \"meas\", which is the default name of\n", + "# the classical register when this is added by the `measure_all` method\n", + "array = data.meas\n", + "print(f\"BitArray: {array}\\n\")\n", + "print(f\"The shape of register `meas` is {data.meas.array.shape}.\\n\")\n", + "print(f\"The bytes in register `alpha`, shot by shot:\\n{data.meas.array}\\n\")" + ] + }, + { + "cell_type": "markdown", + "id": "1c4bda5e-60d7-4027-9f12-be185d4f230d", + "metadata": {}, + "source": [ + "It can sometimes be convenient to convert away from the bytes format in the `BitArray` to bitstrings. The `get_count` method returns a dictionary mapping bitstrings to the number of times that they occurred." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "0277e73b-517e-4ae7-9340-fa9be4b98ca8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Counts: {'1111111111': 1345, '1000000000': 42, '0000000000': 1538, '0000000001': 36, '0000001111': 31, '1101111111': 57, '1110110111': 1, '1111110110': 4, '1111110000': 15, '1111111101': 33, '1111111110': 94, '1111110111': 50, '0000000101': 4, '0001000000': 11, '1111000000': 19, '1111011111': 68, '0000000010': 20, '0000001101': 4, '0000011111': 54, '0000100001': 1, '1111011000': 2, '0000000111': 38, '0000100000': 40, '0001110111': 2, '1101111101': 3, '1110000000': 32, '1100000000': 35, '0010000000': 28, '0000001000': 30, '1101000000': 1, '1111100000': 62, '0000111111': 21, '0111111111': 26, '1111111000': 27, '1110111111': 15, '0000000011': 17, '0011111111': 18, '0001111111': 43, '1111111100': 15, '1111001111': 4, '1111111011': 14, '0111111110': 1, '0011111000': 1, '1111011101': 2, '1111011110': 6, '1111110101': 1, '1000000001': 1, '0010000001': 4, '0001100000': 2, '1000011111': 3, '0010000010': 2, '0100100000': 1, '0001110000': 1, '0011111011': 1, '0000010110': 2, '1111101111': 12, '0011011111': 2, '1011111111': 7, '0000001010': 1, '0001000001': 1, '1101011111': 4, '1101100000': 3, '1110100111': 1, '0000100010': 1, '1101111000': 3, '0101111110': 1, '1111101000': 1, '0011110000': 2, '1111100010': 2, '0001111101': 3, '0001000011': 1, '0000010111': 1, '0000010000': 6, '0000111110': 4, '0111011111': 4, '1011100000': 2, '1110011111': 2, '0000011110': 6, '0011111110': 1, '0000011011': 2, '1110100001': 1, '0011110111': 1, '0000001110': 2, '0011111100': 2, '1100000001': 2, '0111110000': 2, '0010000011': 1, '1111010111': 2, '1101110111': 2, '0000110000': 1, '0000011100': 1, '0111011101': 1, '0010011110': 1, '0000011101': 3, '0100000000': 3, '1111111010': 2, '0000000100': 1, '1100000010': 1, '1110000111': 2, '1110111000': 1, '1111101011': 1, '1011111110': 2, '1000001000': 1, '1111100111': 2, '1111110011': 1, '1001111111': 2, '0111011110': 1, '1110100000': 2, '1110111101': 1, '0010011111': 3, '0001011111': 3, '1101110000': 1, '1111101100': 1, '1000001111': 1, '0000011000': 1, '1111100110': 1, '1011111101': 2, '1111101110': 1, '1110000011': 2, '1111100011': 2, '0111111101': 1, '1111110001': 1, '1010000000': 1, '1111111001': 1, '0000101111': 2, '0011101111': 1, '1111100101': 1, '1111000001': 1, '1111100001': 2, '1100111111': 1, '0000111000': 1, '0000000110': 2, '1110001000': 1, '0000001011': 1, '1001000000': 1, '1111011011': 2, '1101111110': 1, '0111111000': 1, '0111100000': 2, '0000110111': 1, '1110111110': 1, '1001011110': 1, '0011110001': 1, '0000001001': 1, '0001111011': 1, '0001111000': 1, '1100001101': 1}\n" + ] + } + ], + "source": [ + "# optionally, convert away from the native BitArray format to a dictionary format\n", + "counts = data.meas.get_counts()\n", + "print(f\"Counts: {counts}\")" + ] + }, + { + "cell_type": "markdown", + "id": "baed272a-b5ce-4385-bbf5-4245d16fd63e", + "metadata": {}, + "source": [ + "When a circuit contains more than one classical register, the results are stored in different `BitArray` objects. The following example modifies the previous snippet by splitting the classical register into two distinct registers:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "a7cfcc03-1894-4ab3-965b-ec154b2a3766", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "BitArray for register 'alpha': BitArray()\n", + "BitArray for register 'beta': BitArray()\n" + ] + } + ], + "source": [ + "# generate a ten-qubit GHZ circuit with two classical registers\n", + "circuit = QuantumCircuit(\n", + " qreg := QuantumRegister(10),\n", + " alpha := ClassicalRegister(1, \"alpha\"),\n", + " beta := ClassicalRegister(9, \"beta\"),\n", + ")\n", + "circuit.h(0)\n", + "circuit.cx(range(0, 9), range(1, 10))\n", + "\n", + "# append measurements with the `measure_all` method\n", + "circuit.measure([0], alpha)\n", + "circuit.measure(range(1, 10), beta)\n", + "\n", + "# transpile the circuit\n", + "transpiled_circuit = pm.run(circuit)\n", + "\n", + "# run the Sampler job and retrieve the results\n", + "sampler = Sampler(mode=backend)\n", + "job = sampler.run([transpiled_circuit])\n", + "result = job.result()\n", + "\n", + "# the data bin contains two BitArrays, one per register, and can be accessed\n", + "# as attributes using the registers' names\n", + "data = result[0].data\n", + "print(f\"BitArray for register 'alpha': {data.alpha}\")\n", + "print(f\"BitArray for register 'beta': {data.beta}\")" + ] + }, + { + "cell_type": "markdown", + "id": "84312f3e-94dc-4aa4-ace0-86d3c9c63937", + "metadata": {}, + "source": [ + "### Use `BitArray` objects for performant post-processing\n", + "\n", + "Since arrays generally offer better performance compared to dictionaries, it is advisable to perform any post-processing directly on the `BitArray` objects rather than on dictionaries of counts. The `BitArray` class offers a range of methods to perform some common post-processing operations:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "b37b1285-dbe3-4aa0-a806-eacb43cef87e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The shape of register `alpha` is (4096, 1).\n", + "The bytes in register `alpha`, shot by shot:\n", + "[[1]\n", + " [0]\n", + " [0]\n", + " ...\n", + " [0]\n", + " [1]\n", + " [0]]\n", + "\n", + "The shape of register `beta` is (4096, 2).\n", + "The bytes in register `beta`, shot by shot:\n", + "[[ 0 255]\n", + " [ 1 255]\n", + " [ 1 254]\n", + " ...\n", + " [ 0 0]\n", + " [ 1 255]\n", + " [ 0 0]]\n", + "\n", + "The shape of `beta` after post-selection is (0, 2).\n", + "The bytes in `beta` after post-selection:\n", + "[]\n", + "The shape of `beta` after bit-wise slicing is (4096, 1).\n", + "The bytes in `beta` after bit-wise slicing:\n", + "[[7]\n", + " [7]\n", + " [6]\n", + " ...\n", + " [0]\n", + " [7]\n", + " [0]]\n", + "\n", + "The shape of `beta` after shot-wise slicing is (5, 2).\n", + "The bytes in `beta` after shot-wise slicing:\n", + "[[ 0 255]\n", + " [ 1 255]\n", + " [ 1 254]\n", + " [ 0 0]\n", + " [ 0 255]]\n", + "\n", + "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", + " coeffs=[1.+0.j])` is: 0.11962890625\n", + "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", + " coeffs=[1.+0.j])` is: 0.04931640625\n", + "\n", + "The shape of the merged results is (4096, 2).\n", + "The bytes of the merged results:\n", + "[[ 1 255]\n", + " [ 3 254]\n", + " [ 3 252]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 255]\n", + " [ 0 0]]\n", + "\n" + ] + } + ], + "source": [ + "print(f\"The shape of register `alpha` is {data.alpha.array.shape}.\")\n", + "print(f\"The bytes in register `alpha`, shot by shot:\\n{data.alpha.array}\\n\")\n", + "\n", + "print(f\"The shape of register `beta` is {data.beta.array.shape}.\")\n", + "print(f\"The bytes in register `beta`, shot by shot:\\n{data.beta.array}\\n\")\n", + "\n", + "# post-select the bitstrings of `beta` based on having sampled \"1\" in `alpha`\n", + "mask = data.alpha.array == \"0b1\"\n", + "ps_beta = data.beta[mask[:, 0]]\n", + "print(f\"The shape of `beta` after post-selection is {ps_beta.array.shape}.\")\n", + "print(f\"The bytes in `beta` after post-selection:\\n{ps_beta.array}\")\n", + "\n", + "# get a slice of `beta` to retrieve the first three bits\n", + "beta_sl_bits = data.beta.slice_bits([0, 1, 2])\n", + "print(\n", + " f\"The shape of `beta` after bit-wise slicing is {beta_sl_bits.array.shape}.\"\n", + ")\n", + "print(f\"The bytes in `beta` after bit-wise slicing:\\n{beta_sl_bits.array}\\n\")\n", + "\n", + "# get a slice of `beta` to retrieve the bytes of the first five shots\n", + "beta_sl_shots = data.beta.slice_shots([0, 1, 2, 3, 4])\n", + "print(\n", + " f\"The shape of `beta` after shot-wise slicing is {beta_sl_shots.array.shape}.\"\n", + ")\n", + "print(\n", + " f\"The bytes in `beta` after shot-wise slicing:\\n{beta_sl_shots.array}\\n\"\n", + ")\n", + "\n", + "# calculate the expectation value of diagonal operators on `beta`\n", + "ops = [SparsePauliOp(\"ZZZZZZZZZ\"), SparsePauliOp(\"IIIIIIIIZ\")]\n", + "exp_vals = data.beta.expectation_values(ops)\n", + "for o, e in zip(ops, exp_vals):\n", + " print(f\"Exp. val. for observable `{o}` is: {e}\")\n", + "\n", + "# concatenate the bitstrings in `alpha` and `beta` to \"merge\" the results of the two\n", + "# registers\n", + "merged_results = BitArray.concatenate_bits([data.alpha, data.beta])\n", + "print(f\"\\nThe shape of the merged results is {merged_results.array.shape}.\")\n", + "print(f\"The bytes of the merged results:\\n{merged_results.array}\\n\")" + ] + }, + { + "cell_type": "markdown", + "id": "b98bbf1a-ed20-4f00-8273-b61e6986a614", + "metadata": {}, + "source": [ + "## Result metadata\n", + "\n", + "In addition to the execution results, both the `PrimitiveResult` and `SamplerPubResult` objects contain a metadata attribute about the job that was submitted. The metadata containing information for all submitted PUBs (such as the various [runtime options](/docs/api/qiskit-ibm-runtime/options) available) can be found in the `PrimitiveResult.metatada`, while the metadata specific to each PUB is found in `SamplerPubResult.metadata`.\n", + "\n", + "The Sampler result metadata also includes execution timing information called the [_execution span_](#execution-spans).\n", + "\n", + "\n", + "In the metadata field, primitive implementations can return any information about execution that is relevant to them, and there are no key-value pairs that are guaranteed by the base primitive. Thus, the returned metadata might be different in different primitive implementations.\n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "d39a495c-6cc9-4c5d-b988-9480b06f5879", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "The metadata of the PrimitiveResult is:\n", + "'execution' : {'execution_spans': ExecutionSpans([DoubleSliceSpan()])},\n", + "'version' : 2,\n", + "\n", + "The metadata of the PubResult result is:\n", + "'circuit_metadata' : {},\n" + ] + } + ], + "source": [ + "# Print out the results metadata\n", + "print(\"The metadata of the PrimitiveResult is:\")\n", + "for key, val in result.metadata.items():\n", + " print(f\"'{key}' : {val},\")\n", + "\n", + "print(\"\\nThe metadata of the PubResult result is:\")\n", + "for key, val in result[0].metadata.items():\n", + " print(f\"'{key}' : {val},\")" + ] + }, + { + "cell_type": "markdown", + "id": "5c4af5b4-5a9c-4d45-aa74-a0030b3b5ae0", + "metadata": {}, + "source": [ + "\n", + "### View execution spans\n", + "\n", + "The results of [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) jobs executed in Qiskit Runtime contain execution timing information in their metadata.\n", + "This timing information can be used to place upper and lower timestamp bounds on when particular shots were executed on the QPU.\n", + "Shots are grouped into [`ExecutionSpan`](/docs/api/qiskit-ibm-runtime/execution-span-execution-span) objects, each of which indicates a start time, a stop time, and a specification of which shots were collected in the span.\n", + "\n", + "An execution span specifies which data was executed during its window by providing an [`ExecutionSpan.mask`](/docs/api/qiskit-ibm-runtime/execution-span-execution-span#mask) method. This method, given any [Primitive Unified Block (PUB)](/docs/guides/primitive-input-output#pubs) index, returns a boolean mask that is `True` for all shots executed during its window. PUBs are indexed by the order in which they were given to the Sampler run call. If, for example, a PUB has shape `(2, 3)` and was run with four shots, then the mask's shape is `(2, 3, 4)`. See the [execution_span](/docs/api/qiskit-ibm-runtime/execution-span) API page for full details.\n", + "\n", + "To view execution span information, review the metadata of the result returned by `SamplerV2`, which comes in the form of an `ExecutionSpans` object. This object is a list-like container containing instances of subclasses of `ExecutionSpan`, such as `SliceSpan`.\n", + "\n", + "Example:" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "c03ea1ef-1536-491a-8cd7-1d75a8a11fdb", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "ExecutionSpans([DoubleSliceSpan()])\n" + ] + } + ], + "source": [ + "# Define two circuits, each with one parameter with two parameters.\n", + "circuit = QuantumCircuit(2)\n", + "circuit.h(0)\n", + "circuit.cx(0, 1)\n", + "circuit.ry(Parameter(\"a\"), 0)\n", + "circuit.cx(0, 1)\n", + "circuit.h(0)\n", + "circuit.measure_all()\n", + "\n", + "\n", + "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", + "transpiled_circuit = pm.run(circuit)\n", + "\n", + "params = np.random.uniform(size=(2, 3)).T\n", + "\n", + "sampler_pub = (transpiled_circuit, params)\n", + "\n", + "# Instantiate the new Estimator object, then run the transpiled circuit\n", + "# using the set of parameters and observables.\n", + "\n", + "job = sampler.run([sampler_pub], shots=4)\n", + "\n", + "result = job.result()\n", + "spans = job.result().metadata[\"execution\"][\"execution_spans\"]\n", + "print(spans)" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "f9a44122-1c93-4479-900c-ae9653642c7a", + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.primitives import BitArray\n", + "\n", + "# Get the mask of the 1st PUB for the 0th span.\n", + "mask = spans[0].mask(0)\n", + "\n", + "# Decide whether the 0th shot of parameter set (1, 2) occurred in this span.\n", + "in_this_span = mask[2, 1, 0]\n", + "\n", + "# Create a new bit array containing only the PUB-1 data collected during this span.\n", + "bits = result[0].data.meas\n", + "filtered_data = BitArray(bits.array[mask], bits.num_bits)" + ] + }, + { + "cell_type": "markdown", + "id": "f5914a81-7305-4535-aa5a-5c98a1487378", + "metadata": {}, + "source": [ + "Execution spans can be filtered to include information pertaining to specific PUBs, selected by their indices:" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "91709f8b-de00-4a20-ba5a-2fcfabbd2e5e", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ExecutionSpans([DoubleSliceSpan()])" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# take the subset of spans that reference data in PUBs 0 or 2\n", + "spans.filter_by_pub([0, 2])" + ] + }, + { + "cell_type": "markdown", + "id": "12b7de8b-e481-4304-9221-6e573374c8ba", + "metadata": {}, + "source": [ + "View global information about the collection of execution spans:" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "3e21b63c-e4ba-48e7-98b1-ed20597905bf", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Number of execution spans: 1\n", + " Start of the first span: 2026-04-14 20:16:08.452553\n", + " End of the last span: 2026-04-14 20:16:09.434031\n", + " Total duration (s): 0.981478\n" + ] + } + ], + "source": [ + "print(\"Number of execution spans:\", len(spans))\n", + "print(\" Start of the first span:\", spans.start)\n", + "print(\" End of the last span:\", spans.stop)\n", + "print(\" Total duration (s):\", spans.duration)" + ] + }, + { + "cell_type": "markdown", + "id": "8bf5e75b-ccd9-4893-b744-304166fca7a2", + "metadata": {}, + "source": [ + "Extract and inspect a particular span:" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "01f14a30-b683-4fca-baf9-02cd414f395e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + " Start of first span: 2026-04-14 20:16:08.452553\n", + " End of first span: 2026-04-14 20:16:09.434031\n", + "#shots in first span: 24\n" + ] + } + ], + "source": [ + "spans.sort()\n", + "print(\" Start of first span:\", spans[0].start)\n", + "print(\" End of first span:\", spans[0].stop)\n", + "print(\"#shots in first span:\", spans[0].size)" + ] + }, + { + "cell_type": "markdown", + "id": "a19cd90f-195f-4de1-a1f9-3daf9da9941e", + "metadata": {}, + "source": [ + " \n", + "It is possible for time windows specified by distinct execution spans to overlap. This is not because a QPU was performing multiple executions at once, but is instead an artifact of certain classical processing that might happen concurrently with quantum execution. The guarantee being made is that the referenced data definitely occurred in the reported execution span, but not necessarily that the limits of the time window are as tight as possible.\n", + "" + ] + } + ], + "metadata": { + "celltoolbar": "Raw Cell Format", + "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/sampler-noise-management.ipynb b/docs/guides/sampler-noise-management.ipynb new file mode 100644 index 00000000000..7cd773b8e41 --- /dev/null +++ b/docs/guides/sampler-noise-management.ipynb @@ -0,0 +1,146 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "b40b58ca-20e6-411f-8707-80ab3edf414d", + "metadata": {}, + "source": [ + "---\n", + "title: Configure noise management with Sampler\n", + "description: How to configure noise management with the Qiskit Runtime Estimator primitive.\n", + "---\n", + "\n", + "# Configure noise management with Sampler" + ] + }, + { + "cell_type": "markdown", + "id": "9dc0196d-5180-433b-8fbc-8f937330a0ea", + "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", + "\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", + "\n", + "```\n", + "qiskit-ibm-runtime~=0.45.1\n", + "```\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "eaa0b874-f0e6-4fc9-82f7-e993770ebf47", + "metadata": {}, + "source": [ + "There are several ways to manage noise, typically by using various error mitigation and error suppression techniques to avoid errors before they happen. These techniques usually cause pre-processing overhead. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.\n", + "\n", + "Sampler supports the following noise management techniques. See [Error mitigation and suppression techniques](error-mitigation-and-suppression-techniques) for an explanation of each.\n", + "\n", + "- [dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options#dynamicaldecouplingoptions)\n", + "- [Pauli twirling](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", + "\n", + "\n", + "\n", + "Not all options work together on all types of circuits. See the [feature compatibility table](/docs/guides/sampler-options#options-compatibility-table) guide for full details.\n", + "\n", + "\n", + "Example" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "ca9a0d48-34a2-4a22-a24c-46327c622a93", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + ">>> dynamical decoupling sequence to use: XpXm\n", + ">>> gate twirling is turned on: True\n" + ] + } + ], + "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(backend)\n", + "\n", + "# Turn on dynamical decoupling with sequence XpXm.\n", + "sampler.options.dynamical_decoupling.enable = True\n", + "sampler.options.dynamical_decoupling.sequence_type = \"XpXm\"\n", + "# Turn on gate twirling. Requires qiskit_ibm_runtime 0.23.0 or later.\n", + "sampler.options.twirling.enable_gates = True\n", + "\n", + "print(\n", + " f\">>> dynamical decoupling sequence to use: {sampler.options.dynamical_decoupling.sequence_type}\"\n", + ")\n", + "print(\n", + " f\">>> gate twirling is turned on: {sampler.options.twirling.enable_gates}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "db285d76-0e96-4ae4-a65c-3fdae1407bee", + "metadata": {}, + "source": [ + "\n", + "\n", + "## Next steps\n", + "\n", + "\n", + " - Learn more about [error mitigation and error suppression techniques](error-mitigation-and-suppression-techniques).\n", + " - Explore Sampler [options](/docs/guides/sampler-options).\n", + " - Decide what [execution mode](execution-modes) to run your job in.\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/sampler-options.ipynb b/docs/guides/sampler-options.ipynb new file mode 100644 index 00000000000..4e3dfbc42f0 --- /dev/null +++ b/docs/guides/sampler-options.ipynb @@ -0,0 +1,672 @@ +{ + "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", + "\n", + "# Specify Sampler options" + ] + }, + { + "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", + "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": "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", + "- 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", + "\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", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "3ca44016-acfe-4540-ab0e-659b9577c4eb", + "metadata": {}, + "source": [ + "\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." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c2423fcc-7f7f-4674-af6f-fc90f4b28b17", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 8, + "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" + ] + }, + { + "cell_type": "markdown", + "id": "857e40a1-de1d-46f0-9db8-db55a6954f47", + "metadata": {}, + "source": [ + "\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", + "4. 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", + "5. 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:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "e06376f4-fcba-4d03-8cbc-c53ca02d81af", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 6, + "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", + "## 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", + "\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", + "\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", + "\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", + "[`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", + "\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", + "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-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", + "**Choices**: `classified`, `kerneled`, `avg_kerneled`\n", + "\n", + "**Default**: `classified`\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", + "[`max_execution_time` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#max_execution_time)\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**: False\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": "80737dfd-a1c7-4b5f-b1ea-3391dcfa61b7", + "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", + " Incompatible with:\n", + " - Dynamical decoupling\n", + "\n", + " Other notes:\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 dynamic circuits.\n", + "\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - Gate twirling\n", + "\n", + " Compatible with dynamic circuits when using `qiskit-ibm-runtime` v0.42.0 or later.\n", + "\n", + " \n", + "\n", + " \n", + " Incompatible with fractional gates or with stretches.\n", + "\n", + " Other notes:\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", + " - Does not work with non-Clifford entanglers.\n", + "\n", + " \n", + "\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "b95e9e8e-575c-411e-8504-4ef0a00166d3", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "\n", + " - Find more details about the `SamplerV2` methods in the [Sampler API reference](../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", + "" + ] + } + ], + "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/sampler-rest-api.mdx b/docs/guides/sampler-rest-api.mdx new file mode 100644 index 00000000000..cbfa2531185 --- /dev/null +++ b/docs/guides/sampler-rest-api.mdx @@ -0,0 +1,347 @@ +--- +title: ampler with the REST API +description: How to use the Sampler primitive with the Qiskit Runtime REST API. +--- +{/* cspell:ignore IIZII, XIZZZ, accum */} + + +# Sampler with the REST API + +The steps in this topic describe how to run and configure workloads with the REST API, and demonstrate how to invoke them in any program of your choice. + + + This documentation utilizes the Python `requests` module to demonstrate the Qiskit Runtime REST API. However, this workflow can be executed using any language or framework that supports working with REST APIs. Refer to the [API reference documentation](/docs/api/qiskit-ibm-runtime/tags/jobs) for details. + + +## 1. Initialize the account + +Because Qiskit Runtime Sampler is a managed service, you first need to initialize your account. You can then select the device you want to use to run your calculations on. + + +Find details on how to initialize your account, view available backends, and work with tokens in [Set up to use IBM Quantum Platform with REST API](/docs/guides/cloud-setup-rest-api). + + +## 2. Create a QASM circuit + +You need at least one circuit as the input to the Sampler primitive. + + +Define a QASM quantum circuit: + +```python +qasm_string=''' +OPENQASM 3; +include "stdgates.inc"; +qreg q[2]; +creg c[2]; +x q[0]; +cx q[0], q[1]; +c[0] = measure q[0]; +c[1] = measure q[1]; +''' +``` + + +The code snippets given below assume that the `qasm_string` has been transpiled to a new string `resulting_qasm`. + + +## 3. Run the quantum circuit using Sampler V2 API + + + + The jobs below use [Qiskit Runtime V2 primitives](/docs/guides/v2-primitives). `SamplerV2` takes one or more primitive unified blocs (PUBs) as the input. Each PUB is a tuple that contains one circuit and the data broadcasted to that circuit, which can be multiple parameters, and returns one result per PUB. + + + +```python +import requests + +url = 'https://quantum.cloud.ibm.com/api/v1/jobs' +auth_id = "Bearer " +crn = "" +backend = "" + +headers = { + 'Content-Type': 'application/json', + 'Authorization':auth_id, + 'Service-CRN': crn + } +job_input = { + 'program_id': 'sampler', + "backend": backend, + "params": { + "pubs": [[resulting_qasm],[resulting_qasm,None,500]] # primitive unified blocs (PUBs) containing one circuit each. +}} + +response = requests.post(url, headers=headers, json=job_input) + +if response.status_code == 200: + job_id = response.json().get('id') + print("Job created:",response.text) +else: + print(f"Error: {response.status_code}") +``` + + + +## 4. Check job status and get results + +Next, pass the `job_id` to the API: + +```python +response_status_singlejob= requests.get(url+'/'+job_id, headers=headers) +response_status_singlejob.json().get('state') +``` +Output + +```text +>>> Job ID: 58223448-5100-4dec-a47a-942fb30edced +>>> Job Status: JobStatus.RUNNING +``` + +Get job results: +```python +response_result= requests.get(url+'/'+job_id+'/results', headers=headers) + +res_dict=response_result.json() + +# Get results for the first PUB +counts=res_dict['results'][0]['data']['c']['samples'] + +print(counts[:20]) +``` +Output +```text +['0x3', '0x0', '0x2', '0x1', '0x0', '0x3', '0x0', '0x3', '0x1', '0x2', '0x2', '0x0', '0x2', '0x0', '0x3', '0x3', '0x2', '0x0', '0x1', '0x0'] +``` + +## 5. Work with Qiskit Runtime options + +Error mitigation techniques allow users to mitigate circuit errors by modeling the device noise at the time of execution. This typically results in quantum pre-processing overhead related to model training, and classical post-processing overhead to mitigate errors in the raw results by using the generated model. + +The error mitigation techniques built in to primitives are advanced resilience options. To specify these options, use the `resilience_level` option when submitting your job. +Sampler V2 does not support specifying resilience levels. However, you can turn on or off individual error mitigation / suppression methods. + +The following examples demonstrate the default options for dynamical decoupling and twirling. Find more options and further details in the [Error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) topic. + +### Dynamical decoupling +```python +import requests + +url = 'https://quantum.cloud.ibm.com/api/v1/jobs' +auth_id = "Bearer " +crn = "" +backend = "" + +headers = { + 'Content-Type': 'application/json', + 'Authorization':auth_id, + 'Service-CRN': crn + } +job_input = { + 'program_id': 'sampler', + "backend": backend, + "params": { + "pubs": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each. + "options": { + "dynamical_decoupling": { + "enable": True, + "sequence_type": 'XpXm', + "extra_slack_distribution": 'middle', + "scheduling_method": 'alap', + }, + }, + } +} + +response = requests.post(url, headers=headers, json=job_input) + +if response.status_code == 200: + job_id = response.json().get('id') + print("Job created:",response.text) +else: + print(f"Error: {response.status_code}") +``` +### Twirling +```python +import requests + +url = 'https://quantum.cloud.ibm.com/api/v1/jobs' +auth_id = "Bearer " +crn = "" +backend = "" + +headers = { + 'Content-Type': 'application/json', + 'Authorization':auth_id, + 'Service-CRN': crn + } +job_input = { + 'program_id': 'sampler', + "backend": backend, + "params": { + "pubs": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each. + "options": { + "twirling": { + "enable_gates": True, + "enable_measure": True, + "num_randomizations": "auto", + "shots_per_randomization": "auto", + "strategy": "active-accum", + }, + }, + } +} + +response = requests.post(url, headers=headers, json=job_input) + +if response.status_code == 200: + job_id = response.json().get('id') + print("Job created:",response.text) +else: + print(f"Error: {response.status_code}") +``` + + + +## Parameterized circuits + +### 1. Initialize the account + +Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the device you want to use to run your calculations on. + + +Find details on how to initialize your account, view available backends, and invalidate tokens in this [topic](/docs/guides/cloud-setup-rest-api). + + +### 2. Define parameters + +```python +import requests +import qiskit_ibm_runtime +from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit.transpiler import generate_preset_pass_manager +from qiskit.qasm3 import dumps +from qiskit import QuantumCircuit +from qiskit.circuit import Parameter +from qiskit import transpile + +service = QiskitRuntimeService(channel='ibm_quantum') +backend = service.backend("") + +pm = generate_preset_pass_manager(backend=backend, optimization_level=1) + +theta = Parameter('theta') +phi = Parameter('phi') +parameter_values = {'theta': 1.57, 'phi': 3.14} # In case we want to pass a dictionary +``` + + +### 3. Create a quantum circuit and add parameterized gates + +```python +qc = QuantumCircuit(2) + +# Add parameterized gates +qc.rx(theta, 0) +qc.ry(phi, 1) +qc.cx(0, 1) +qc.measure_all() + +# Draw the original circuit +qc.draw('mpl') + +# Get an ISA circuit +isa_circuit = pm.run(qc) +``` + +### 4. Generate QASM 3 code + +```python +qasm_str = dumps(isa_circuit) +print("Generated QASM 3 code:") +print(qasm_str) +``` + +### 5. Run the quantum circuit using Sampler V2 API + +```python +import requests + +url = 'https://quantum.cloud.ibm.com/api/v1/jobs' +auth_id = "Bearer " +crn = "" +backend = "" + +headers = { + 'Content-Type': 'application/json', + 'Authorization':auth_id, + 'Service-CRN': crn + } + +job_input = { + 'program_id': 'sampler', + "backend": backend, + "params": { + # Choose one option: direct parameter transfer or through a dictionary + #"pubs": [[qasm_str,[1,2],500]], # primitive unified blocs (PUBs) containing one circuit each. + "pubs": [[qasm_str,parameter_values,500]], # primitive unified blocs (PUBs) containing one circuit each. +}} + +response = requests.post(url, headers=headers, json=job_input) + +if response.status_code == 200: + job_id = response.json().get('id') + print(f"Job created: {response.text}") +else: + print(f"Error: {response.status_code}") +``` + +```python +print(response.text) +``` + + +### 6. Check job status and get results + +Next, pass the `job_id` to the API: + +```python +response_status_singlejob = requests.get(f"{url}/{job_id}", headers=headers) +response_status_singlejob.json().get('state') +``` + +Output + +```text +{'status': 'Completed'} +``` + +Get job results: + +```python +response_result = requests.get(f"{url}/{job_id}/results", headers=headers) + +res_dict=response_result.json() + +# Get results for the first PUB +counts=res_dict['results'][0]['data']['c']['samples'] + +print(counts[:20]) +``` + +Output + +```text +['0x1', '0x2', '0x1', '0x2', '0x1', '0x2', '0x0', '0x2', '0x1', '0x1', '0x2', '0x2', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1', '0x1'] +``` + +## Next steps + + + + - There are several ways to run workloads, depending on your needs: job mode, session mode, and batch mode. Learn how to work with session mode and batch mode in the [execution modes topic](/docs/guides/execution-modes-rest-api). Note that Open Plan users cannot submit session jobs. + - Learn how to [initialize your account](/docs/guides/cloud-setup-rest-api) with REST API. + - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning. + - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section. + diff --git a/docs/guides/serverless-first-program.ipynb b/docs/guides/serverless-first-program.ipynb index 60a7816f08d..2a532614db7 100644 --- a/docs/guides/serverless-first-program.ipynb +++ b/docs/guides/serverless-first-program.ipynb @@ -406,7 +406,7 @@ "\n", "\n", "\n", - "- Learn how to pass inputs and run your program remotely in the [Run your first Qiskit Serverless workload remotely](./serverless-run-first-workload) topic.\n", + "- Learn how to pass inputs and run your program remotely in the [Run your first Qiskit Serverless workload remotely](/docs/guides/serverless-run-first-workload) topic.\n", "\n", "" ] diff --git a/docs/guides/serverless-manage-resources.ipynb b/docs/guides/serverless-manage-resources.ipynb index 8430f17cd40..a5969825e04 100644 --- a/docs/guides/serverless-manage-resources.ipynb +++ b/docs/guides/serverless-manage-resources.ipynb @@ -141,7 +141,7 @@ "source": [ "## Parallel workflows\n", "\n", - "For classical tasks that can be parallelized, use the `@distribute_task` decorator to define compute requirements needed to perform a task. Start by recalling the `transpile_remote.py` example from the [Write your first Qiskit Serverless program](./serverless-first-program) topic with the following code.\n", + "For classical tasks that can be parallelized, use the `@distribute_task` decorator to define compute requirements needed to perform a task. Start by recalling the `transpile_remote.py` example from the [Write your first Qiskit Serverless program](/docs/guides/serverless-first-program) topic with the following code.\n", "\n", "The following code requires that you have already [saved your credentials](/docs/guides/cloud-setup)." ] @@ -663,7 +663,7 @@ "\n", "\n", "\n", - "- See a full example that [ports existing code to Qiskit Serverless](./serverless-port-code).\n", + "- See a full example that [ports existing code to Qiskit Serverless](/docs/guides/serverless-port-code).\n", "- Read a paper in which researchers used Qiskit Serverless and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n", "\n", "" diff --git a/docs/guides/serverless-run-first-workload.ipynb b/docs/guides/serverless-run-first-workload.ipynb index 4f166e377da..b800839a0ee 100644 --- a/docs/guides/serverless-run-first-workload.ipynb +++ b/docs/guides/serverless-run-first-workload.ipynb @@ -59,7 +59,7 @@ "source": [ "## List programs available\n", "\n", - "You can use `QiskitServerless.list()` to fetch a list of the available programs to run with Qiskit Serverless. This includes the previously uploaded [`transpile_remote_serverless`](./serverless-first-program)." + "You can use `QiskitServerless.list()` to fetch a list of the available programs to run with Qiskit Serverless. This includes the previously uploaded [`transpile_remote_serverless`](/docs/guides/serverless-first-program)." ] }, { @@ -441,7 +441,7 @@ "\n", "\n", "\n", - "- Explore [compute and data management tools](./serverless-manage-resources) available to your program, including parallelization.\n", + "- Explore [compute and data management tools](/docs/guides/serverless-manage-resources) available to your program, including parallelization.\n", "\n", "" ] diff --git a/docs/guides/set-optimization.ipynb b/docs/guides/set-optimization.ipynb index cbce448d46f..044b8844620 100644 --- a/docs/guides/set-optimization.ipynb +++ b/docs/guides/set-optimization.ipynb @@ -390,7 +390,7 @@ "jp-MarkdownHeadingCollapsed": true }, "source": [ - "Adjusting the optimization level can change other aspects of the circuit too, not just the number of ECR gates. For examples of how setting optimization level changes the layout, see [Representing quantum computers](./represent-quantum-computers).\n", + "Adjusting the optimization level can change other aspects of the circuit too, not just the number of ECR gates. For examples of how setting optimization level changes the layout, see [Representing quantum computers](/docs/guides/represent-quantum-computers).\n", "\n", "## Next steps\n", "\n", diff --git a/docs/guides/simulate-stabilizer-circuits.ipynb b/docs/guides/simulate-stabilizer-circuits.ipynb index ce3eb377444..9a36f3def21 100644 --- a/docs/guides/simulate-stabilizer-circuits.ipynb +++ b/docs/guides/simulate-stabilizer-circuits.ipynb @@ -254,7 +254,7 @@ "## Next steps\n", "\n", "\n", - " - To simulate circuits with Qiskit Aer, see [Exact and noisy simulation with Qiskit Aer primitives](./simulate-with-qiskit-sdk-primitives).\n", + " - To simulate circuits with Qiskit Aer, see [Exact and noisy simulation with Qiskit Aer primitives](/docs/guides/simulate-with-qiskit-sdk-primitives).\n", " - Review the [Qiskit Aer](https://qiskit.org/ecosystem/aer/) documentation.\n", "" ] diff --git a/docs/guides/simulate-with-qiskit-aer.ipynb b/docs/guides/simulate-with-qiskit-aer.ipynb index 31c35ce03a1..f1f9155e39d 100644 --- a/docs/guides/simulate-with-qiskit-aer.ipynb +++ b/docs/guides/simulate-with-qiskit-aer.ipynb @@ -136,7 +136,7 @@ "id": "134d97a2-8420-4931-85b4-324679655e24", "metadata": {}, "source": [ - "Now, let's initialize a noise model that includes depolarizing error of 2% on every CX gate. In practice, the error arising from the two-qubit gates, which are CX gates here, are the dominant source of error when running a circuit. See [Build noise models](./build-noise-models) for an overview of constructing noise models in Qiskit Aer.\n", + "Now, let's initialize a noise model that includes depolarizing error of 2% on every CX gate. In practice, the error arising from the two-qubit gates, which are CX gates here, are the dominant source of error when running a circuit. See [Build noise models](/docs/guides/build-noise-models) for an overview of constructing noise models in Qiskit Aer.\n", "\n", "In the next cell, we construct an Estimator that incorporates this noise model and use it to compute the expectation value of the observable." ] diff --git a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb index 3afd1f8ed58..37c92f94df6 100644 --- a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb +++ b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb @@ -50,7 +50,7 @@ "source": [ "The reference primitives in the Qiskit SDK perform local statevector simulations. These simulations do not support\n", "modeling device noise, but are useful for quickly prototyping algorithms before looking into more advanced simulation\n", - "techniques ([using Qiskit Aer](./simulate-stabilizer-circuits)) or running on real devices ([Qiskit Runtime primitives](primitives)).\n", + "techniques ([using Qiskit Aer](/docs/guides/simulate-stabilizer-circuits)) or running on real devices ([Qiskit Runtime primitives](primitives)).\n", "\n", "The Estimator primitive can compute expectation values of circuits, and the Sampler primitive can sample\n", "from output distributions of circuits.\n", @@ -64,7 +64,7 @@ "\n", "The following code prepares the inputs that will be used in the examples that follow. The expected input type for the\n", "observables is [`qiskit.quantum_info.SparsePauliOp`](../api/qiskit/qiskit.quantum_info.SparsePauliOp). Note that\n", - "the circuit in the example is parametrized, but you can also run the Estimator on non-parametrized circuits.\n", + "the circuit in the example is parametrized, but you can also run Estimator on non-parametrized circuits.\n", "\n", "\n", " Any circuit passed to an Estimator must **not** include any **measurements**.\n", @@ -252,14 +252,14 @@ "id": "d54f110f-004a-4337-8b4d-7d4287f22be9", "metadata": {}, "source": [ - "For a full example, see the [Primitives examples](primitives-examples#estimator-examples) page.\n", + "For a full example, see the [Estimator examples](/docs/guides/estimator-examples) page.\n", "\n", "## Use the reference Sampler\n", "\n", "The reference implementations of `SamplerV2` in `qiskit.primitives` is the [`StatevectorSampler`](../api/qiskit/qiskit.primitives.StatevectorSampler) class. It takes circuits and parameters as inputs and returns the results from sampling from the output probability distributions as a quasi-probability distribution of output states.\n", "\n", "The following code prepares the inputs used in the examples that follow. Note that\n", - "these examples run a single parametrized circuit, but you can also run the Sampler\n", + "these examples run a single parametrized circuit, but you can also run Sampler\n", "on non-parametrized circuits." ] }, @@ -462,7 +462,7 @@ "# Transpile circuit\n", "pm = generate_preset_pass_manager(optimization_level=1)\n", "isa_circuit = pm.run(circuit)\n", - "# Run using sampler\n", + "# Run using Sampler\n", "result = sampler.run([circuit]).result()\n", "# Access result data for PUB 0\n", "data_pub = result[0].data\n", @@ -519,7 +519,7 @@ "id": "1c0e76fe-4b5d-4fd4-9eec-da5332d76cfb", "metadata": {}, "source": [ - "For a full example, see the [Primitives examples](./primitives-examples#sampler-examples) page.\n", + "For a full example, see the [Sampler examples](/docs/guides/sampler-examples) page.\n", "## Next steps\n", "\n", "\n", diff --git a/docs/guides/specify-runtime-options.ipynb b/docs/guides/specify-runtime-options.ipynb deleted file mode 100644 index 303a870e2a7..00000000000 --- a/docs/guides/specify-runtime-options.ipynb +++ /dev/null @@ -1,497 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "8bbb8d7d-bcd5-4092-9df1-9930c67b17bc", - "metadata": {}, - "source": [ - "---\n", - "title: Specify options\n", - "description: Specify options when building with Qiskit Runtime primitives.\n", - "---\n", - "\n", - "\n", - "# Specify options" - ] - }, - { - "cell_type": "markdown", - "id": "73e3d6f4", - "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", - "\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.1\n", - "qiskit-ibm-runtime~=0.45.1\n", - "```\n", - "\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "8fdcbe4a", - "metadata": {}, - "source": [ - "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`](/docs/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`](/docs/api/qiskit-ibm-runtime/options-estimator-options) and [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options))." - ] - }, - { - "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`](/docs/api/qiskit-ibm-runtime/options-estimator-options) and [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options)) do not need to be instantiated if you are setting options after initializing the primitive." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "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": 4, - "id": "f2c12ead-4785-4d4f-bf4a-f015295d7083", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "" - ] - }, - "execution_count": 4, - "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)\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 relevant setup from `estimator.options.resilience_level = 0`." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "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", - "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, 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`. In addition, 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 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](/docs/api/qiskit-ibm-runtime/options-twirling-options) (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": 6, - "id": "43ed5d23-8d2e-43a7-82a9-b563de861ab1", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "" - ] - }, - "execution_count": 6, - "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": "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": 7, - "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": 8, - "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/estimator-v2).\n", - " - Find more details about the `SamplerV2` methods in the [Sampler API reference](../api/qiskit-ibm-runtime/sampler-v2).\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": { - "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/synthesize-unitary-operators.ipynb b/docs/guides/synthesize-unitary-operators.ipynb index 0440be699e3..4dd89b35ce2 100644 --- a/docs/guides/synthesize-unitary-operators.ipynb +++ b/docs/guides/synthesize-unitary-operators.ipynb @@ -189,7 +189,7 @@ "\n", "\n", " - See an example of circuit decomposition in the [Grover's Algorithm](/docs/tutorials/grovers-algorithm) tutorial.\n", - " - For more information about the Qiskit transpiler, visit the [Transpile section](./transpile).\n", + " - For more information about the Qiskit transpiler, visit the [Transpile section](/docs/guides/transpile).\n", "" ] } diff --git a/docs/guides/tools-intro.mdx b/docs/guides/tools-intro.mdx index cb147966e81..07301088233 100644 --- a/docs/guides/tools-intro.mdx +++ b/docs/guides/tools-intro.mdx @@ -27,11 +27,11 @@ Some of the most useful features of the Qiskit SDK include: - **Transpiler** ([`qiskit.transpiler`](/docs/api/qiskit/transpiler)) - For transforming and adapting quantum circuits to suit specific device topology, and optimizing for execution on real quantum processing units (QPUs). -- **Primitives** ([`qiskit.primitives`](/docs/api/qiskit/primitives)) - The module that contains the base definitions and reference implementations of the Sampler and Estimator primitives, from which different quantum hardware providers can derive their own implementations. See more information about the Qiskit Runtime primitives [in the documentation](./primitives). +- **Primitives** ([`qiskit.primitives`](/docs/api/qiskit/primitives)) - The module that contains the base definitions and reference implementations of the Sampler and Estimator primitives, from which different quantum hardware providers can derive their own implementations. See more information about the Qiskit Runtime primitives [in the documentation](/docs/guides/primitives). ### Installation -For a more detailed introduction to installing the Qiskit SDK, check out the [installation page](./install-qiskit). If you're ready to install it now, simply run: +For a more detailed introduction to installing the Qiskit SDK, check out the [installation page](/docs/guides/install-qiskit). If you're ready to install it now, simply run: ```bash pip install qiskit diff --git a/docs/guides/transpile.mdx b/docs/guides/transpile.mdx index 60f7a335a5b..2da90877b27 100644 --- a/docs/guides/transpile.mdx +++ b/docs/guides/transpile.mdx @@ -9,7 +9,7 @@ description: Introduction to transpiling quantum circuits in the Qiskit SDK. ![An overview of transpilation and the relevant tools to use, either locally or in the cloud.](/docs/images/guides/transpile/transpile-intro.svg) -Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum computers. This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based [Qiskit Transpiler Service](/docs/guides/qiskit-transpiler-service) available to Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure runtime compilation for Qiskit Runtime](/docs/guides/configure-error-suppression) topic. +Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum computers. This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based [Qiskit Transpiler Service](/docs/guides/qiskit-transpiler-service) available to Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the [Configure runtime compilation for Qiskit Runtime](/docs/guides/error-mitigation-and-suppression-techniques) topic. The process of transpilation takes a circuit that contains your instructions: diff --git a/docs/guides/transpiler-plugins.ipynb b/docs/guides/transpiler-plugins.ipynb index 1ecd5ea5c53..504786d4109 100644 --- a/docs/guides/transpiler-plugins.ipynb +++ b/docs/guides/transpiler-plugins.ipynb @@ -426,7 +426,7 @@ "## Next steps\n", "\n", "\n", - " - [Create a transpiler plugin](./create-transpiler-plugin).\n", + " - [Create a transpiler plugin](/docs/guides/create-transpiler-plugin).\n", " - Check out the [tutorials](/docs/tutorials) for examples of transpiling and running quantum circuits.\n", "" ] diff --git a/docs/guides/transpiler-stages.ipynb b/docs/guides/transpiler-stages.ipynb index c0be69deba1..63c766ceb79 100644 --- a/docs/guides/transpiler-stages.ipynb +++ b/docs/guides/transpiler-stages.ipynb @@ -82,7 +82,7 @@ "metadata": {}, "source": [ "## Layout stage\n", - "The next stage involves the layout or connectivity of the backend a circuit will be sent to. In general, quantum circuits are abstract entities whose qubits are \"virtual\" or \"logical\" representations of actual qubits used in computations. To execute a sequence of gates, a one-to-one mapping from the \"virtual\" qubits to the \"physical\" qubits in an actual quantum device is necessary. This mapping is stored as a `Layout` object and is part of the constraints defined within a backend's [instruction set architecture (ISA)](./transpile#instruction-set-architecture).\n", + "The next stage involves the layout or connectivity of the backend a circuit will be sent to. In general, quantum circuits are abstract entities whose qubits are \"virtual\" or \"logical\" representations of actual qubits used in computations. To execute a sequence of gates, a one-to-one mapping from the \"virtual\" qubits to the \"physical\" qubits in an actual quantum device is necessary. This mapping is stored as a `Layout` object and is part of the constraints defined within a backend's [instruction set architecture (ISA)](/docs/guides/transpile#instruction-set-architecture).\n", "\n", "\n", "![This image illustrates qubits being mapped from the wire representation to a diagram that represents how the qubits are connected on the QPU.](/docs/images/guides/transpiler-stages/layout-mapping.svg \"Qubit mapping\")\n", @@ -240,7 +240,7 @@ "source": [ "## Translation stage\n", "\n", - "When writing a quantum circuit, you are free to use any quantum gate (unitary operation) that you like, along with a collection of non-gate operations such as qubit measurement or reset instructions. However, most quantum devices only natively support a handful of quantum gate and non-gate operations. These native gates are part of the definition of a target's [ISA](./transpile#instruction-set-architecture) and this stage of the preset `PassManagers` translates (or *unrolls*) the gates specified in a circuit to the native basis gates of a specified backend. This is an important step, as it allows the circuit to be executed by the backend, but typically leads to an increase in the depth and number of gates.\n", + "When writing a quantum circuit, you are free to use any quantum gate (unitary operation) that you like, along with a collection of non-gate operations such as qubit measurement or reset instructions. However, most quantum devices only natively support a handful of quantum gate and non-gate operations. These native gates are part of the definition of a target's [ISA](/docs/guides/transpile#instruction-set-architecture) and this stage of the preset `PassManagers` translates (or *unrolls*) the gates specified in a circuit to the native basis gates of a specified backend. This is an important step, as it allows the circuit to be executed by the backend, but typically leads to an increase in the depth and number of gates.\n", "\n", "Two special cases are especially important to highlight, and help illustrate what this stage does.\n", "\n", diff --git a/docs/guides/upgrade-from-open.mdx b/docs/guides/upgrade-from-open.mdx index 35c5f9e5bb5..03c44e0e53a 100644 --- a/docs/guides/upgrade-from-open.mdx +++ b/docs/guides/upgrade-from-open.mdx @@ -8,11 +8,11 @@ description: upgrade from the IBM Quantum Open Plan to an IBM Cloud Pay-As-You-G This guide is for entities who want to upgrade from the IBM Quantum® Open Plan to an IBM Cloud® Pay-As-You-Go Plan. For instructions to set up a cloud account, set up a service instance, and work with users, follow these steps. -If you are an individual setting up the service for the first time or if you have been invited to an instance by an administrator, follow the steps in [Install Qiskit](./install-qiskit) instead. +If you are an individual setting up the service for the first time or if you have been invited to an instance by an administrator, follow the steps in [Install Qiskit](/docs/guides/install-qiskit) instead. ## Before you begin -If necessary, follow the steps in the [Set up to use IBM Cloud](./cloud-setup#cloud) section to complete the following: +If necessary, follow the steps in the [Set up to use IBM Cloud](/docs/guides/cloud-setup#cloud) section to complete the following: - Sign up for an IBM Cloud account. - Create an IBM Quantum instance. diff --git a/docs/guides/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index dea326dddd0..61572292a82 100644 --- a/docs/guides/v2-primitives.mdx +++ b/docs/guides/v2-primitives.mdx @@ -215,7 +215,7 @@ The output is now in the [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubRes - The V1 output format was a dictionary of bitstrings (as an int) as the key and quasi-probabilities as the value for each circuit. The V2 format has the same key (but as a string) and counts as the value. To convert the V2 format to V1, divide the counts by the number of shots, where the number of shots selected is described in the [Specify options](/docs/guides/specify-runtime-options#shots) guide. + The V1 output format was a dictionary of bitstrings (as an int) as the key and quasi-probabilities as the value for each circuit. The V2 format has the same key (but as a string) and counts as the value. To convert the V2 format to V1, divide the counts by the number of shots, where the number of shots selected is described in the [Sampler options](/docs/guides/sampler-options#shots) guide. ```python v2_result = sampler_v2_job.result() @@ -491,7 +491,7 @@ print(f"Job {job.job_id()} is still running: {job.status() is JobStatus.RUNNING} 1. You might need to reshape your arrays of observables or parameter sets if you want to apply their outer product. For example, an array of observables of shape (4, 1) and an array of parameter sets of shape (1, 6) will give you a result of (4, 6) expectation values. See the [Numpy broadcasting rules](https://numpy.org/doc/stable/user/basics.broadcasting.html) for more details. 2. You can optionally specify the precision you want for that specific PUB. -5. Update the estimator `run()` method to pass in the list of PUBs. For example, `run([(circuit1, observable1, parameter_set1)])`. +5. Update Estimator's `run()` method to pass in the list of PUBs. For example, `run([(circuit1, observable1, parameter_set1)])`. You can optionally specify a `precision` here, which would apply to all PUBs. 6. Estimator V2 job results are grouped by PUBs. You can see the expectation value and standard error for each PUB by indexing to it. For example: ```python @@ -878,7 +878,7 @@ print(f" > Expectation values job 2: {another_result.values}") 3. Review all the [supported options](/docs/api/qiskit-ibm-runtime/options) and make updates accordingly. 4. Group each circuit you want to run with the observables and parameter values you want to apply to the circuit in a tuple (a PUB). For example, use `(circuit1, parameter_set1)` if you want to run `circuit1` with `parameter_set1`. You can optionally specify the shots you want for that specific PUB. -5. Update the sampler `run()` method to pass in the list of PUBs. For example, `run([(circuit1, parameter_set1)])`. +5. Update Sampler's `run()` method to pass in the list of PUBs. For example, `run([(circuit1, parameter_set1)])`. You can optionally specify `shots` here, which would apply to all PUBs. 6. Sampler V2 job results are grouped by PUBs. You can see the output data for each PUB by indexing to it. While Sampler V2 returns unweighted samples, the result class has a convenience method to get counts instead. For example: ```python @@ -1206,7 +1206,7 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}") ## Next steps - - Learn more about setting options in the [Specify options](/docs/guides/specify-runtime-options) guide. - - Learn more details about [Primitive inputs and outputs](/docs/guides/primitive-input-output). + - Learn more about setting options in the [Sampler options](/docs/guides/sampler-options) and [Estimator options](/docs/guides/estimator-options) guides. + - Learn more details about [Primitive inputs and outputs](/docs/guides/primitive-input-output#pubs). - Experiment with the [CHSH Inequality](/docs/tutorials/chsh-inequality) tutorial. diff --git a/docs/tutorials/advanced-techniques-for-qaoa.ipynb b/docs/tutorials/advanced-techniques-for-qaoa.ipynb index 3c62a7d241c..2931606059c 100644 --- a/docs/tutorials/advanced-techniques-for-qaoa.ipynb +++ b/docs/tutorials/advanced-techniques-for-qaoa.ipynb @@ -114,7 +114,7 @@ "\n", "### Graph → Hamiltonian\n", "\n", - "First, map the problem onto a quantum circuit that is suited for the QAOA. Details on this process can be found in the [introductory QAOA tutorial.](/docs/tutorials/quantum-approximate-optimization-algorithm)" + "First, map the problem onto a quantum circuit that is suited for the QAOA. Details on this process can be found in the [introductory QAOA tutorial](/docs/tutorials/quantum-approximate-optimization-algorithm)." ] }, { diff --git a/docs/tutorials/ai-transpiler-introduction.ipynb b/docs/tutorials/ai-transpiler-introduction.ipynb index 146e9c769c0..738b6c4fcf4 100644 --- a/docs/tutorials/ai-transpiler-introduction.ipynb +++ b/docs/tutorials/ai-transpiler-introduction.ipynb @@ -52,7 +52,7 @@ "![Graph showing AI transpiler performance against Qiskit](/docs/images/tutorials/ai-transpiler-introduction/ai-transpiler-benchmarks.avif)\n", "\n", "\n", - "In benchmarking tests, the AI transpiler consistently produced shallower, higher-quality circuits compared to the standard Qiskit transpiler. For these tests, we used Qiskit’s default pass manager strategy, configured with [`generate_preset_passmanager`]. While this default strategy is often effective, it can struggle with larger or more complex circuits. By contrast, AI-powered passes achieved an average 24% reduction in two-qubit gate counts and a 36% reduction in circuit depth for large circuits (100+ qubits) when transpiling to the heavy-hex topology of IBM Quantum hardware. For more information on these benchmarks, refer to this [blog.](https://www.ibm.com/quantum/blog/qiskit-performance)\n", + "In benchmarking tests, the AI transpiler consistently produced shallower, higher-quality circuits compared to the standard Qiskit transpiler. For these tests, we used Qiskit’s default pass manager strategy, configured with [`generate_preset_passmanager`]. While this default strategy is often effective, it can struggle with larger or more complex circuits. By contrast, AI-powered passes achieved an average 24% reduction in two-qubit gate counts and a 36% reduction in circuit depth for large circuits (100+ qubits) when transpiling to the heavy-hex topology of IBM Quantum hardware. For more information on these benchmarks, refer to this [blog](https://www.ibm.com/quantum/blog/qiskit-performance).\n", "\n", "This tutorial explores the key benefits of AI passes and how it compares to traditional methods." ] diff --git a/docs/tutorials/colibritd-pde.ipynb b/docs/tutorials/colibritd-pde.ipynb index eed20587690..c04bb1be725 100644 --- a/docs/tutorials/colibritd-pde.ipynb +++ b/docs/tutorials/colibritd-pde.ipynb @@ -46,7 +46,7 @@ "This tutorial seeks to teach on an introductory level how to use the QUICK-PDE\n", "function to solve complex multi-physics problems on 156Q Heron R2 QPUs by using\n", "ColibriTD's H-DES (Hybrid Differential Equation Solver).\n", - "The underlying algorithm is described in [the H-DES paper.](https://arxiv.org/abs/2410.01130)\n", + "The underlying algorithm is described in [the H-DES paper](https://arxiv.org/abs/2410.01130).\n", "Note that this solver can also solve non-linear equations.\n", "\n", "Multi-physics problems - including fluids dynamics, heat diffusion, and material\n", @@ -83,7 +83,7 @@ "* Qiskit SDK v2.0 or later (`pip install qiskit`)\n", "* Qiskit Functions Catalog (`pip install qiskit-ibm-catalog`)\n", "* Matplotlib (`pip install matplotlib`)\n", - "* Access to the QUICK-PDE function. Fill out the [form to request access.](https://forms.cloud.microsoft/e/3Wi9cbjQPK)" + "* Access to the QUICK-PDE function. Fill out the [form to request access](https://forms.cloud.microsoft/e/3Wi9cbjQPK)." ] }, { diff --git a/docs/tutorials/combine-error-mitigation-techniques.ipynb b/docs/tutorials/combine-error-mitigation-techniques.ipynb index 4b7cf3e60fe..1ff6193f938 100644 --- a/docs/tutorials/combine-error-mitigation-techniques.ipynb +++ b/docs/tutorials/combine-error-mitigation-techniques.ipynb @@ -53,7 +53,7 @@ "- Gate twirling\n", "- Zero-noise extrapolation (ZNE)\n", "\n", - "Note that an alternative to implementing these techniques individually is to implement them using a [resilience level](/docs/guides/configure-error-mitigation#example), whereby `resilience_level` takes values 0, 1, 2:\n", + "Note that an alternative to implementing these techniques individually is to implement them using a [resilience level](/docs/guides/estimator-noise-management), whereby `resilience_level` takes values 0, 1, 2:\n", "\n", "- 0 : No mitigation is implemented.\n", "- 1 : Measurement error mitigation is implemented.\n", diff --git a/docs/tutorials/depth-reduction-with-circuit-cutting.ipynb b/docs/tutorials/depth-reduction-with-circuit-cutting.ipynb index 0403b82f367..d67caa5c64b 100644 --- a/docs/tutorials/depth-reduction-with-circuit-cutting.ipynb +++ b/docs/tutorials/depth-reduction-with-circuit-cutting.ipynb @@ -315,7 +315,7 @@ "source": [ "## Step 3: Execute using Qiskit primitives\n", "\n", - "Execute the target circuits (\"subexperiments\") with the Sampler Primitive.\n", + "Execute the target circuits (\"subexperiments\") with the Sampler primitive.\n", "\n", "* Input: Target circuits\n", "* Output: Quasi-probability distributions" diff --git a/docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb b/docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb index 27eeb3acd31..4158da42c59 100644 --- a/docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb +++ b/docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb @@ -673,7 +673,7 @@ "source": [ "## References\n", "\n", - "[\\[1\\] Carrera Vazquez, A., Tornow, C., Ristè, D. et al. Combining quantum processors with real-time classical communication. Nature 636, 75-79 (2024).](https://www.nature.com/articles/s41586-024-08178-2)" + "[\\[1\\] Carrera Vazquez, A., Tornow, C., Ristè, D. et al. Combining quantum processors with real-time classical communication. Nature 636, 75-79 (2024)](https://www.nature.com/articles/s41586-024-08178-2)." ] } ], diff --git a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb index 238761a1c3d..c5a7dc92fe3 100644 --- a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb +++ b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb @@ -357,7 +357,7 @@ "id": "082883fc-22fa-4539-a4e2-9f3ef97d7334", "metadata": {}, "source": [ - "We can also configure the `options` for transpilation, error suppression, and error mitigation. Default settings will be used if we don't wish to specify these. The IBM Circuit function comes with commonly used options for `optimization_level`, which controls how much circuit optimization to perform, and `mitigation_level`, which specifies how much error suppression and mitigation to apply. Note that the `mitigation_level` of the IBM Circuit function is distinct from the `resilience_level` used in the [Qiskit Runtime Estimator](/docs/guides/configure-error-mitigation). For a detailed description of these commonly used options as well as other advanced options, visit the [documentation for the IBM Circuit function](/docs/guides/ibm-circuit-function).\n", + "We can also configure the `options` for transpilation, error suppression, and error mitigation. Default settings will be used if we don't wish to specify these. The IBM Circuit function comes with commonly used options for `optimization_level`, which controls how much circuit optimization to perform, and `mitigation_level`, which specifies how much error suppression and mitigation to apply. Note that the `mitigation_level` of the IBM Circuit function is distinct from the `resilience_level` used in the [Qiskit Runtime Estimator](/docs/guides/error-mitigation-and-suppression-techniques). For a detailed description of these commonly used options as well as other advanced options, visit the [documentation for the IBM Circuit function](/docs/guides/ibm-circuit-function).\n", "\n", "In this tutorial, we will set the `default_precision`, `optimization_level: 3` and `mitigation_level: 3`, which will turn on gate twirling and Zero Noise Extrapolation (ZNE) via Probabilistic Error Amplification (PEA) on top of the default level 1 settings." ] @@ -420,7 +420,7 @@ "id": "e510ff6e-7022-48c6-b146-6e48611d7d12", "metadata": {}, "source": [ - "The result from running the function has the same format as the [Estimator](/docs/guides/primitive-input-output#estimator-output)." + "The result from running the function has the same format as the [Estimator](/docs/guides/estimator-input-output)." ] }, { diff --git a/docs/tutorials/fractional-gates.ipynb b/docs/tutorials/fractional-gates.ipynb index 384e5e7ff55..179a361c42b 100644 --- a/docs/tutorials/fractional-gates.ipynb +++ b/docs/tutorials/fractional-gates.ipynb @@ -134,7 +134,7 @@ "metadata": {}, "source": [ "This tutorial demonstrates how to use fractional gates via the second approach through an example inspired by the quantum kernel method.\n", - "To better understand where quantum kernels are likely to be useful, we recommend reading [Liu, Arunachalam & Temme (2021).](https://www.nature.com/articles/s41567-021-01287-z)\n", + "To better understand where quantum kernels are likely to be useful, we recommend reading [Liu, Arunachalam & Temme (2021)](https://www.nature.com/articles/s41567-021-01287-z).\n", "\n", "You can also work through the [Quantum kernel training](/docs/tutorials/quantum-kernel-training) tutorial and the [Quantum kernels](/learning/courses/quantum-machine-learning/quantum-kernel-methods) lesson in the Quantum machine learning course on IBM Quantum Learning." ] @@ -1084,7 +1084,7 @@ "By introducing a custom decomposition rule, as shown in the following,\n", "we can reduce the number of single-qubit gates required to implement a U gate.\n", "\n", - "This feature is currently under discussion in this [GitHub issue.](https://github.com/Qiskit/qiskit/issues/13455)" + "This feature is currently under discussion in this [GitHub issue](https://github.com/Qiskit/qiskit/issues/13455)." ] }, { diff --git a/docs/tutorials/ghz-spacetime-codes.ipynb b/docs/tutorials/ghz-spacetime-codes.ipynb index ce79d3bfac5..35323676e76 100644 --- a/docs/tutorials/ghz-spacetime-codes.ipynb +++ b/docs/tutorials/ghz-spacetime-codes.ipynb @@ -1673,14 +1673,14 @@ } ], "source": [ - "# Select the sampler options\n", + "# Select the Sampler options\n", "sampler = Sampler(mode=backend)\n", "sampler.options.default_shots = SHOTS\n", "sampler.options.dynamical_decoupling.enable = False\n", "sampler.options.execution.rep_delay = 0.00025\n", "\n", "# Submit the job\n", - "print(\"Submitting sampler job\")\n", + "print(\"Submitting Sampler job\")\n", "ghz_job = sampler.run([isa_circuit])\n", "\n", "print(ghz_job.job_id())" diff --git a/docs/tutorials/global-data-quantum-optimizer.ipynb b/docs/tutorials/global-data-quantum-optimizer.ipynb index b62267823a8..39a554eb9de 100644 --- a/docs/tutorials/global-data-quantum-optimizer.ipynb +++ b/docs/tutorials/global-data-quantum-optimizer.ipynb @@ -106,7 +106,7 @@ "source": [ "To use the Quantum Portfolio Optimizer, select the function via the Qiskit Functions Catalog. You need an IBM Quantum Premium Plan or Flex Plan account with a license from Global Data Quantum to run this function.\n", "\n", - "First, authenticate with your [API key.](https://quantum.cloud.ibm.com) Then, load the desired function from the Qiskit Functions Catalog. Here, you are accessing the `quantum_portfolio_optimizer` function from the catalog by using the `QiskitFunctionsCatalog` class. This function allows us to use the predefined Quantum Portfolio Optimization solver." + "First, authenticate with your [API key](https://quantum.cloud.ibm.com). Then, load the desired function from the Qiskit Functions Catalog. Here, you are accessing the `quantum_portfolio_optimizer` function from the catalog by using the `QiskitFunctionsCatalog` class. This function allows us to use the predefined Quantum Portfolio Optimization solver." ] }, { @@ -301,7 +301,7 @@ "id": "06608c0a-34ac-47b4-84c5-da98458e6dab", "metadata": {}, "source": [ - "The `optimizer_settings` dictionary configures the optimization process, including parameters such as `num_generations` for the number of iterations and `population_size` for the number of candidate solutions per generation. Other settings control aspects like the recombination rate, parallel jobs, batch size, and mutation range. Additionally, the primitive settings, such as `estimator_shots`, `estimator_precision`, and `sampler_shots`, define the quantum estimator and sampler configurations for the optimization process." + "The `optimizer_settings` dictionary configures the optimization process, including parameters such as `num_generations` for the number of iterations and `population_size` for the number of candidate solutions per generation. Other settings control aspects like the recombination rate, parallel jobs, batch size, and mutation range. Additionally, the primitive settings, such as `estimator_shots`, `estimator_precision`, and `sampler_shots`, define the quantum Estimator and Sampler configurations for the optimization process." ] }, { @@ -667,7 +667,7 @@ "source": [ "## References\n", "\n", - "[1] [Nodar, Álvaro, Irene De León, Danel Arias, Ernesto Mamedaliev, María Esperanza Molina, Manuel Martín-Cordero, Senaida Hernández-Santana et al. \"Scaling the Variational Quantum Eigensolver for Dynamic Portfolio Optimization.\" arXiv preprint arXiv:2412.19150 (2024).](https://arxiv.org/pdf/2412.19150)" + "[1] [Nodar, Álvaro, Irene De León, Danel Arias, Ernesto Mamedaliev, María Esperanza Molina, Manuel Martín-Cordero, Senaida Hernández-Santana et al. \"Scaling the Variational Quantum Eigensolver for Dynamic Portfolio Optimization.\" arXiv preprint arXiv:2412.19150 (2024)](https://arxiv.org/pdf/2412.19150)." ] }, { diff --git a/docs/tutorials/grovers-algorithm.ipynb b/docs/tutorials/grovers-algorithm.ipynb index d8cd56c06a3..b942ad84cdb 100644 --- a/docs/tutorials/grovers-algorithm.ipynb +++ b/docs/tutorials/grovers-algorithm.ipynb @@ -364,7 +364,7 @@ "\n", "Amplitude amplification is a sampling problem that is suitable for execution with the [`Sampler`](/docs/api/qiskit-ibm-runtime/sampler-v2) runtime primitive.\n", "\n", - "Note that the `run()` method of [Qiskit Runtime `SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) takes an iterable of `primitive unified blocks (PUBs)`. For sampler, each PUB is an iterable in the format `(circuit, parameter_values)`. However, at a minimum, it takes a list of quantum circuit(s)." + "Note that the `run()` method of [Qiskit Runtime `SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) takes an iterable of `primitive unified blocks (PUBs)`. For Sampler, each PUB is an iterable in the format `(circuit, parameter_values)`. However, at a minimum, it takes a list of quantum circuit(s)." ] }, { diff --git a/docs/tutorials/krylov-quantum-diagonalization.ipynb b/docs/tutorials/krylov-quantum-diagonalization.ipynb index 91751cad92a..d6b7f364347 100644 --- a/docs/tutorials/krylov-quantum-diagonalization.ipynb +++ b/docs/tutorials/krylov-quantum-diagonalization.ipynb @@ -1112,7 +1112,7 @@ "id": "794edf4c-d539-4864-865d-52a88a450b5c", "metadata": {}, "source": [ - "Execute circuits for $S$ and $\\tilde{H}$ with the Estimator" + "Execute circuits for $S$ and $\\tilde{H}$ with Estimator" ] }, { diff --git a/docs/tutorials/multi-product-formula.ipynb b/docs/tutorials/multi-product-formula.ipynb index 1041d1b0f24..d2628acee87 100644 --- a/docs/tutorials/multi-product-formula.ipynb +++ b/docs/tutorials/multi-product-formula.ipynb @@ -746,7 +746,7 @@ "metadata": {}, "source": [ "Note that you have complete freedom over how to solve this optimization problem, which means that you can change the optimization solver, its convergence thresholds, and so on.\n", - "Check out the respective guide on [How to use the approximate model.](https://qiskit.github.io/qiskit-addon-mpf/how_tos/using_approximate_model.html)" + "Check out the respective guide on [How to use the approximate model](https://qiskit.github.io/qiskit-addon-mpf/how_tos/using_approximate_model.html)." ] }, { @@ -2523,7 +2523,7 @@ "\n", "Overall, the approximate static coefficients still give a more accurate solution than the product formula with higher number of Trotter steps with the same amount of Trotter error in the noiseless setting.\n", "\n", - "It is also important to note that in the example that reproduces the experiment in Ref. [\\[3\\]](#references), the time point $t=3$ is beyond the limit at which it is expected that the PF with $k=2$ behaves well, which is $t/k>1$ as discussed in this [guide.](https://qiskit.github.io/qiskit-addon-mpf/how_tos/choose_trotter_steps.html)" + "It is also important to note that in the example that reproduces the experiment in Ref. [\\[3\\]](#references), the time point $t=3$ is beyond the limit at which it is expected that the PF with $k=2$ behaves well, which is $t/k>1$ as discussed in this [guide](https://qiskit.github.io/qiskit-addon-mpf/how_tos/choose_trotter_steps.html)." ] }, { @@ -2533,11 +2533,11 @@ "source": [ "## References\n", "\n", - "[1] [Vazquez, A. C., Egger, D. J., Ochsner, D., & Woerner, S. (2023). Well-conditioned multi-product formulas for hardware-friendly Hamiltonian simulation. Quantum, 7, 1067.](https://quantum-journal.org/papers/q-2023-07-25-1067/)\n", + "[1] [Vazquez, A. C., Egger, D. J., Ochsner, D., & Woerner, S. (2023). Well-conditioned multi-product formulas for hardware-friendly Hamiltonian simulation. Quantum, 7, 1067](https://quantum-journal.org/papers/q-2023-07-25-1067/).\n", "\n", - "[2] [Zhuk, S., Robertson, N. F., & Bravyi, S. (2024). Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation. Physical Review Research, 6(3), 033309.](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309)\n", + "[2] [Zhuk, S., Robertson, N. F., & Bravyi, S. (2024). Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation. Physical Review Research, 6(3), 033309](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309).\n", "\n", - "[3] [Robertson, N. F., et al. (2024). Tensor network enhanced dynamic multiproduct formulas. arXiv preprint arXiv:2407.17405.](https://arxiv.org/abs/2407.17405)" + "[3] [Robertson, N. F., et al. (2024). Tensor network enhanced dynamic multiproduct formulas. arXiv preprint arXiv:2407.17405](https://arxiv.org/abs/2407.17405)." ] } ], diff --git a/docs/tutorials/operator-back-propagation.ipynb b/docs/tutorials/operator-back-propagation.ipynb index a6bb9039c99..69964d7de6b 100644 --- a/docs/tutorials/operator-back-propagation.ipynb +++ b/docs/tutorials/operator-back-propagation.ipynb @@ -601,7 +601,7 @@ "id": "2c95ead4-3a9f-423b-b3ad-a9109a8420b2", "metadata": {}, "source": [ - "We shall use resilience_level = 2 for this example." + "We shall use resilience_level = 2 for this example." ] }, { diff --git a/docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb b/docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb index 70b02102501..fdbf80ec5d5 100644 --- a/docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb +++ b/docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb @@ -132,8 +132,8 @@ "\n", "### Max-Cut Problem\n", "The Max-Cut problem is a combinatorial optimization problem that is defined on a graph $G = (V, E)$, where $V$ is the set of vertices and $E$ is the set of edges. The goal is to partition the vertices into two sets, $S$ and $V \\setminus S$, such that the number of edges between the two sets is maximized.\n", - "For the detailed description of the Max-Cut problem, please refer to the [\"Quantum approximate optimization algorithm\"](./quantum-approximate-optimization-algorithm) tutorial.\n", - "Also, the Max-Cut problem is used as an example in the tutorial [\"Advanced Techniques for QAOA\"](./advanced-techniques-for-qaoa).\n", + "For the detailed description of the Max-Cut problem, please refer to the [\"Quantum approximate optimization algorithm\"](/docs/tutorials/quantum-approximate-optimization-algorithm) tutorial.\n", + "Also, the Max-Cut problem is used as an example in the tutorial [\"Advanced Techniques for QAOA\"](/docs/tutorials/advanced-techniques-for-qaoa).\n", "In those tutorials, the QAOA algorithm is used to solve the Max-Cut problem.\n", "\n", "\n", diff --git a/docs/tutorials/qedma-2d-ising-with-qesem.ipynb b/docs/tutorials/qedma-2d-ising-with-qesem.ipynb index 9adb0b831fb..64ce8eeb265 100644 --- a/docs/tutorials/qedma-2d-ising-with-qesem.ipynb +++ b/docs/tutorials/qedma-2d-ising-with-qesem.ipynb @@ -75,7 +75,7 @@ "4. Circuit characterization - builds a tailored local error model and fits it to QPU measurements to quantify residual noise.\n", "5. Error mitigation - constructs multi-type quasi-probabilistic decompositions, and samples from them in an adaptive process that minimizes mitigation QPU time and sensitivity to hardware fluctuations, achieving high accuracies at large circuit volumes.\n", "\n", - "For more information on QESEM and a utility-scale experiment of this model on a 103-qubit, high-connectivity subgraph of the native heavy-hex geometry of `ibm_marrakesh`, refer to [Reliable high-accuracy error mitigation for utility-scale quantum circuits.](https://arxiv.org/abs/2508.10997)" + "For more information on QESEM and a utility-scale experiment of this model on a 103-qubit, high-connectivity subgraph of the native heavy-hex geometry of `ibm_marrakesh`, refer to [Reliable high-accuracy error mitigation for utility-scale quantum circuits](https://arxiv.org/abs/2508.10997)." ] }, { @@ -247,7 +247,7 @@ "source": [ "Next we create a function to calculate ideal expectation values using `AerSimulator`.\n", "\n", - "Note that for large circuits (30 or more qubits) we recommend using precalculated values from belief-propagation (BP) PEPS simulations. This code includes precalculated values for 35 qubits as an example, based on the BP approach for evolving a PEPS tensor network introduced [in this paper](https://www.science.org/doi/10.1126/sciadv.adk4321) (which we refer to as PEPS-BP), using the tensor-network Python package [quimb.](https://joss.theoj.org/papers/10.21105/joss.00819)" + "Note that for large circuits (30 or more qubits) we recommend using precalculated values from belief-propagation (BP) PEPS simulations. This code includes precalculated values for 35 qubits as an example, based on the BP approach for evolving a PEPS tensor network introduced [in this paper](https://www.science.org/doi/10.1126/sciadv.adk4321) (which we refer to as PEPS-BP), using the tensor-network Python package [quimb](https://joss.theoj.org/papers/10.21105/joss.00819)." ] }, { diff --git a/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb b/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb index 86a7338199b..12364164513 100644 --- a/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb +++ b/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb @@ -499,7 +499,7 @@ "metadata": {}, "source": [ "#### Define backend and execution primitive\n", - "Use the **Qiskit Runtime primitives** to interact with IBM® backends. The two primitives are Sampler and Estimator, and the choice of primitive depends on what type of measurement you want to run on the quantum computer. For the minimization of $H_C$, use the Estimator since the measurement of the cost function is simply the expectation value of $\\langle H_C \\rangle$." + "Use the **Qiskit Runtime primitives** to interact with IBM® backends. The two primitives are Sampler and Estimator, and the choice of primitive depends on what type of measurement you want to run on the quantum computer. For the minimization of $H_C$, use Estimator since the measurement of the cost function is simply the expectation value of $\\langle H_C \\rangle$." ] }, { @@ -513,7 +513,7 @@ "\n", "![Illustration showing the behavior of Single job, Batch, and Session runtime modes.](/docs/images/tutorials/quantum-approximate-optimization-algorithm/runtime-modes.avif)\n", "\n", - "You can plug the sampler-based cost function into the SciPy minimizing routine to find the optimal parameters." + "You can plug the Sampler-based cost function into the SciPy minimizing routine to find the optimal parameters." ] }, { diff --git a/docs/tutorials/quantum-phase-estimation-qctrl.ipynb b/docs/tutorials/quantum-phase-estimation-qctrl.ipynb index feb77aaf891..8f58209727f 100644 --- a/docs/tutorials/quantum-phase-estimation-qctrl.ipynb +++ b/docs/tutorials/quantum-phase-estimation-qctrl.ipynb @@ -375,7 +375,7 @@ "metadata": {}, "outputs": [], "source": [ - "# Run the circuit using the sampler\n", + "# Run the circuit using Sampler\n", "fire_opal_job = perf_mgmt.run(\n", " primitive=\"sampler\",\n", " pubs=[qasm2.dumps(circuits_quantum_phase_estimation)],\n", diff --git a/docs/tutorials/repetition-codes.ipynb b/docs/tutorials/repetition-codes.ipynb index 87808026bb4..0213808d271 100644 --- a/docs/tutorials/repetition-codes.ipynb +++ b/docs/tutorials/repetition-codes.ipynb @@ -25,7 +25,7 @@ "\n", "You can exploit additional ancilla qubits and entanglement to measure *stabilizers* that do not transform encoded quantum information, while still informing you of some classes of errors that might have occurred. A quantum stabilizer code encodes $k$ logical qubits into $n$ physical qubits. Stabilizer codes critically focus on correcting a discrete error set with support from the Pauli group $\\Pi^n$.\n", "\n", - "For more information about QEC, refer to [Quantum Error Correction for Beginners.](https://arxiv.org/abs/0905.2794)" + "For more information about QEC, refer to [Quantum Error Correction for Beginners](https://arxiv.org/abs/0905.2794)." ] }, { @@ -243,7 +243,7 @@ "source": [ "## Step 2. Optimize the problem for quantum execution\n", "\n", - "To reduce the total job execution time, Qiskit primitives only accept circuits and observables that conforms to the instructions and connectivity supported by the target system (referred to as instruction set architecture (ISA) circuits and observables). [Learn more about transpilation.](/docs/guides/transpile)" + "To reduce the total job execution time, Qiskit primitives only accept circuits and observables that conforms to the instructions and connectivity supported by the target system (referred to as instruction set architecture (ISA) circuits and observables). [Learn more about transpilation](/docs/guides/transpile)." ] }, { diff --git a/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb b/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb index 5eb19dc81a1..909b729155c 100644 --- a/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb +++ b/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb @@ -33,7 +33,7 @@ "We suggest that users are familiar with the following topics before going through this tutorial:\n", "- [Sample-based quantum diagonalization of a chemistry Hamiltonian](/docs/tutorials/sample-based-quantum-diagonalization)\n", "- [Krylov quantum diagonalization of lattice Hamiltonians](/docs/tutorials/krylov-quantum-diagonalization)\n", - "- [Qiskit primitives](/docs/guides/get-started-with-primitives)" + "- [Qiskit primitives](/docs/guides/primitives)" ] }, { diff --git a/docs/tutorials/sml-classification.ipynb b/docs/tutorials/sml-classification.ipynb index b9dec783737..b834280fcec 100644 --- a/docs/tutorials/sml-classification.ipynb +++ b/docs/tutorials/sml-classification.ipynb @@ -43,7 +43,7 @@ "What you will do here: prepare and balance the grid-stability dataset; establish a classical AdaBoost baseline; run several quantum configurations that vary ensemble width and regularization; execute on IBM® simulators or QPUs via Qiskit Serverless; and compare accuracy, precision, recall, and F1 across all runs. Along the way, you will use the function’s action pattern (`create`, `fit`, `predict`, `fit_predict`, `create_fit_predict`) and key controls:\n", "- Regularization types: `onsite` (λ) for direct sparsity and `alpha` for a ratio-based trade-off between interaction and onsite terms\n", "- Auto-regularization: set `regularization=\"auto\"` with a target selection ratio to adapt sparsity automatically\n", - "- Optimizer options: simulator versus QPU, repetitions, classical optimizer and its options, transpilation depth, and runtime sampler/estimator settings\n", + "- Optimizer options: simulator versus QPU, repetitions, classical optimizer and its options, transpilation depth, and Qiskit Runtime Sampler or Estimator settings\n", "\n", "Benchmarks in the documentation show that accuracy improves as the number of learners (qubits) increases on challenging problems, with the quantum classifier matching or exceeding a comparable classical ensemble. In this tutorial, you will reproduce the workflow end-to-end and examine when increasing ensemble width or switching to adaptive regularization yields better F1 at reasonable resource usage. The result is a grounded view of how a quantum optimization step can complement, rather than replace, classical ensemble learning in real applications." ] diff --git a/learning/courses/quantum-chem-with-vqe/geometry.ipynb b/learning/courses/quantum-chem-with-vqe/geometry.ipynb index f2f5ea0d0ad..0fdf43e9651 100644 --- a/learning/courses/quantum-chem-with-vqe/geometry.ipynb +++ b/learning/courses/quantum-chem-with-vqe/geometry.ipynb @@ -349,7 +349,7 @@ "source": [ "## Step 3: Execute using Qiskit primitives.\n", "\n", - "In the code block below, we set up an array to store our outputs from each step in our interatomic distance $x$. We have chosen the range of $x$ based on our knowledge of the experimental value for the equilibrium bond length: 0.74 Angstrom. We will run this first on a simulator, and will thus be importing our estimator (BackendEstimator) from `qiskit.primitives`. For each geometry step, we build the Hamiltonian and allow a certain number of optimization steps (here 500) using the optimizer \"cobyla\". At each geometry step, we store both the total energy and the electronic energy. Because of the high number of optimizer steps, this may take an hour or more. You may wish to modify the inputs below to reduce the required time." + "In the code block below, we set up an array to store our outputs from each step in our interatomic distance $x$. We have chosen the range of $x$ based on our knowledge of the experimental value for the equilibrium bond length: 0.74 Angstrom. We will run this first on a simulator, and will thus be importing our Estimator (BackendEstimator) from `qiskit.primitives`. For each geometry step, we build the Hamiltonian and allow a certain number of optimization steps (here 500) using the optimizer \"cobyla\". At each geometry step, we store both the total energy and the electronic energy. Because of the high number of optimizer steps, this may take an hour or more. You may wish to modify the inputs below to reduce the required time." ] }, { diff --git a/learning/courses/quantum-chem-with-vqe/ground-state.ipynb b/learning/courses/quantum-chem-with-vqe/ground-state.ipynb index 670b76f3d93..56237aebc6d 100644 --- a/learning/courses/quantum-chem-with-vqe/ground-state.ipynb +++ b/learning/courses/quantum-chem-with-vqe/ground-state.ipynb @@ -313,7 +313,7 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": null, "id": "dd54bb0e-c94b-4168-b1e7-2ca036d2c231", "metadata": {}, "outputs": [], @@ -321,7 +321,7 @@ "# We will start by using a local simulator\n", "from qiskit_aer import AerSimulator\n", "\n", - "# Import an estimator, this time from qiskit (we will import from Runtime for real hardware)\n", + "# Import Estimator, this time from Qiskit (we will import from Qiskit Runtime for real QPUs)\n", "from qiskit.primitives import BackendEstimatorV2\n", "\n", "# generate a simulator that mimics the real quantum system\n", @@ -407,7 +407,7 @@ "\n", "* Runtime sessions: VQE is inherently iterative, with the classical optimizer selecting new variational parameters, and thus new gates being used, in each subsequent trial. Without using sessions, this could result in additional queue time between each trial circuit. Encapsulating the VQE calculation inside a session results in only one initial queue prior to the job's start, but no additional queue time between variational steps. This strategy was already used in the previous lesson's example, but may play an even more important role when varying geometry. For more about sessions, review the [execution modes documentation](/docs/guides/execution-modes).\n", "* Estimator's built-in optimization: In Estimator there are built-in options for optimizing a calculation. In many contexts (Estimator included), settings are limited to 0 and 1, with 0 indicating no optimization, and 1 (the default) indicating some optimization of your circuit to hardware selected. Some other contexts allow settings of 0, 1, 2, or 3. For more on the specific methods used in different settings, see the [documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options). Here, we will actually set optimization to 0, and use 'skip\\_transpilation = true', because we have already transpiled our circuit using the pass manager above, in the optimization section.\n", - "* Estimator's built-in resilience: As with optimization, Estimator has built-in settings for resilience against errors, corresponding to different approaches to error mitigation. To learn about resilience level settings, refer to the [documentation](/docs/guides/configure-error-mitigation).\n", + "* Estimator's built-in resilience: As with optimization, Estimator has built-in settings for resilience against errors, corresponding to different approaches to error mitigation. To learn about resilience level settings, refer to the [documentation](/docs/guides/error-mitigation-and-suppression-techniques).\n", "\n", "It is worth noting that error mitigation plays a nuanced role in the convergence of a VQE calculation. The classical optimizer is searching parameter space for those parameters that minimize the energy. When you are very far from the optimal parameters, a steep gradient may be apparent to the classical optimizer even in the presence of errors. But as the calculation converges and you approach the optimal values, the gradient becomes smaller, and more easily washed out by errors. How much error mitigation do you want to use? At what points in the convergence? These are choices you must make for your particular use case.\n", "\n", diff --git a/learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb b/learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb index 47e711be47c..3d95f1aa6e4 100644 --- a/learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb +++ b/learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb @@ -17,7 +17,7 @@ "\n", "Watch the video on quantum circuits and primitives from Olivia Lanes, or open the video in a separate window on [YouTube.](https://youtube.com/watch?v=NTplT4WnNbk)\n", "\n", - "\n", + "\n", "\n", "## Lesson overview\n", "\n", @@ -55,7 +55,7 @@ "\n", "To turn your quantum problem into instructions for a quantum computer, you'll use Qiskit, the open-source software development kit designed for work on quantum computers developed by IBM. There's also the Qiskit Ecosystem — a collection of software tutorials and functions that build or extend upon the core functionalities of Qiskit — and Qiskit Runtime — a quantum computing service and programming model that allows users to design and optimize their quantum workloads and execute them efficiently by using Qiskit Runtime Primitives.\n", "\n", - "A primitive is a small building block that you can use to design a larger circuit or job. The two primitives that are most important to us are the sampler and the estimator, which we'll discuss in more depth shortly.\n", + "A primitive is a small building block that you can use to design a larger circuit or job. The two primitives that are most important to us are Sampler and Estimator, which we'll discuss in more depth shortly.\n", "\n", "With the recent release of Qiskit v1.0, Qiskit has become more performative and stable than ever before. So, for those of you just getting started, you came in at the perfect time! For those of you that are already familiar with Qiskit, you'll need to download and reinstall the newest version. For a full installation guide, visit [the Install Qiskit](/docs/guides/install-qiskit) guide.\n", "\n", @@ -151,7 +151,7 @@ "\n", "### Execute\n", "\n", - "Now we're ready to execute the quantum program. The Qiskit Runtime primitives provide an interface to IBM Quantum hardware, and they also abstract error suppression and mitigation away from the user. There are two primitives to choose from: the Sampler and the Estimator.\n", + "Now we're ready to execute the quantum program. The Qiskit Runtime primitives provide an interface to IBM Quantum hardware, and they also abstract error suppression and mitigation away from the user. There are two primitives to choose from: Sampler and Estimator.\n", "\n", "\n", "[Qiskit Runtime's Sampler](/docs/api/qiskit-ibm-runtime/sampler) runs the circuit multiple times on a quantum device, performing measurements on each run, and reconstructing the probability distribution from the recovered bit strings. The more runs (or shots) it performs, the more accurate the results will be, but this requires more time and quantum resources. Specifically, it calculates the probability of obtaining each possible standard basis state by measuring the state prepared by the circuit.\n", diff --git a/learning/courses/quantum-computing-in-practice/simulating-nature.ipynb b/learning/courses/quantum-computing-in-practice/simulating-nature.ipynb index 08e533648cf..8b2e28d7d43 100644 --- a/learning/courses/quantum-computing-in-practice/simulating-nature.ipynb +++ b/learning/courses/quantum-computing-in-practice/simulating-nature.ipynb @@ -200,7 +200,7 @@ "\n", "After completing the optimization step, we are ready to execute the circuit using a primitive. We are considering a simulation experiment in which the goal is to understand how certain properties of the system change over time. For this purpose, the Estimator primitive is the most appropriate choice, as it allows you to measure the expectation values of observables that correspond to these properties.\n", "\n", - "Next, we use options including [error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques), to improve the Estimator's accuracy. Finally, we run the experiment to collect the results.\n", + "Next, we use options including [error suppression and mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques), to improve Estimator's accuracy. Finally, we run the experiment to collect the results.\n", "\n", "__7. Post-process__\n", "\n", @@ -327,7 +327,7 @@ "\n", "### Qiskit patterns step 3: Execute using primitives\n", "\n", - "Now, it is time to [run our circuit](/docs/tutorials/probabilistic-error-amplification#step-3-execute-using-qiskit-primitives). We will use the Estimator as our primary tool for this experiment because our goal is to measure the total magnetization of the system. The Estimator is specifically designed to estimate the expectation values of observables, making it the ideal choice here.\n", + "Now, it is time to [run our circuit](/docs/tutorials/probabilistic-error-amplification#step-3-execute-using-qiskit-primitives). We will use Estimator as our primary tool for this experiment because our goal is to measure the total magnetization of the system. The Estimator is specifically designed to estimate the expectation values of observables, making it the ideal choice here.\n", "At this stage, it is also essential to configure our error mitigation settings. We will apply Zero Noise Extrapolation (ZNE) to improve the accuracy of our results. In the tutorial, you will see that we specify two or more noise factor values at which to evaluate the extrapolated models, and we select “Probabilistic Error Amplification” (PEA) as our amplification method. PEA is preferred for this experiment because it scales significantly better than other options, which is crucial when working with systems of 100 or more qubits.\n", "\n", "This is all that is required to run the experiment.\n", diff --git a/learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb b/learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb index a8ed31ee7c0..87d7e91e202 100644 --- a/learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb +++ b/learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb @@ -181,7 +181,7 @@ "\n", "Now, we're almost ready to run the circuit — I promise! But first, it is important to note that you can send your job in a variety of different ways, which are called execution modes.\n", "\n", - "- Job mode: A single primitive request of the estimator or the sampler is made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer.\n", + "- Job mode: A single primitive request of the Estimator or Sampler primitive is made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer.\n", "\n", "- Batch mode: A multi-job manager for efficiently running an experiment that is comprised of bundle of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously\n", "\n", diff --git a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb index 99c553c96f6..5f92e24fcab 100644 --- a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb +++ b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb @@ -29,11 +29,11 @@ "source": [ "## 1. What is VQE?\n", "\n", - "The variational quantum eigensolver is an algorithm that uses classical and quantum computing in conjunction to accomplish a task. There are 4 main components of a VQE calculation:\n", + "The variational quantum eigensolver is an algorithm that uses classical and quantum computing in conjunction to accomplish a task. There are four main components of a VQE calculation:\n", "\n", "* __An operator__: Often a Hamiltonian, which we’ll call $H$, that describes a property of your system that you wish to optimize. Another way of saying this is that you are seeking the eigenvector of this operator that corresponds to the minimum eigenvalue. We often call that eigenvector the “ground state”.\n", "* __An “ansatz”__ (a German word meaning “approach”): this is a quantum circuit that prepares a quantum state approximating the eigenvector you’re seeking. Really the ansatz is a family of quantum circuits, because some of the gates in the ansatz are parametrized, that is, they are fed a parameter which we can vary. This family of quantum circuits can prepare a family of quantum states approximating the ground state.\n", - "* __An estimator__: a means of estimating the expectation value of the operator $H$ over the current variational quantum state. Sometimes what we really care about is simply this expectation value, which we call a cost function. Sometimes, we care about a more complicated function that can still be written starting from one or more expectation values.\n", + "* __An Estimator__: a means of estimating the expectation value of the operator $H$ over the current variational quantum state. Sometimes what we really care about is simply this expectation value, which we call a cost function. Sometimes, we care about a more complicated function that can still be written starting from one or more expectation values.\n", "* __A classical optimizer__: an algorithm that varies parameters to try to minimize the cost function.\n", "\n", "Let's look at each of these components in more depth." @@ -207,7 +207,7 @@ "A common workflow (demonstrated in Section 3.3) is to use one of these algorithms as the method inside a minimizer like scipy's ```minimize``` function. This takes as its arguments:\n", "* Some function to be minimized. This is often the energy expectation value. But these are generally referred to as \"cost functions\".\n", "* A set of parameters from which to begin the search. Often called $x_0$ or $\\theta_0$.\n", - "* Arguments, including arguments of the cost function. In quantum computing with Qiskit, these arguments will include the ansatz, the Hamiltonian, and the estimator, which is discussed more in the next subsection.\n", + "* Arguments, including arguments of the cost function. In quantum computing with Qiskit, these arguments will include the ansatz, the Hamiltonian, and the Estimator primitive, which is discussed more in the next subsection.\n", "* A 'method' of minimization. This refers to the specific algorithm used to search the parameter space. This is where we would specify, for example, COBYLA or SLSQP.\n", "* Options. The options available may differ by method. But an example which practically all methods would include is the maximum number of iterations of the optimizer before ending the search: 'maxiter'.\n", "\n", @@ -350,7 +350,7 @@ "\n", "So we decompose our matrix $H$ into a sum of Paulis acting on different qubits. Some elements of that sum can be measured all at once; we call this a *group of commuting Paulis*. Depending on how many non-commuting terms there are, we may need many such groups. Call the number of such groups of commuting Pauli strings $N_\\text{GCP}$. If $N_\\text{GCP}$ is small, this could work well. If $H$ has millions of groups, this will not be useful.\n", "\n", - "The processes required for estimation of the expectation value are collected together in the Qiskit Runtime primitive called Estimator. To learn more about Estimator, see the [API reference](/docs/api/qiskit-ibm-runtime/estimator-v2) in IBM Quantum® Documentation. One can simply use Estimator directly, but Estimator returns much more than just the lowest energy eigenvalue. For example, it also returns information on ensemble standard error. Thus, in the context of minimization problems, one often sees Estimator inside a cost function. To learn more about Estimator inputs and outputs see this [guide](/docs/guides/primitive-input-output) on IBM Quantum Documentation.\n", + "The processes required for estimation of the expectation value are collected together in the Qiskit Runtime primitive called Estimator. To learn more about Estimator, see the [API reference](/docs/api/qiskit-ibm-runtime/estimator-v2) in IBM Quantum® Documentation. One can simply use Estimator directly, but Estimator returns much more than just the lowest energy eigenvalue. For example, it also returns information on ensemble standard error. Thus, in the context of minimization problems, one often sees Estimator inside a cost function. To learn more about Estimator inputs and outputs see this [guide](/docs/guides/primitive-input-output#pubs) on IBM Quantum Documentation.\n", "\n", "You record the expectation value (or the cost function) for the set of parameters $\\vec{\\theta_i}$ used in your state, and then you update the parameters. Over time, you could use the expectation values or cost-function values you’ve estimated to approximate a gradient of your cost function in the subspace of states sampled by your ansatz. Both gradient-based, and gradient-free classical optimizers exist. Both suffer from potential trainability issues, like multiple local minima, and large regions of parameter space with near-zero gradient, called *barren plateaus*.\n", "\n", @@ -630,18 +630,18 @@ "\n", "#### 3.3.1 Reporting out values\n", "\n", - "We define a cost function here that takes as arguments the structures we have built in previous steps: the parameters, the ansatz, and the Hamiltonian. It also uses the estimator which we have not yet defined. We include code to track the history of our cost function, so that we can check convergence behavior." + "We define a cost function here that takes as arguments the structures we have built in previous steps: the parameters, the ansatz, and the Hamiltonian. It also uses Estimator, which we have not yet defined. We include code to track the history of our cost function, so that we can check convergence behavior." ] }, { "cell_type": "code", - "execution_count": 11, + "execution_count": null, "id": "bb1d8999-77aa-4c1a-adae-8974eda9e63b", "metadata": {}, "outputs": [], "source": [ "def cost_func(params, ansatz, hamiltonian, estimator):\n", - " \"\"\"Return estimate of energy from estimator\n", + " \"\"\"Return estimate of energy from Estimator\n", "\n", " Parameters:\n", " params (ndarray): Array of ansatz parameters\n", @@ -938,7 +938,7 @@ "\n", "* Heuristic nature: VQE does not guarantee convergence to the correct ground state energy, as its performance depends on the choice of ansatz and optimization methods[\\[1-2\\]](#references). If a poor ansatz is chosen that lacks the requisite entanglement for the desired ground state, no classical optimizer can reach that ground state.\n", "* Potentially numerous parameters: A very expressive ansatz may have so many parameters that the minimization iterations are very time-consuming.\n", - "* High measurement overhead: In VQE, an estimator is used to estimate the expectation value of each term in the Hamiltonian. Most Hamiltonians of interest will have terms that cannot be simultaneously estimated. This can make VQE resource-intensive for large systems with complicated Hamiltonians[\\[1\\]](#references).\n", + "* High measurement overhead: In VQE, Estimator is used to estimate the expectation value of each term in the Hamiltonian. Most Hamiltonians of interest will have terms that cannot be simultaneously estimated. This can make VQE resource-intensive for large systems with complicated Hamiltonians[\\[1\\]](#references).\n", "* Effects of noise: When the classical optimizer is searching for a minimum, noisy calculations can confuse it and steer it away from the true minimum or delay its convergence. One possible solution for this is leveraging state-of-the-art error mitigation and error suppression techniques[\\[2-3\\]](#references) from IBM.\n", "* Barren plateaus: These regions of vanishing gradients[\\[2-3\\]](#references) exist even in the absence of noise, but noise makes them more troublesome since the change in expectation values due to noise could be larger than the change from updating parameters in these barren regions.\n", "\n", diff --git a/learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb b/learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb index 655c4405a7e..5b92b7718ef 100644 --- a/learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb +++ b/learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb @@ -756,7 +756,7 @@ "source": [ "### 3.3 Execute using Estimator (with different resilience levels)\n", "\n", - "Setting the resilienece level (`estimator.options.resilience_level`) is the easiest way to apply error mitigation when using Qiskit Estimator. Estimator supports the following resilience levels (as of 2024/06/28). See more details in the [Configure error mitigation](/docs/guides/configure-error-mitigation) guide.\n", + "Setting the resilienece level (`estimator.options.resilience_level`) is the easiest way to apply error mitigation when using Qiskit Estimator. Estimator supports the following resilience levels (as of 2024/06/28). See more details in the [Configure error mitigation](/docs/guides/error-mitigation-and-suppression-techniques) guide.\n", "\n", "![image.png](/learning/images/courses/utility-scale-quantum-computing/error-mitigation/res_level.avif)" ] @@ -935,7 +935,7 @@ "metadata": {}, "source": [ "See the following guides and API reference for the details of error mitigation options.\n", - "- [Configure error mitigation](/docs/guides/configure-error-mitigation)\n", + "- [Configure error mitigation](/docs/guides/error-mitigation-and-suppression-techniques)\n", "- [Introduction to options](/docs/guides/runtime-options-overview)\n", "- [EstimatorOptions](/docs/api/qiskit-ibm-runtime/options-estimator-options)\n", "- [SamplerOptions](/docs/api/qiskit-ibm-runtime/options-sampler-options)" diff --git a/learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb b/learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb index db8472d3af5..2a18f355aeb 100644 --- a/learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb +++ b/learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb @@ -1220,7 +1220,7 @@ "outputs": [ { "ename": "IBMInputValueError", - "evalue": "'The instruction ccx on qubits (0, 1, 2) is not supported by the target system. Circuits that do not match the target hardware definition are no longer supported after March 4, 2024. See the transpilation documentation (/docs/guides/transpile) for instructions to transform circuits and the primitive examples (/docs/guides/primitives-examples) to see this coupled with operator transformations.'", + "evalue": "'The instruction ccx on qubits (0, 1, 2) is not supported by the target system. Circuits that do not match the target hardware definition are no longer supported after March 4, 2024. See the transpilation documentation (/docs/guides/transpile) for instructions to transform circuits and the primitive examples (/docs/guides/sampler-examples) to see this coupled with operator transformations.'", "output_type": "error", "traceback": [ "\u001b[31m---------------------------------------------------------------------------\u001b[39m", diff --git a/learning/courses/utility-scale-quantum-computing/utility-iii.ipynb b/learning/courses/utility-scale-quantum-computing/utility-iii.ipynb index d443fe9b125..a3c492784b7 100644 --- a/learning/courses/utility-scale-quantum-computing/utility-iii.ipynb +++ b/learning/courses/utility-scale-quantum-computing/utility-iii.ipynb @@ -1922,7 +1922,7 @@ "id": "2c40dc0f-93a0-4fae-980f-b7c5ab449a40", "metadata": {}, "source": [ - "You can set the error suppression options in Sampler V2. Refer to the [Configure error mitigation](/docs/guides/configure-error-mitigation#advanced-error) guide and the [`ExecutionOptionsV2`](/docs/api/qiskit-ibm-runtime/options-execution-options-v2) API reference for more information." + "You can set the error suppression options in Sampler V2. Refer to the [Sampler noise management](/docs/guides/sampler-noise-management) guide and the [`ExecutionOptionsV2`](/docs/api/qiskit-ibm-runtime/options-execution-options-v2) API reference for more information." ] }, { diff --git a/learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb b/learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb index 8cfcf3c57b6..f99e6becff3 100644 --- a/learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb +++ b/learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb @@ -1528,7 +1528,7 @@ "metadata": {}, "source": [ "#### Define backend and execution primitive\n", - "Use the **Qiskit Runtime primitives** to interact with IBM® backends. The two primitives are Sampler and Estimator, and the choice of primitive depends on what type of measurement you want to run on the quantum computer. For the minimization of $H_C$, use the Estimator since the measurement of the cost function is simply the expectation value of $\\langle H_C \\rangle$." + "Use the **Qiskit Runtime primitives** to interact with IBM® backends. The two primitives are Sampler and Estimator, and the choice of primitive depends on what type of measurement you want to run on the quantum computer. For the minimization of $H_C$, use Estimator since the measurement of the cost function is simply the expectation value of $\\langle H_C \\rangle$." ] }, { diff --git a/learning/courses/variational-algorithm-design/cost-functions.ipynb b/learning/courses/variational-algorithm-design/cost-functions.ipynb index 08ee6c85c5a..249ace62c26 100644 --- a/learning/courses/variational-algorithm-design/cost-functions.ipynb +++ b/learning/courses/variational-algorithm-design/cost-functions.ipynb @@ -1037,7 +1037,7 @@ "source": [ "### Error Suppression\n", "\n", - "[Error suppression](/docs/guides/configure-error-suppression) refers to techniques used to optimize and transform a circuit during compilation in order to minimize errors. This is a basic error handling technique that usually results in some classical pre-processing overhead to the overall runtime. The overhead includes transpiling circuits to run on quantum hardware by:\n", + "[Error suppression](/docs/guides/error-mitigation-and-suppression-techniques) refers to techniques used to optimize and transform a circuit during compilation in order to minimize errors. This is a basic error handling technique that usually results in some classical pre-processing overhead to the overall runtime. The overhead includes transpiling circuits to run on quantum hardware by:\n", "\n", "- Expressing the circuit using the native gates available on a quantum system\n", "- Mapping the virtual qubits to physical qubits\n", @@ -1243,7 +1243,7 @@ "source": [ "### Error Mitigation\n", "\n", - "[Error mitigation](/docs/guides/configure-error-mitigation) refers to techniques that allow users to reduce circuit errors by modeling the device noise at the time of execution. Typically, this results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model.\n", + "[Error mitigation](/docs/guides/error-mitigation-and-suppression-techniques) refers to techniques that allow users to reduce circuit errors by modeling the device noise at the time of execution. Typically, this results in quantum pre-processing overhead related to model training and classical post-processing overhead to mitigate errors in the raw results by using the generated model.\n", "\n", "The Qiskit Runtime primitive's `resilience_level` option specifies the amount of resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times due to quantum sampling overhead. Resilience levels can be used to configure the trade-off between cost and accuracy when applying error mitigation to your primitive query.\n", "\n", @@ -1284,7 +1284,7 @@ "\n", "![A diagram showing steps in ZNE. Noise is artificially amplified by different factors. Then the values are extrapolated to what they should be at zero noise.](/learning/images/courses/variational-algorithm-design/cost-functions/cost-function-zne-stages.svg)\n", "\n", - "We can set this with `options.resilience_level = 2`. We can optimize this further by exploring a variety of `noise_factors`, `noise_amplifiers`, and `extrapolators`, but this is outside the scope of this course. We encourage you to experiment with these [options as described here](/docs/guides/configure-error-mitigation).\n", + "We can set this with `options.resilience_level = 2`. We can optimize this further by exploring a variety of `noise_factors`, `noise_amplifiers`, and `extrapolators`, but this is outside the scope of this course. We encourage you to experiment with these [options as described here](/docs/guides/error-mitigation-and-suppression-techniques).\n", "\n", "Each method comes with its own associated overhead: a trade-off between the number of quantum computations needed (time) and the accuracy of our results:\n", "\n", diff --git a/learning/modules/computer-science/vqe.ipynb b/learning/modules/computer-science/vqe.ipynb index 78008b24926..5f5f303e4bc 100644 --- a/learning/modules/computer-science/vqe.ipynb +++ b/learning/modules/computer-science/vqe.ipynb @@ -971,7 +971,7 @@ "source": [ "Congratulations! You have just finished your first quantum chemistry experiment successfully. We can see a difference between the exact ground state energy of the Hamiltonian and ours, but because we used a default error mitigation technique (which corrects readout errors), the difference is minor. This is a very good start!\n", "\n", - "Note: You can get a better result by setting a level of error mitigation using [`resilience_level`](/docs/guides/configure-error-mitigation). The default value is 1, and if you set a higher value, it will use more QPU time but might return a better result." + "Note: You can get a better result by setting a level of error mitigation using [`resilience_level`](/docs/guides/error-mitigation-and-suppression-techniques). The default value is 1, and if you set a higher value, it will use more QPU time but might return a better result." ] }, { diff --git a/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb b/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb index 0569a8e6583..625d954ce7b 100644 --- a/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb +++ b/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb @@ -267,7 +267,7 @@ "source": [ "### Step 3: Execute using Qiskit Runtime primitives\n", "\n", - "We can use sampler to collect statistics on the measurements. We will construct the Sampler primitive to run on a real quantum computer using ```mode = backend```. There are other modes for other workflows, and we will use one below. Sampler will be used by calling its run() method with a list of \"pubs\" (Primitive Unified Blocs). Each pub contains up to three values that, together, define a computation unit of work for the estimator to complete: circuits, observables, parameters. You can also provide a list of circuits, a list of observables, and a list of parameters. For more information, read the [Overview of PUBs.](/docs/guides/primitive-input-output#overview-of-pubs)\n", + "We can use sampler to collect statistics on the measurements. We will construct the Sampler primitive to run on a real quantum computer using ```mode = backend```. There are other modes for other workflows, and we will use one below. Sampler will be used by calling its run() method with a list of \"pubs\" (Primitive Unified Blocs). Each pub contains up to three values that, together, define a computation unit of work for the estimator to complete: circuits, observables, parameters. You can also provide a list of circuits, a list of observables, and a list of parameters. For more information, read the [Overview of PUBs.](/docs/guides/primitive-input-output#pubs)\n", "\n", "We want to run on a real quantum computer, so that we are carrying out a real quantum physics experiment. If you exhaust your allotted time on real quantum computers, you can comment out the code below for the quantum computer, and uncomment the code for running on a simulator." ] diff --git a/public/docs/images/guides/configure-error-mitigation/resilience-2.svg b/public/docs/images/guides/configure-error-mitigation/resilience-2.svg deleted file mode 100644 index efbb2f341df..00000000000 --- a/public/docs/images/guides/configure-error-mitigation/resilience-2.svg +++ /dev/null @@ -1,33 +0,0 @@ - - - - - - Mitigated value - Expectation value - Noise amplification factor - Exact value - Unmitigated value - Noise amplified values - diff --git a/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.avif b/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.avif new file mode 100644 index 00000000000..153f3a47169 Binary files /dev/null and b/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.avif differ diff --git a/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.svg b/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.svg deleted file mode 100644 index 8852136d5db..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.avif b/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.avif new file mode 100644 index 00000000000..f31fe156893 Binary files /dev/null and b/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.avif differ diff --git a/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.svg b/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.svg deleted file mode 100644 index 01f34e0d6f0..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.avif b/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.avif new file mode 100644 index 00000000000..10d79aa05ca Binary files /dev/null and b/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.avif differ diff --git a/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.svg b/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.svg deleted file mode 100644 index ec3c0d3cce5..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.avif b/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.avif new file mode 100644 index 00000000000..e423623bb3e Binary files /dev/null and b/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.avif differ diff --git a/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg b/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg deleted file mode 100644 index 46dc2646211..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/primitive-input-output/broadcasting.avif b/public/docs/images/guides/primitive-input-output/broadcasting.avif new file mode 100644 index 00000000000..e1f059942c0 Binary files /dev/null and b/public/docs/images/guides/primitive-input-output/broadcasting.avif differ diff --git a/public/docs/images/guides/primitive-input-output/broadcasting.svg b/public/docs/images/guides/primitive-input-output/broadcasting.svg deleted file mode 100644 index 533bb0ab40b..00000000000 --- a/public/docs/images/guides/primitive-input-output/broadcasting.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 2d82d9a427f..7bb870de44a 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -172,7 +172,11 @@ notifications: - "`@mtreinish`" "docs/guides/composer": - "`@abbycross`" - "docs/guides/configure-error-mitigation": + "docs/guides/sampler-noise-management": + - "@jyu00" + - "`@beckykd`" + - "`@abbycross`" + "docs/guides/estimator-noise-management": - "@jyu00" - "`@beckykd`" - "`@abbycross`" @@ -226,7 +230,10 @@ notifications: - "abbycross" - "@jyu00" - "`@beckykd`" - + "docs/guides/get-started-with-backend-primitives": + - "abbycross" + - "@jyu00" + - "@beckykd" "docs/guides/fair-share-scheduler": - "`@lerongil`" - "@jyu00" @@ -235,8 +242,41 @@ notifications: - "@kaelynj" "docs/guides/measure-qubits": - "`@beckykd`" - "docs/guides/get-started-with-primitives": - - "@ElePT" + "docs/guides/estimator-examples": + - "@abbycross" + - "`@beckykd`" + - "@jyu00" + "docs/guides/estimator-input-output": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/estimator-options": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/get-started-with-sampler": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/primitive-input-output": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-examples": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-input-output": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-options": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/get-started-with-estimator": + - "@abbycross" + - "@beckykd" - "@jyu00" "docs/guides/ha-dr": - "`@abbycross`" @@ -248,24 +288,24 @@ notifications: - "`@abbycross`" - "`@beckykd`" "docs/guides/responsibilities": - - "`@abbycross`" - - "`@beckykd`" + - "@abbycross" + - "@beckykd" "docs/guides/hello-world": - - "`@abbycross`" - - "`@beckykd`" + - "@abbycross" + - "@beckykd" "docs/guides/allocation-limits": - "`@abbycross`" - "`@beckykd`" "docs/guides/qiskit-runtime-primitives": - - "`@abbycross`" - - "`@beckykd`" + - "@abbycross" + - "@beckykd" "docs/guides/install-c-api": - - "`@abbycross`" - - "`@beckykd`" + - "@abbycross" + - "@beckykd" - "@cryoris" "docs/guides/install-qiskit": - - "`@abbycross`" - - "`@beckykd`" + - "@abbycross" + - "@beckykd" - "`@mtreinish`" "docs/guides/install-qiskit-source": - "`@mtreinish`" @@ -359,14 +399,9 @@ notifications: - "@ElePT" - "`@beckykd`" - "`@abbycross`" - "docs/guides/primitives-examples": - - "@jyu00" - - "`@beckykd`" - - "`@abbycross`" - - "`@blakejohnson`" "docs/guides/processor-types": - "`@lerongil`" - - "`@abbycross`" + - "@abbycross" "docs/guides/qiskit-code-assistant": - "cbjuan" - "`@abbycross`" @@ -434,8 +469,6 @@ notifications: - "`@kevinsung`" "docs/guides/specify-observables-pauli": - "@Cryoris" - "docs/guides/specify-runtime-options": - - "`@beckykd`" "docs/guides/synthesize-unitary-operators": - "@Cryoris" "docs/guides/qpu-information": @@ -496,10 +529,14 @@ notifications: "docs/guides/v2-primitives": - "@jyu00" - "@ElePT" - - "`@beckykd`" - "docs/guides/primitive-input-output": + - "@beckykd" + "docs/guides/sampler-rest-api": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" - "@kaelynj" - "docs/guides/primitives-rest-api": + "docs/guides/estimator-rest-api": - "@born-2learn" - "@HuangJunye" - "@pacomf" diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index c2f873b4eaf..f164934bc92 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -22,6 +22,22 @@ export function ignoreTitleMismatch(filepath: string): boolean { } const IGNORE_TITLE_MISMATCHES: string[] = [ + "docs/guides/directed-execution-model.mdx", + "docs/guides/estimator-examples.ipynb", + "docs/guides/estimator-input-output.ipynb", + "docs/guides/estimator-options.ipynb", + "docs/guides/estimator-rest-api.ipynb", + "docs/guides/estimator-broadcasting.mdx", + "docs/guides/broadcasting.mdx", + "docs/guides/get-started-with-sampler.ipynb", + "docs/guides/pubs.ipynb", + "docs/guides/estimator-noise-management.ipynb", + "docs/guides/sampler-noise-management.ipynb", + "docs/guides/sampler-examples.ipynb", + "docs/guides/sampler-rest-api.mdx", + "docs/guides/sampler-input-output.ipynb", + "docs/guides/sampler-options.ipynb", + "docs/guides/get-started-with-estimator.ipynb", "docs/guides/external-providers-primitives-v2.mdx", "docs/guides/create-a-provider.mdx", "docs/guides/local-simulators.mdx", diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index ff44fa0c92f..6e4b3d43bc0 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -11,14 +11,13 @@ test-strategies.extended = {} test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ "docs/guides/DAG-representation.ipynb", - "docs/guides/qiskit-runtime-primitives.ipynb", "docs/guides/bit-ordering.ipynb", "docs/guides/build-noise-models.ipynb", "docs/guides/circuit-library.ipynb", "docs/guides/classical-feedforward-and-control-flow.ipynb", "docs/guides/common-parameters.ipynb", - "docs/guides/configure-error-mitigation.ipynb", - "docs/guides/configure-error-suppression.ipynb", + "docs/guides/estimator-noise-management.ipynb", + "docs/guides/sampler-noise-management.ipynb", "docs/guides/construct-circuits.ipynb", "docs/guides/create-transpiler-plugin.ipynb", "docs/guides/custom-backend.ipynb", @@ -51,7 +50,6 @@ notebooks = [ "docs/guides/transpiler-plugins.ipynb", "docs/guides/transpiler-stages.ipynb", "docs/guides/visualize-circuits.ipynb", - "docs/guides/circuit-transpilation-settings.ipynb", ] # Mock the following notebooks using a 6-qubit local simulator @@ -60,7 +58,6 @@ test-strategies.ci = { patch = "qiskit-fake-provider", num_qubits = 6 } test-strategies.extended = { patch = "qiskit-fake-provider", num_qubits = 6 } test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "docs/guides/specify-runtime-options.ipynb", "docs/guides/visualize-results.ipynb", ] @@ -68,6 +65,9 @@ notebooks = [ # test-eagle device, which returns nonsense results. Use this to test notebooks # that submit large jobs to test notebooks that use functions, which accept # only a backend name (string) rather than a `Backend` object. +# Use this ANY time the results (postprocessing) are not important. For example, +# for showing how to format & run a job. Don't use it if you're trying to explain +# something about the results. Put a notebook here if it's timing out in CI. [groups.test-eagle] test-strategies.extended = { patch = "qiskit-ibm-runtime", backend = "test_eagle_us-east", qiskit_runtime_service_args = "" } test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } @@ -78,8 +78,16 @@ notebooks = [ "docs/guides/functions.ipynb", "docs/guides/get-started-with-primitives.ipynb", "docs/guides/ibm-circuit-function.ipynb", - "docs/guides/primitives-examples.ipynb", + "docs/guides/sampler-examples.ipynb", + "docs/guides/estimator-examples.ipynb", "docs/guides/execute-dynamic-circuits.ipynb", + "docs/guides/estimator-rest-api.ipynb", + "docs/guides/get-started-with-sampler.ipynb", + "docs/guides/sampler-input-output.ipynb", + "docs/guides/sampler-options.ipynb", + "docs/guides/estimator-input-output.ipynb", + "docs/guides/estimator-options.ipynb", + "docs/guides/get-started-with-estimator.ipynb", "docs/guides/qiskit-addons-sqd-get-started.ipynb", "docs/guides/multiverse-computing-singularity.ipynb", "docs/guides/qunova-chemistry.ipynb", @@ -91,16 +99,14 @@ notebooks = [ "docs/guides/add-job-tags.ipynb", "docs/guides/qiskit-runtime-circuit-timing.ipynb", "docs/guides/visualize-circuit-timing.ipynb", + "docs/guides/circuit-transpilation-settings.ipynb", ] # Only run the following notebooks in our fortnightly cron job on real hardware. [groups.cron-job-only] test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "docs/guides/primitives-rest-api.ipynb", "docs/guides/hello-world.ipynb", - # The following notebook takes >300s to run and should be executed in the - # cron job. Even though it does not use real hardware # The following notebooks don't seem to work with `test-eagle`, but I'm not # sure why. I've added them here to run on the next cron job so we can diff --git a/scripts/js/commands/checkMarkdown.ts b/scripts/js/commands/checkMarkdown.ts index fc9649433e7..0799c5d47b9 100644 --- a/scripts/js/commands/checkMarkdown.ts +++ b/scripts/js/commands/checkMarkdown.ts @@ -1,4 +1,4 @@ -// This code is a Qiskit project. +// This code is a Qiskit project.session // // (C) Copyright IBM 2025. // diff --git a/scripts/js/lib/links/ignores.ts b/scripts/js/lib/links/ignores.ts index 622897ab8cf..fef69a250d0 100644 --- a/scripts/js/lib/links/ignores.ts +++ b/scripts/js/lib/links/ignores.ts @@ -168,6 +168,10 @@ const ALWAYS_IGNORED_URLS__SHOULD_FIX: string[] = [ "https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/backend_status_schema.json", "https://github.com/Qiskit/ibm-quantum-schemas/blob/main/schemas/default_pulse_configuration_schema.json", + // These links should work when redirects are in place. + "/docs/guides/configure-error-mitigation", + "/docs/guides/configure-error-suppression", + // These links are from old IQP and do not work any more "https://auth.quantum-computing.ibm.com/api", "https://auth.quantum.ibm.com/api",