From 26b38e976cbfe1ee5705ea2f3f95c5aa83a3b478 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 16 Jan 2026 17:20:13 -0500 Subject: [PATCH 001/118] Reorder toc, move hello world --- docs/guides/_toc.json | 1825 +++++++++--------- docs/{tutorials => guides}/hello-world.ipynb | 0 qiskit_bot.yaml | 2 +- scripts/config/notebook-testing.toml | 597 +++--- 4 files changed, 1219 insertions(+), 1205 deletions(-) rename docs/{tutorials => guides}/hello-world.ipynb (100%) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 9c5b3eb7e2c..c152f7f5e57 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -1,973 +1,986 @@ { - "title": "Documentation", - "collapsed": true, - "children": [ - { - "title": "Get started", - "children": [ + "title": "Documentation", + "collapsed": true, + "children": [ { - "title": "Introduction", - "url": "/docs/guides" - }, - { - "title": "Quickstart", - "url": "/docs/guides/quick-start" - }, - { - "title": "Install", - "children": [ - { - "title": "Install Qiskit", - "url": "/docs/guides/install-qiskit" - }, - { - "title": "Online lab environments", - "url": "/docs/guides/online-lab-environments" - }, - { - "title": "Advanced install", - "children": [ + "title": "Get started", + "children": [ { - "title": "Install the Qiskit SDK from source", - "url": "/docs/guides/install-qiskit-source" + "title": "Introduction", + "url": "/docs/guides" }, { - "title": "Configure the Qiskit SDK locally", - "url": "/docs/guides/configure-qiskit-local" + "title": "Quickstart", + "url": "/docs/guides/quick-start" }, { - "title": "Install the Qiskit C API", - "url": "/docs/guides/install-c-api" + "title": "Install", + "children": [ + { + "title": "Install Qiskit", + "url": "/docs/guides/install-qiskit" + }, + { + "title": "Install the Qiskit SDK from source", + "url": "/docs/guides/install-qiskit-source" + }, + { + "title": "Configure the Qiskit SDK locally", + "url": "/docs/guides/configure-qiskit-local" + }, + { + "title": "Install the Qiskit C API", + "url": "/docs/guides/install-c-api" + }, + { + "title": "Extend Qiskit in Python with C", + "url": "/docs/guides/c-extension-for-python" + } + ] }, { - "title": "Extend Qiskit in Python with C", - "url": "/docs/guides/c-extension-for-python" - } - ] - } - ] - }, - { - "title": "Development workflow", - "children": [ - { - "title": "Introduction to Qiskit patterns", - "url": "/docs/guides/intro-to-patterns" - }, - { - "title": "Map the problem to circuits", - "url": "/docs/guides/map-problem-to-circuits" - }, - { - "title": "Optimize for hardware", - "url": "/docs/guides/optimize-for-hardware" - }, - { - "title": "Execute on hardware", - "url": "/docs/guides/execute-on-hardware" - }, - { - "title": "Post-process results", - "url": "/docs/guides/post-process-results" - } - ] - }, - { - "title": "Latest updates", - "url": "/docs/guides/latest-updates" - } - ], - "collapsible": false - }, - { - "title": "IBM Quantum Platform", - "children": [ - { - "title": "Set up IBM Quantum Platform", - "children": [ - { - "title": "Set up your IBM Cloud account", - "url": "/docs/guides/cloud-setup" - }, - { - "title": "Set up your IBM Cloud account - invited users", - "url": "/docs/guides/cloud-setup-invited", - "platform": "cloud" - }, - { - "title": "Set up your IBM Cloud account in an untrusted environment", - "url": "/docs/guides/cloud-setup-untrusted", - "platform": "cloud" - }, - { - "title": "Set up to use IBM Quantum Platform with REST API", - "url": "/docs/guides/cloud-setup-rest-api", - "platform": "cloud" - }, - { - "title": "Save your login credentials", - "url": "/docs/guides/save-credentials", - "platform": "cloud" - }, - { - "title": "Initialize your Qiskit Runtime service account", - "url": "/docs/guides/initialize-account", - "platform": "cloud" - }, - { - "title": "Set up for an organization", - "children": [ - { - "title": "Setup considerations", - "url": "/docs/guides/considerations-set-up-runtime" - }, - { - "title": "Configure IBM Quantum Platform", - "url": "/docs/guides/quickstart-steps-org" - } - ] - } - ] - }, - { - "title": "IBM Quantum plans", - "children": [ - { - "title": "Overview of plans", - "url": "/docs/guides/plans-overview" - }, - { - "title": "Upgrade from the Open Plan", - "url": "/docs/guides/upgrade-from-open" - }, - { - "title": "Manage cost on the Pay-As-You-Go Plan", - "url": "/docs/guides/manage-cost" - } - ] - }, - { - "title": "Work with instances", - "children": [ - { - "title": "Create and manage instances", - "url": "/docs/guides/instances" - }, - { - "title": "Set allocation limits", - "url": "/docs/guides/allocation-limits" - }, - { - "title": "Use IBM Cloud Platform APIs to access instances", - "url": "/docs/guides/access-instances-platform-apis" - } - ] - }, - { - "title": "Accounts, access groups, and policies", - "children": [ - { - "title": "Cloud account structure", - "url": "/docs/guides/cloud-account-structure" - }, - { - "title": "Create access groups and policies", - "url": "/docs/guides/access-groups" - }, - { - "title": "Set up custom roles", - "url": "/docs/guides/custom-roles" - } - ] - }, - { - "title": "Manage users", - "children": [ - { - "title": "Invite users and manage access", - "url": "/docs/guides/invite-and-manage-users" - }, - { - "title": "Manage ID provider users", - "url": "/docs/guides/manage-appid" - }, - { - "title": "Manage IBM Cloud users", - "url": "/docs/guides/manage-cloud-users" - } - ] - }, - { - "title": "Logging", - "url": "/docs/guides/logging" - } - ], - "collapsible": false - }, - { - "title": "Qiskit Functions", - "children": [ - { - "title": "Introduction to Qiskit Functions", - "url": "/docs/guides/functions" - }, - { - "title": "Circuit functions", - "children": [ - { - "title": "IBM Circuit function", - "url": "/docs/guides/ibm-circuit-function" - }, - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/guides/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/guides/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/guides/qedma-qesem" - } - ] - }, - { - "title": "Application functions", - "children": [ - { - "title": "Kipu Quantum Iskay Quantum Optimizer", - "url": "/docs/guides/kipu-optimization" - }, - { - "title": "Multiverse Computing Singularity", - "url": "/docs/guides/multiverse-computing-singularity" - }, - { - "title": "Q-CTRL Optimization Solver", - "url": "/docs/guides/q-ctrl-optimization-solver" - }, - { - "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", - "url": "/docs/guides/global-data-quantum-optimizer" - }, - { - "title": "QUICK-PDE: A Qiskit Function by ColibriTD", - "url": "/docs/guides/colibritd-pde" - }, - { - "title": "Qunova Computing HI-VQE Chemistry", - "url": "/docs/guides/qunova-chemistry" - } - ] - }, - { - "title": "Qiskit Function templates", - "children": [ - { - "title": "Introduction to Qiskit Function templates", - "url": "/docs/guides/qiskit-function-templates" - }, - { - "title": "Template for chemistry simulation", - "url": "/docs/guides/function-template-chemistry-workflow" - }, - { - "title": "Template for Hamiltonian simulation", - "url": "/docs/guides/function-template-hamiltonian-simulation" - } - ] - } - ], - "collapsible": false - }, - { - "title": "Tools", - "children": [ - { - "title": "Introduction to Qiskit", - "url": "/docs/guides/tools-intro" - }, - { - "title": "Circuits and operators", - "children": [ - { - "title": "Circuit library", - "url": "/docs/guides/circuit-library" - }, - { - "title": "Construct circuits", - "url": "/docs/guides/construct-circuits" - }, - { - "title": "Fractional gates", - "url": "/docs/guides/fractional-gates" - }, - { - "title": "Classical feedforward and control flow", - "url": "/docs/guides/classical-feedforward-and-control-flow" - }, - { - "title": "Deferred timing resolution using stretch", - "url": "/docs/guides/stretch" - }, - { - "title": "Measure qubits", - "url": "/docs/guides/measure-qubits" - }, - { - "title": "Synthesize unitary operators", - "url": "/docs/guides/synthesize-unitary-operators" - }, - { - "title": "Bit-ordering in the Qiskit SDK", - "url": "/docs/guides/bit-ordering" - }, - { - "title": "Save circuits to disk", - "url": "/docs/guides/save-circuits" - }, - { - "title": "Operators module overview", - "url": "/docs/guides/operators-overview" - }, - { - "title": "Specify observables in the Pauli basis", - "url": "/docs/guides/specify-observables-pauli" - }, - { - "title": "The Operator class", - "url": "/docs/guides/operator-class" - }, - { - "title": "OpenQASM", - "children": [ - { - "title": "Intro to OpenQASM", - "url": "/docs/guides/introduction-to-qasm" + "title": "Run on quantum hardware", + "url": "/docs/guides/hello-world" }, { - "title": "OpenQASM 2 and the Qiskit SDK", - "url": "/docs/guides/interoperate-qiskit-qasm2" + "title": "Development Workflow", + "url": "/docs/guides/intro-to-patterns" }, { - "title": "OpenQASM 3 and the Qiskit SDK", - "url": "/docs/guides/interoperate-qiskit-qasm3" + "title": "Online lab environments", + "url": "/docs/guides/online-lab-environments" }, { - "title": "OpenQASM 3 feature table", - "url": "/docs/guides/qasm-feature-table" + "title": "IBM Quantum Composer", + "url": "/docs/guides/composer" }, { - "title": "OpenQASM 3.x live specification", - "url": "https://openqasm.com/" + "title": "Latest updates", + "url": "/docs/guides/latest-updates" } - ] - } - ] + ], + "collapsible": false }, { - "title": "Transpiler", - "children": [ - { - "title": "Introduction to transpilation", - "url": "/docs/guides/transpile" - }, - { - "title": "Transpiler stages", - "url": "/docs/guides/transpiler-stages" - }, - { - "title": "Transpile with pass managers", - "url": "/docs/guides/transpile-with-pass-managers" - }, - { - "title": "Create a pass manager for dynamical decoupling", - "url": "/docs/guides/dynamical-decoupling-pass-manager" - }, - { - "title": "Configure preset pass managers", - "children": [ + "title": "Qiskit", + "children": [ { - "title": "Default settings and configuration options", - "url": "/docs/guides/defaults-and-configuration-options" + "title": "Introduction to Qiskit", + "url": "/docs/guides/tools-intro" }, { - "title": "Set optimization level", - "url": "/docs/guides/set-optimization" + "title": "Circuits and operators", + "children": [ + { + "title": "Overview", + "url": "/docs/guides/construct-circuits" + }, + { + "title": "Circuit library", + "url": "/docs/guides/circuit-library" + }, + { + "title": "Save circuits to disk", + "url": "/docs/guides/save-circuits" + }, + { + "title": "Measure qubits", + "url": "/docs/guides/measure-qubits" + }, + { + "title": "Operators module", + "children": [ + { + "title": "Operators module overview", + "url": "/docs/guides/operators-overview" + }, + { + "title": "The Operator class", + "url": "/docs/guides/operator-class" + }, + { + "title": "Synthesize unitary operators", + "url": "/docs/guides/synthesize-unitary-operators" + }, + { + "title": "Specify observables in the Pauli basis", + "url": "/docs/guides/specify-observables-pauli" + } + ] + }, + { + "title": "Advanced circuit building", + "children": [ + { + "title": "Fractional gates", + "url": "/docs/guides/fractional-gates" + }, + { + "title": "Classical feedforward and control flow", + "url": "/docs/guides/classical-feedforward-and-control-flow" + }, + { + "title": "Deferred timing resolution using stretch", + "url": "/docs/guides/stretch" + }, + { + "title": "Bit-ordering in the Qiskit SDK", + "url": "/docs/guides/bit-ordering" + } + ] + }, + { + "title": "OpenQASM", + "children": [ + { + "title": "Intro to OpenQASM", + "url": "/docs/guides/introduction-to-qasm" + }, + { + "title": "OpenQASM 2 and the Qiskit SDK", + "url": "/docs/guides/interoperate-qiskit-qasm2" + }, + { + "title": "OpenQASM 3 and the Qiskit SDK", + "url": "/docs/guides/interoperate-qiskit-qasm3" + }, + { + "title": "OpenQASM 3 feature table", + "url": "/docs/guides/qasm-feature-table" + }, + { + "title": "OpenQASM 3.x live specification", + "url": "https://openqasm.com/" + } + ] + } + ] }, { - "title": "Commonly used parameters for transpilation", - "url": "/docs/guides/common-parameters" + "title": "Transpilation", + "children": [ + { + "title": "Introduction to transpilation", + "url": "/docs/guides/transpile" + }, + { + "title": "Transpiler stages", + "url": "/docs/guides/transpiler-stages" + }, + { + "title": "Transpile with pass managers", + "url": "/docs/guides/transpile-with-pass-managers" + }, + { + "title": "Create a pass manager for dynamical decoupling", + "url": "/docs/guides/dynamical-decoupling-pass-manager" + }, + { + "title": "Configure preset pass managers", + "children": [ + { + "title": "Default settings and configuration options", + "url": "/docs/guides/defaults-and-configuration-options" + }, + { + "title": "Set optimization level", + "url": "/docs/guides/set-optimization" + }, + { + "title": "Commonly used parameters for transpilation", + "url": "/docs/guides/common-parameters" + }, + { + "title": "Represent quantum computers", + "url": "/docs/guides/represent-quantum-computers" + } + ] + }, + { + "title": "Advanced transpilation resources", + "children": [ + { + "title": "Write a custom transpiler pass", + "url": "/docs/guides/custom-transpiler-pass" + }, + { + "title": "Create and transpile against custom backends", + "url": "/docs/guides/custom-backend" + }, + { + "title": "Install and use transpiler plugins", + "url": "/docs/guides/transpiler-plugins" + }, + { + "title": "Create a transpiler plugin", + "url": "/docs/guides/create-transpiler-plugin" + }, + { + "title": "Work with DAGs in transpiler passes", + "url": "/docs/guides/DAG-representation" + } + ] + } + ] }, { - "title": "Represent quantum computers", - "url": "/docs/guides/represent-quantum-computers" - } - ] - }, - { - "title": "Qiskit Transpiler Service", - "children": [ - { - "title": "Transpile circuits remotely with the Qiskit Transpiler Service", - "url": "/docs/guides/qiskit-transpiler-service" + "title": "Primitives", + "children": [ + { + "title": "Introduction to primitives", + "url": "/docs/guides/primitives" + }, + { + "title": "Get started with primitives", + "url": "/docs/guides/get-started-with-primitives" + }, + { + "title": "Primitive inputs and outputs", + "url": "/docs/guides/primitive-input-output" + }, + { + "title": "Exact simulation with Qiskit SDK primitives", + "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" + } + ] }, { - "title": "AI transpiler passes", - "url": "/docs/guides/ai-transpiler-passes" - } - ] - }, - { - "title": "Advanced transpilation resources", - "children": [ - { - "title": "Write a custom transpiler pass", - "url": "/docs/guides/custom-transpiler-pass" - }, - { - "title": "Create and transpile against custom backends", - "url": "/docs/guides/custom-backend" + "title": "Verification", + "children": [ + { + "title": "Simulate circuits with noise", + "children": [ + { + "title": "Exact and noisy simulation with Qiskit Aer primitives", + "url": "/docs/guides/simulate-with-qiskit-aer" + }, + { + "title": "Build noise models", + "url": "/docs/guides/build-noise-models" + }, + { + "title": "Efficient simulation of stabilizer circuits with Qiskit Aer primitives", + "url": "/docs/guides/simulate-stabilizer-circuits" + }, + { + "title": "Debug Qiskit Runtime jobs", + "url": "/docs/guides/debug-qiskit-runtime-jobs" + } + ] + }, + { + "title": "Visualization", + "children": [ + { + "title": "Visualize circuits", + "url": "/docs/guides/visualize-circuits" + }, + { + "title": "Visualize circuit timing", + "url": "/docs/guides/visualize-circuit-timing", + "isNew": true, + "isNewDate": "2025-11-20" + }, + { + "title": "Plot quantum states", + "url": "/docs/guides/plot-quantum-states" + }, + { + "title": "Visualize results", + "url": "/docs/guides/visualize-results" + } + ] + } + ] }, { - "title": "Install and use transpiler plugins", - "url": "/docs/guides/transpiler-plugins" + "title": "Integrations", + "children": [ + { + "title": "Create a provider", + "url": "/docs/guides/create-a-provider" + }, + { + "title": "Quantum resource management interface (QRMI)", + "url": "/docs/guides/qrmi", + "isNew": true + }, + { + "title": "SPANK plugin for QRMI", + "url": "/docs/guides/slurm-plugin", + "isNew": true + }, + { + "title": "SPANK plugin user guide", + "url": "/docs/guides/slurm-hpc-ux", + "isNew": true + } + ] }, { - "title": "Create a transpiler plugin", - "url": "/docs/guides/create-transpiler-plugin" + "title": "Qiskit code assistant", + "children": [ + { + "title": "Qiskit Code Assistant overview", + "url": "/docs/guides/qiskit-code-assistant" + }, + { + "title": "Use Qiskit Code Assistant in JupyterLab", + "url": "/docs/guides/qiskit-code-assistant-jupyterlab" + }, + { + "title": "Use Qiskit Code Assistant in VS Code", + "url": "/docs/guides/qiskit-code-assistant-vscode" + }, + { + "title": "Use Qiskit Code Assistant in local mode", + "url": "/docs/guides/qiskit-code-assistant-local" + }, + { + "title": "Qiskit Code Assistant - OpenAI API compatibility", + "url": "/docs/guides/qiskit-code-assistant-openai-api" + } + ] }, { - "title": "Work with DAGs in transpiler passes", - "url": "/docs/guides/DAG-representation" + "title": "Advanced techniques", + "children": [ + { + "title": "Error mitigation and suppression", + "url": "/docs/guides/error-mitigation-and-suppression-techniques" + }, + { + "title": "Qiskit addons overview", + "url": "/docs/guides/addons" + }, + { + "title": "Sample-based quantum diagonalization (SQD)", + "children": [ + { + "title": "SQD addon overview", + "url": "/docs/guides/qiskit-addons-sqd" + }, + { + "title": "Get started with SQD", + "url": "/docs/guides/qiskit-addons-sqd-get-started" + } + ] + }, + { + "title": "Approximate quantum compilation (AQC-Tensor)", + "children": [ + { + "title": "AQC-Tensor addon overview", + "url": "/docs/guides/qiskit-addons-aqc" + }, + { + "title": "Get started with AQC-Tensor", + "url": "/docs/guides/qiskit-addons-aqc-get-started" + } + ] + }, + { + "title": "Operator backpropagation (OBP)", + "children": [ + { + "title": "OBP addon overview", + "url": "/docs/guides/qiskit-addons-obp" + }, + { + "title": "Get started with OBP", + "url": "/docs/guides/qiskit-addons-obp-get-started" + } + ] + }, + { + "title": "Circuit cutting (CC)", + "children": [ + { + "title": "Circuit cutting overview", + "url": "/docs/guides/qiskit-addons-cutting" + }, + { + "title": "Get started with gate cuts", + "url": "/docs/guides/qiskit-addons-cutting-gates" + }, + { + "title": "Get started with wire cuts", + "url": "/docs/guides/qiskit-addons-cutting-wires" + } + ] + }, + { + "title": "Qiskit addon utilities", + "url": "/docs/guides/qiskit-addons-utils" + } + ] } - ] - } - ] - }, - { - "title": "Debugging tools", - "children": [ - { - "title": "Introduction to debugging tools", - "url": "/docs/guides/debugging-tools" - }, - { - "title": "Exact simulation with Qiskit SDK primitives", - "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" - }, - { - "title": "Exact and noisy simulation with Qiskit Aer primitives", - "url": "/docs/guides/simulate-with-qiskit-aer" - }, - { - "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": "Build noise models", - "url": "/docs/guides/build-noise-models" - }, - { - "title": "Efficient simulation of stabilizer circuits with Qiskit Aer primitives", - "url": "/docs/guides/simulate-stabilizer-circuits" - } - ] + ], + "collapsible": false }, { - "title": "Primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/primitives" - }, - { - "title": "Get started with primitives", - "url": "/docs/guides/get-started-with-primitives" - }, - { - "title": "Primitive inputs and outputs", - "url": "/docs/guides/primitive-input-output" - }, - { - "title": "Primitives examples", - "url": "/docs/guides/primitives-examples" - }, - { - "title": "Primitives with REST API", - "url": "/docs/guides/primitives-rest-api" - }, - { - "title": "Noise learning", - "url": "/docs/guides/noise-learning" - }, - { - "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": "Error mitigation and suppression techniques", - "url": "/docs/guides/error-mitigation-and-suppression-techniques" - }, - { - "title": "Configure error mitigation", - "url": "/docs/guides/configure-error-mitigation" - }, - { - "title": "Configure error suppression", - "url": "/docs/guides/configure-error-suppression" - } - ] - }, - { - "title": "Execution modes", - "children": [ - { - "title": "Introduction to execution modes", - "url": "/docs/guides/execution-modes" - }, - { - "title": "Choose the right execution mode", - "url": "/docs/guides/choose-execution-mode" - }, - { - "title": "Run jobs in a batch", - "url": "/docs/guides/run-jobs-batch" - }, - { - "title": "Run jobs in a session", - "url": "/docs/guides/run-jobs-session" - }, - { - "title": "Execution modes using REST API", - "url": "/docs/guides/execution-modes-rest-api" - } - ] - }, - { - "title": "Manage jobs", - "children": [ - { - "title": "Monitor or cancel a job", - "url": "/docs/guides/monitor-job" - }, - { - "title": "Workload usage", - "url": "/docs/guides/estimate-job-run-time" - }, - { - "title": "Minimize job run time", - "url": "/docs/guides/minimize-time" - }, - { - "title": "Maximum execution time", - "url": "/docs/guides/max-execution-time" - }, - { - "title": "Job limits", - "url": "/docs/guides/job-limits" - }, - { - "title": "Organize and search by job tags", - "url": "/docs/guides/add-job-tags" - }, - { - "title": "Retrieve and save job results", - "url": "/docs/guides/save-jobs" - } - ] - }, - { - "title": "IBM quantum computers", - "children": [ - { - "title": "Processor types", - "url": "/docs/guides/processor-types" - }, - { - "title": "QPU information", - "url": "/docs/guides/qpu-information" - }, - { - "title": "Get backend information with Qiskit", - "url": "/docs/guides/get-qpu-information" - }, - { - "title": "Calibration jobs", - "url": "/docs/guides/calibration-jobs" - }, - { - "title": "Qubit initialization", - "url": "/docs/guides/repetition-rate-execution" - }, - { - "title": "Retired cloud QPUs", - "url": "/docs/guides/retired-qpus" - }, - { - "title": "Fair-share scheduler", - "url": "/docs/guides/fair-share-scheduler" - }, - { - "title": "View cost", - "url": "/docs/guides/view-cost" - } - ] - }, - { - "title": "High-performance compute", - "children": [ - { - "title": "Quantum resource management interface (QRMI)", - "url": "/docs/guides/qrmi", - "isNew": true - }, - { - "title": "SPANK plugin for QRMI", - "url": "/docs/guides/slurm-plugin", - "isNew": true - }, - { - "title": "SPANK plugin user guide", - "url": "/docs/guides/slurm-hpc-ux", - "isNew": true - } - ] - }, - { - "title": "Visualization", - "children": [ - { - "title": "Visualize circuits", - "url": "/docs/guides/visualize-circuits" - }, - { - "title": "Visualize circuit timing", - "url": "/docs/guides/visualize-circuit-timing", - "isNew": true, - "isNewDate": "2025-11-20" - }, - { - "title": "Plot quantum states", - "url": "/docs/guides/plot-quantum-states" - }, - { - "title": "Visualize results", - "url": "/docs/guides/visualize-results" - }, - { - "title": "IBM Quantum Composer", - "url": "/docs/guides/composer" - } - ] - }, - { - "title": "Qiskit Serverless", - "children": [ - { - "title": "Qiskit Serverless overview", - "url": "/docs/guides/serverless" - }, - { - "title": "Write your first Qiskit Serverless program", - "url": "/docs/guides/serverless-first-program" - }, - { - "title": "Run your first Qiskit Serverless workload remotely", - "url": "/docs/guides/serverless-run-first-workload" - }, - { - "title": "Manage Qiskit Serverless compute and data resources", - "url": "/docs/guides/serverless-manage-resources" - }, - { - "title": "Port code to Qiskit Serverless", - "url": "/docs/guides/serverless-port-code" - } - ] - }, - { - "title": "Qiskit addons", - "children": [ - { - "title": "Qiskit addons overview", - "url": "/docs/guides/addons" - }, - { - "title": "Qiskit addon utilities", - "url": "/docs/guides/qiskit-addons-utils" - }, - { - "title": "Sample-based quantum diagonalization (SQD)", - "children": [ - { - "title": "SQD addon overview", - "url": "/docs/guides/qiskit-addons-sqd" - }, - { - "title": "Get started with SQD", - "url": "/docs/guides/qiskit-addons-sqd-get-started" - } - ] - }, - { - "title": "Approximate quantum compilation (AQC-Tensor)", - "children": [ - { - "title": "AQC-Tensor addon overview", - "url": "/docs/guides/qiskit-addons-aqc" - }, - { - "title": "Get started with AQC-Tensor", - "url": "/docs/guides/qiskit-addons-aqc-get-started" - } - ] - }, - { - "title": "Operator backpropagation (OBP)", - "children": [ - { - "title": "OBP addon overview", - "url": "/docs/guides/qiskit-addons-obp" + "title": "QPU Access", + "children": [ + { + "title": "Execute on hardware", + "children": [ + { + "title": "Qiskit Runtime Primitives", + "children": [ + { + "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": "Qiskit Runtime local testing mode", + "url": "/docs/guides/local-testing-mode" + } + ] + } + ] }, { - "title": "Get started with OBP", - "url": "/docs/guides/qiskit-addons-obp-get-started" - } - ] - }, - { - "title": "Multi-product formulas (MPF)", - "children": [ - { - "title": "MPF addon overview", - "url": "/docs/guides/qiskit-addons-mpf" + "title": "IBM quantum computers", + "children": [ + { + "title": "Processor types", + "url": "/docs/guides/processor-types" + }, + { + "title": "QPU information", + "url": "/docs/guides/qpu-information" + }, + { + "title": "Get backend information with Qiskit", + "url": "/docs/guides/get-qpu-information" + }, + { + "title": "Calibration jobs", + "url": "/docs/guides/calibration-jobs" + }, + { + "title": "Qubit initialization", + "url": "/docs/guides/repetition-rate-execution" + }, + { + "title": "Retired cloud QPUs", + "url": "/docs/guides/retired-qpus" + }, + { + "title": "Fair-share scheduler", + "url": "/docs/guides/fair-share-scheduler" + }, + { + "title": "View cost", + "url": "/docs/guides/view-cost" + } + ] }, { - "title": "Get started with MPFs", - "url": "/docs/guides/qiskit-addons-mpf-get-started" - } - ] - }, - { - "title": "Circuit cutting (CC)", - "children": [ - { - "title": "Circuit cutting overview", - "url": "/docs/guides/qiskit-addons-cutting" + "title": "Manage noise", + "children": [ + { + "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": "Get started with gate cuts", - "url": "/docs/guides/qiskit-addons-cutting-gates" + "title": "Manage workload execution", + "children": [ + { + "title": "Monitor or cancel a job", + "url": "/docs/guides/monitor-job" + }, + { + "title": "Workload usage", + "url": "/docs/guides/estimate-job-run-time" + }, + { + "title": "Minimize job run time", + "url": "/docs/guides/minimize-time" + }, + { + "title": "Maximum execution time", + "url": "/docs/guides/max-execution-time" + }, + { + "title": "Job limits", + "url": "/docs/guides/job-limits" + }, + { + "title": "Organize and search by job tags", + "url": "/docs/guides/add-job-tags" + }, + { + "title": "Retrieve and save job results", + "url": "/docs/guides/save-jobs" + } + ] }, { - "title": "Get started with wire cuts", - "url": "/docs/guides/qiskit-addons-cutting-wires" - } - ] - } - ] - }, - { - "title": "Qiskit Code Assistant", - "children": [ - { - "title": "Qiskit Code Assistant overview", - "url": "/docs/guides/qiskit-code-assistant" - }, - { - "title": "Use Qiskit Code Assistant in JupyterLab", - "url": "/docs/guides/qiskit-code-assistant-jupyterlab" - }, - { - "title": "Use Qiskit Code Assistant in VS Code", - "url": "/docs/guides/qiskit-code-assistant-vscode" - }, - { - "title": "Use Qiskit Code Assistant in local mode", - "url": "/docs/guides/qiskit-code-assistant-local" - }, - { - "title": "Qiskit Code Assistant - OpenAI API compatibility", - "url": "/docs/guides/qiskit-code-assistant-openai-api" - } - ] - }, - { - "title": "Qiskit MCP Servers", - "url": "/docs/guides/qiskit-mcp-servers" - } - ], - "collapsible": false - }, - { - "title": "Additional resources", - "collapsible": false, - "children": [ - { - "title": "Support and FAQ", - "children": [ - { - "title": "Support", - "url": "/docs/guides/support" - }, - { - "title": "Frequently-asked questions", - "url": "/docs/guides/faq" - }, - { - "title": "Execution modes FAQ", - "url": "/docs/guides/execution-modes-faq" - } - ] - }, - { - "title": "Migration guides", - "children": [ - { - "title": "Migrate to Qiskit 2.0", - "children": [ - { - "title": "Qiskit v2.0 migration guide", - "url": "/docs/guides/qiskit-2.0" + "title": "Execution modes", + "children": [ + { + "title": "Introduction to execution modes", + "url": "/docs/guides/execution-modes" + }, + { + "title": "Choose the right execution mode", + "url": "/docs/guides/choose-execution-mode" + }, + { + "title": "Run jobs in a batch", + "url": "/docs/guides/run-jobs-batch" + }, + { + "title": "Run jobs in a session", + "url": "/docs/guides/run-jobs-session" + }, + { + "title": "Execution modes using REST API", + "url": "/docs/guides/execution-modes-rest-api" + } + ] }, { - "title": "Migrate from BackendV1 to BackendV2", - "url": "/docs/guides/qiskit-backendv1-to-v2" - } - ] - }, - { - "title": "Migrate to Qiskit 1.0", - "children": [ - { - "title": "Introduction", - "url": "/docs/guides/qiskit-1.0" + "title": "IBM Quantum Platform", + "children": [ + { + "title": "Set up IBM Quantum Platform", + "children": [ + { + "title": "Set up your IBM Cloud account", + "url": "/docs/guides/cloud-setup" + }, + { + "title": "Set up your IBM Cloud account - invited users", + "url": "/docs/guides/cloud-setup-invited", + "platform": "cloud" + }, + { + "title": "Set up your IBM Cloud account in an untrusted environment", + "url": "/docs/guides/cloud-setup-untrusted", + "platform": "cloud" + }, + { + "title": "Set up to use IBM Quantum Platform with REST API", + "url": "/docs/guides/cloud-setup-rest-api", + "platform": "cloud" + }, + { + "title": "Save your login credentials", + "url": "/docs/guides/save-credentials", + "platform": "cloud" + }, + { + "title": "Initialize your Qiskit Runtime service account", + "url": "/docs/guides/initialize-account", + "platform": "cloud" + }, + { + "title": "Set up for an organization", + "children": [ + { + "title": "Setup considerations", + "url": "/docs/guides/considerations-set-up-runtime" + }, + { + "title": "Configure IBM Quantum Platform", + "url": "/docs/guides/quickstart-steps-org" + } + ] + } + ] + }, + { + "title": "IBM Quantum plans", + "children": [ + { + "title": "Overview of plans", + "url": "/docs/guides/plans-overview" + }, + { + "title": "Upgrade from the Open Plan", + "url": "/docs/guides/upgrade-from-open" + }, + { + "title": "Manage cost on the Pay-As-You-Go Plan", + "url": "/docs/guides/manage-cost" + } + ] + }, + { + "title": "Work with instances", + "children": [ + { + "title": "Create and manage instances", + "url": "/docs/guides/instances" + }, + { + "title": "Set allocation limits", + "url": "/docs/guides/allocation-limits" + }, + { + "title": "Use IBM Cloud Platform APIs to access instances", + "url": "/docs/guides/access-instances-platform-apis" + } + ] + }, + { + "title": "Accounts, access groups, and policies", + "children": [ + { + "title": "Cloud account structure", + "url": "/docs/guides/cloud-account-structure" + }, + { + "title": "Create access groups and policies", + "url": "/docs/guides/access-groups" + }, + { + "title": "Set up custom roles", + "url": "/docs/guides/custom-roles" + } + ] + }, + { + "title": "Manage users", + "children": [ + { + "title": "Invite users and manage access", + "url": "/docs/guides/invite-and-manage-users" + }, + { + "title": "Manage ID provider users", + "url": "/docs/guides/manage-appid" + }, + { + "title": "Manage IBM Cloud users", + "url": "/docs/guides/manage-cloud-users" + } + ] + }, + { + "title": "Logging", + "url": "/docs/guides/logging" + } + ] }, { - "title": "Understand the breaking package changes", - "url": "/docs/guides/metapackage-migration" + "title": "Circuit functions", + "children": [ + { + "title": "IBM Circuit function", + "url": "/docs/guides/ibm-circuit-function" + }, + { + "title": "Algorithmiq Tensor-network error mitigation", + "url": "/docs/guides/algorithmiq-tem" + }, + { + "title": "Q-CTRL Performance Management", + "url": "/docs/guides/q-ctrl-performance-management" + }, + { + "title": "Qedma QESEM", + "url": "/docs/guides/qedma-qesem" + } + ] }, { - "title": "Install the new package", - "url": "/docs/guides/qiskit-1.0-installation" + "title": "Qiskit Serverless", + "children": [ + { + "title": "Qiskit Serverless overview", + "url": "/docs/guides/serverless" + }, + { + "title": "Write your first Qiskit Serverless program", + "url": "/docs/guides/serverless-first-program" + }, + { + "title": "Run your first Qiskit Serverless workload remotely", + "url": "/docs/guides/serverless-run-first-workload" + }, + { + "title": "Manage Qiskit Serverless compute and data resources", + "url": "/docs/guides/serverless-manage-resources" + }, + { + "title": "Port code to Qiskit Serverless", + "url": "/docs/guides/serverless-port-code" + } + ] }, { - "title": "Feature changes", - "url": "/docs/guides/qiskit-1.0-features" + "title": "Qiskit Transpiler Service", + "children": [ + { + "title": "Transpile circuits remotely with the Qiskit Transpiler Service", + "url": "/docs/guides/qiskit-transpiler-service" + }, + { + "title": "AI transpiler passes", + "url": "/docs/guides/ai-transpiler-passes" + } + ] } - ] - }, - { - "title": "Migrate from Qiskit Pulse to fractional gates", - "url": "/docs/guides/pulse-migration" - }, - { - "title": "Migrate to the Qiskit Runtime V2 primitives", - "url": "/docs/guides/v2-primitives" - }, - { - "title": "Migrate to local simulators", - "url": "/docs/guides/local-simulators" - } - ] + ], + "collapsible": false }, { - "title": "Open-source resources", - "children": [ - { - "title": "Introduction", - "url": "/docs/guides/open-source" - }, - { - "title": "Code of conduct", - "url": "/docs/guides/code-of-conduct" - }, - { - "title": "Contributor license agreements", - "children": [ - { - "title": "Individual contributor", - "url": "/docs/open-source/qiskit-cla.pdf" + "title": "Tools for applications", + "children": [ + { + "title": "Multi-product formulas (MPF)", + "children": [ + { + "title": "MPF addon overview", + "url": "/docs/guides/qiskit-addons-mpf" + }, + { + "title": "Get started with MPFs", + "url": "/docs/guides/qiskit-addons-mpf-get-started" + } + ] }, { - "title": "Corporate contributor", - "url": "/docs/open-source/qiskit-corporate-cla.pdf" + "title": "Qiskit Functions", + "children": [ + { + "title": "Introduction to Qiskit Functions", + "url": "/docs/guides/functions" + }, + { + "title": "Application functions", + "children": [ + { + "title": "Kipu Quantum Iskay Quantum Optimizer", + "url": "/docs/guides/kipu-optimization" + }, + { + "title": "Multiverse Computing Singularity", + "url": "/docs/guides/multiverse-computing-singularity" + }, + { + "title": "Q-CTRL Optimization Solver", + "url": "/docs/guides/q-ctrl-optimization-solver" + }, + { + "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", + "url": "/docs/guides/global-data-quantum-optimizer" + }, + { + "title": "QUICK-PDE: A Qiskit Function by ColibriTD", + "url": "/docs/guides/colibritd-pde" + }, + { + "title": "Qunova Computing HI-VQE Chemistry", + "url": "/docs/guides/qunova-chemistry" + } + ] + }, + { + "title": "Qiskit Function templates", + "children": [ + { + "title": "Introduction to Qiskit Function templates", + "url": "/docs/guides/qiskit-function-templates" + }, + { + "title": "Template for chemistry simulation", + "url": "/docs/guides/function-template-chemistry-workflow" + }, + { + "title": "Template for Hamiltonian simulation", + "url": "/docs/guides/function-template-hamiltonian-simulation" + } + ] + } + ] } - ] - }, - { - "title": "Qiskit SDK", - "children": [ - { - "title": "Version strategy", - "url": "/docs/guides/qiskit-sdk-version-strategy" + ], + "collapsible": false + }, + { + "title": "Additional resources", + "collapsible": false, + "children": [ + { + "title": "Support and FAQ", + "children": [ + { + "title": "Support", + "url": "/docs/guides/support" + }, + { + "title": "Frequently-asked questions", + "url": "/docs/guides/faq" + }, + { + "title": "Execution modes FAQ", + "url": "/docs/guides/execution-modes-faq" + } + ] }, { - "title": "Create a provider", - "url": "/docs/guides/create-a-provider" + "title": "Migration guides", + "children": [ + { + "title": "Migrate to Qiskit 2.0", + "children": [ + { + "title": "Qiskit v2.0 migration guide", + "url": "/docs/guides/qiskit-2.0" + }, + { + "title": "Migrate from BackendV1 to BackendV2", + "url": "/docs/guides/qiskit-backendv1-to-v2" + } + ] + }, + { + "title": "Migrate to Qiskit 1.0", + "children": [ + { + "title": "Introduction", + "url": "/docs/guides/qiskit-1.0" + }, + { + "title": "Understand the breaking package changes", + "url": "/docs/guides/metapackage-migration" + }, + { + "title": "Install the new package", + "url": "/docs/guides/qiskit-1.0-installation" + }, + { + "title": "Feature changes", + "url": "/docs/guides/qiskit-1.0-features" + } + ] + }, + { + "title": "Migrate from Qiskit Pulse to fractional gates", + "url": "/docs/guides/pulse-migration" + }, + { + "title": "Migrate to the Qiskit Runtime V2 primitives", + "url": "/docs/guides/v2-primitives" + }, + { + "title": "Migrate to local simulators", + "url": "/docs/guides/local-simulators" + } + ] }, { - "title": "Contributor guide", - "url": "https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md" + "title": "Open-source resources", + "children": [ + { + "title": "Introduction", + "url": "/docs/guides/open-source" + }, + { + "title": "Code of conduct", + "url": "/docs/guides/code-of-conduct" + }, + { + "title": "Contributor license agreements", + "children": [ + { + "title": "Individual contributor", + "url": "/docs/open-source/qiskit-cla.pdf" + }, + { + "title": "Corporate contributor", + "url": "/docs/open-source/qiskit-corporate-cla.pdf" + } + ] + }, + { + "title": "Qiskit SDK", + "children": [ + { + "title": "Version strategy", + "url": "/docs/guides/qiskit-sdk-version-strategy" + }, + { + "title": "Create a provider", + "url": "/docs/guides/create-a-provider" + }, + { + "title": "Contributor guide", + "url": "https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md" + }, + { + "title": "Maintainer guide", + "url": "https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md" + } + ] + }, + { + "title": "Qiskit ecosystem", + "url": "https://www.ibm.com/quantum/ecosystem" + } + ] }, { - "title": "Maintainer guide", - "url": "https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md" + "title": "Security and compliance", + "collapsed": true, + "children": [ + { + "title": "Securing your data", + "url": "/docs/guides/secure-data" + }, + { + "title": "Understanding your responsibilities when using Qiskit Runtime", + "url": "/docs/guides/responsibilities" + }, + { + "title": "Use virtual private endpoints for VPC", + "url": "/docs/guides/virtual-private-endpoints" + }, + { + "title": "High availability and disaster recovery", + "url": "/docs/guides/ha-dr" + }, + { + "title": "Activity tracking events for Qiskit Runtime", + "url": "/docs/guides/observability" + }, + { + "title": "Protecting Qiskit Runtime Service resources with context-based restrictions", + "url": "/docs/guides/context-based-restrictions" + } + ] } - ] - }, - { - "title": "Qiskit ecosystem", - "url": "https://www.ibm.com/quantum/ecosystem" - } - ] - }, - { - "title": "Security and compliance", - "collapsed": true, - "children": [ - { - "title": "Securing your data", - "url": "/docs/guides/secure-data" - }, - { - "title": "Understanding your responsibilities when using Qiskit Runtime", - "url": "/docs/guides/responsibilities" - }, - { - "title": "Use virtual private endpoints for VPC", - "url": "/docs/guides/virtual-private-endpoints" - }, - - { - "title": "High availability and disaster recovery", - "url": "/docs/guides/ha-dr" - }, - { - "title": "Activity tracking events for Qiskit Runtime", - "url": "/docs/guides/observability" - }, - { - "title": "Protecting Qiskit Runtime Service resources with context-based restrictions", - "url": "/docs/guides/context-based-restrictions" - } - ] - } - ] - } - ] -} + ] + } + ] +} \ No newline at end of file diff --git a/docs/tutorials/hello-world.ipynb b/docs/guides/hello-world.ipynb similarity index 100% rename from docs/tutorials/hello-world.ipynb rename to docs/guides/hello-world.ipynb diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index fad84a9e378..719275143ad 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -159,7 +159,7 @@ notifications: "docs/guides/responsibilities": - "@abbycross" - "@beckykd" - "docs/tutorials/hello-world": + "docs/guides/hello-world": - "@abbycross" - "@beckykd" "docs/guides/allocation-limits": diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index f3b0f1c64c7..7bd449fc8b2 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -1,71 +1,72 @@ default-strategy = "ci" [test-strategies] -ci = { timeout = 300 } # For regular CI -extended = { timeout = 1000 } # Extended checks using test-eagle +ci = { timeout = 300 } # For regular CI +extended = { timeout = 1000 } # Extended checks using test-eagle # For notebooks to be tested in CI "normally" (no mocking) [groups.normal] test-strategies.ci = {} test-strategies.extended = {} -test-strategies.hardware = { patch="qiskit-ibm-runtime-open" } +test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "docs/guides/DAG-representation.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/construct-circuits.ipynb", - "docs/guides/create-transpiler-plugin.ipynb", - "docs/guides/custom-backend.ipynb", - "docs/guides/custom-transpiler-pass.ipynb", - "docs/guides/defaults-and-configuration-options.ipynb", - "docs/guides/dynamical-decoupling-pass-manager.ipynb", - "docs/guides/error-mitigation-and-suppression-techniques.ipynb", - "docs/guides/execution-modes-rest-api.ipynb", - "docs/guides/get-qpu-information.ipynb", - "docs/guides/interoperate-qiskit-qasm2.ipynb", - "docs/guides/interoperate-qiskit-qasm3.ipynb", - "docs/guides/local-testing-mode.ipynb", - "docs/guides/max-execution-time.ipynb", - "docs/guides/measure-qubits.ipynb", - "docs/guides/operator-class.ipynb", - "docs/guides/operators-overview.ipynb", - "docs/guides/plot-quantum-states.ipynb", - "docs/guides/primitives-rest-api.ipynb", - "docs/guides/qiskit-addons-aqc-get-started.ipynb", - "docs/guides/qiskit-addons-cutting-wires.ipynb", - "docs/guides/qiskit-addons-mpf-get-started.ipynb", - "docs/guides/qiskit-addons-mpf.ipynb", - "docs/guides/qiskit-addons-utils.ipynb", - "docs/guides/quick-start.ipynb", - "docs/guides/repetition-rate-execution.ipynb", - "docs/guides/represent-quantum-computers.ipynb", - "docs/guides/save-circuits.ipynb", - "docs/guides/save-jobs.ipynb", - "docs/guides/set-optimization.ipynb", - "docs/guides/simulate-stabilizer-circuits.ipynb", - "docs/guides/simulate-with-qiskit-aer.ipynb", - "docs/guides/simulate-with-qiskit-sdk-primitives.ipynb", - "docs/guides/specify-observables-pauli.ipynb", - "docs/guides/synthesize-unitary-operators.ipynb", - "docs/guides/transpile-with-pass-managers.ipynb", - "docs/guides/transpiler-plugins.ipynb", - "docs/guides/transpiler-stages.ipynb", - "docs/guides/visualize-circuits.ipynb", + "docs/guides/DAG-representation.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/construct-circuits.ipynb", + "docs/guides/create-transpiler-plugin.ipynb", + "docs/guides/custom-backend.ipynb", + "docs/guides/custom-transpiler-pass.ipynb", + "docs/guides/defaults-and-configuration-options.ipynb", + "docs/guides/dynamical-decoupling-pass-manager.ipynb", + "docs/guides/error-mitigation-and-suppression-techniques.ipynb", + "docs/guides/execution-modes-rest-api.ipynb", + "docs/guides/get-qpu-information.ipynb", + "docs/guides/interoperate-qiskit-qasm2.ipynb", + "docs/guides/interoperate-qiskit-qasm3.ipynb", + "docs/guides/local-testing-mode.ipynb", + "docs/guides/max-execution-time.ipynb", + "docs/guides/measure-qubits.ipynb", + "docs/guides/operator-class.ipynb", + "docs/guides/operators-overview.ipynb", + "docs/guides/plot-quantum-states.ipynb", + "docs/guides/primitives-rest-api.ipynb", + "docs/guides/qiskit-addons-aqc-get-started.ipynb", + "docs/guides/qiskit-addons-cutting-wires.ipynb", + "docs/guides/qiskit-addons-mpf-get-started.ipynb", + "docs/guides/qiskit-addons-mpf.ipynb", + "docs/guides/qiskit-addons-utils.ipynb", + "docs/guides/quick-start.ipynb", + "docs/guides/repetition-rate-execution.ipynb", + "docs/guides/represent-quantum-computers.ipynb", + "docs/guides/save-circuits.ipynb", + "docs/guides/save-jobs.ipynb", + "docs/guides/set-optimization.ipynb", + "docs/guides/simulate-stabilizer-circuits.ipynb", + "docs/guides/simulate-with-qiskit-aer.ipynb", + "docs/guides/simulate-with-qiskit-sdk-primitives.ipynb", + "docs/guides/specify-observables-pauli.ipynb", + "docs/guides/synthesize-unitary-operators.ipynb", + "docs/guides/transpile-with-pass-managers.ipynb", + "docs/guides/transpiler-plugins.ipynb", + "docs/guides/transpiler-stages.ipynb", + "docs/guides/visualize-circuits.ipynb", ] # Mock the following notebooks using a 6-qubit local simulator [groups.local-sim] -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" } +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", + "docs/guides/specify-runtime-options.ipynb", + "docs/guides/visualize-results.ipynb", + "docs/guides/hello-world.ipynb", ] # Mock the following notebooks in our extended checks using IBM Quantum's @@ -73,271 +74,271 @@ notebooks = [ # that submit large jobs to test notebooks that use functions, which accept # only a backend name (string) rather than a `Backend` object. [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" } +test-strategies.extended = { patch = "qiskit-ibm-runtime", backend = "test_eagle_us-east", qiskit_runtime_service_args = "" } +test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "docs/guides/algorithmiq-tem.ipynb", - "docs/guides/debug-qiskit-runtime-jobs.ipynb", - "docs/guides/fractional-gates.ipynb", - "docs/guides/functions.ipynb", - "docs/guides/get-started-with-primitives.ipynb", - "docs/guides/ibm-circuit-function.ipynb", - "docs/guides/primitives-examples.ipynb", - "docs/guides/qiskit-addons-obp-get-started.ipynb", - "docs/guides/qiskit-addons-sqd-get-started.ipynb", - "docs/guides/multiverse-computing-singularity.ipynb", - "docs/guides/qunova-chemistry.ipynb", - "docs/guides/ai-transpiler-passes.ipynb", - "docs/guides/primitives.ipynb", - "docs/guides/run-jobs-batch.ipynb", - "docs/guides/run-jobs-session.ipynb", - "docs/guides/primitive-input-output.ipynb", - "docs/guides/add-job-tags.ipynb", - "docs/guides/visualize-circuit-timing.ipynb", + "docs/guides/algorithmiq-tem.ipynb", + "docs/guides/debug-qiskit-runtime-jobs.ipynb", + "docs/guides/fractional-gates.ipynb", + "docs/guides/functions.ipynb", + "docs/guides/get-started-with-primitives.ipynb", + "docs/guides/ibm-circuit-function.ipynb", + "docs/guides/primitives-examples.ipynb", + "docs/guides/qiskit-addons-obp-get-started.ipynb", + "docs/guides/qiskit-addons-sqd-get-started.ipynb", + "docs/guides/multiverse-computing-singularity.ipynb", + "docs/guides/qunova-chemistry.ipynb", + "docs/guides/ai-transpiler-passes.ipynb", + "docs/guides/primitives.ipynb", + "docs/guides/run-jobs-batch.ipynb", + "docs/guides/run-jobs-session.ipynb", + "docs/guides/primitive-input-output.ipynb", + "docs/guides/add-job-tags.ipynb", + "docs/guides/visualize-circuit-timing.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" } +test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "docs/tutorials/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 - "docs/guides/qiskit-addons-cutting-gates.ipynb", + "docs/tutorials/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 + "docs/guides/qiskit-addons-cutting-gates.ipynb", - # 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 - # confirm on actual 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 + # confirm on actual hardware. - # This timed out for me, even though I saw the job finish. Maybe it needs - # longer? Running in cron job to remove time limit. - "docs/guides/noise-learning.ipynb", + # This timed out for me, even though I saw the job finish. Maybe it needs + # longer? Running in cron job to remove time limit. + "docs/guides/noise-learning.ipynb", - # This timed out with no jobs submitted. Adding to the cron to see if it - # needs longer. - "docs/guides/qedma-qesem.ipynb", + # This timed out with no jobs submitted. Adding to the cron to see if it + # needs longer. + "docs/guides/qedma-qesem.ipynb", - # Got: `QiskitServerlessException: "Q-CTRL: Failed to execute Qiskit - # Function. Failed to compile the circuit. - # compiler_exceptions=[TranspilerError('More virtual qubits - # exist than physical.')]"` - "docs/guides/q-ctrl-optimization-solver.ipynb", + # Got: `QiskitServerlessException: "Q-CTRL: Failed to execute Qiskit + # Function. Failed to compile the circuit. + # compiler_exceptions=[TranspilerError('More virtual qubits + # exist than physical.')]"` + "docs/guides/q-ctrl-optimization-solver.ipynb", - # Got: `QiskitServerlessException: "Q-CTRL: Failed to execute Qiskit - # Function. could not broadcast input array from shape (3996,5) into - # shape (4000,5)"` - # Timed out when I re-ran it. - "docs/guides/q-ctrl-performance-management.ipynb", + # Got: `QiskitServerlessException: "Q-CTRL: Failed to execute Qiskit + # Function. could not broadcast input array from shape (3996,5) into + # shape (4000,5)"` + # Timed out when I re-ran it. + "docs/guides/q-ctrl-performance-management.ipynb", ] # Don't ever test the following notebooks [groups.exclude] notebooks = [ - # This notebook contains undefined variables so can't run at all. - "docs/guides/function-template-hamiltonian-simulation.ipynb", - "docs/guides/function-template-chemistry-workflow.ipynb", + # This notebook contains undefined variables so can't run at all. + "docs/guides/function-template-hamiltonian-simulation.ipynb", + "docs/guides/function-template-chemistry-workflow.ipynb", - # Only works in runtime 0.41.1 - "docs/guides/monitor-job.ipynb", + # Only works in runtime 0.41.1 + "docs/guides/monitor-job.ipynb", - # These notebooks are failing with auth errors and need investigating - "docs/guides/serverless-first-program.ipynb", - "docs/guides/serverless-run-first-workload.ipynb", - "docs/guides/serverless-manage-resources.ipynb", + # These notebooks are failing with auth errors and need investigating + "docs/guides/serverless-first-program.ipynb", + "docs/guides/serverless-run-first-workload.ipynb", + "docs/guides/serverless-manage-resources.ipynb", - # This notebook might work but we didn't have time to test it before merging - "docs/guides/kipu-optimization.ipynb", - "docs/guides/global-data-quantum-optimizer.ipynb", - "docs/guides/colibritd-pde.ipynb", + # This notebook might work but we didn't have time to test it before merging + "docs/guides/kipu-optimization.ipynb", + "docs/guides/global-data-quantum-optimizer.ipynb", + "docs/guides/colibritd-pde.ipynb", - # These notebooks have code snippets which are embedded in cloud/legacy tags - # and can't be run until we convert them to testable snippets - "docs/guides/retired-qpus.ipynb", - "docs/guides/estimate-job-run-time.ipynb", - "docs/guides/serverless-port-code.ipynb", + # These notebooks have code snippets which are embedded in cloud/legacy tags + # and can't be run until we convert them to testable snippets + "docs/guides/retired-qpus.ipynb", + "docs/guides/estimate-job-run-time.ipynb", + "docs/guides/serverless-port-code.ipynb", - # This is temporarily broken while the transpiler service migrates to cloud - "docs/guides/qiskit-transpiler-service.ipynb", + # This is temporarily broken while the transpiler service migrates to cloud + "docs/guides/qiskit-transpiler-service.ipynb", - # We never run tutorials notebooks - "docs/tutorials/ghz-spacetime-codes.ipynb", - "docs/tutorials/sml-classification.ipynb", - "docs/tutorials/qedma-2d-ising-with-qesem.ipynb", - "docs/tutorials/readout-error-mitigation-sampler.ipynb", - "docs/tutorials/quantum-phase-estimation-qctrl.ipynb", - "docs/tutorials/transverse-field-ising-model.ipynb", - "docs/tutorials/fractional-gates.ipynb", - "docs/tutorials/shors-algorithm.ipynb", - "docs/tutorials/multi-product-formula.ipynb", - "docs/tutorials/advanced-techniques-for-qaoa.ipynb", - "docs/tutorials/ai-transpiler-introduction.ipynb", - "docs/tutorials/circuit-transpilation-settings.ipynb", - "docs/tutorials/grovers-algorithm.ipynb", - "docs/tutorials/spin-chain-vqe.ipynb", - "docs/tutorials/quantum-approximate-optimization-algorithm.ipynb", - "docs/tutorials/quantum-kernel-training.ipynb", - "docs/tutorials/projected-quantum-kernels.ipynb", - "docs/tutorials/transpilation-optimizations-with-sabre.ipynb", - "docs/tutorials/qunova-hivqe.ipynb", - "docs/tutorials/real-time-benchmarking-for-qubit-selection.ipynb", - "docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb", - "docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver.ipynb", - "docs/tutorials/chsh-inequality.ipynb", - "docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb", - "docs/tutorials/combine-error-mitigation-techniques.ipynb", - "docs/tutorials/periodic-boundary-conditions-with-circuit-cutting.ipynb", - "docs/tutorials/repetition-codes.ipynb", - "docs/tutorials/error-mitigation-with-qiskit-functions.ipynb", - "docs/tutorials/operator-back-propagation.ipynb", - "docs/tutorials/depth-reduction-with-circuit-cutting.ipynb", - "docs/tutorials/long-range-entanglement.ipynb", - "docs/tutorials/wire-cutting.ipynb", - "docs/tutorials/krylov-quantum-diagonalization.ipynb", - "docs/tutorials/probabilistic-error-amplification.ipynb", - "docs/tutorials/sample-based-quantum-diagonalization.ipynb", - "docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb", - "docs/tutorials/nishimori-phase-transition.ipynb", - "docs/tutorials/global-data-quantum-optimizer.ipynb", - "docs/tutorials/colibritd-pde.ipynb", - "docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb", - "docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb", - "docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer.ipynb", + # We never run tutorials notebooks + "docs/tutorials/ghz-spacetime-codes.ipynb", + "docs/tutorials/sml-classification.ipynb", + "docs/tutorials/qedma-2d-ising-with-qesem.ipynb", + "docs/tutorials/readout-error-mitigation-sampler.ipynb", + "docs/tutorials/quantum-phase-estimation-qctrl.ipynb", + "docs/tutorials/transverse-field-ising-model.ipynb", + "docs/tutorials/fractional-gates.ipynb", + "docs/tutorials/shors-algorithm.ipynb", + "docs/tutorials/multi-product-formula.ipynb", + "docs/tutorials/advanced-techniques-for-qaoa.ipynb", + "docs/tutorials/ai-transpiler-introduction.ipynb", + "docs/tutorials/circuit-transpilation-settings.ipynb", + "docs/tutorials/grovers-algorithm.ipynb", + "docs/tutorials/spin-chain-vqe.ipynb", + "docs/tutorials/quantum-approximate-optimization-algorithm.ipynb", + "docs/tutorials/quantum-kernel-training.ipynb", + "docs/tutorials/projected-quantum-kernels.ipynb", + "docs/tutorials/transpilation-optimizations-with-sabre.ipynb", + "docs/tutorials/qunova-hivqe.ipynb", + "docs/tutorials/real-time-benchmarking-for-qubit-selection.ipynb", + "docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb", + "docs/tutorials/solve-higher-order-binary-optimization-problems-with-q-ctrls-optimization-solver.ipynb", + "docs/tutorials/chsh-inequality.ipynb", + "docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb", + "docs/tutorials/combine-error-mitigation-techniques.ipynb", + "docs/tutorials/periodic-boundary-conditions-with-circuit-cutting.ipynb", + "docs/tutorials/repetition-codes.ipynb", + "docs/tutorials/error-mitigation-with-qiskit-functions.ipynb", + "docs/tutorials/operator-back-propagation.ipynb", + "docs/tutorials/depth-reduction-with-circuit-cutting.ipynb", + "docs/tutorials/long-range-entanglement.ipynb", + "docs/tutorials/wire-cutting.ipynb", + "docs/tutorials/krylov-quantum-diagonalization.ipynb", + "docs/tutorials/probabilistic-error-amplification.ipynb", + "docs/tutorials/sample-based-quantum-diagonalization.ipynb", + "docs/tutorials/pauli-correlation-encoding-for-qaoa.ipynb", + "docs/tutorials/nishimori-phase-transition.ipynb", + "docs/tutorials/global-data-quantum-optimizer.ipynb", + "docs/tutorials/colibritd-pde.ipynb", + "docs/tutorials/edc-cut-bell-pair-benchmarking.ipynb", + "docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb", + "docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer.ipynb", - # Don't test any learning notebooks - "learning/courses/quantum-computing-in-practice/introduction.ipynb", - "learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb", - "learning/courses/quantum-computing-in-practice/mapping.ipynb", - "learning/courses/quantum-computing-in-practice/applications-of-qc.ipynb", - "learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb", - "learning/courses/quantum-computing-in-practice/simulating-nature.ipynb", - "learning/courses/quantum-diagonalization-algorithms/sqd-overview.ipynb", - "learning/courses/quantum-diagonalization-algorithms/skqd.ipynb", - "learning/courses/quantum-diagonalization-algorithms/krylov.ipynb", - "learning/courses/quantum-diagonalization-algorithms/sqd-implementation.ipynb", - "learning/courses/quantum-diagonalization-algorithms/introduction.ipynb", - "learning/courses/quantum-diagonalization-algorithms/vqe.ipynb", - "learning/courses/quantum-machine-learning/classical-ml-review.ipynb", - "learning/courses/quantum-machine-learning/data-encoding.ipynb", - "learning/courses/quantum-machine-learning/introduction.ipynb", - "learning/courses/quantum-machine-learning/quantum-kernel-methods.ipynb", - "learning/courses/quantum-machine-learning/qvc-qnn.ipynb", - "learning/courses/basics-of-quantum-information/single-systems/introduction.ipynb", - "learning/courses/basics-of-quantum-information/single-systems/classical-information.ipynb", - "learning/courses/basics-of-quantum-information/single-systems/quantum-information.ipynb", - "learning/courses/basics-of-quantum-information/single-systems/qiskit-implementation.ipynb", - "learning/courses/basics-of-quantum-information/multiple-systems/introduction.ipynb", - "learning/courses/basics-of-quantum-information/multiple-systems/classical-information.ipynb", - "learning/courses/basics-of-quantum-information/multiple-systems/quantum-information.ipynb", - "learning/courses/basics-of-quantum-information/multiple-systems/qiskit-implementation.ipynb", - "learning/courses/basics-of-quantum-information/quantum-circuits/introduction.ipynb", - "learning/courses/basics-of-quantum-information/quantum-circuits/circuits.ipynb", - "learning/courses/basics-of-quantum-information/quantum-circuits/inner-products-and-projections.ipynb", - "learning/courses/basics-of-quantum-information/quantum-circuits/limitations-on-quantum-information.ipynb", - "learning/courses/basics-of-quantum-information/entanglement-in-action/introduction.ipynb", - "learning/courses/basics-of-quantum-information/entanglement-in-action/quantum-teleportation.ipynb", - "learning/courses/basics-of-quantum-information/entanglement-in-action/superdense-coding.ipynb", - "learning/courses/basics-of-quantum-information/entanglement-in-action/chsh-game.ipynb", - "learning/courses/basics-of-quantum-information/entanglement-in-action/qiskit-implementation.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/introduction.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/query-model-of-computation.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/deutsch-algorithm.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/deutsch-jozsa-algorithm.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/simon-algorithm.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/introduction.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/factoring-and-gcd.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/measuring-computational-cost.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/simulating-classical-computations.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/introduction.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/phase-estimation-problem.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/phase-estimation-procedure.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/shor-algorithm.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/introduction.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/unstructured-search.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/grover-algorithm-description.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/analysis.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/number-of-iterations.ipynb", - "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/concluding-remarks.ipynb", - "learning/courses/general-formulation-of-quantum-information/density-matrices/introduction.ipynb", - "learning/courses/general-formulation-of-quantum-information/density-matrices/density-matrix-basics.ipynb", - "learning/courses/general-formulation-of-quantum-information/density-matrices/convex-combinations.ipynb", - "learning/courses/general-formulation-of-quantum-information/density-matrices/bloch-sphere.ipynb", - "learning/courses/general-formulation-of-quantum-information/density-matrices/multiple-systems.ipynb", - "learning/courses/general-formulation-of-quantum-information/quantum-channels/introduction.ipynb", - "learning/courses/general-formulation-of-quantum-information/quantum-channels/quantum-channel-basics.ipynb", - "learning/courses/general-formulation-of-quantum-information/quantum-channels/representations-of-channels.ipynb", - "learning/courses/general-formulation-of-quantum-information/quantum-channels/representation-equivalence.ipynb", - "learning/courses/general-formulation-of-quantum-information/general-measurements/introduction.ipynb", - "learning/courses/general-formulation-of-quantum-information/general-measurements/formulations-of-measurements.ipynb", - "learning/courses/general-formulation-of-quantum-information/general-measurements/naimark-theorem.ipynb", - "learning/courses/general-formulation-of-quantum-information/general-measurements/discrimination-and-tomography.ipynb", - "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/introduction.ipynb", - "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/purifications.ipynb", - "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/fidelity.ipynb", - "learning/courses/general-formulation-of-quantum-information/exam.ipynb", - "learning/courses/quantum-business-foundations/start-your-quantum-journey.ipynb", - "learning/courses/quantum-business-foundations/introduction-to-quantum-computing.ipynb", - "learning/courses/quantum-business-foundations/quantum-technology.ipynb", - "learning/courses/quantum-business-foundations/business-impacts.ipynb", - "learning/courses/quantum-business-foundations/exam.ipynb", - "learning/courses/quantum-business-foundations/how-to-become-quantum-ready.ipynb", - "learning/courses/quantum-business-foundations/quantum-computing-fundamentals.ipynb", - "learning/modules/computer-science/deutsch-jozsa.ipynb", - "learning/modules/computer-science/vqe.ipynb", - "learning/modules/computer-science/grovers.ipynb", - "learning/modules/computer-science/quantum-key-distribution.ipynb", - "learning/modules/computer-science/quantum-teleportation.ipynb", - "learning/modules/computer-science/shors-algorithm.ipynb", - "learning/modules/computer-science/qft.ipynb", - "learning/modules/quantum-mechanics/superposition-with-qiskit.ipynb", - "learning/modules/quantum-mechanics/stern-gerlach-measurements-with-qiskit.ipynb", - "learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb", - "learning/modules/quantum-mechanics/bells-inequality-with-qiskit.ipynb", - "learning/modules/quantum-mechanics/get-started-with-qiskit.ipynb", - "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/introduction.ipynb", - "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/repetition-codes.ipynb", - "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/shor-code.ipynb", - "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/discretization-of-errors.ipynb", - "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/introduction.ipynb", - "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/pauli-operations-and-observables.ipynb", - "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/repetition-code-revisited.ipynb", - "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/stabilizer-codes.ipynb", - "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/introduction.ipynb", - "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/css-codes.ipynb", - "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/toric-code.ipynb", - "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/other-code-families.ipynb", - "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/introduction.ipynb", - "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/approach-to-fault-tolerance.ipynb", - "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/controlling-error-propagation.ipynb", - "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/threshold-theorem.ipynb", - "learning/courses/quantum-safe-cryptography/cryptographic-hash-functions.ipynb", - "learning/courses/quantum-safe-cryptography/quantum-safe-cryptography.ipynb", - "learning/courses/quantum-safe-cryptography/symmetric-key-cryptography.ipynb", - "learning/courses/quantum-safe-cryptography/WhatNext.ipynb", - "learning/courses/quantum-safe-cryptography/asymmetric-key-cryptography.ipynb", - "learning/courses/quantum-chem-with-vqe/introduction.ipynb", - "learning/courses/quantum-chem-with-vqe/hamiltonian-construction.ipynb", - "learning/courses/quantum-chem-with-vqe/ansatz.ipynb", - "learning/courses/quantum-chem-with-vqe/classical-optimizers.ipynb", - "learning/courses/quantum-chem-with-vqe/ground-state.ipynb", - "learning/courses/quantum-chem-with-vqe/geometry.ipynb", - "learning/courses/variational-algorithm-design/variational-algorithms.ipynb", - "learning/courses/variational-algorithm-design/reference-states.ipynb", - "learning/courses/variational-algorithm-design/ansaetze-and-variational-forms.ipynb", - "learning/courses/variational-algorithm-design/cost-functions.ipynb", - "learning/courses/variational-algorithm-design/optimization-loops.ipynb", - "learning/courses/variational-algorithm-design/examples-and-applications.ipynb", - "learning/courses/variational-algorithm-design/instances-and-extensions.ipynb", - "learning/courses/utility-scale-quantum-computing/utility-ii.ipynb", - "learning/courses/utility-scale-quantum-computing/quantum-simulation.ipynb", - "learning/courses/utility-scale-quantum-computing/bits-gates-and-circuits.ipynb", - "learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb", - "learning/courses/utility-scale-quantum-computing/quantum-phase-estimation.ipynb", - "learning/courses/utility-scale-quantum-computing/utility-iii.ipynb", - "learning/courses/utility-scale-quantum-computing/teleportation.ipynb", - "learning/courses/utility-scale-quantum-computing/utility-i.ipynb", - "learning/courses/utility-scale-quantum-computing/introduction.ipynb", - "learning/courses/utility-scale-quantum-computing/hardware.ipynb", - "learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb", - "learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb", - "learning/courses/utility-scale-quantum-computing/grovers-algorithm.ipynb", + # Don't test any learning notebooks + "learning/courses/quantum-computing-in-practice/introduction.ipynb", + "learning/courses/quantum-computing-in-practice/running-quantum-circuits.ipynb", + "learning/courses/quantum-computing-in-practice/mapping.ipynb", + "learning/courses/quantum-computing-in-practice/applications-of-qc.ipynb", + "learning/courses/quantum-computing-in-practice/utility-scale-qaoa.ipynb", + "learning/courses/quantum-computing-in-practice/simulating-nature.ipynb", + "learning/courses/quantum-diagonalization-algorithms/sqd-overview.ipynb", + "learning/courses/quantum-diagonalization-algorithms/skqd.ipynb", + "learning/courses/quantum-diagonalization-algorithms/krylov.ipynb", + "learning/courses/quantum-diagonalization-algorithms/sqd-implementation.ipynb", + "learning/courses/quantum-diagonalization-algorithms/introduction.ipynb", + "learning/courses/quantum-diagonalization-algorithms/vqe.ipynb", + "learning/courses/quantum-machine-learning/classical-ml-review.ipynb", + "learning/courses/quantum-machine-learning/data-encoding.ipynb", + "learning/courses/quantum-machine-learning/introduction.ipynb", + "learning/courses/quantum-machine-learning/quantum-kernel-methods.ipynb", + "learning/courses/quantum-machine-learning/qvc-qnn.ipynb", + "learning/courses/basics-of-quantum-information/single-systems/introduction.ipynb", + "learning/courses/basics-of-quantum-information/single-systems/classical-information.ipynb", + "learning/courses/basics-of-quantum-information/single-systems/quantum-information.ipynb", + "learning/courses/basics-of-quantum-information/single-systems/qiskit-implementation.ipynb", + "learning/courses/basics-of-quantum-information/multiple-systems/introduction.ipynb", + "learning/courses/basics-of-quantum-information/multiple-systems/classical-information.ipynb", + "learning/courses/basics-of-quantum-information/multiple-systems/quantum-information.ipynb", + "learning/courses/basics-of-quantum-information/multiple-systems/qiskit-implementation.ipynb", + "learning/courses/basics-of-quantum-information/quantum-circuits/introduction.ipynb", + "learning/courses/basics-of-quantum-information/quantum-circuits/circuits.ipynb", + "learning/courses/basics-of-quantum-information/quantum-circuits/inner-products-and-projections.ipynb", + "learning/courses/basics-of-quantum-information/quantum-circuits/limitations-on-quantum-information.ipynb", + "learning/courses/basics-of-quantum-information/entanglement-in-action/introduction.ipynb", + "learning/courses/basics-of-quantum-information/entanglement-in-action/quantum-teleportation.ipynb", + "learning/courses/basics-of-quantum-information/entanglement-in-action/superdense-coding.ipynb", + "learning/courses/basics-of-quantum-information/entanglement-in-action/chsh-game.ipynb", + "learning/courses/basics-of-quantum-information/entanglement-in-action/qiskit-implementation.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/introduction.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/query-model-of-computation.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/deutsch-algorithm.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/deutsch-jozsa-algorithm.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-query-algorithms/simon-algorithm.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/introduction.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/factoring-and-gcd.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/measuring-computational-cost.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/quantum-algorithmic-foundations/simulating-classical-computations.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/introduction.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/phase-estimation-problem.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/phase-estimation-procedure.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/phase-estimation-and-factoring/shor-algorithm.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/introduction.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/unstructured-search.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/grover-algorithm-description.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/analysis.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/number-of-iterations.ipynb", + "learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/concluding-remarks.ipynb", + "learning/courses/general-formulation-of-quantum-information/density-matrices/introduction.ipynb", + "learning/courses/general-formulation-of-quantum-information/density-matrices/density-matrix-basics.ipynb", + "learning/courses/general-formulation-of-quantum-information/density-matrices/convex-combinations.ipynb", + "learning/courses/general-formulation-of-quantum-information/density-matrices/bloch-sphere.ipynb", + "learning/courses/general-formulation-of-quantum-information/density-matrices/multiple-systems.ipynb", + "learning/courses/general-formulation-of-quantum-information/quantum-channels/introduction.ipynb", + "learning/courses/general-formulation-of-quantum-information/quantum-channels/quantum-channel-basics.ipynb", + "learning/courses/general-formulation-of-quantum-information/quantum-channels/representations-of-channels.ipynb", + "learning/courses/general-formulation-of-quantum-information/quantum-channels/representation-equivalence.ipynb", + "learning/courses/general-formulation-of-quantum-information/general-measurements/introduction.ipynb", + "learning/courses/general-formulation-of-quantum-information/general-measurements/formulations-of-measurements.ipynb", + "learning/courses/general-formulation-of-quantum-information/general-measurements/naimark-theorem.ipynb", + "learning/courses/general-formulation-of-quantum-information/general-measurements/discrimination-and-tomography.ipynb", + "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/introduction.ipynb", + "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/purifications.ipynb", + "learning/courses/general-formulation-of-quantum-information/purifications-and-fidelity/fidelity.ipynb", + "learning/courses/general-formulation-of-quantum-information/exam.ipynb", + "learning/courses/quantum-business-foundations/start-your-quantum-journey.ipynb", + "learning/courses/quantum-business-foundations/introduction-to-quantum-computing.ipynb", + "learning/courses/quantum-business-foundations/quantum-technology.ipynb", + "learning/courses/quantum-business-foundations/business-impacts.ipynb", + "learning/courses/quantum-business-foundations/exam.ipynb", + "learning/courses/quantum-business-foundations/how-to-become-quantum-ready.ipynb", + "learning/courses/quantum-business-foundations/quantum-computing-fundamentals.ipynb", + "learning/modules/computer-science/deutsch-jozsa.ipynb", + "learning/modules/computer-science/vqe.ipynb", + "learning/modules/computer-science/grovers.ipynb", + "learning/modules/computer-science/quantum-key-distribution.ipynb", + "learning/modules/computer-science/quantum-teleportation.ipynb", + "learning/modules/computer-science/shors-algorithm.ipynb", + "learning/modules/computer-science/qft.ipynb", + "learning/modules/quantum-mechanics/superposition-with-qiskit.ipynb", + "learning/modules/quantum-mechanics/stern-gerlach-measurements-with-qiskit.ipynb", + "learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb", + "learning/modules/quantum-mechanics/bells-inequality-with-qiskit.ipynb", + "learning/modules/quantum-mechanics/get-started-with-qiskit.ipynb", + "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/introduction.ipynb", + "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/repetition-codes.ipynb", + "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/shor-code.ipynb", + "learning/courses/foundations-of-quantum-error-correction/correcting-quantum-errors/discretization-of-errors.ipynb", + "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/introduction.ipynb", + "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/pauli-operations-and-observables.ipynb", + "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/repetition-code-revisited.ipynb", + "learning/courses/foundations-of-quantum-error-correction/stabilizer-formalism/stabilizer-codes.ipynb", + "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/introduction.ipynb", + "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/css-codes.ipynb", + "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/toric-code.ipynb", + "learning/courses/foundations-of-quantum-error-correction/quantum-code-constructions/other-code-families.ipynb", + "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/introduction.ipynb", + "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/approach-to-fault-tolerance.ipynb", + "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/controlling-error-propagation.ipynb", + "learning/courses/foundations-of-quantum-error-correction/fault-tolerant-quantum-computing/threshold-theorem.ipynb", + "learning/courses/quantum-safe-cryptography/cryptographic-hash-functions.ipynb", + "learning/courses/quantum-safe-cryptography/quantum-safe-cryptography.ipynb", + "learning/courses/quantum-safe-cryptography/symmetric-key-cryptography.ipynb", + "learning/courses/quantum-safe-cryptography/WhatNext.ipynb", + "learning/courses/quantum-safe-cryptography/asymmetric-key-cryptography.ipynb", + "learning/courses/quantum-chem-with-vqe/introduction.ipynb", + "learning/courses/quantum-chem-with-vqe/hamiltonian-construction.ipynb", + "learning/courses/quantum-chem-with-vqe/ansatz.ipynb", + "learning/courses/quantum-chem-with-vqe/classical-optimizers.ipynb", + "learning/courses/quantum-chem-with-vqe/ground-state.ipynb", + "learning/courses/quantum-chem-with-vqe/geometry.ipynb", + "learning/courses/variational-algorithm-design/variational-algorithms.ipynb", + "learning/courses/variational-algorithm-design/reference-states.ipynb", + "learning/courses/variational-algorithm-design/ansaetze-and-variational-forms.ipynb", + "learning/courses/variational-algorithm-design/cost-functions.ipynb", + "learning/courses/variational-algorithm-design/optimization-loops.ipynb", + "learning/courses/variational-algorithm-design/examples-and-applications.ipynb", + "learning/courses/variational-algorithm-design/instances-and-extensions.ipynb", + "learning/courses/utility-scale-quantum-computing/utility-ii.ipynb", + "learning/courses/utility-scale-quantum-computing/quantum-simulation.ipynb", + "learning/courses/utility-scale-quantum-computing/bits-gates-and-circuits.ipynb", + "learning/courses/utility-scale-quantum-computing/quantum-circuit-optimization.ipynb", + "learning/courses/utility-scale-quantum-computing/quantum-phase-estimation.ipynb", + "learning/courses/utility-scale-quantum-computing/utility-iii.ipynb", + "learning/courses/utility-scale-quantum-computing/teleportation.ipynb", + "learning/courses/utility-scale-quantum-computing/utility-i.ipynb", + "learning/courses/utility-scale-quantum-computing/introduction.ipynb", + "learning/courses/utility-scale-quantum-computing/hardware.ipynb", + "learning/courses/utility-scale-quantum-computing/error-mitigation.ipynb", + "learning/courses/utility-scale-quantum-computing/variational-quantum-algorithms.ipynb", + "learning/courses/utility-scale-quantum-computing/grovers-algorithm.ipynb", ] From eef64fe31653e2d1c040b6e089e9afe5aeddc14a Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 23 Jan 2026 13:47:46 -0500 Subject: [PATCH 002/118] Add updated overview image --- docs/guides/index.mdx | 2 +- .../images/guides/index/overview-image.jpg | Bin 0 -> 788198 bytes 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 public/docs/images/guides/index/overview-image.jpg diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 137f0471393..0fcea6399ad 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -11,7 +11,7 @@ Welcome to the documentation for Qiskit, its related packages, and IBM Quantum&r Qiskit provides a modular and extensible framework for quantum research and development across algorithms, high-performance computing, and quantum information science. With it, researchers can build, optimize, and execute quantum workflows with specialized addons, software tools, and extensive resources. Through IBM Quantum Platform, users can access Quantum Compute services, such as Qiskit Runtime and the Qiskit Functions Catalog, to run workloads efficiently on the IBM® fleet of quantum computers. -![A graphic showing the different components of IBM Quantum Platform and Qiskit.](/docs/images/guides/index/overview-image.svg) +![A graphic showing the different components of IBM Quantum Platform and Qiskit.](/docs/images/guides/index/overview-image.jpg) Beyond Qiskit and its related packages is the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem), a catalog of open-source projects that interface with Qiskit to extend its functionality. diff --git a/public/docs/images/guides/index/overview-image.jpg b/public/docs/images/guides/index/overview-image.jpg new file mode 100644 index 0000000000000000000000000000000000000000..b30e03e504cf917e21e11b1cc93c669a43936164 GIT binary patch literal 788198 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 %*hLHClct1D<~fIkT}FBtBCoBz z3^L^-%WvM)--RgpX7_=v$z1iF3*y@n^>G-=kxTB7yB}d>4otyrjnd>%8^8aivi5^J&Qk4alS7NpxEAH$v9^Qm$f# zq3Le1j9cC=)&{1Dawb%pY7PrqZa`n~Am0C6m{Q2E#mpq(FdY?;@_eN`Jogh8oNGnH zwb#fig_;eE|6rh6DHZyqkaD`ey*ca`2*RHr81y|oTXFo+!EdyteoE8MWFOtlcb?Q~OYAy4NkZ zy03a=cAUZ∋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�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ֵM{)QFFbAt!rkQbD_~Tx8z%5 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

8JHLCVDz2W->WQ#kbD7MjO_4;8g<< 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≠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 U00IC3fB--MAn@lU0NU&O7ozW0A^-pY literal 0 HcmV?d00001 From 50e9c218ddd9789bf701dc8976df242967fb4cce Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 23 Jan 2026 14:04:19 -0500 Subject: [PATCH 003/118] Placate CI, add new overview image --- docs/guides/_toc.json | 10 +++++++++- docs/guides/cloud-setup-invited.mdx | 2 +- docs/guides/cloud-setup-rest-api.mdx | 2 +- docs/guides/cloud-setup-untrusted.mdx | 2 +- docs/guides/cloud-setup.mdx | 2 +- docs/guides/configure-qiskit-local.mdx | 2 +- docs/guides/index.mdx | 2 +- docs/guides/initialize-account.mdx | 2 +- docs/guides/install-qiskit-source.mdx | 2 +- docs/guides/install-qiskit.mdx | 2 +- docs/guides/quick-start.ipynb | 2 +- docs/guides/save-credentials.mdx | 2 +- docs/guides/upgrade-from-open.mdx | 2 +- docs/tutorials/_toc.json | 2 +- docs/tutorials/index.mdx | 2 +- .../images/guides/index/overview-image.avif | Bin 0 -> 791720 bytes .../images/guides/index/overview-image.jpg | Bin 788198 -> 0 bytes public/docs/tutorials/llms.txt | 2 +- 18 files changed, 24 insertions(+), 16 deletions(-) create mode 100644 public/docs/images/guides/index/overview-image.avif delete mode 100644 public/docs/images/guides/index/overview-image.jpg diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index c152f7f5e57..129f966dc57 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -245,11 +245,15 @@ ] }, { - "title": "Verification", + "title": "Debugging", "children": [ { "title": "Simulate circuits with noise", "children": [ + { + "title": "Introduction to debugging tools", + "url": "/docs/guides/debugging-tools" + }, { "title": "Exact and noisy simulation with Qiskit Aer primitives", "url": "/docs/guides/simulate-with-qiskit-aer" @@ -314,6 +318,10 @@ "title": "SPANK plugin user guide", "url": "/docs/guides/slurm-hpc-ux", "isNew": true + }, + { + "title": "Qiskit MCP servers", + "url": "/docs/guides/qiskit-mcp-servers" } ] }, diff --git a/docs/guides/cloud-setup-invited.mdx b/docs/guides/cloud-setup-invited.mdx index 58b727ffcf1..b192ca446cc 100644 --- a/docs/guides/cloud-setup-invited.mdx +++ b/docs/guides/cloud-setup-invited.mdx @@ -56,6 +56,6 @@ If you are using a trusted Python environment, such as a personal laptop, it is - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - [Set up to use IBM Quantum Platform with REST API](/docs/guides/cloud-setup-rest-api) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/cloud-setup-rest-api.mdx b/docs/guides/cloud-setup-rest-api.mdx index 017ec4ec2c8..5d594c8c0d6 100644 --- a/docs/guides/cloud-setup-rest-api.mdx +++ b/docs/guides/cloud-setup-rest-api.mdx @@ -97,6 +97,6 @@ curl -X 'GET' \ - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/cloud-setup-untrusted.mdx b/docs/guides/cloud-setup-untrusted.mdx index d08da5df4ad..4e44c21cccd 100644 --- a/docs/guides/cloud-setup-untrusted.mdx +++ b/docs/guides/cloud-setup-untrusted.mdx @@ -70,6 +70,6 @@ Follow these steps to use your API key directly to authenticate to the Qiskit Ru - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/cloud-setup.mdx b/docs/guides/cloud-setup.mdx index f15865836cd..daeb9aad6d3 100644 --- a/docs/guides/cloud-setup.mdx +++ b/docs/guides/cloud-setup.mdx @@ -57,7 +57,7 @@ If you are using a trusted Python environment, such as a personal laptop, it is - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - [View your available QPUs.](/docs/guides/qpu-information#available) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/configure-qiskit-local.mdx b/docs/guides/configure-qiskit-local.mdx index 137e3e2cc9f..23eb78d9eee 100644 --- a/docs/guides/configure-qiskit-local.mdx +++ b/docs/guides/configure-qiskit-local.mdx @@ -55,6 +55,6 @@ Set these environment variables to alter the default behavior of Qiskit: - Try a tutorial, such as [Grover's algorithm](/docs/tutorials/grovers-algorithm). - - [Run the Hello world program](/docs/tutorials/hello-world). + - [Run the Hello world program](/docs/guides/hello-world). - Read the [contributing guidelines](https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md) if you want to contribute to the open-source Qiskit SDK. diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 0fcea6399ad..339a8ae1b93 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -11,7 +11,7 @@ Welcome to the documentation for Qiskit, its related packages, and IBM Quantum&r Qiskit provides a modular and extensible framework for quantum research and development across algorithms, high-performance computing, and quantum information science. With it, researchers can build, optimize, and execute quantum workflows with specialized addons, software tools, and extensive resources. Through IBM Quantum Platform, users can access Quantum Compute services, such as Qiskit Runtime and the Qiskit Functions Catalog, to run workloads efficiently on the IBM® fleet of quantum computers. -![A graphic showing the different components of IBM Quantum Platform and Qiskit.](/docs/images/guides/index/overview-image.jpg) +![A graphic showing the different components of IBM Quantum Platform and Qiskit.](/docs/images/guides/index/overview-image.avif) Beyond Qiskit and its related packages is the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem), a catalog of open-source projects that interface with Qiskit to extend its functionality. diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx index e0b9292276d..907aec77fbf 100644 --- a/docs/guides/initialize-account.mdx +++ b/docs/guides/initialize-account.mdx @@ -196,6 +196,6 @@ service = QiskitRuntimeService(channel="local") - [Create and manage instances.](/docs/guides/instances) - [Initialize the service in an untrusted environment.](/docs/guides/cloud-setup-untrusted) - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. diff --git a/docs/guides/install-qiskit-source.mdx b/docs/guides/install-qiskit-source.mdx index 2a449bf0353..cbc1e9ae221 100644 --- a/docs/guides/install-qiskit-source.mdx +++ b/docs/guides/install-qiskit-source.mdx @@ -148,6 +148,6 @@ pip install -e ".[dev]" - Read the [contributing guidelines](https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md) to contribute to the open-source Qiskit SDK. - - [Run the Hello world program](/docs/tutorials/hello-world). + - [Run the Hello world program](/docs/guides/hello-world). - Try a tutorial, such as [Grover's algorithm](/docs/tutorials/grovers-algorithm). diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index ae0ca781831..ea54f030a42 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -299,6 +299,6 @@ In the Qiskit v1.x release series, the supported platforms are: - Set up your [IBM Cloud account.](/docs/guides/cloud-setup) - [Configure Qiskit locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - Try an IBM Quantum Learning [tutorial.](/docs/tutorials) diff --git a/docs/guides/quick-start.ipynb b/docs/guides/quick-start.ipynb index eae2ea1c806..3369d0db6b5 100644 --- a/docs/guides/quick-start.ipynb +++ b/docs/guides/quick-start.ipynb @@ -255,7 +255,7 @@ "## Next steps\n", "\n", "\n", - "- Run a circuit on real quantum hardware in the [Hello world](/docs/tutorials/hello-world) tutorial.\n", + "- Run a circuit on real quantum hardware in the [Hello world](/docs/guides/hello-world) tutorial.\n", "- Not ready to run on hardware? Start your quantum journey with the [Basics of quantum information](/learning/courses/basics-of-quantum-information) course.\n", "" ] diff --git a/docs/guides/save-credentials.mdx b/docs/guides/save-credentials.mdx index 2116c9326ca..bf3ab8b7a9c 100644 --- a/docs/guides/save-credentials.mdx +++ b/docs/guides/save-credentials.mdx @@ -125,7 +125,7 @@ To view all credentials that you have saved, run `service.saved_accounts()`. No - [Initialize the Qiskit Runtime service in an **untrusted environment**.](/docs/guides/cloud-setup-untrusted) - [View your available QPUs.](/docs/guides/qpu-information#available) - [Configure the Qiskit SDK locally.](/docs/guides/configure-qiskit-local) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - Try a [tutorial.](/docs/tutorials) \ No newline at end of file diff --git a/docs/guides/upgrade-from-open.mdx b/docs/guides/upgrade-from-open.mdx index c03a71f2ca7..11088712cb6 100644 --- a/docs/guides/upgrade-from-open.mdx +++ b/docs/guides/upgrade-from-open.mdx @@ -48,6 +48,6 @@ It is recommended that you set up a [cost limit](/docs/guides/manage-cost#cost-l - [Manage cost](manage-cost) when using the Pay-As-You-Go Plan. - Learn about the available [plans.](plans-overview) - - Follow the steps in [Hello world](/docs/tutorials/hello-world) to write and run a quantum program. + - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/tutorials/_toc.json b/docs/tutorials/_toc.json index 4df998d824a..04e6ec03cee 100644 --- a/docs/tutorials/_toc.json +++ b/docs/tutorials/_toc.json @@ -13,7 +13,7 @@ }, { "title": "Hello world", - "url": "/docs/tutorials/hello-world" + "url": "/docs/guides/hello-world" }, { "title": "CHSH inequality", diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx index e6d61ebc25b..4dfe9c69ac1 100644 --- a/docs/tutorials/index.mdx +++ b/docs/tutorials/index.mdx @@ -15,7 +15,7 @@ Use these tutorials to learn how to apply Qiskit to common quantum computing use These tutorials are for beginners who are ready to explore running quantum algorithms on a quantum computer. -* [Hello world](/docs/tutorials/hello-world) +* [Hello world](/docs/guides/hello-world) * [CHSH inequality](/docs/tutorials/chsh-inequality) ## Explore workflows toward advantage diff --git a/public/docs/images/guides/index/overview-image.avif b/public/docs/images/guides/index/overview-image.avif new file mode 100644 index 0000000000000000000000000000000000000000..cdc21867d874859ca8fe023a3ea9afcf9cc64e0a GIT binary patch literal 791720 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

G+jilv*ltF6Ow`rW5iC2z`^#1l2a#2 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

9s1xaoVfv90Kc7dSQr(jXMNt6|=nJ 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%0AGB;Bi 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%0A6$qv;yGO(yoTu+SN2sbUv@$zy`_*VB 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

-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

8JHLCVDz2W->WQ#kbD7MjO_4;8g<< z4M;M?R%Q>w-3C@v#bU1|tGP}Oe7=vXO81xW_8-#UrtqZgt;{_5jlqv zQFV|0Yi=sobmU^fNT{S~&LH2V176V22i3|8u9ljY74(v)#?@mvO|KY~Z(hf(y}98(C;jAwV#Rn{ zTAX`uz1tOpV5u#mf=Q4FesvWoEqaWuOQ_ueYnm)~JzBPYJ6t00j<8s%vsDP7x%*&h z&>WP9uC1+eokf?s;#+e-X@)})HAzQ)_AQzlopjzXa&`WKNPs$KWy7u~C3Mmx7!#Un zYqunMM|l)Qu)p{`G21*Th`b{`Ld|JEh1nlR8B`P_ zp;O_;6QQ^&syjbN$;EQD5dY@c9)SZ^@a#ThRDkTv{nXc~AQ$5gr5~y}FAul*`DB@dc^tmeUDmP$Y` z<$h1*+L`r|Nn$`onE?d4S=?f6A#=5AMO|PH5Jlm?bO304WK4hnW3iNf&sd7Zq^V-thlxl^oSBa2PSUJjt=@`zsA1H(3QM|JsnQsaS&rJ*KDv{Rlf z)&&o(s;2!&UMqGH5J8`(P`Oa%_d0=hm23P?RQY(bFFGcqZZVLkE4aa?0g<~@5+jo; zAHn}rf2R%xIT)!as4OW`S2vO;JaGCmY;ux2(-4q0+t|>Mf=y4}4!DgpdsnoTaRE;5 zHNZU1_%PRM_dR$76dXU~CHo)?_~G{3ZfLQ~xqtgfUP<#==kl@^##|0{u5=p-zDH4i0rj&6K%X4ObO--5$pmNlTgwxa*?; z@=$8>d9j0pMt7#;@ljIcmgN^3A@I}dmQ`q%wFAW3^>ZDSjyj7VTo1^^6*1F=)HIzn z@F_-cYxy13vfgdRxB?8#tSgcF%(EMJcH}a@T8n&C5Re0_T`S5Af%3O=Y+sapo>@{H z4wdVUTfaL+iV?pX*x}MA8+Ey6w^w`5(CfW%e!S?vw%W6yjcxiO@E$LP~5UIk0&nX>Dzo;xtdvA+Fmvd zva*@c64QB6Ta7GjY}$)pj=;;u0-9X|y{X*Si%s|1tokmd>Yh{Dv^QOli;+2c?`;}+e!CT6m)7rX+v63oDgLHobUmn-9 z)h#q2aGK`aku=<%(UeJRa zw;L@LK92^jD5j&UJN_4Y?*Z1-wyurpTDq3Yy68$(s#K*5h%BX-fB^!MP!?Sh0@9@~ zMG*o4DWMmolaK&`1Of(@A}ut5B$QA@YC@GNAbPX+z5AT~+`Z4<>)dnC|D1pS=HYSX z8Dq>b%{RX}<{002zxVC8m0{IwIKM=D=9GmCQ)!&tHwV`HH)s)f@{rL{*4jB2_caiE zRZ0c50lD1Ii~M`kOVr}8Hu!!2E$C%@A+oymC;6}~5IJsjL+X<&GGgsV#@z5~?T>de zXA|Cr4@y<`mXGU7hwJ#78+2<$-WqgeI9MhOBlJT_x5EeTAE;37bgI@b(z&?>kzsO4ejq{RT4@m1OGb*a$&$^F?Hyu6ZoMW| z3`3&cM%NK`?qP^xAZ=rE>sjP}NpR~)sq<5gt!gSE?XyPzhDhM5|Mf_sDRMb+b9vp;%+Uh`e15@ zqva%nEYhaBNejSF2Bp#<*Hn0j7}T}Ra1&k1Ras_92_`0~yjB-@LBv9Z{l?vFR|$vs zX(z+%GnX2b2UU0i3DgWn8C-19=_ar6&F0pGigHw)uH;+PropybB8(`GTnWCuOF~yP zn>IDlO7?$lY4K~UX~ms^_7aFekEVB$WSZ zP^NNIrjsdY7c~-w(ZlZvXE#aIHpPxflx^h2PC|O*hX_jt5ffLJc?-S7!#+|mCzzrE5;5)RFLgOEVc)7l+2lG3dH-WqEep$t9es zm$^#&e9gGUnFG|N{Q2sDs!D?Y%?7c(GLYzGondM|5u$x_CfPg2fO&YwQ zkmIaG!E3J?r7~H7lz0-pat9@E%#xawadT1Kgj@G1kE7`XH8GoxTrDFi2y_{*shgNr zzc_I1K~jm#%=67An0SMuU*@U4O@SS8(ed^Y`kk5HgG)E9ang#J{d0;)MQ<|ZW{h}L zjLju$OqGjL%9@a+`UqEB^}`$QePc`;j$@msRxAV$8P-E6d)ky**|0BtKZ~ON&f03i z3!WZm)$@R8EWvYD$yl|eKy&}o((LS~&%VP4nQYBR?T7U##?Z<+&9GE_5K)h~+oP4Q z3>8bw0aq>}>uKKJTV$-eSyH)6Et^kwfi=^qn<(Yr?oSe!w0Ji9L=e#@aUG}YwiP;b z-qIV}g^6%cx!A!CN}X zNLCq&*}8jq(Pwn7X7kv(s6MtKjq1CU0iG{4h!ILYox$3#sxAoGxvklc*lQGkg68P- zbK>5<$(CrXZE}-heQH3}$MG9Yb1NN;w|1Anx{yooCY`XHb6S8lo}HY~^jb`%Jl;vH z7-sjq@8&Pn*k#wZ#y8W~OHv!0`R8$|rJn34SQU%3c3Q|UO`kF8XXg-)wtO@!Q5MT-oOZK9&7wm%eFdj-ib_)1jeL z78X9xpyFudhI!klPLXn3!(53@7l}j4$*kv>@R{j))oK#KBjW9@xGv&idpt zJZ$qI8U50~c^-5SF9dKcM`h_Hp;HG1YpnIq)$t(2ieExQUtke-*&5nsKAAbBFUJoZ z+U|6)fRClN7~t4o42)p6Xd0WaIX)lt79$*_dG{Zty8PkF?_`=ze6i7d9`$_3a9v8& z!Z{+P@Ws^T`b2;25$bhHyH<~g&JD*ew3@HS!fB;x7Cly@zy9IQ|F)qlZA4@2XrRrzF6VWnw_o7k)ibUs&u zuScLD@s%YIWCK=UZ>hWkBl6`(1ZO>R97==EwJYTo>S_^pTPr$S0GS$zcY@BYAlGA~ zmuT`I*opAK&{@>Y(FxKP2j~GBsb-ZZm@*PkGc@Y6N>7GXNt*S~&0m?A1e-bUTk+pZ zGJZODil$=itDMwDGl0?Oyl)>yyJsem-dZR8X!?Gg2=3Dfs3eT2bN;^4DQh(!q_R$V z4LUs!95n0IP)FA?fUTU0tEN2Mn^tC@+{{TBl2!Jq)9Kyq;%j2YimM~^GR=>^wo(k&8ly!m{73H&} zgNW?Co5s<7$F5@6l2k)NN^Kl2d}_ylfP}i+FKPh!;}B?cT<$;x0v#8J1F@l{fKm|X zji{76C^QYPC&G0!(?503?dDOJ*kr>ye)kNEvKu;=E>Bv^QRE-4P8f{OaVAdLboNfp zpRQ}=>69r}<2fJ&4GsaB09VzBy&~30kM!XU=0)KVhc%zai)c636q`bKZ0fX!p}Ks) zuZ9wOp8~!(jCAZEB4g)e{PfMnC98WDYt-@a2*nf?Ls8ZHdayXEezGMw`To63fL^=_}4jl$6AVfI0K zlfj)^YLYm+x|E1o(o#>m1P{o)Xl?!IWJTrBq+h?9SLwLz-3cpc(zbH5FYF*Od~Pft z>#fw?{;sJ{o?nobQwmNyd<7a-eaN0dMIPJJ6~pc~UUv(H^qiBAU7NhWi+_e7Hu>jh1whsTKwl|UHz#1o1)^w8L+pLmY5P0nqDd;BBgN&vQ)}lioVlJ z(TTOY22L-9$i3Ot(lG&9;G5=_3!_@;mIk%WcPBW|S-rk)79EOB_ln)(8dr)316nnv zj36lgGTt)#P(&QLUeC#TDlb~N^W%+sD*?Puo^{kN#cq3X9Zxn;dK#MmgO51D?k_dY z30!xZVpO-VL}@3iN=F>P5M~nrSFSQ_ZL-f|lLD1ER7z&AW!MQd<06vTe1gsS6ii>M z-?@G^6VSY^MhGSkJr81n9F`Zi@+!SQ{lCn7eABqwpv}<8%(TVp5*KIpM0#G@-cKs7 zB7*HFg|s7fhW5Y-9*GQbOs0ZO3pGVwi)y*-O(c~1)ozkg3_6X)lVM`69QJ!;781tK zj;Qtf7pZdafIuATg+Lw<2ZuenA}%i1gw5KgXHG$HNx8+{k~(b5e^t{JdidP1+4qG? zk6fYIgD9ojO%-<(kpCob~A+?fRRlC8FdiP#XeEik5%%>^|WWMun%ryFX|9^U;{n@Zr!mHSP5k02SKARUNw+90DVxtf{ zBNIE#yJ^U;$9{=6YmCJ5EnC+c?_c--%bhq02;=)=64JmtBXGpHd-Qz&a;t%$NM!G% z4z%N;?kn0>vSl=EDB9mo({Pc*eDIgk{?YOHeiOroxa?D^KxEl4R+`eW4G?gctjSR8 z<9e*lNiV0@;Hc9FkvcIfnWCa1v<46RIIi}7F&})yga?_g zT~y(@aGKsxYEV6-VhxUds%fBF39>zTGXjuiw<229Cj?N5NSznElvQ}z<;K#Ic-B1q zl9d7Lr)`ww$6(mot%<6XW>h=ytsrH^7h6DYH zVGNM1#F~e7j0rE6qyPYZWvDzN8~(E_bo+!NFqb$dZVJc_dBW>!9?~!N2K6?Iy{a|>RSf-b< zVIS!?-{IK!j{bnWMOiinm_LS1#t#BfNIfX_zi8in|9owJwi*Od&tQf_DgMcVo_X@* zP(sYErOmPH)uP)zV%-2Syh`wcOl-3EO}}3KHLOLwBflLFFtt-jEjWzH2>%Qdb?3X; zuBxzN6C#*uE)OKL%A>}LRD*i%u$qOd>YI6p;3XC(TY^ERGH>KHL{|naQ=+%%k^6cik-PaF1A8%io*)A$$d}76{%*jGaEJwwGvNR}^AydQ} zIHvJqy2p)viw^kOLgKzv`#ktPLnF80G@2Nis0NVyWbh#-aE9AAE4J_QT9V)8-D$gV zf6CxW+QaR|51dXfHhPM$$_H)p?-|x1-)}jwWq}{xAEgrqokW{ViP;#o*sK)@%=)ye z%gZTcrRwr%OEammZzK@37KRQ(>VyXO7Y`%GwPM)VDQr1Z)Y9QfKn=dl_5$x>YnwP5 zvE*u8bVu*JxbLrj>s^1S%L1|EZzQkVI;j3iCgUBjDyl<@6&-+^XYIy&(JN|!2EBB5P%y{R z1RAG=b`i8H8#!^Eq#}8_kx;4d9Ewe7unZBwfe~lQKUsn#LtW#EHdj$oPdP2=+hhrN zt=lq`XcyTm-}%g(Z!LYj6f^UqWr?Ngz1<<3y@|!zF+42FzS+sfhhcX43mi+O;)xw`?i$wPD(2+BnPA!H7~*zFViFA_YuN+#<9({48h za@BJGd|TjZj!{u+AVDS7SPNdOvO;9Y;m09xw(CEW4xg5t6lbeY>}jmC>0QF7*zdaa z0Q{o%8VD4CXEW-8mKZ>e3M5nvSP|Dz zTz~yB5rS;`A%n76ovtAKe!M+~omyhX$7k2ny{HxI99V5K+Bl)WnGA}5*tF|p*G~cb zV7a2mBnI!U{h$IOu0Lp8#=7T3T~PU6w0U|V9K0~OJigmBT;`QE=TEf=#C(8Qab2uP z&wX$U?1k}?aNvSC$y6|zRciW%EbTkh#SOJQ!23)Zdc3Cuo%Lb1AAL=*Qr1rP za(>ycUyt6*XOAJxMT7Um$tbph`NBuFE;$5z%ED9*jlXo>R5VqUBtC~XUQAU^wlrBz z(eK&$*_YK|EDK*8pSGRYS*s$m7)?bsQUU=@yVaT4lrLP`h7L50t6mzAg@d#*F}E&@ExlihR6LT(^v;;z@!#25i1|k6}yY z%YVq}|7oLB=q0ZGd#u|Bx-^kjdGXp$Hw~gDj z0nm}RaQ^L|_W2(-sJ69_rubS+uTH%?djIYjQ|IA@B`dPXo_5LCV;&oEfnP4@yktca z*tAa|fARXw*A@S9SASh|;+J)YOHGZQP51(j2R&TTwKdv_U%DM3ehQ)oqb)836v;3* z)4Z+}ng-7rlc}nj5MygWr^{fTa@{}b*;#=P$*V&g%ZOIYe1IiIrb*H-EaYxiwuzfV zFVQ}qK=w)sQf1$k{VTs|piC}w$(xP`?KuDz(V z{B9);gS#~kRyaz@m~Ls~leu*sQ`00$HnNE9p+cWy1;z!brtsrLkZ{d|o2r zlxrZqYi9u_<|3O%&J$Ib11;PsBMkVfA_MZ~*(3@ekmD0QN_FF%HRIHk0vzewb#3@g zvrXXS(~O3-1fmW63S!}NeaQLUL%!ER&4ykLsn2NfU23GW&qRZ1JaaZa#iql6L&NKF z+oP9@-m`>lA>GS6RkhWk4aM2o3I*OsGZ3AGu1Y1}oB!YpLtRX$XRA1xkUWT5kl^V$ ziPznmje8pD6_qn{))RR2H86E@Y~fAS(1%Yg+D~ThUJMpHCzAAGwCZNCPSWph34lDe zn{v8(Ssez~p_wmLz)BvE;qT1H!{h;4@ba>joRMs63svhaYbs?QEtRqbP)V{i7RPI_ zC*(b3HW4Vg+9WGeV<4b_Jvy>s2$^AQX#tRJsVy-;KlM5LzUZCb8O+7RhGV1`JkQpu z9}0XwIf^VM!0jkQMNLg6NH(P|&6^u~t-1KM%UqB5>nHeYdhaB~<8y$b` z9_n%J@od_qSXj#K4>!tgcH3!8q=}`wpZW3pYktW1tJL)8cFk(=6)c_MkHNYVT9&y= zVUhHqhDzolCPx!`&%L4|o2_OQt8OZn?C6146D9SGy%Am0cXX41+3$(nV{^LNt77%p zuQNR}^x+eQxom}Q*7Eb=@9EPJf+t|q4i>f4?Cvpi5$D@u_+Z_)Hi8dQADkO{HS%6w z4D5NAzZ4wksPDm2A*)Q+2b@X({^fkotAbW=5C5iYm`2(VbD@jc?f}a{cgxa} z93^>4z_?~3bf-8b1LjI-fFCN^3l_>I2V|Qd3WW6mJu*c*Siod~w@jbHwS?JGbJgR| zT&@p(T9Ze#b-I39IcsV?)}j06t%`A?o9hpiVO;vflJ_MiPpp;~QHP1+VK62(6s5NX zvQPz>Rp%6iil_`5%?GBMilGL=Cz@$&ttmE3Yl5KqxwbX2k1Ap8w@9 zSE{VO^YvJ_`R>sb*XU-b2wp^-Z>cS2os?U?dT-!VNKT6%%VIUmV$EF2=<}Yo!e37N z$4CBUih}a;7h9;8gI&R)cMvUj_;Q=_RaKc0>5`25qliy~e8(&5k9bRn-9A``hu|0!I%5yIOV>l!?*y*<@Zk04?Tci@Myrt&tbdNv zOO0m*_g{60A%t$**R&BsU=aodb5@0Wt=9eqKRuPdT|BSEv+V6CkB1vnrRF`#dhiC% znLH+m0JxR9UNQ-icYTd2v>9hTG;P;A+{(@aod8(&#AnQ)Vn-rF?BK0;`uf898ndIiQqzT7mDl z;kTA&FTO*dCZUdqcd2$MjCTL0gY?851cA%X;$(kPqOS@J!`XntznzxKOKV8BG z7JE2is#?O4bPxzeLQ(T_5J3jYo*WXJ-@ga5)SKqrqsJ=U7Uw;UQ||> z#NE!Gzkq?H2T5Ng$Csfp(by`nTt%cYh|>$2x%uVip!vlo4u)10*M8#B^iu?aS5>@? zR_PFcjO=}E;LkqZf!izW^Z-?i+etIT$V?Kp2ay$qq}SHYStLb|Sf;(N2p|^sz1Ds4(U{2bO*sQV=)7ZRvDF zmBy*u8g{XUK-YS#TKl@P%EH>e&9B%%(E}NmV0*$$-%wN1;7A1Ig-%GUZ(wk*Hn762 z9P5M5Po9i8jb_RRF`IpIyh#`52RQdgKyY$ETJDET^_nlg+6+g8pOqvQz*Kvt%7 zJfOfNy>8YidrW+uM1pBC&5JvNp_4EU&&=m=H+3|Q;iKk9=f{77Xun!TCHxk&24prjrKs z5g#-eW7knB3Cj_J8$dsLVg;2C(N$mgBi&OC@};&(iqDYS=(A=LwR2_!QiXfVVP#1) z=)CzHAHmLI<>3!5p;76E`aVVRdq_ij1S2v76}*tbnkbHkDII$_{Bg`TaCA|5)vrfvxn=h?v_+pqZ4VpGo) zLn3!~VnFFdm378F*%4PCq`;}%8Dx%^OCqlC8K%Z!SZ*bs>K1!JT2iEORQQ85duWQ= zJy-v0;s`JPTv^#7L*6K#-~O&~|MP|a0y|smADu)#9LAg)*!{lc7r*si-6IU=Md{M3kZ9{N#Neg& z1`v5Wkr6h?>iUrTgOKMr{#OrkpUf6^k)eIP&HL74>M);0PkNAbAhO=^DsxBZsbU?x zQKlsQ6|)1v)-nOIg&g}~AoQ*x&flPmM)?rPGvF$4Vg(LTcahc@8|}4}auBFN$0rtv z;y9FC(n&njx+KIEjxKX?-AxRa#}rGNbR+r}DqFXQ(^zY$s_c2s5(U08K9#$4(8wBm z5PZ#@nglSF$qo0O+5WfYtg6psm%}bwl^JyvPHOD01QEYV>Q0{gglbM zW_ZNmdo1{|`iGnhhuuZ+wX;rVB#0k%#e{Zcf%3|k zgHRDI7RD*tkE`6ws-vPMyVvRNm!myx#R$OXtU12)#s1Q!^{#7fE0gbpw(X-bcSdh< zhfHj@e^lReeeP(L^sV-rHNN@Aw`bvh^2qS@m=;qrvOA39^{!)NUCDYidW!42K>_?7 zAUoIXGmCa9;yeerUwT=LNwAe3JJJ*xic_7hPE;* zTU(;l;O2(&2e7oZj;`U-tvm57ZHq@y;r?v_HYu<4n5!g|F>Uf`u1*Hb;N#(m1Pgit zEeD>c6)BeC@otY1lqs3cmNJ!PhGmY^8&n;>BQoW6yq9-`Yl%e-Veh==B0pf4XU+4m z?%HyB`*sjHdcmn&@UI)krbcgr^A z+6STf%+4Fjk7`05e+)VMTpu!0n)I>0+Q12R<9@5>N}5KhH^?EsryX!T*V#XKY%|hb z9~x^S&jU487Kat*Y}xG6rlI#L;xqayY8ivw`4yF@rKGnhx1{E7HQfN$zSHd<1cDEq zRbR5)?oijtk=q4k+pj|j#TA#|lXAoT@wE2B<`1i6ObfkG}Euf5pQWcxH ze)%TsdWi>vo@`^tJ$ill#(moC+X*SbFZ#t6-OE+m0|L6+_P47j!uL{*r%>)Hu}%h7z8>`LX+v74 zO+rjPq*2eWi%(vDpss_$E!$#p9uYQ|dNsUTyX!CK@UKtI& zakvcM*%6jNw7D;Rb5C5prb~gU{&v61!Lz+}5;Nh0?_B5QSLL^Yf{ zlV-XtQYd3$X3h>HqJ^P6Di9W?Xp)_>Z<;;T;z8%Aa>DED?j>!njOLD9i5(>yHsrjD zkN$bJq(!6C{#?u}zJx}%$1+o7xe#P&n9`wLoBpAWTXt`n3wmYEQO4^D<4hWHAZ=Mj z)>;X8A7g2kE#@FNlG8xM9a^^QnGu8Zlcti)R`t!Q^@7FYKk8iB8GJ)adMs>?K#Wke zA5t>Q6iE|<5S7YxK(dX`8>!{iT!BIosDhr?2}C@v0vZUmjlByd9Nzg^-N3!>dhAHJay>bmtaUz{#{bM7-Lk_l^R;kDU3*9O~jymsLt!REV<3&-oE+6S;gzcjkuR$uOY-Ar~J@7h0*e z`$>+>@d1(Fl74+GT$P4O_j6<@G{4V$f@^+)RkSTuwO$8RjA;IFmHv1}Yta6H@g=ju zR&l6XR1-|eb?LUVyEzc`t1Gxo-#zA@*VB%yruOjqjzZZQC|`5BRR>kiTkWvwev*M= zR?J*OH2P zEiV?vog>C_t$+FJF@BbvOM+p@F=}Rcllg^Dp!dr*!=#?>rDdOip@Uch5{F%bdy~PM zd=D8zu!*ma%bKcSwD#;*a0pb?7nIa>#cy`MFM-p?X%^=YEJINZKL4E>+`4K7W_P%1 zz}(GijIy46gO5&Mwn@kwhV)7Qum=f(V|f8M;zJ~1n+=4ctz+4MxOIImFmL9o=C-gM z>cO1?JdYkb{S=B6Uvgv%f>+u3)@oY~AeBe^=Ve*gmsWw9*=&ZH`wIj|j+L#!`tuft z6Q9QxbR4$Gsu4z?3#OxN3U8i?&k77mwo<*z!oH%u)8m3Xjzc;isq&xLT3VnPMWcyCo;*ck7 z?ZJ9J6Z64vZufAr{vq$D;LU{nf#R0yN$7*`yT2ZDsdnfW`uG1s@^{ncr-0EK+aVns zG^bxebyh&jq_&ojvg&w|G{!n*@I7RPLAkbgE9ui4P0Z2-sUrkAW_aX2 z_^*D0At>_r+}C5Zwz$Rf`%^hB;!zg9t+IxXe4qJVZOuE-nmxs;esQyKS7v8oW?F05 z_HAfZeQ4f&1LdA_Ye!w6@gZ$|iLgm0ek-|;wPGT*gs`)N&CM$SjSH`Hb3FV)es zbrO6lUGu#MWe!+075Qzf?>0sP9?45zUOmX4UlYh3v1XnQyU~Ci0HFgBdikjFK-)19 zQrzMibPbmIlD7bz!xN$(n(7%Kc7@;w`aJn0=zFWM8Ra~8D}44X_k#@cMQT;_#Tx+1 z(X7IU^u35F<0r)>1Td{-9Vh}FyF{UsbTk}vSDOmnwu6JGK`bmer{0|SfWz2xKe%-U z5`&d8Yu^u&KSvv{zDwZG_V0A9C*ZOxDwZ}W1V=@ViYZdFlTdXTc3EXNm6{nURG{F+ zNhm}mcAa7lON!Fu|3;^C9m^;`u*dZfH5)Q z&JBZ=$kE+-H(%edf+nu(7xDh=@T zMNaOA6`^I_W3$B{+bGNbq50=hCtynTHU1rvSKY$D07DqCQ}(20kCO)XVpN&~VARvqwB^ev|UqeUq}- zwZoPN&Q=-e&HD44=bY7C=Q)*UGIn|zqt`c|hkwt}ltfsV{oQ@SMGN9!QZyq~HTTgQ zcPk&O;I<l4(SgZEq~vd zGEyF?bCM}t9zwfj&Q8yST`O&BVp$%_GKnlpLaD6Dfh;(RGx@v4^Ub?~ni_m>NKLth zMH-rr{9kfW>SaK6kuc1C@x>OjOaOtMR#^7Movq-_pxx{r@WlVsT;ym`8qJ*++qso&ph(UnLn?THNHYwI!}e68zGHMgD3H(PVDXw3 zIHS4Wk^Dpt;x8&wt+qYASlDfj$%($&Ft)9hIG-#gE;xcmHiPebm)3uWaWL71b`LCY zcgn>l5?ST8mNJTd2J!MPBMnVG)>u@-tK~}Uasy_^_eV|9Q-eZxGgqB`Q){snXGgED z#)Ao}7so%m_pY)Nq(O}k*n!RmDX@x3k2)4)d9q2hVT@(T19D)asvBe5h5hPxTx$>r zY=_^QYESF)){PlvQTc!^`fm;FEeulX?G%i~3GTWhYOkF6jsYJ>9gShuD>(l65 zGWEhmSAsW?Pxh>-!Anw)#9AZbM#a z4_0Eq8tpXlW~D80%Gl;Y6Y0#=h>xoy;3Axoefxop7Vso5o_0jLnC>l)i}Vcc1b)Df zY;$4#Tsxkp0<6^bKqpnprgC|a>YnAMKKb=}*)Z1^#9!v)g^?i7tNFt;j3PhP58x_L zcTa^-Y_0}+nPe<0W9x%o1n+_DF(PCTjmH9JUxCiGw}vOlm)gof=WP|Jf-7Uc{gZ&( zAFe(D3jFDFRnX<5E3D)xbG?E$`(iq`$@9~seAh$S7%@ah#;vFa@4szmi^1v4tCz3uuHTQ^xUaii`0B@P>8a$yf}!ZThkBaPKNh~*(HW;kqe-0L z&|j&4+rhtP$^VcP*M9-y{!1i2{qKJt{>N-Q{O@i`4$wQP&01>A_A|6js0L^FnYqNH zANDe%7J`yjaA%XGr|#|VzuDWxK0BPk%H>3X3)=n*zxcQ#uJP-!^r^yD2KnXT>z5aX zqBca{m51r9g&TkAoB5gfSvXpk`t=wL_ys*@>@^?rhtvGO$1K=QUBEdDx-rfuwO_Y~ z7nYCvpY0KiYo8GalOy|@#(Om+-V-yC%t6@J`}tzrGpC)}iG&ga)TC+5^0X!tL7JR# zE{ipu58eh0z8xWlpe5%Pt?!g6Zfbd`X{zW6K9WSVBia_ePsT3yI5 z)h!9hLtmPIe3Nuokkumj#mxT<#gE$HuzzwTKey@oZ?)g7@y$2BJqzDPhHoR`zsg9M zHz8$LkaOvK4EXvyx0rjnB||!5iac?#2W+!kMMRO-jH_L;$J`ZKP-N2yhrtfrjvJcWF z&(oZ9=utQU9`L*Z4FZK<_htxnJE#&1H!AiMtz$B4DR#@22+^J9Agk@+5&Sqkw%W#>Uci*#+i8mxcOF84EWt~-qx(qc|KqYFj*l!~~PN10|` z_y27c#oEsZiCNAvyrlM~mrYDeFhxDxEBJBOhU5 z?wmWU()4EUviIv?5J8ByunMZ6NO1xftbXc%*xo#E9=WeKHl63}rq~aUFjx8~Ej_g$) zf_Ko*;!E{-#>w4ME9j1n+Nbze89oD`O|850n*-Vwo}D=hH6QmaCrhgzuGe%5trWJc;k^@HB@_?00^z5S&r+svfs13jZp+7FQO64n}azoO#u z)@)=NhRYzV++Th*`u*Qt2>&0x{7j}tZ@QPZHiZ7TcHl`mY}3&XTV4yBJT&h3dhCTx znf)z#!VVfN{y9tIFTH@&2eG#fz}qV%r*a?qH6cf#{({YMOoD;tt@Ev!u7=>&AE zAFr)8S{)EXx=P=X-#+m1#HdFgc($E_P&@XW%eL~>pVe&YcR48zry2nikjeL2s>X5%KoTq!a|sUX=p`e%jS& z@h(lvIp?v8t->t_{eVZ!`%U{x#ZdKVO&nKYuEyj!&zAb6CD>|Mnhz{86~%={k3IEx z_=T+sSic=cjiAUMW>#_64Vw>2A>V;?0NUa5+wbNxS4A)?Rq?_l!?p}AA`#pGbAX@q zm)Y{Or0NP0gMZm|-k4!m#bD9teCh<3J`$vIoc$&33qoy%j*gfLF8Bb`$4SWv_O$pKX9_cH={rw?D7BZfm8XHv(B@-1m z{mJPK^VHAY=0U{Qa}i0Ay=3wyP-wotlr)MW%4G+_IkXwcKS+C9Q}HUQVK-Rix76f9 z1MQ}t)VvqsgEO2stDk6%zh!C3N~`oWXQyY}7kjL)XC_vPwZU4axymr_eFCx2i|SXi zUhZikQEop8i93q^P;5J3r%1#x{bd6No`_#KN6jg>Cm1J@>EOK+Zci)0F*nuEbSh?4 zj89Wn;Kr}SVce+%;qF`g8FnU8V+@u}etrw`R@v+WtbYr>36EXQYbq-XonWU!GaYyA z=L1mFDCU)0c5e19#=_)l;dx{NNbBQS;y?7^KU8`CbToJSCb2=0;#YANh1zv|y0SPk zTgE??TKF+;VoJX*-N*dvF?}slSx-zz`CyPN^O`OYXujGMy6|X;ok8UuVa_I2A9u|m znZH@|+rb6c$_M0-`7F!PSJe8Hp(}9V+Y& zvI!QKpZH!6+6Ga9CS9*Blx_zLROX(k467c~_Kbpv*2S8+h|OHdxs?XXa;^8ljy>II zFIrF5Gg^!X9r)n&-gujGp+sN-`&kRkX?5oVlQRrelU^n0+R-tP+jn2}`yAL->*h4i z3@FJcP<%lk`zu#I`_Iuc=Y2@-b=w)g4oi1t*eobj`Qn#WGP&{$hYhn9oRUab{JqZ% z@K6H?L#;@okBCWd&wsY+@XhmT!0-%M&|4le&6Xtf7|5mO2i9*}c*DGM=>V=*R<`oN zu55B)oU607RS!V4QyGL?)VIet<}EE~Wp|OKdrA6lii$h~{%@J2@1J&WCc=K|Ec0LK zh!Wv#uN~b}8Xn`lEj}d5%dc1z1RCDg&^QTn>(2RUsG*`6HEcc}U9b+We;IsA3Y{Yp zcHga{z>|36<cxteXrB`l< zvb5Yg!xM2COS9<3RstfS0aEGBeo5jLY zM#2J>s^%nUnoxKZVeM4+8B4+s4}JKOT;+j;*2>ZGw1-A?X$h!yYGl3~KHZ|Ofr{1A zisX+3bj*O~Bi)1CAtM?=0JAL;n@4S*OJ~sVaT(FSktChEE)r6@HE@92~Vs5Dr%`FSzpj3#{r|GvV+)Sotc5_57R8F*cvf67y5pmc}LQJ z_>2--8gSO}js}6EQN@d4oN*kuJTkC`Up)7#*gT)9h>h|1`OSz&M!S(IwaS)EvhF6* z&I1vP(|-e%Jpm}oPYxF77-0+wopa?n#dPAA>*^rY+({0$v;o(_D_a)hnhXJ8*tSSj+?`sWJ~Xz_0jNNhPJ8yhA+s) zW_L{9@Zz7=dMijIHFt~&3Yf|h5|%pgXT@@Q^klvs`>{eL-yQjUME9mTOajc-W2?5- z4wCB`LwFPy)T7SX6W&qgmveS&*8}~<#HfQU`PdYk_lC|wK<87}SDlha&ldd&J^hF{ z%+rpIoXWF*=;r_3MyDK?b@r8prWvnd_9B%hj%Esr$U%GBK1U_9(eFft6+~eA2Q+!k zC^Ny|{-5)YTRA@cdMq`6_23SBgC>}&<95sF+TgPvrvub2#%l|HURRBnr528F7f$4v zr|hqV+5g?^{%s+@9pyaySHWP^Bl`0jpTDfk1qUMtBlb}vy!XByQ_O9l;w-x(P<_N3 zu$T{587??SH!EX$%etrJfzmDD#ca)b)+><>;6wWMP9}>ot}Xj=^}J_vSpUI%?3fW^ zMKk9qV&T@Rzdyzmfj~vUxs81AMtt!K)$zO+^fdVH~vXO+B1VuzbH?+jSrpo*ti#Zo?qw_tN85C~xDi}vL_AQFq^&)GF4!@zx z$bu<{g$~+Qd4;O+=p_y&;Ve?$plp;Cb?U*gQJwdQywavJ+sdSJuH~^{N_Tx|EI6LtcSfs9HHxG!KKJpVhWA)IH zcg!2C6>jTJnJ87GcL?Nn^uPz3z(aKW<946;zJ(l<`z*8$x|xM;WTEt|_22X)u6LZn zc(kYc^AeIhXbCVc3t+PvQ|->QO^;Or%~(Lryx_?Sz6WL+eKLaq*Ev~VsxeV#szo=R zPxa!<-y{!d`=jS6WP1$CR;J9a9@CfR3cL7r%oW@bfB{oo0$j8C<8o8DLY(=ErKn(q zzj)=}`qO`J$@h=)+iUYmvAuZj;4@`!fYEamJ*^NayA7mBtpgA|RC1&Tt(?ROT-cJwo( zm6~Zv7{a4DyMV99VuG<6m$bB~vPov#Kw~o(KW^83*dqf6_#W-E_^gVpYh#WgRspyr zg}g>7;q|BGS)IBcTkXd1`PuaMku%V7<0a+|-VrV_h=r5UqQ&d>55@j|s)4EGRA#&+ zMeR~iiu?v4IkgCi&K7-ark6->(p5H88J~LF4oWR>8>Lc#^R_;ha+2J~s-~)485BpH z!JRG_*qqPTV}9$Yn&IhT`vsKYO9A#dC*6JAuTl;bTvJ?zuO38VM0zd@9^kJl%VSLF z*a8W?0yVUfVv>k~=KY;0RcxSI+53Y%)dXvZTLWG375rw!Tu$t)$$B=Ofw9Yym3GtL z_^9C^7{>}7JE!Nb*EiG|MPSMB+K!_kz|*+5RW>UYrZNxj%lsNFau&Pf@7((~h4hh> z92}_ny~=;ZH;?l;d>1V%WTayhR=k&%B3093H1N(hG-S>5-WSUIt`GV1$%T2>qM@VF zWY$o3`F!Qd_5Z@F4q}GogoenAfvRGfZGR1Me@b%)hw#6<% zgoV?~D7dHkhpzO$TmtaP|Ha*VMm4#u?ZU3DF1t&FNJpg;nv{S6!L1THXn=$okPZm} zOz1`5rGgSjkPe}!p@oD56G$LIaH+IVr6iOHETu^o5Kt`Zi+i6v-uL~!Z=A8u`E|yb zKX_n_hva$YocEmbzVGY4uHIl-o(U(cnC%!>QDN-R;-3$;azfqDO+3DpUsR^4l4x8k zdGox-)AQl92Zce4$FcHQf8*1@r)c>n{3T~2_Yt+SlP5oL0E$*RA|*uRTNF%IDQes7 znphvH90u_l<;fE39r+kNNt!FjPro0F&f2hlHQF_u&*L~1W!hKVqR-9%07fN69kIae zig8H0<&}Dbot^T-b8k;2f}ih_9klQX?YzfJcl0<#ZE({Bl;4Ss0Tgw#^&&AE)!3& z1wnCM&02nQdNSaeoJtD8`U}8s{*Z2WPJLb6L2!C+eEMpYPzV>#hi=! zL?W~lY%9yO8!QgU!_0M$PGqZBC*Tn1d_e=<$lR5wKDMZwwHgrSr&+e!0;TzT6p2_-T`Wn8 z6beaoYe|tpQq;^7DO!q$!eEgP)5c-m0V|J+GG^k{T(xszcmoo-sf&%Zm`?R2hsf+q z-!jawL3==5(3aoI0ZkWWZT_>Z( zTjEEm8qT@cKj+<0tlmWKx+pmHhS7We-FtU7J|itXXv*9Obk8s>yf6J%ZE*+gwYf9ndhW%R|sMr^zYHzn~qchlpoc&TUtnXMOYt=j2@c{{I`dA~S`}`k~ zsC;+$YG~==iSNJm?4R3J@G@EvlR?XsOFNWl86EPo09Z-~*FXyqh(GgU~7?@MD7NWvYj|PLdcIq3f z1{(On9sWjL40a%UKVS7(w)hck#fXh?SnSKQ^1pN9@Av;}-~2EA{(p?8V0fAMt*Sdp zXs=`!5)$%lCck)lnJf=}VD>G9{HwNei+xULP=TP~O1?@egYkO8W7RHssjv?gH3 z4L{)v?D$+9X=K9Afv5^cdJa#Xpkz%Oq~Ia$YoPQJePSLSI~wYWPrQJ~Diyg8Z0t{M zYLt3f#SC4n_H@oN)%FZ(gzxZbR*NkC&F9lna2Q{QOP3s)%m|O?RM?+lt$6c*tOIwdxPjaPXzr$HR1&U#7Y2AJQ zJ|OOYX@>mUH$w`5ag4{y^7prjzo`UFX(qe|k%XC!jWqXnC1o#*?r>Fn=agjKEj(B9 zSBE(rrjJ0jnE?vbNLy$qOt!Z1Y15^5M|;RxS&`RYHPn%ZK>A^e$)Y%A{$$jNDVMS8 zn!B;|k$kn5uI>p9$+T1eHp|nIC)0nc#&9mWl{3+3qsN%?3lC>kZRaN3#g|59*~mJd zs6#;!2UZ;#Tf`*w!MNu7jt}Kof8zz(i%!jo#uYR~az4 zqO$g0klU9EeD`Oyu;^2LvPL~8HXlGI7U>PY!BU@6GSj|RR+W~bA%?31o?5y+fFz}y zAZz|$3*qP4(dggq<^S)E{}<#n{-$Pva|}q_^$+<`9Cx530~G(8Rib3p7Yj&8ZvNT! zx2GLUt34QT6g$-p=b(U$)z|NR1`n;)Ldzc(dcBSb^5dngMx>Qw!4cQ zqg=ciaxYyL>v(qDPUhvut{}I0l?PWWW~ABW43Eo7DEaxjS4WRdqGIel&rRxj ze;wI&uI%ldH={pp_p)35s1T5OIPNUX-3X6Osg{zk~f zCyje%NAkWN%25~bgL3oV5?9|U6L}hFfkt4XQv==7)NCqbTnpZu!LS}l!gOA9`aIRC z>M?J|(DWKr{e*=8J zRN@hjx$;hU8blxW(vg(%(m5*EsTbots`vIYM$=URL(&*KcJQAsYcgpNrq6+mY3r}} zahPFdi!rh`pDAPgQ|V z3V$1Jn+~&}dN_R*74kSKf8t9pwLmu<9Ds^ozcRJgil8Y#H&15NH}P18?#-utSjoUu zto)lE}ivK9OI#1uj9e^OWxE?SsU~nn#==y*@2ny!g+yisc_w74e zvZMjdTA#$1@1g%Zjk&;|HIrZQwwe%405B&n#I!IGz8r6P^WVz7#TUOXriXdrQ&ht+f=^|$3!U9NB+3ZoW6lJ%t|?{ z;^s!A5=Q(6HOb}3%eK9lDO{7cP!9I-W4oUpN@y(lYZiemJ<#*Gv{HJ_;XCSt?(*Qsnw>{v<2G+VV)pa~{d^Fl3uq|<0F zpWwN=n;vD?yT4reRuGXscgeowamI#R%z$L$54vEq5cceQX-h#^uxz4ceHp&i-#iEt zbM>Y5zrOFE*OTT!$g^^3*HN zoRF1$C3&- zY88)%x4vrku+3LXwIEw=hI+JH*%iL;2CeryPVIDO->_{WR3|z5>{0SX-g}hN#8-hWwP%1PCR#jn(KQFs=0@BU)6 zHka*#)kF9*DpDK9PB$bDVN~`szb7pX5{8M1gsp6fXbso zHXOWwxdw z?KJq%oCeiqUv~ZL69J$PK3_DZrYp1}cG1^%uFc;4E)|))YY_FFD*f){mTSM6&G$N+ z@4U9fvtIOTF4LY46J>la@G}3p`*}R z!=m^?+>&=@V&{p*1O)hC!S7}uQ=gk}9KyJ%RRGK#b~YQG6#4YiC!*vS2xW z(ojaru+p5x*2|&4|7Vx(r};~loh>$uKA##GH|6y*ea>H@r9;hcVZtCAqU`EnHe6Wk zI2is#!mH68j+^#dtl$E@O4-2D@GjR0dQ6S^}j#O7pE>C)?E&@ZB3Oj2fk}nPR;Yy5HR!}m=nkW29ndQp^@)qmtDG*Gtwu2NpBS_Gsy|Wx=l8MX%5xKIxZH= zdB2s*^KQL;b^5YO8}qPNwOoNE-7k1!9BvSqjs8&if!~%?>$g^DW|^)`g1Ix7#v$UZ z-IL4i(Hao+!DuEOc`Q#J(aJ6QhJeVUFOB3yt&gL2RIAAW*sI?QKwtIssLa_|gGXNv zS^#daNyHG~xjdutvLi}FY3V$NDjV67&PH`wk5^3tuJm5<`Rsr7)c@pq*0d4r2Eu&V z%9UmY-R+;c6vISMu#l6c`H^!yDRhRi>=TiiE3cED;K1r4d-!2(Cqy?SeA=Vg1-V83CxKK%^h72oe*W zyrAR}h|7nzJ9Cnq0|V^h&yVl_wNK8-XV#Im`LyP*eQNZ_fA&V)$-k_MzLQaNTdpT; z${;I9Ubcm?AxOi22B&(1<{HqIp88*OY)rnpzv?ZtPUBZs^%xt-g-Ga2ef|}Hl zO#t6rYG+{K@r97)Ij1Xu&LP>27h4Qrts~3GSV0jALfF1TPFBGUM76-I#H+K3gAuh& zBUbyp1l-W`<+xC3ao7ibR^ONvn7j~S|B_bsw6SBHx*V$RhaJS{vq>^>rK%#b!lVIz z*wRBv24uno;^NR9QxzfIRgY4VTdbe|t@zwV`aG&)uDB!Ii4{X9a<48AMvlKS9%CLW zPhJG(?T|}H-J^m2mH%e%oU!v7W!3o?D=8zvnGh>bA108F%2A)^07MN6#gvAA%1?jt zvv+Rg7~B|J@f`2H>!E-23`mBPRZw(Wprd^+5rt+UR_?XmK=RLeETbt@N@*@lBs-pf zy6T{<4U4vL$#r1?@|<7zl@ar$kwBFM620w0+bB;dPln3u;E4FO9lG7~t)CEVs)-l< z@J1E+R;(;W)5n1%9NrJR4ztipevX@29d#1M(o49@R68_#^6`DaGM$zzQK@0W6|iV` z4r*L~?eXKN^I!Y0j}ctb8`)-H^1mVW)0!SbdilY<9&nEE_>GGJyp{BT-yO$16-Dy~G4+ z1Cj!F>*J43+8TSXuj59sWvQfv6Wmr*pfVmuc?VFj$Tb`S`&)LJc`8L;(#7A$m0cvHy#!zcjQJyo%2VgLd&*>gPR+LhmG$+gt>n2=*}HqJ z?K4+k;?09T@TI*I2_n@DLVPGnV@U(}Bx`WM&iVKwmupH%1}dp=w)Jdyf=I0$6W%R- zxDppPZm4f%=me6N8#H5f?Cgjfb{HL1P~=7-fEB@U|Ln#6v_Np#*?U%Mdc}cpg0rXV z8)gP`yMz5UKF|5oW-nLpjG6sJBj^Mfgkhp<;Z*OO=n;1JSax3H`3TnAHU7yemM3*B zS{ok}ZPrR4v148l{LchKYlJR*gQ)L$yYAMS;6)nPxi}c-8a>T6aM3+8G*(qiCj9OzNQ#%!jHHr z{>xnMwd=_A5{TwvV$6$}xWD%8R$BIcC{7Ejnk#z_J##87yRPD0R-D_PL3E9JbIzZB zWhO)$K6$UX^N=X~=;8$K8&7)73uQQstH1)zd-u(2#dfCmp*UDEg#0AfE zvt_jH#AC{f#Gri{lZH{`u0)z!2t;Wg{ov; zCQmP^+acZJ{Q0pe{NU*e;mQk}hDAJ^%HL$(86!|O9xH6TM&zhuaa3%YAJtYfkQ)mM zg*!Br+XUfP66HjBFUl&@CExR%(+_3x!F+iW^$Ijxi(=iEW zatg6+@}sJ4@86E~A5!9JDD-70N*{O;urV2Wc(OVAor@@w)uDUN+Ydx9ptw46SCxsr zK+mvzslfLXkNFM2X%NEj!YXH|R&S2>1yxc5v=x|Jdx}r~TAy9p-B27VPHZ1fh;s!7 z_JzY-1C3R;`!NqGZ#7C|jAlkm;?u!qjVw?H4W9)K@Sim@x|Q+n_*wN7Hb0=KnK$Qu z3PUoQ4qO_;6}&B_czQ0{BCb0Eal%_1aBt%c_-M;R+z!-fz-3->;pqHJIoybs4ge|^ z*`(De!K73`d5YC0qBYz3(zqpQ#yoWQrs*{gbVxe$1cGq^k+a_~|9sNa{`^0J^v-CJ zqTp@x?9KpXw=o(|z}I3@otA59x|N#OUpc#9K}2MouOo@PRVYl6T16y6EWCi_s{ZmB zYyIGXOoFv&IHqN}3Y~h1juy`Oy!zu-M*}A8^t*5M+JaZ^#pOqAhBkGbahyX;F!6pu zZeG;j!CASg@mKh9<;pcU<6y3X>8kCX5P1}ds|M%3ad6sU44FN$_);=9LC#Dpmh~cc zP)H(AW&~ydvwyll!}6hcY@Rp}55bUPU{KC0wd;B#<*}*x#bc*Eh_Vq&U(hutgkPsU zEQ3E6fBzi-fB4nzar`@4U@lMUtHGVc(H-(g^MN~6aQ3*5TaF540U#H91kK-gV@CjT zZB0_4yoP4&_e%(wtKaCe;|X)Is+*Om0e-d&>#SxX#6Js1?R!8`a=jdITMw~NQU9Ea z_4!kn4i9qQxj7o{Lm%W?ffC;~;PnB@8@n0ke2@=$e7dXsfhTXPhgC zfI^fmGUqHH-4Sn_3FBtPzHtqym&J4D#yY^7`IjrawWZB21H{f}^Y}678re*PM=|5Q zJ$sz2n^PI(IZ^Y})}Vsm367<3rrpl@2Cw2SF@B~xSo+52r`hl;3UaHQk`4~TATSeA zP4!F#V^irGD1})Ji;e;5&skE+okg5Q4m?h5-PKQ0>sqsQav!y-dVe#So^U?a$6r~> zm(54pOUiZUuGW$s?iGG(`)ZT;)nyqXURk@mEc8I2QNiz2hsV}oQOmA2AzYYK71sHB z1eI8Np~ z-3rWf(XO_&XO)KL_SDiEJ);}p1x^ihRjoNvWb)4tae4~mExCpRg~sO{Q^tf(6(*e; z(_s??y>T0a{xG>ptvbCjUP0H^h`jYIed75eta^D+yl2QKK5TWe#VNc`b*l0GL`vE) z-`LKZ%g;qWX&m+r#t{xySK$t%W_ff;%`+I~j~y4@$#MW*^pyqW&*7j9>zRNxYavt6 z7+7doB_^H-i+?^0Z_TXRzI}cVIqtLcnOFAi!H1W3>ec_+=lCQi=||~b`+mKQp8Zqq z+3Ug=0qbTeRUf)nTbfuw6t-DiL(lrlo_W^@*h5RoE!)hc zp@IaK(ulLmknIQH;zDI<(?lvs<6ItReu4mJEtYja^_}L;2=ErVe@-bKDZ*KkNWcU& z-=Fc~14kHK;q6CB-$xO4=*9;%i0Dy4E?XEPP+)PFMn5KKM7*P+K5JZu+}REGy0a(u zU@hy8t+W0MufE6pGAM+()Oe8d^vGWp z3}8^xP><=r+7^_C?PRpZhnl{5##GHBClFG$cu-X=-bJw2RP*e4PiO0y_LLPJ!Isn# zGSwLU#$FItZSg6h3QkI>Lh1$Ph_57nB^kb7m06t}tpRx!EJ9zO`Fb|Mcg$q{26tPW z1%EiZrDqGaojVOPQO7rqdk#BIAQnY|^(;~Yg6@E&37YYVZcT}z8Hgmdziq<2lz7O0 zMS2(6JY3N%C*F-?T+<>K=lSE;I}&1`k+DhF_1g@_EXU1{<;}!bUEFE(7&zB9|9 z32Xb$hi`Td2`B1~X=gQLJG2)d&^k7jf*N%AC-?-sLH}du*KHRKs9iww$S_B&uk08) z>dRF|$IKFmXuh&A&-V+Df!=n2qoSrEOF&be|mUlrN0 zHGOaCEgNgj8H!VbLyz>Yw)8<^v>9OgOnA%UD1Dc}wZhsbs4KHu{L8G2#~^*+ku zA!QD;W?=#IS~FJ!QWO;_^jV83O3UF=Rq59p(~drTcCy3h^LvBiQ@+cT$9#L^u$%6d zHp}IH6k2eTuiCV2!lLrsCCv!to-^xUU287OblJYt0k;b|1gxz`glaVEs@F8~U;ZlE zpX0`T0}}aAarzV`t)J|jY-WKLin1^RXFit+_JTp;e1lM&R^f0!c%MPln}Dqdbe}(k zXrqC-)z7v}#QoVfU4u@RbmJuv;o6d}LZ6q>WG`B%#}65CGA-7$xI~ENa{ru3r zc#kIg$X{Hn{$utLXL%ltQXA-3(tLB(1Y!3={t(b}u`+b=)5ua1ziRd^ivyPG3nCQ2Evl=Y#>6vk%!MJn8uj0_}a{b%u>$A~MqoAU7C!+++?C}dH5p8C^UuJaW$1-ASu`TEP{ z4*b2W;ots<7b9&YaVh+xeq*V^KQLYd>QKR6*U)LnbBSsb!}ZRB>*JxxED;3bhu^xT zW7X@V@&~yBcX~s^=ZQIh(Nfp>@yQqX{4@2k!?y*-)i%+ew#6FJAMHCnSGVmnvS}9E z_V4}DmAyATtE>)UGO)?v8b8ctn4Z80h4JRo&OleC0j-#IgLnYw5x1m;BJBZX>r}LF zC$22&JKzgOMMC8GMT?qNcThj|ZX$#&+ty3MA!RNu4#_yA4jWlNwa)5staGv6o2J-S5%^ z-ydJuYb=QH8J_;pe|b=qJU6f0CRBPPBkKqb8i)v=git2Cp04Vx#yIj`Ka15R?i8r3 z9)H7|C-E^4P=UOiF3*JIN}cP1?H0pEB}j0y7jeOp7AvzON_H;+Wr$UbvHqU?!xffv z<9Crw)4d47kxGc$(|ikuZbpX)eQ=cug`N->BHSBvnkS|)C1<@N!mTcb2+!QQT)H9r z?f0<>p@Q>;@SM*Tslt1;=gpcL2UCS=nROZbTUNX9@BfEnACV{U!(<5+;G3`M77 z&LzB?ZjkFxtK(cO1q`(nVN*76)g6}E2eZCi;+ql=GWw~`$oky3pDXq;H$VYTy4G# zu*g3_kpg6`;QKI&BoYNk0s>=>;ZuVZ!3^8^I(@b=P`89!=siB}8K!k`UNb0W;9{GC zFK`f*)hi5mwk+~vCYKo0$)Kw_LXs}&w7Rw&3mxyFx()D{wsUp-)N`_&ioQBzl3&TP z$rv^{;`CI1Bq0cZv@Y_`TFhTZmgitdxl{$h7#w`|J%B=(A4utlZ`{I0%wJ}!l)M9f zOH2zB*K5bRG*ljCo+H*(*bNL;f7+V}5L>|loI}O>;B@2l zS0rC!nHpZaxhlrlF09o&Ec`0!qF3zAw$ZaC*h3=f(HN_f^XAZ!ax1N6rE}X%UH>4( z2`y@HuiUx1o8_+7Uc`clurn98PY@Qb#gXb=?LcxRQ4aajZl42DGg09vw$!MmkAx^+ zu7E4D0%0E7RNGSG{mU*YyXwLEdauJNK%h=!8VBlHUlMU`_m48Y&?(i8HDmV=&wp5j z++<3d+Y}66d{oxS)C`)hlrzTV?IwPMQLRm-E;t=g=NbkhM;l}MCh2b}n+t$S6ZTik zh-8{3y&>!gHQ?0nrsXw5ITw2?8wDXyZZT#mM{}q2KGutmf;ItIr$InH6JeI3ikFoI3u~RXa~P??lG;slEq z8D*!9CCxboTzcxpsMS0x(`+iTvDF-1sO>Bpsu{{xb!`cNw{P;1wYW)^CZW|(s$yrbEG38$55ibe|CVsd|Wze>* zXC@2ZuRjm2Da)WJ2Bdhy{@Ul==~(xss{Q-qboKS&zxI82>~RMPz0K_ptZBu%-eG5c zdZKz#H~TrZq_0l!sQ9a`eOSO$jr8qbBv}{Sk5BL+K%bwZW*7JcdPXC|tt3 zU7J>*CMrPG=$mCskt*kgCUmj}!^*z|m1X2Spg`NkAcHsEEtNBm%k z-%EX~jMdr*OaJOn&-zT`iw4JbSNsZFa&i)eOpL(g57wt&M5bFFm#VkiJvr49^Zt{N z6~gBtFGjwL)`A=eYYD9TnQkl;=xv%YI!4W{IHD4I{!h5Rl3NE!gxQB#pnk$r#Kcu9 zATZGh3g)G#x-G(ZTdd5!9!|=eDKiMyzHRlQq3UuFcH+AYHv)N+0iOq4*<;ux!#UqJ zCAv(dEqgks*2LzO$0VxhU;C z#f%ZA-Ac`aTscxrjuG^VoBF?guSV}!*&ai#tWCd=Z7gX;v_uhp$-DX|XMTns=Xfh? zko9>@wjfN)O17JM%$rVy$6lQo*6*#H3t62wW`u@ojgpoXDH;jgYRPP2Rl}sF#vHYR z{T5hrb7E#Gl)MyN{UA`Rel{G?mfJI1EhQF8MvF@26` z5%#@6&71#poaEmVbiD72O$QCCcyZ@1A;2n7c%JIBLY@n-AK07*@RO)?opm0Ry}4< zPC7p6c9{LuI4xj6Y24kYLbGF1^UC5^7z8x!vZSiT_B;?j%dvNbQ;mfCvtZ33lVp#v zyxy?kk-v{N<3xd88kcy8oxrVtRae=s1j_{!PFU_3F$CM>nuY}sASUL~YbHW+=l-u6 zw|(ge4>wz<94`bWHQSG>4k-V4dOb)Z0TJUAx$2sj|LlGNHn8@w&K9s+aOGfb+?r9e zrtX7V*}+E|#9dTC;rQY28!d~nH8(4QHE~4=e79MQQR!v}-xWl=TMB?mjkYyqH9D=z z@ak0#>Z-wBF&K^LjQLl{$1H6ebw#C&|MA4DTB_3770J#N5W|*_CtZd#JRCzTa+SdKFwb#S>cQE16=PRzj zh)$CTn1zegc2|{Pp;*&vsmZ6d`SRsgpboIr5yRad@p)JLPPGbXniz-V<*dsDf2*TI zLJCp-MQE~i9TlAnxFC@WVr_0nNJPWx-yzzDoO_&gy0OjaDVev$nN6?6isZ6Ik|*X? zTPqAYmNA@4sv{-ItVb-NTNIwNt0!dEgWEwb7}09kn zUr7A`7PG&5RlCp|CEAxdu-7?ko1d#T!|dsq$2Y2Ws*Z^f6P5o;wI+F4fv&AHIr4PTbWj|*8?7Ot$#g#WO^+rbFWr!=l1ow`X(LrBw7s zK1%glhq%iv2Ims2j`}u%mU~$?#{>*khEu2PtgZdj=I&9|6g({$w&wBmbY))aGMetb zbL>;pGW@IdcrJO8Rg=tSG<;}ts7&a6RuM9p3!9jDr5JosR~vNIIKv}8tFV8f?Nc~- zi&dWy&oOwJru85D_U%8m@J+Po)#S7Hhpew^(5hWlzMtakjJ%9oL^Y$dVY+Zrr7}Xi zH{bLF>Gu6Q3f;ow)?$?HsD@2Ii>U-CXZS4AQu%q>W(U0w4Qs* zNSIo# zeQ=Jx2yQ?keFExy+H!PZCxO=N3Q8PPyI^fW@s~T}YH5I_@i1?@sO2E=QAc#;His+X z77nP$@t$x`MiTL4ng)6lKHXkduHR=$R!#x>GrR+;T_$YCQM4rBv_v-hpkFnS@G@Bg z32PQ{7I|uO@lT_JWkMJaqg;na}`~T`^hz& zYg|RqRIXgCE!~+89QBOW^twiz2lpm=b+SZzR~JomDt=9zrvv1E0)-!vYf`4%MA!(R zuXCwnsl@wD`^Pe`eSHFoZeKfun_+}bG?ZP*w$r1<_$J7~k z;O2b5;=tA#T%_amThx$VA%5BXTF7L27Q%Ctx&MIB?Igmml2=7)6o$bsUp}|DRF!Q@ zu2fG!A!9U?`IT(Mhc4JyU6h#Cwg5$wIFixl8bPf}(bgo}<+e zDYx}wlp`!z#fJ&uGB~;@*y*atrr=sNW7d)dAk6vS^$D&U!H2tC+v*){L*%Xj!`{ym zZk3eZT5dX?(%hqI7lC}P#kL%>F+PKcZs4fMdQ`HS2R%bQ-t@ezUgzJaglK24J3G!= z8O3R{>aWtggOwSt=7GAt&@o*$v2xXlSr*HREiaNFAgc?>Zxg@;@|4!vGZWESwVV;_~XJT>>um&v@+qwNLRA`z*E5&egNW-9O&j zxGqM%kxA!uDCvi|kM#z5FFUdD_3Ay(iu|@^6P3lUXdF;b3#=JO?g+1egPD^+)G7f@ z;U>f{tMlc%s~2_A&u#;lciPVUFhM z(=O^0`4hr7c^cPly;FU8DS=+YPS@%s*&?-5g|q=%mxMp~IldYqHzrRwjsI#l8li>= zEy>HY)_9v$uJj6WwA_GM)bTn7TZRc>c=ep>CoLPN1iDT6AF~27Yg;vqB_Fj9&LoDl z#N^#MwJ5YTv24%gxB%;rrIhOE9Z$PeT09E^a!@XT!7hCoS}AYhKCDP}C68ipnPzV41UQeyjNin8gw=R6z?SdTr(1rUuL}lW3#JX4f zxAc=!4{PtTM3oDUJeT!K7V|60GddT<{t}1VGoeUtu-XL9eGWSPFry|;Vdso`O^LsH zP5*<=PG!4#rL(e}9Z^wA(l-%^xE&-aT4*;f?V4Bo^W4lSYLP}!ji_b;x{Brs!z1?~ zn_Y%MDLPyslA4m^D9Q(DMr(SU@x!^#23+V=9_nh=YZsSS&Wyb#)#eIL>LAtFg8Kha zs_<5nqlNkCi6?yNFzn%+coO~XfP!aPgtpoJ_v2;-8u$QCOz*3WrsH>eG?#pmWe6?=8Xu>y#hn#i@U7KJ4Z~)`r>Md9tn1^ZVKt3McGlLOwD|XYmo|0z3ekTK|xR; zdte<)>6=AmFyN3;Jp+LKekut6ipz=eE@ZUiqa{RY9cYlKU|bfNreaM7el)QEgT5M zo)jplenSL2{vW9=2r5V96FnWqpcg7W*0_Fj&wtM^%$48l>Q`R=zkwog={wyQ09TpPr0C28nq^&FJ980?~97+sy6 zvc%N_5+eo{ISZ$Mash_vw}|!PtVmm${@AS884L-i^L^^}d#OFc&F*98ho7eS}wtER4J^5Edslb37wa8)5PxQ5#G1oD=KW?cXb{cAr5~w9;991Bu79y{SVjruX~I zw2U=1wT-Mg&n8KfRBE$FjX+deTt!yU?6Y!sa&FMX3;nQ_g_z?kL0(_}fz(nc*f254 z#m%9mdI6OlZp6q~xTAORBH`s9>|?H(7qq5N^-WmOi-Xq~$BD8kVeQ>DJ2l2}&kYu8 zj1U%RN}4iDKqf_Rud>;DKn#~?!Zil5qF9FX1kJ*ULY3bKkU9X5Y!+n}@|IF$f#{H5 z`DaismSjfZyKL#FiO6aV(D!~vS$i@O_~Q3czk-oFM%+YWo-f1A)2qgA-JxYOr>;^DR3*@^+bmT@=5swI@enfmtVyU(`+KTsgMf-0b+>uSEDZuQyx+?0-Y=O zDtmqHee_g7X?R+zCJ z?MLv~-wN0hdm2%GZ=@B)B6r8Kk4&CDo|jhbDb5OvC5S2F?D*PCrT9SeiU!X*wEwMo zx$RRMFum_YyQ4f+m}@w!dqKVE7*VmGH}McpxeLrt(-)!165_u)h{T|6ZJtVrf(ZY6 z?f(p<{sI4JL{Wa;j6ke&CETXh8`2{x2K@XnU0}#wsJ*FQayR=+K#F$jlG=*V)xXo^ z)i5j;us#n82xqs4w@!VZim9xu7Br%R5eK3ryktLox1#w-P->3z^Y?Td!XLyUI%o+0 z;NN9%Yx<%Lx+W3t9sA0H$@4E~UQsH4?Ced8G3sht9zWq=CGYh8EBmxM94rBFb=&$K%#)nHcPT((X@HX@*|;7-QOrrydVyYq~lE{<2!;lD=geiolG;v#eT zf%#FE@nH|FjW8;v_0KPUH6!e=ijafMt>7f5>t@Jy*>nD0xeQmqOG8F0i@+YaVP_WL z{8u(~`@Yir`?da)O!Y&F$Y)$`dwyfNh%@6L#bj3dR2N}Z{iiQZjR+Tb3RaziS z{#2<`iJDD}E?bXF%9=pCYEu71`Iu@qfM5eDnJ`PP`! zi^4BwnFI;u)bVtL@qwxbzN!6h-kl_x{hD^X|-?mnSfjSD9g$x$`UE&vkvQuS$vwWNiN-CP@W1MBov<8prU03@(r^U4zVuUA z18~wqD8IQEz(7VYxD&7VH44t-fMcQAv=l`5bYeYJ{gpmGU-%%s9F74?z|SUE-?cO@ zRp8LmN+m{$(KcFn`Z^11e-4%9q)MPfk=5?2|E!hIUW95#sj7S{3=E7#=ihw!XzoIw zYgJ%gM>T$JEUEuirO!G3+yxX`-BNL__WL@2)VWyyqH@0fKg9&A#QD^UJEyd31AJ4L zi9VrCO~6GzbCt(7hjfZ)J{fyleIv_%2k;ln>(?!YTX+)g3qUSU#5)gSG6wBxoSIx8 zD?ZqGvn5j@`&-=7!v%FN6N%S;zNRjt+=i=BbE-iG#mDExD&g7@X#zkuP!z}mt3}Z$ z_ZCNjVq}nRDzRH{7Y`f*1Q6-cd*K6nv2o|bryo{G0>u*m3J zKZWompsdtp&9Q≠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 U00IC3fB--MAn@lU0NU&O7ozW0A^-pY diff --git a/public/docs/tutorials/llms.txt b/public/docs/tutorials/llms.txt index c72bdd73b83..e6d29c35eb0 100644 --- a/public/docs/tutorials/llms.txt +++ b/public/docs/tutorials/llms.txt @@ -37,7 +37,7 @@ These tutorials are for beginners who are ready to explore running quantum algor -- [Hello world](https://raw.githubusercontent.com/Qiskit/documentation/refs/heads/main/docs/tutorials/hello-world.ipynb) +- [Hello world](https://raw.githubusercontent.com/Qiskit/documentation/refs/heads/main/docs/guides/hello-world.ipynb) - [CHSH inequality](https://raw.githubusercontent.com/Qiskit/documentation/refs/heads/main/docs/tutorials/chsh-inequality.ipynb) From 9d9ede56bf3d187a1712f3a1cd62bd413f624aea Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 23 Jan 2026 14:17:07 -0500 Subject: [PATCH 004/118] Give orphan page a home --- docs/guides/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 12d4606809a..c407cc97714 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -175,6 +175,10 @@ "title": "Create a pass manager for dynamical decoupling", "url": "/docs/guides/dynamical-decoupling-pass-manager" }, + { + "title": "Compare transpiler settings", + "url": "/docs/guides/circuit-transpilation-settings" + }, { "title": "Configure preset pass managers", "children": [ From c627c8110c99f7375ff10c3ce8582209bc6419d0 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Fri, 23 Jan 2026 14:22:03 -0500 Subject: [PATCH 005/118] Remove stale image --- .../images/guides/index/overview-image.svg | 98 ------------------- 1 file changed, 98 deletions(-) delete mode 100644 public/docs/images/guides/index/overview-image.svg diff --git a/public/docs/images/guides/index/overview-image.svg b/public/docs/images/guides/index/overview-image.svg deleted file mode 100644 index eac06e420be..00000000000 --- a/public/docs/images/guides/index/overview-image.svg +++ /dev/null @@ -1,98 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From e6c9ed997681c6e0f20cd833e35010173e89aaef Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Wed, 4 Feb 2026 11:53:16 -0500 Subject: [PATCH 006/118] Integrate feedback for page ordering --- docs/guides/_toc.json | 72 +++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index c407cc97714..b672ce6ca7d 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -13,6 +13,10 @@ "title": "Quickstart", "url": "/docs/guides/quick-start" }, + { + "title": "Hello world", + "url": "/docs/guides/hello-world" + }, { "title": "Install", "children": [ @@ -38,10 +42,6 @@ } ] }, - { - "title": "Run on quantum hardware", - "url": "/docs/guides/hello-world" - }, { "title": "Development Workflow", "url": "/docs/guides/intro-to-patterns" @@ -301,13 +301,13 @@ } ] }, + { + "title": "Create a provider", + "url": "/docs/guides/create-a-provider" + }, { "title": "Integrations", "children": [ - { - "title": "Create a provider", - "url": "/docs/guides/create-a-provider" - }, { "title": "Quantum resource management interface (QRMI)", "url": "/docs/guides/qrmi", @@ -355,12 +355,8 @@ ] }, { - "title": "Advanced techniques", + "title": "Qiskit addons", "children": [ - { - "title": "Error mitigation and suppression", - "url": "/docs/guides/error-mitigation-and-suppression-techniques" - }, { "title": "Qiskit addons overview", "url": "/docs/guides/addons" @@ -431,7 +427,7 @@ "collapsible": false }, { - "title": "QPU Access", + "title": "Platform Access", "children": [ { "title": "Execute on hardware", @@ -507,6 +503,10 @@ { "title": "Manage noise", "children": [ + { + "title": "Error mitigation and suppression", + "url": "/docs/guides/error-mitigation-and-suppression-techniques" + }, { "title": "Noise learning", "url": "/docs/guides/noise-learning" @@ -703,27 +703,6 @@ } ] }, - { - "title": "Circuit functions", - "children": [ - { - "title": "IBM Circuit function", - "url": "/docs/guides/ibm-circuit-function" - }, - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/guides/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/guides/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/guides/qedma-qesem" - } - ] - }, { "title": "Qiskit Serverless", "children": [ @@ -788,6 +767,27 @@ "title": "Introduction to Qiskit Functions", "url": "/docs/guides/functions" }, + { + "title": "Circuit functions", + "children": [ + { + "title": "IBM Circuit function", + "url": "/docs/guides/ibm-circuit-function" + }, + { + "title": "Algorithmiq Tensor-network error mitigation", + "url": "/docs/guides/algorithmiq-tem" + }, + { + "title": "Q-CTRL Performance Management", + "url": "/docs/guides/q-ctrl-performance-management" + }, + { + "title": "Qedma QESEM", + "url": "/docs/guides/qedma-qesem" + } + ] + }, { "title": "Application functions", "children": [ @@ -995,4 +995,4 @@ ] } ] -} +} \ No newline at end of file From fba7bf13b7391046158ffb81638100ef8fb653a9 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Wed, 4 Feb 2026 12:17:37 -0500 Subject: [PATCH 007/118] Move addons together, revamp their overview page --- docs/guides/_toc.json | 153 ++++++++++++++++++------------------- docs/guides/addons.mdx | 167 ++++++++++++++++++++++++----------------- 2 files changed, 173 insertions(+), 147 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index b672ce6ca7d..46824ed3995 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -362,28 +362,28 @@ "url": "/docs/guides/addons" }, { - "title": "Sample-based quantum diagonalization (SQD)", + "title": "Approximate quantum compilation (AQC-Tensor)", "children": [ { - "title": "SQD addon overview", - "url": "/docs/guides/qiskit-addons-sqd" + "title": "AQC-Tensor addon overview", + "url": "/docs/guides/qiskit-addons-aqc" }, { - "title": "Get started with SQD", - "url": "/docs/guides/qiskit-addons-sqd-get-started" + "title": "Get started with AQC-Tensor", + "url": "/docs/guides/qiskit-addons-aqc-get-started" } ] }, { - "title": "Approximate quantum compilation (AQC-Tensor)", + "title": "Multi-product formulas (MPF)", "children": [ { - "title": "AQC-Tensor addon overview", - "url": "/docs/guides/qiskit-addons-aqc" + "title": "MPF addon overview", + "url": "/docs/guides/qiskit-addons-mpf" }, { - "title": "Get started with AQC-Tensor", - "url": "/docs/guides/qiskit-addons-aqc-get-started" + "title": "Get started with MPFs", + "url": "/docs/guides/qiskit-addons-mpf-get-started" } ] }, @@ -417,6 +417,19 @@ } ] }, + { + "title": "Sample-based quantum diagonalization (SQD)", + "children": [ + { + "title": "SQD addon overview", + "url": "/docs/guides/qiskit-addons-sqd" + }, + { + "title": "Get started with SQD", + "url": "/docs/guides/qiskit-addons-sqd-get-started" + } + ] + }, { "title": "Qiskit addon utilities", "url": "/docs/guides/qiskit-addons-utils" @@ -748,91 +761,73 @@ "title": "Tools for applications", "children": [ { - "title": "Multi-product formulas (MPF)", + "title": "Introduction to Qiskit Functions", + "url": "/docs/guides/functions" + }, + { + "title": "Circuit functions", "children": [ { - "title": "MPF addon overview", - "url": "/docs/guides/qiskit-addons-mpf" + "title": "IBM Circuit function", + "url": "/docs/guides/ibm-circuit-function" }, { - "title": "Get started with MPFs", - "url": "/docs/guides/qiskit-addons-mpf-get-started" + "title": "Algorithmiq Tensor-network error mitigation", + "url": "/docs/guides/algorithmiq-tem" + }, + { + "title": "Q-CTRL Performance Management", + "url": "/docs/guides/q-ctrl-performance-management" + }, + { + "title": "Qedma QESEM", + "url": "/docs/guides/qedma-qesem" } ] }, { - "title": "Qiskit Functions", + "title": "Application functions", "children": [ { - "title": "Introduction to Qiskit Functions", - "url": "/docs/guides/functions" + "title": "Kipu Quantum Iskay Quantum Optimizer", + "url": "/docs/guides/kipu-optimization" }, { - "title": "Circuit functions", - "children": [ - { - "title": "IBM Circuit function", - "url": "/docs/guides/ibm-circuit-function" - }, - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/guides/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/guides/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/guides/qedma-qesem" - } - ] + "title": "Multiverse Computing Singularity", + "url": "/docs/guides/multiverse-computing-singularity" }, { - "title": "Application functions", - "children": [ - { - "title": "Kipu Quantum Iskay Quantum Optimizer", - "url": "/docs/guides/kipu-optimization" - }, - { - "title": "Multiverse Computing Singularity", - "url": "/docs/guides/multiverse-computing-singularity" - }, - { - "title": "Q-CTRL Optimization Solver", - "url": "/docs/guides/q-ctrl-optimization-solver" - }, - { - "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", - "url": "/docs/guides/global-data-quantum-optimizer" - }, - { - "title": "QUICK-PDE: A Qiskit Function by ColibriTD", - "url": "/docs/guides/colibritd-pde" - }, - { - "title": "Qunova Computing HI-VQE Chemistry", - "url": "/docs/guides/qunova-chemistry" - } - ] + "title": "Q-CTRL Optimization Solver", + "url": "/docs/guides/q-ctrl-optimization-solver" }, { - "title": "Qiskit Function templates", - "children": [ - { - "title": "Introduction to Qiskit Function templates", - "url": "/docs/guides/qiskit-function-templates" - }, - { - "title": "Template for chemistry simulation", - "url": "/docs/guides/function-template-chemistry-workflow" - }, - { - "title": "Template for Hamiltonian simulation", - "url": "/docs/guides/function-template-hamiltonian-simulation" - } - ] + "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", + "url": "/docs/guides/global-data-quantum-optimizer" + }, + { + "title": "QUICK-PDE: A Qiskit Function by ColibriTD", + "url": "/docs/guides/colibritd-pde" + }, + { + "title": "Qunova Computing HI-VQE Chemistry", + "url": "/docs/guides/qunova-chemistry" + } + ] + }, + { + "title": "Qiskit Function templates", + "children": [ + { + "title": "Introduction to Qiskit Function templates", + "url": "/docs/guides/qiskit-function-templates" + }, + { + "title": "Template for chemistry simulation", + "url": "/docs/guides/function-template-chemistry-workflow" + }, + { + "title": "Template for Hamiltonian simulation", + "url": "/docs/guides/function-template-hamiltonian-simulation" } ] } diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 736d9ada65e..27595092790 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -9,83 +9,114 @@ description: Understand the Qiskit addon tools, which help you build utility-gra Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These capabilities build on Qiskit's performant foundation of tools for creating and running quantum algorithms. They are provided as modular software components that can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. -## Addons for mapping - -### Approximate quantum compilation with tensor networks - -Approximate quantum compilation with tensor networks (AQC-Tensor) enables the construction of high-fidelity circuits with reduced depth. - -- Visit the [GitHub repository.](https://github.com/Qiskit/qiskit-addon-aqc-tensor) -- Read the [documentation.](/docs/guides/qiskit-addons-aqc) -- Read the tutorial on using AQC to [improve Trotterized time evolution.](/docs/tutorials/approximate-quantum-compilation-for-time-evolution) - -### Multi-product formulas - -Multi-product formulas (MPF) reduce the Trotter error of Hamiltonian dynamics through a weighted combination of several circuit executions. - -- Visit the [GitHub repository.](https://github.com/Qiskit/qiskit-addon-mpf) -- Read the [documentation.](https://qiskit.github.io/qiskit-addon-mpf) - -### Optimization mapper - -The Optimization Mapper addon contains functionality to model optimization problems by formulating them in abstract models and then converting into representations that a quantum computer can understand. - -- Read the [documentation](https://qiskit.github.io/qiskit-addon-opt-mapper/) for how-to guides and API references. -- Visit the [GitHub](https://github.com/qiskit/qiskit-addon-opt-mapper) repository. - - -## Addons for optimizing - -### Operator backpropagation - -Operator backpropagation (OBP) reduces circuit depth by trimming operations from the end at the cost of more operator measurements. +Many of these addons are also powered by the `qiskit-addon-utils` package. You can find more information about this supplemental package in [this topic](/docs/guides/qiskit-addons-utils). -- Visit the [GitHub repository.](https://github.com/Qiskit/qiskit-addon-obp) -- Read the [documentation.](/docs/guides/qiskit-addons-obp) -- Read the tutorial on using [OBP to improve expectation values.](/docs/tutorials/operator-back-propagation) - -### Circuit cutting - -Circuit cutting reduces the depth of transpiled circuits by decomposing entangling gates between non-adjacent qubits. - -- Visit the [GitHub repository.](https://github.com/Qiskit/qiskit-addon-cutting) -- Read the [documentation.](https://qiskit.github.io/qiskit-addon-cutting) - -## Addons for post-processing - -### Sample-based quantum diagonalization - -Sample-based quantum diagonalization (SQD) classically post-processes noisy quantum samples to yield more accurate eigenvalue estimations of quantum system Hamiltonians, for example in chemistry applications. - -- Visit the [GitHub repository.](https://github.com/Qiskit/qiskit-addon-sqd) -- Read the [documentation.](/docs/guides/qiskit-addons-sqd) -- Read the tutorial on [Sample-based quantum diagonalization of a chemistry Hamiltonian.](/docs/tutorials/sample-based-quantum-diagonalization) +## Addons for mapping -### SQD for HPC -This addon is an HPC-ready implementation of the SQD addon. It is written in modern C++17 standards and is designed to create a single compiled binary for use with MPI. + + + + + + + + + +## Addons for optimizing workloads + + + + + + + -- Visit the [API reference](https://qiskit.github.io/qiskit-addon-sqd-hpc/) documentation. -- View the [GitHub](https://github.com/qiskit/qiskit-addon-sqd-hpc) repository. ## Addons for error mitigation -### M3 (mthree) - -Matrix-free Measurement Mitigation (M3) is a package for scalable quantum measurement error mitigation that can be computed in parallel. - -- Visit the [documentation](https://qiskit.github.io/qiskit-addon-mthree/) for how-to guides, tutorials, and API references. -- Visit the package's [GitHub](https://github.com/Qiskit/qiskit-addon-mthree) page. + + + + + + -### Shaded lightcones - -The shaded lightcones addon uses Pauli propagation to reduce the number of error terms in a noise model that need to be mitigated, according to the specifics of the target observable. This has the effect of reducing the sampling overhead for probabilistic error cancellation (PEC) workflows. - -- Visit the [documentation](https://qiskit.github.io/qiskit-addon-slc/) for how-to guides, tutorials, and API references. +## Addons for post-processing -### Propagated noise absorption + + + + + + + -Propagated noise absorption (PNA) uses Pauli propagation to absorb information from a noise model into a target observable. Measuring this modified observable has the effect of mitigating the noise as represented by the model. -- Visit the [documentation](https://qiskit.github.io/qiskit-addon-pna/apidocs/qiskit_addon_pna.html) for how-to guides, tutorials, and API references. From 4bd8970d2f6c718ce2abf03b44a465dfdd180164 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 11:31:11 -0500 Subject: [PATCH 008/118] move dev workflow pg to addl resources --- docs/guides/_toc.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 46824ed3995..e1143a7505e 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -42,10 +42,6 @@ } ] }, - { - "title": "Development Workflow", - "url": "/docs/guides/intro-to-patterns" - }, { "title": "Online lab environments", "url": "/docs/guides/online-lab-environments" @@ -855,6 +851,10 @@ } ] }, + { + "title": "Development workflow", + "url": "/docs/guides/intro-to-patterns" + }, { "title": "Migration guides", "children": [ From d1fa5909d771ac6e14910e7692daa4951526758a Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 11:32:15 -0500 Subject: [PATCH 009/118] move install to Qiskit --- docs/guides/_toc.json | 46 +++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index e1143a7505e..38e38e1f72a 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -18,7 +18,29 @@ "url": "/docs/guides/hello-world" }, { - "title": "Install", + "title": "Online lab environments", + "url": "/docs/guides/online-lab-environments" + }, + { + "title": "IBM Quantum Composer", + "url": "/docs/guides/composer" + }, + { + "title": "Latest updates", + "url": "/docs/guides/latest-updates" + } + ], + "collapsible": false + }, + { + "title": "Qiskit", + "children": [ + { + "title": "Introduction to Qiskit", + "url": "/docs/guides/tools-intro" + }, + { + "title": "Advanced install", "children": [ { "title": "Install Qiskit", @@ -42,28 +64,6 @@ } ] }, - { - "title": "Online lab environments", - "url": "/docs/guides/online-lab-environments" - }, - { - "title": "IBM Quantum Composer", - "url": "/docs/guides/composer" - }, - { - "title": "Latest updates", - "url": "/docs/guides/latest-updates" - } - ], - "collapsible": false - }, - { - "title": "Qiskit", - "children": [ - { - "title": "Introduction to Qiskit", - "url": "/docs/guides/tools-intro" - }, { "title": "Circuits and operators", "children": [ From 5df997426c33e2cd4edc9c8aad94bc7a290888b8 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 11:54:19 -0500 Subject: [PATCH 010/118] Rename hello world and move. Update link names. --- docs/guides/_toc.json | 8 ++++---- docs/guides/cloud-setup-invited.mdx | 2 +- docs/guides/cloud-setup-rest-api.mdx | 2 +- docs/guides/cloud-setup-untrusted.mdx | 2 +- docs/guides/cloud-setup.mdx | 2 +- docs/guides/hello-world.ipynb | 9 ++++----- docs/guides/initialize-account.mdx | 2 +- docs/guides/install-qiskit.mdx | 2 +- docs/guides/quick-start.ipynb | 2 +- docs/guides/save-credentials.mdx | 2 +- docs/guides/upgrade-from-open.mdx | 2 +- .../introduction.ipynb | 2 +- 12 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 38e38e1f72a..f6251d16321 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -13,10 +13,6 @@ "title": "Quickstart", "url": "/docs/guides/quick-start" }, - { - "title": "Hello world", - "url": "/docs/guides/hello-world" - }, { "title": "Online lab environments", "url": "/docs/guides/online-lab-environments" @@ -438,6 +434,10 @@ { "title": "Platform Access", "children": [ + { + "title": "Run your first circuit on hardware", + "url": "/docs/guides/hello-world" + }, { "title": "Execute on hardware", "children": [ diff --git a/docs/guides/cloud-setup-invited.mdx b/docs/guides/cloud-setup-invited.mdx index b192ca446cc..a8df3277857 100644 --- a/docs/guides/cloud-setup-invited.mdx +++ b/docs/guides/cloud-setup-invited.mdx @@ -56,6 +56,6 @@ If you are using a trusted Python environment, such as a personal laptop, it is - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - [Set up to use IBM Quantum Platform with REST API](/docs/guides/cloud-setup-rest-api) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/cloud-setup-rest-api.mdx b/docs/guides/cloud-setup-rest-api.mdx index 5d594c8c0d6..12bba3c3307 100644 --- a/docs/guides/cloud-setup-rest-api.mdx +++ b/docs/guides/cloud-setup-rest-api.mdx @@ -97,6 +97,6 @@ curl -X 'GET' \ - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/cloud-setup-untrusted.mdx b/docs/guides/cloud-setup-untrusted.mdx index f81c8e6d39b..ab0349d09db 100644 --- a/docs/guides/cloud-setup-untrusted.mdx +++ b/docs/guides/cloud-setup-untrusted.mdx @@ -74,6 +74,6 @@ Follow these steps to use your API key directly to authenticate to the Qiskit Ru - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - Try a [tutorial](/docs/tutorials). diff --git a/docs/guides/cloud-setup.mdx b/docs/guides/cloud-setup.mdx index daeb9aad6d3..664d8dc9305 100644 --- a/docs/guides/cloud-setup.mdx +++ b/docs/guides/cloud-setup.mdx @@ -57,7 +57,7 @@ If you are using a trusted Python environment, such as a personal laptop, it is - [Overview of available plans.](plans-overview) - [Configure the Qiskit SDK locally.](configure-qiskit-local) - [View your available QPUs.](/docs/guides/qpu-information#available) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index 0eac52fe7f7..5ad3ecee93b 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Hello world\n", + "title: Run your first circuit on hardware\n", "description: Get started using Qiskit with IBM Quantum hardware in this Hello World example\n", "---\n", "\n", "\n", - "# Hello world" + "# Run your first circuit on hardware" ] }, { @@ -48,7 +48,7 @@ "id": "1a3c196d-545d-417f-b34e-fa422aa9a394", "metadata": {}, "source": [ - "This example contains two parts. You will first create a simple quantum program and run it on a quantum processing unit (QPU). Because actual quantum research requires much more robust programs, in the second section ([Scale to large numbers of qubits](#scale-to-large-numbers-of-qubits)), you will scale the simple program up to utility level." + "This example contains two parts. You will first create a simple \"Hello world\" quantum program and run it on a quantum processing unit (QPU). Because actual quantum research requires much more robust programs, in the second section ([Scale to large numbers of qubits](#scale-to-large-numbers-of-qubits)), you will scale the simple program up to utility level." ] }, { @@ -525,8 +525,7 @@ " return qc\n", "\n", "\n", - "# Create a new circuit with two qubits (first argument) and two classical\n", - "# bits (second argument)\n", + "# Create a new circuit with a hundred qubits in the GHZ state\n", "n = 100\n", "qc = get_qc_for_n_qubit_GHZ_state(n)" ] diff --git a/docs/guides/initialize-account.mdx b/docs/guides/initialize-account.mdx index bdeb47c624f..d868d4762ed 100644 --- a/docs/guides/initialize-account.mdx +++ b/docs/guides/initialize-account.mdx @@ -197,6 +197,6 @@ service = QiskitRuntimeService(channel="local") - [Create and manage instances.](/docs/guides/instances) - [Initialize the service in an untrusted environment.](/docs/guides/cloud-setup-untrusted) - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx index ea54f030a42..6ca6a08b944 100644 --- a/docs/guides/install-qiskit.mdx +++ b/docs/guides/install-qiskit.mdx @@ -299,6 +299,6 @@ In the Qiskit v1.x release series, the supported platforms are: - Set up your [IBM Cloud account.](/docs/guides/cloud-setup) - [Configure Qiskit locally.](configure-qiskit-local) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - Try an IBM Quantum Learning [tutorial.](/docs/tutorials) diff --git a/docs/guides/quick-start.ipynb b/docs/guides/quick-start.ipynb index c205aad3709..d4b05bf2df0 100644 --- a/docs/guides/quick-start.ipynb +++ b/docs/guides/quick-start.ipynb @@ -255,7 +255,7 @@ "## Next steps\n", "\n", "\n", - "- Follow the steps in [Hello world](/docs/guides/hello-world) to run a circuit on real quantum hardware.\n", + "- Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to run a circuit on real quantum hardware.\n", "- Not ready to run on hardware? Start your quantum journey with the [Basics of quantum information](/learning/courses/basics-of-quantum-information) course.\n", "" ] diff --git a/docs/guides/save-credentials.mdx b/docs/guides/save-credentials.mdx index bf3ab8b7a9c..751d1d0ec96 100644 --- a/docs/guides/save-credentials.mdx +++ b/docs/guides/save-credentials.mdx @@ -125,7 +125,7 @@ To view all credentials that you have saved, run `service.saved_accounts()`. No - [Initialize the Qiskit Runtime service in an **untrusted environment**.](/docs/guides/cloud-setup-untrusted) - [View your available QPUs.](/docs/guides/qpu-information#available) - [Configure the Qiskit SDK locally.](/docs/guides/configure-qiskit-local) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - [Set up to use IBM Quantum Platform with REST API.](/docs/guides/cloud-setup-rest-api) - Try a [tutorial.](/docs/tutorials) \ No newline at end of file diff --git a/docs/guides/upgrade-from-open.mdx b/docs/guides/upgrade-from-open.mdx index 11088712cb6..0ada4486afb 100644 --- a/docs/guides/upgrade-from-open.mdx +++ b/docs/guides/upgrade-from-open.mdx @@ -48,6 +48,6 @@ It is recommended that you set up a [cost limit](/docs/guides/manage-cost#cost-l - [Manage cost](manage-cost) when using the Pay-As-You-Go Plan. - Learn about the available [plans.](plans-overview) - - Follow the steps in [Hello world](/docs/guides/hello-world) to write and run a quantum program. + - Follow the steps in the [Run your first circuit on hardware](/docs/guides/hello-world) guide to write and run a quantum program. - Try a [tutorial](/docs/tutorials). \ No newline at end of file diff --git a/learning/courses/integrating-quantum-and-high-performance-computing/introduction.ipynb b/learning/courses/integrating-quantum-and-high-performance-computing/introduction.ipynb index 5e4bbd10618..1c67cb3c16b 100644 --- a/learning/courses/integrating-quantum-and-high-performance-computing/introduction.ipynb +++ b/learning/courses/integrating-quantum-and-high-performance-computing/introduction.ipynb @@ -141,7 +141,7 @@ "\n", "* [IBM Quantum® Composer guide](/docs/guides/composer): A walkthrough of Composer, a graphical quantum programming tool that lets you drag and drop operations to build quantum circuits and run them on quantum hardware.\n", "* [Introduction to Qiskit](/docs/guides): A set of guides to help you install and configure Qiskit.\n", - "* [Hello world](/docs/guides/hello-world): A short tutorial on Qiskit in which you set up and run your first quantum program.\n", + "* [Run your first circuit on hardware](/docs/guides/hello-world): A short tutorial on Qiskit in which you set up and run your first quantum program.\n", "* [Quantum diagonalization algorithms](/learning/courses/quantum-diagonalization-algorithms): A course covering several types of quantum algorithms, including SQD which will be used in this course.\n", "\n", "Additional resources are also provided in this [GitHub repo](https://github.com/christopherporter1/hpc-course-demos).\n", From 401fe8972e2a182743a716207acfd2ad9dfe41a6 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 11:57:27 -0500 Subject: [PATCH 011/118] move online environments to install --- docs/guides/_toc.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index f6251d16321..9172b0333d9 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -13,10 +13,6 @@ "title": "Quickstart", "url": "/docs/guides/quick-start" }, - { - "title": "Online lab environments", - "url": "/docs/guides/online-lab-environments" - }, { "title": "IBM Quantum Composer", "url": "/docs/guides/composer" @@ -57,6 +53,10 @@ { "title": "Extend Qiskit in Python with C", "url": "/docs/guides/c-extension-for-python" + }, + { + "title": "Online lab environments", + "url": "/docs/guides/online-lab-environments" } ] }, From 38f077bf2ef56308325152929c0a47e3ff43280f Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 11:58:41 -0500 Subject: [PATCH 012/118] change applications tools section name --- docs/guides/_toc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 9172b0333d9..04bf77e6fd9 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -754,7 +754,7 @@ "collapsible": false }, { - "title": "Tools for applications", + "title": "Applications research tools", "children": [ { "title": "Introduction to Qiskit Functions", From c939d65e49267956131e3e017d382bd3003b79d8 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:01:33 -0500 Subject: [PATCH 013/118] rename addon section and remove links to individ addons --- docs/guides/_toc.json | 75 +------------------------------------------ 1 file changed, 1 insertion(+), 74 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 04bf77e6fd9..1c507693dee 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -347,84 +347,11 @@ ] }, { - "title": "Qiskit addons", + "title": "Advanced techniques", "children": [ { "title": "Qiskit addons overview", "url": "/docs/guides/addons" - }, - { - "title": "Approximate quantum compilation (AQC-Tensor)", - "children": [ - { - "title": "AQC-Tensor addon overview", - "url": "/docs/guides/qiskit-addons-aqc" - }, - { - "title": "Get started with AQC-Tensor", - "url": "/docs/guides/qiskit-addons-aqc-get-started" - } - ] - }, - { - "title": "Multi-product formulas (MPF)", - "children": [ - { - "title": "MPF addon overview", - "url": "/docs/guides/qiskit-addons-mpf" - }, - { - "title": "Get started with MPFs", - "url": "/docs/guides/qiskit-addons-mpf-get-started" - } - ] - }, - { - "title": "Operator backpropagation (OBP)", - "children": [ - { - "title": "OBP addon overview", - "url": "/docs/guides/qiskit-addons-obp" - }, - { - "title": "Get started with OBP", - "url": "/docs/guides/qiskit-addons-obp-get-started" - } - ] - }, - { - "title": "Circuit cutting (CC)", - "children": [ - { - "title": "Circuit cutting overview", - "url": "/docs/guides/qiskit-addons-cutting" - }, - { - "title": "Get started with gate cuts", - "url": "/docs/guides/qiskit-addons-cutting-gates" - }, - { - "title": "Get started with wire cuts", - "url": "/docs/guides/qiskit-addons-cutting-wires" - } - ] - }, - { - "title": "Sample-based quantum diagonalization (SQD)", - "children": [ - { - "title": "SQD addon overview", - "url": "/docs/guides/qiskit-addons-sqd" - }, - { - "title": "Get started with SQD", - "url": "/docs/guides/qiskit-addons-sqd-get-started" - } - ] - }, - { - "title": "Qiskit addon utilities", - "url": "/docs/guides/qiskit-addons-utils" } ] } From 4d1395a4d740bddf78f2c5bb8ec6562b1612aa2f Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:07:16 -0500 Subject: [PATCH 014/118] rename platform access --- docs/guides/_toc.json | 58 ++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 34 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 1c507693dee..104e0490178 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -348,18 +348,13 @@ }, { "title": "Advanced techniques", - "children": [ - { - "title": "Qiskit addons overview", - "url": "/docs/guides/addons" - } - ] + "url": "/docs/guides/addons" } ], "collapsible": false }, { - "title": "Platform Access", + "title": "IBM Quantum Compute platform", "children": [ { "title": "Run your first circuit on hardware", @@ -369,33 +364,28 @@ "title": "Execute on hardware", "children": [ { - "title": "Qiskit Runtime Primitives", - "children": [ - { - "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": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - } - ] + "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": "Qiskit Runtime local testing mode", + "url": "/docs/guides/local-testing-mode" } ] }, From 3b18400954a803fe10fc27bd6e14790b5897dd59 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:16:41 -0500 Subject: [PATCH 015/118] move SQD to applications research tools --- docs/guides/_toc.json | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 104e0490178..1fa602a954e 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -743,7 +743,20 @@ "url": "/docs/guides/function-template-hamiltonian-simulation" } ] - } + }, + { + "title": "Sample-based quantum diagonalization (SQD)", + "children": [ + { + "title": "SQD addon overview", + "url": "/docs/guides/qiskit-addons-sqd" + }, + { + "title": "Get started with SQD", + "url": "/docs/guides/qiskit-addons-sqd-get-started" + } + ] + }, ], "collapsible": false }, From 47bb0c836ab5f5bb326dffb4c92107ee7afe010a Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:34:57 -0500 Subject: [PATCH 016/118] remove addons guides except sqd --- docs/guides/_toc.json | 14 +- .../qiskit-addons-aqc-get-started.ipynb | 555 ----------------- docs/guides/qiskit-addons-aqc.mdx | 87 --- docs/guides/qiskit-addons-cutting-gates.ipynb | 506 ---------------- docs/guides/qiskit-addons-cutting-wires.ipynb | 565 ------------------ docs/guides/qiskit-addons-cutting.mdx | 158 ----- .../qiskit-addons-mpf-get-started.ipynb | 413 ------------- docs/guides/qiskit-addons-mpf.ipynb | 149 ----- .../qiskit-addons-obp-get-started.ipynb | 536 ----------------- docs/guides/qiskit-addons-obp.mdx | 100 ---- docs/guides/qiskit-addons-utils.ipynb | 477 --------------- 11 files changed, 7 insertions(+), 3553 deletions(-) delete mode 100644 docs/guides/qiskit-addons-aqc-get-started.ipynb delete mode 100644 docs/guides/qiskit-addons-aqc.mdx delete mode 100644 docs/guides/qiskit-addons-cutting-gates.ipynb delete mode 100644 docs/guides/qiskit-addons-cutting-wires.ipynb delete mode 100644 docs/guides/qiskit-addons-cutting.mdx delete mode 100644 docs/guides/qiskit-addons-mpf-get-started.ipynb delete mode 100644 docs/guides/qiskit-addons-mpf.ipynb delete mode 100644 docs/guides/qiskit-addons-obp-get-started.ipynb delete mode 100644 docs/guides/qiskit-addons-obp.mdx delete mode 100644 docs/guides/qiskit-addons-utils.ipynb diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 1fa602a954e..b4e120d324a 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -13,10 +13,6 @@ "title": "Quickstart", "url": "/docs/guides/quick-start" }, - { - "title": "IBM Quantum Composer", - "url": "/docs/guides/composer" - }, { "title": "Latest updates", "url": "/docs/guides/latest-updates" @@ -32,7 +28,7 @@ "url": "/docs/guides/tools-intro" }, { - "title": "Advanced install", + "title": "Install", "children": [ { "title": "Install Qiskit", @@ -756,13 +752,17 @@ "url": "/docs/guides/qiskit-addons-sqd-get-started" } ] - }, + } ], "collapsible": false }, + { + "title": "IBM Quantum Composer", + "url": "/docs/guides/composer" + }, { "title": "Additional resources", - "collapsible": false, + "collapsible": true, "children": [ { "title": "Support and FAQ", diff --git a/docs/guides/qiskit-addons-aqc-get-started.ipynb b/docs/guides/qiskit-addons-aqc-get-started.ipynb deleted file mode 100644 index 90e8aeb34c6..00000000000 --- a/docs/guides/qiskit-addons-aqc-get-started.ipynb +++ /dev/null @@ -1,555 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "ceff06e5-ea87-4526-a726-c9345f55e592", - "metadata": {}, - "source": [ - "---\n", - "title: Get started with AQC-Tensor\n", - "description: Example workflow to compress circuits using approximate quantum compilation\n", - "---\n", - "\n", - "\n", - "# Getting started with Approximate quantum compilation with tensor networks (AQC-Tensor)" - ] - }, - { - "cell_type": "markdown", - "id": "cb4ff5eb", - "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-aer~=0.17\n", - "qiskit-addon-utils~=0.3.0\n", - "qiskit-addon-aqc-tensor[aer,quimb-jax]~=0.2.0; sys.platform != 'darwin'\n", - "scipy~=1.16.3\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "d8d85b16", - "metadata": {}, - "source": [ - "This guide demonstrates a simple working example to get started with AQC-Tensor. In this example, you will take a Trotter circuit which simulates the evolution of a transverse field Ising model and use the AQC-Tensor method to reduce the resulting circuit depth. In addition, this example requires the `qiskit-addon-utils` package for the problem generator, `qiskit-aer` for the tensor-network simulation, and `scipy` for the parameter optimization.\n", - "\n", - "To begin, recall that the Hamiltonian of the transverse field Ising model has the form\n", - "\n", - "$$ \\mathcal{H}_{Ising} = \\sum_{i=1}^N J_{i,(i+1)}Z_iZ_{i+1} + h_i X_i $$\n", - "\n", - "where we'll assume periodic boundary conditions which imply that for $i=10$ we obtain $i+1=11\\rightarrow 1$ and $J$ is the coupling strength between two sites and $h$ is the strength of the external magnetic field.\n", - "\n", - "The following code snippet will generate the Hamiltonian of a 10-site Ising chain with periodic boundary conditions." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "8b610d5a-c551-4b53-a37a-a2161d361a47", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit.transpiler import CouplingMap\n", - "from qiskit_addon_utils.problem_generators import generate_xyz_hamiltonian\n", - "from qiskit.synthesis import SuzukiTrotter\n", - "from qiskit_addon_utils.problem_generators import (\n", - " generate_time_evolution_circuit,\n", - ")\n", - "from qiskit_addon_aqc_tensor import generate_ansatz_from_circuit\n", - "from qiskit_addon_aqc_tensor.simulation import tensornetwork_from_circuit\n", - "from qiskit_addon_aqc_tensor.simulation import compute_overlap\n", - "from qiskit_addon_aqc_tensor.objective import MaximizeStateFidelity\n", - "from qiskit_aer import AerSimulator\n", - "from scipy.optimize import OptimizeResult, minimize\n", - "\n", - "\n", - "# Generate some coupling map to use for this example\n", - "coupling_map = CouplingMap.from_heavy_hex(3, bidirectional=False)\n", - "\n", - "# Choose a 10-qubit circle on this coupling map\n", - "reduced_coupling_map = coupling_map.reduce(\n", - " [0, 13, 1, 14, 10, 16, 4, 15, 3, 9]\n", - ")\n", - "\n", - "# Get a qubit operator describing the Ising field model\n", - "hamiltonian = generate_xyz_hamiltonian(\n", - " reduced_coupling_map,\n", - " coupling_constants=(0.0, 0.0, 1.0),\n", - " ext_magnetic_field=(0.4, 0.0, 0.0),\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "559638bb-33b4-4a9c-b9d1-fac58a622119", - "metadata": {}, - "source": [ - "## Split the time evolution into two pieces for classical and quantum execution\n", - "\n", - "The overall goal of this example is to simulate time evolution of the model Hamiltonian. We do so here by Trotter evolution, which will be split into two portions.\n", - "\n", - "1. An initial portion which is simulable using matrix product states (MPS). This will be what is 'compiled' using AQC-Tensor.\n", - "2. A subsequent portion which will be executed on quantum hardware.\n", - "\n", - "We'll choose to evolve the system up to time $t_f=5$ and use AQC-Tensor to compress the time evolution up to time $t=4$, then evolve using ordinary Trotter steps up to time $t_f$.\n", - "\n", - "From here we will next generate two circuits, one which will be compressed using AQC-Tensor and one which will be executed on a QPU. For the first circuit, since this will be simulated classically using matrix product states, we will use a generous number of layers to minimize Trotter error. Meanwhile the second circuit simulating time evolution from $t_i=4$ to $t_f=5$ will use much fewer layers in order to minimize depth." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3081dca8-24cd-4995-bd99-cd94d71d1b99", - "metadata": {}, - "outputs": [], - "source": [ - "# Generate circuit to be compressed\n", - "aqc_evolution_time = 4.0\n", - "aqc_target_num_trotter_steps = 45\n", - "\n", - "aqc_target_circuit = generate_time_evolution_circuit(\n", - " hamiltonian,\n", - " synthesis=SuzukiTrotter(reps=aqc_target_num_trotter_steps),\n", - " time=aqc_evolution_time,\n", - ")\n", - "\n", - "# Generate circuit to execute on hardware\n", - "subsequent_evolution_time = 1.0\n", - "subsequent_num_trotter_steps = 5\n", - "\n", - "subsequent_circuit = generate_time_evolution_circuit(\n", - " hamiltonian,\n", - " synthesis=SuzukiTrotter(reps=subsequent_num_trotter_steps),\n", - " time=subsequent_evolution_time,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "fbfa7baa-6f73-434d-84a6-8940a8a0e43f", - "metadata": {}, - "source": [ - "For comparison purposes, we will also generate a third circuit. One which evolves until $t=4$, but which has the same number of layers as the second circuit evolving from $t_i=4$ to $t_f=5$. This is the circuit we *would have* executed has we not used the AQC-Tensor technique. We'll call this the *comparison* circuit for now." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "a8a27d6f-6013-424d-b640-4d3d7311cee3", - "metadata": {}, - "outputs": [], - "source": [ - "aqc_comparison_num_trotter_steps = int(\n", - " subsequent_num_trotter_steps\n", - " / subsequent_evolution_time\n", - " * aqc_evolution_time\n", - ")\n", - "aqc_comparison_num_trotter_steps\n", - "\n", - "comparison_circuit = generate_time_evolution_circuit(\n", - " hamiltonian,\n", - " synthesis=SuzukiTrotter(reps=aqc_comparison_num_trotter_steps),\n", - " time=aqc_evolution_time,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "df4e1487-79e3-4af8-b66c-ea610db99259", - "metadata": {}, - "source": [ - "## Generate ansatz and construct MPS simulation\n", - "\n", - "Next we will generate the ansatz we will optimize. It will evolve to the same evolution time as our first circuit (from $t_i=0$ to $t_f=4$), but with fewer Trotter steps.\n", - "\n", - "Once the circuit has been generated, we then pass it to AQC-Tensor's `generate_ansatz_from_circuit()` function which analyzes the two-qubit connectivity and returns two things. First is a generated ansatz circuit with the same two-qubit connectivity, and the second is a set of parameters which, when plugged into the ansatz, yield the input circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "e08edb92-da1f-4131-85f5-f89006f7a2dd", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "aqc_ansatz_num_trotter_steps = 5\n", - "\n", - "aqc_good_circuit = generate_time_evolution_circuit(\n", - " hamiltonian,\n", - " synthesis=SuzukiTrotter(reps=aqc_ansatz_num_trotter_steps),\n", - " time=aqc_evolution_time,\n", - ")\n", - "\n", - "aqc_ansatz, aqc_initial_parameters = generate_ansatz_from_circuit(\n", - " aqc_good_circuit, qubits_initially_zero=True\n", - ")\n", - "aqc_ansatz.draw(\"mpl\", fold=-1)" - ] - }, - { - "cell_type": "markdown", - "id": "ec70cdcb-1257-449f-9a21-620c980f2492", - "metadata": {}, - "source": [ - "Next we will build the MPS representation of the state to be approximated by AQC. We will also calculate the fidelity $|\\langle\\psi_1 | \\psi_2 \\rangle |^2$ between the state prepared by the comparison circuit vs the one circuit which generates the target state (which used more Trotter steps)." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "dad8e00c-eed1-4f17-8760-4d9590eb34c0", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Comparison fidelity: 0.9997111919739693\n" - ] - } - ], - "source": [ - "# Generate MPS simulator settings and obtain the MPS representation of the target state\n", - "simulator_settings = AerSimulator(\n", - " method=\"matrix_product_state\",\n", - " matrix_product_state_max_bond_dimension=100,\n", - ")\n", - "aqc_target_mps = tensornetwork_from_circuit(\n", - " aqc_target_circuit, simulator_settings\n", - ")\n", - "\n", - "\n", - "# Compute the fidelity between the MPS representation of the target state and the state produced by the comparison circuit\n", - "comparison_mps = tensornetwork_from_circuit(\n", - " comparison_circuit, simulator_settings\n", - ")\n", - "comparison_fidelity = (\n", - " abs(compute_overlap(comparison_mps, aqc_target_mps)) ** 2\n", - ")\n", - "print(f\"Comparison fidelity: {comparison_fidelity}\")" - ] - }, - { - "cell_type": "markdown", - "id": "31f51c71-4066-4554-8101-c5c829b95fdc", - "metadata": {}, - "source": [ - "## Optimize the parameters of the ansatz using the MPS\n", - "\n", - "Lastly, we will optimize the ansatz circuit such that it produces the target state better than our `comparison_fidelity`. The cost function to minimize will be the `MaximizeStateFidelity` and will be optimized using scipy's L-BFGS optimizer." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "4b784b22-d6b3-408c-bce4-58b351b24fed", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.95084365\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.98409893\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99142033\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99521405\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99566673\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99650054\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99683487\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99720426\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99761726\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99809073\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99838244\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99861841\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99874617\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99892696\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99908129\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99917737\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99925456\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99933134\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99947173\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99956469\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99964488\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99967419\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.99968821\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Intermediate result: Fidelity 0.9997448\n", - "Done after 24 iterations.\n" - ] - } - ], - "source": [ - "objective = MaximizeStateFidelity(\n", - " aqc_target_mps, aqc_ansatz, simulator_settings\n", - ")\n", - "\n", - "stopping_point = 1 - comparison_fidelity\n", - "\n", - "\n", - "def callback(intermediate_result: OptimizeResult):\n", - " print(f\"Intermediate result: Fidelity {1 - intermediate_result.fun:.8}\")\n", - " if intermediate_result.fun < stopping_point:\n", - " # Good enough for now\n", - " raise StopIteration\n", - "\n", - "\n", - "result = minimize(\n", - " objective,\n", - " aqc_initial_parameters,\n", - " method=\"L-BFGS-B\",\n", - " jac=True,\n", - " options={\"maxiter\": 100},\n", - " callback=callback,\n", - ")\n", - "if (\n", - " result.status\n", - " not in (\n", - " 0,\n", - " 1,\n", - " 99,\n", - " )\n", - "): # 0 => success; 1 => max iterations reached; 99 => early termination via StopIteration\n", - " raise RuntimeError(\n", - " f\"Optimization failed: {result.message} (status={result.status})\"\n", - " )\n", - "\n", - "print(f\"Done after {result.nit} iterations.\")\n", - "aqc_final_parameters = result.x" - ] - }, - { - "cell_type": "markdown", - "id": "d1322051-28d4-4fde-aa8e-6da467badb92", - "metadata": {}, - "source": [ - "At this point we have a set of parameters which generate the target state with a higher fidelity than what the comparison circuit would have produced without using AQC. With these optimal parameters, the compressed circuit now has less Trotter error *and* less depth than the original circuit.\n", - "\n", - "As a final step, the following code snippet builds the full time evolution circuit which can be passed to a transpiler pipeline and executed on quantum hardware." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "45abbabe-0289-4a09-aa99-89f70bdc535d", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "final_circuit = aqc_ansatz.assign_parameters(aqc_final_parameters)\n", - "final_circuit.compose(subsequent_circuit, inplace=True)\n", - "final_circuit.draw(\"mpl\", fold=-1)" - ] - }, - { - "cell_type": "markdown", - "id": "b5c547d1-2103-4716-8da2-cd2b24f1f9c1", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Try the [Approximate quantum compilation for time evolution circuits](/docs/tutorials/approximate-quantum-compilation-for-time-evolution) tutorial.\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": 2 -} diff --git a/docs/guides/qiskit-addons-aqc.mdx b/docs/guides/qiskit-addons-aqc.mdx deleted file mode 100644 index 92083ac15af..00000000000 --- a/docs/guides/qiskit-addons-aqc.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Approximate quantum compilation with tensor networks -description: Overview of the addon for approximate quantum compilation using tensor networks ---- - -# Approximate quantum compilation with tensor networks (AQC-Tensor) - -The Approximate quantum compilation with tensor networks (AQC-Tensor) Qiskit addon enables users to compile the *initial portion* of a circuit into a nearly equivalent approximation of that circuit, but with much fewer layers. This is accomplished using tensor networks using the method described in [[1]](#references). Its primary utility is in circuits which simulate time evolution, but may be applicable to any class of circuits which has access to: - -1. A great intermediate state, known as the “target state,” that can be achieved by tensor-network simulation; and, -2. A good circuit that prepares an approximation to the target state, but with fewer layers when compiled to the target hardware device. - - -The technique generates an ansatz circuit based on a larger target circuit which a user ultimately wants to execute on a QPU. This is accomplished by first simulating some portion of the target circuit by tensor network methods and obtaining an accurate description of an intermediate state which the ansatz circuit will approximate. Once this intermediate state is found, it is used as a cost function in order to optimize the ansatz circuit's parameters. After the optimization is complete, the remaining portion of the target circuit is appended to the ansatz and then executed on quantum hardware. - - -## Install the AQC-Tensor package - -There are two ways to install the AQC-Tensor package: PyPI and building from source. It is recommended to install these packages in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies. - -### Install from PyPI - -The most straightforward way to install the AQC-Tensor package is via PyPI. In order to use the package, you must also install at least one tensor network backend. The following code snippet will install the addon, along with `quimb` (for tensor network support) and `jax` (for automatic differentiation). If you are interested, check out the package on [GitHub](https://github.com/Qiskit/qiskit-addon-aqc-tensor) - -```bash -pip install 'qiskit-addon-aqc-tensor[quimb-jax]' -``` - -### Install from source - -
- -Click here to read how to install this package manually. - - -If you wish to contribute to this package or want to install it manually, first clone the repository: - -```bash -git clone git clone git@github.com:Qiskit/qiskit-addon-aqc-tensor.git -``` -and install the package via `pip`. If you plan on running the tutorials found in the package repository, install the notebook dependencies as well. If you plan on developing in the repository, you may also want to install the `dev` dependencies. -```bash -pip install tox jupyterlab -e '.[notebook-dependencies,dev]' -``` -
- -## Theoretical Background - -The AQC-Tensor procedure is explained in detail in [[1]](#references). This section provides an overview of the technique. - -![Diagram depicting the approximate quantum compilation procedure](/docs/images/guides/qiskit-addons/aqc_diagram.avif) - -In general, AQC-Tensor requires three things as input: -1. A description of the **target state** in the form of a tensor network. This can be generated by simulating a circuit on a tensor network simulator, or it could be generated in some other way (for example, by performing time evolution on a matrix-product state using the time-dependent variational principle). -2. A parametrized **ansatz circuit**. Ideally one which contains hardware-efficient connectivity, such that it will have a reasonable depth on the target hardware. -3. **Initial parameters** to plug into the ansatz circuit, such that the resulting state is already a *good* approximation of the target state. (This is not, in principle, required for AQC, but it helps to give the optimizer a sensible starting point.) - -The technique is to then iteratively optimize the parameters of the ansatz circuit, such that the state it generates is as close to the target state as possible. - -### Ansatz generation - -To generate (2) and (3) from the above list, the `qiskit-addon-aqc` package possesses a function, `generated_ansatz_from_circuit()` which will take an input circuit and outputs a parameterized ansatz and initial set of parameters. The parameters returned by the function are such that, when plugged into the ansatz, will generate a state that is exactly equivalent to the input circuit, up to a global phase. - -The ansatz which is generated by this function uses 9 parameters per two-qubit block and is based on the KAK decomposition, which parametrizes any two-qubit gate in terms of three parameters, up to single-qubit rotations. The single-qubit rotations are then decomposed as $ZXZ$, each of which has three parameters. This results in the ansatz circuit containing 3 parameters for each two-qubit block of the original circuit, plus 3 parameters for an outgoing single-qubit rotation on each of the two qubits (for a total of 9 parameters). After adding these blocks, the ansatz is completed by adding a layer of single-qubit rotations to each active qubit at the start of the circuit. - -### Tensor-network simulation - -To obtain a description of the target state which is desired, this addon uses a matrix product state (the simplest form of a tensor network) and supports the following tensor-network simulators: -- MPS simulator found in Qiskit Aer -- Quimb's [eager](https://quimb.readthedocs.io/en/latest/tensor/tensor-circuit-mps.html) [`CircuitMPS`](https://quimb.readthedocs.io/en/latest/autoapi/quimb/tensor/index.html#quimb.tensor.CircuitMPS) simulator -- Quimb's [lazy](https://quimb.readthedocs.io/en/latest/tensor/tensor-circuit.html) [`Circuit`](https://quimb.readthedocs.io/en/latest/autoapi/quimb/tensor/index.html#quimb.tensor.Circuit) simulator - -The most important parameter of a tensor network is its maximum bond dimension, $\chi$. This parameter limits how much entanglement can be represented with a tensor network, and thus to what depth a given circuit can be faithfully simulated. - -Given a circuit with $L$ qubits, a matrix-product state needs at most a bond dimension of $\chi_{exact} = 2^{L/2}$ in order to exactly simulate the circuit to *any* depth. This is out of reach for general utility-scale circuits acting on 100+ qubits. For this reason, if you are attempting to experiment with this addon for a toy-problem with few qubits, it is important to ensure that $\chi < 2^{L/2}$. This way, when you scale the problem to a larger circuit, the target state remains classically simulable. - -## Next steps - - - - Read through the page on [getting started with AQC-Tensor](/docs/guides/qiskit-addons-aqc-get-started) - - Read the tutorial on using AQC to [improve Trotterized time evolution.](/docs/tutorials/approximate-quantum-compilation-for-time-evolution) - - - -## References - -[1] Robertson, Niall F., et al. ["Approximate Quantum Compiling for Quantum Simulation: A Tensor Network based approach"](https://arxiv.org/abs/2301.08609) arXiv preprint arXiv:2301.08609 (2023). diff --git a/docs/guides/qiskit-addons-cutting-gates.ipynb b/docs/guides/qiskit-addons-cutting-gates.ipynb deleted file mode 100644 index 2fb2c6e2186..00000000000 --- a/docs/guides/qiskit-addons-cutting-gates.ipynb +++ /dev/null @@ -1,506 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "8fd79758-2771-41ce-b17e-e8bfdf5b1023", - "metadata": {}, - "source": [ - "---\n", - "title: Get started with gate cutting\n", - "description: Two worked examples of gate cutting using the circuit cutting addon to get started with the package\n", - "---\n", - "\n", - "\n", - "# Get started with circuit cutting using gate cuts" - ] - }, - { - "cell_type": "markdown", - "id": "091552e5", - "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", - "qiskit-aer~=0.17\n", - "qiskit-addon-cutting~=0.10.0\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "d6a15cd2", - "metadata": {}, - "source": [ - "This guide demonstrates two working examples of gate cuts with the `qiskit-addon-cutting` package. The first example shows how to reduce circuit depth (the number of circuit instructions) by cutting entangling gates on non-adjacent qubits that would otherwise incur a SWAP overhead when transpiled to hardware. The second example covers how to use gate cutting to reduce the circuit width (the number of qubits) by splitting a circuit into several circuits with fewer qubits.\n", - "\n", - "Both examples will use the [`efficient_su2`](/docs/api/qiskit/qiskit.circuit.library.efficient_su2) ansatz and reconstructs the same observable." - ] - }, - { - "cell_type": "markdown", - "id": "e58752cf-2628-4c99-805b-4d82055b547a", - "metadata": {}, - "source": [ - "## Gate cutting to reduce circuit depth\n", - "\n", - "The following workflow reduces a circuit's depth by cutting distant gates, avoiding a large series of SWAP gates that would otherwise be introduced.\n", - "\n", - "Start with the [`efficient_su2`](/docs/api/qiskit/qiskit.circuit.library.efficient_su2) ansatz, with \"circular\" entanglement to introduce distant gates." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "1551c440-c158-478a-a8fe-86df834c59bd", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Observable: SparsePauliOp(['ZZII', 'IZZI', 'IIZZ', 'XIXI', 'ZIZZ', 'IXIX'],\n", - " coeffs=[ 1.+0.j, 1.+0.j, -1.+0.j, 1.+0.j, 1.+0.j, 1.+0.j])\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 1, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.circuit.library import efficient_su2\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime.fake_provider import FakeManilaV2\n", - "from qiskit_ibm_runtime import SamplerV2, Batch\n", - "from qiskit_aer.primitives import EstimatorV2\n", - "from qiskit_addon_cutting import (\n", - " cut_gates,\n", - " partition_problem,\n", - " generate_cutting_experiments,\n", - " reconstruct_expectation_values,\n", - ")\n", - "\n", - "circuit = efficient_su2(num_qubits=4, entanglement=\"circular\")\n", - "circuit.assign_parameters([0.4] * len(circuit.parameters), inplace=True)\n", - "\n", - "\n", - "observable = SparsePauliOp([\"ZZII\", \"IZZI\", \"-IIZZ\", \"XIXI\", \"ZIZZ\", \"IXIX\"])\n", - "print(f\"Observable: {observable}\")\n", - "circuit.draw(\"mpl\", scale=0.8)" - ] - }, - { - "cell_type": "markdown", - "id": "87b8819b-75d7-4a9e-b91a-00b6155fda9a", - "metadata": {}, - "source": [ - "Each of the [`CNOT`](/docs/api/qiskit/qiskit.circuit.library.CXGate) gates between qubits $q_0$ and $q_3$ introduce two SWAP gates after transpilation (assuming the qubits are connected in a straight line). To avoid this increase in depth, you can replace these distant gates with [`TwoQubitQPDGate`](/docs/api/qiskit-addon-cutting/qpd-two-qubit-qpd-gate) objects using the [`cut_gates()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#cut_gates) method. This function also returns a list of [`QPDBasis`](../api/qiskit-addon-cutting/qpd-qpd-basis) instances - one for each decomposition." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "66dc0a14-ab51-4190-9cda-1c0373e91b9e", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# Find the indices of the distant gates\n", - "cut_indices = [\n", - " i\n", - " for i, instruction in enumerate(circuit.data)\n", - " if {circuit.find_bit(q)[0] for q in instruction.qubits} == {0, 3}\n", - "]\n", - "\n", - "# Decompose distant CNOTs into TwoQubitQPDGate instances\n", - "qpd_circuit, bases = cut_gates(circuit, cut_indices)\n", - "\n", - "qpd_circuit.draw(\"mpl\", scale=0.8)" - ] - }, - { - "cell_type": "markdown", - "id": "e9871e55-59f8-48e2-a9ca-2645dcb7d2bf", - "metadata": {}, - "source": [ - "Now that the cut gate instructions have been added, the subexperiments will have a smaller depth after transpilation than the original circuit. The code snippet below generates the subexperiments using the [`generate_cutting_experiments`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#generate_cutting_experiments), which ingests the circuit and observable to reconstruct.\n", - "\n", - "\n", - " The `num_samples` argument specifies how many samples to draw from the quasi-probability distribution and determines the accuracy of the coefficients used for the reconstruction. Passing infinity (`np.inf`) will ensure all coefficients are calculated exactly. Read the API docs on [generating weights](/docs/api/qiskit-addon-cutting/qpd#generate_qpd_weights) and [generating cutting experiments](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#generate_cutting_experiments) for more information.\n", - "\n", - "\n", - "Once the subexperiments are generated, you can then transpile them and use the `Sampler` primitive to sample the distribution and reconstruct the estimated expectation values. The following code block generates, transpiles, and executes the subexperiments. It then reconstructs the results and compares them to the exact expectation value." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "682d5724-d8bc-40e6-b42e-9224a600fe7a", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Reconstructed expectation value: 0.49812826\n", - "Exact expectation value: 0.50497603\n", - "Error in estimation: -0.00684778\n", - "Relative error in estimation: -0.0135606\n" - ] - } - ], - "source": [ - "# Generate the subexperiments and sampling coefficients\n", - "subexperiments, coefficients = generate_cutting_experiments(\n", - " circuits=qpd_circuit, observables=observable.paulis, num_samples=np.inf\n", - ")\n", - "\n", - "# Set a backend to use and transpile the subexperiments\n", - "backend = FakeManilaV2()\n", - "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=1, backend=backend\n", - ")\n", - "isa_subexperiments = pass_manager.run(subexperiments)\n", - "\n", - "# Set up the Qiskit Runtime Sampler primitive, submit the subexperiments, and retrieve the results\n", - "sampler = SamplerV2(backend)\n", - "job = sampler.run(isa_subexperiments, shots=4096 * 3)\n", - "results = job.result()\n", - "\n", - "\n", - "# Reconstruct the results\n", - "reconstructed_expval_terms = reconstruct_expectation_values(\n", - " results,\n", - " coefficients,\n", - " observable.paulis,\n", - ")\n", - "\n", - "# Apply the coefficients of the original observable\n", - "reconstructed_expval = np.dot(reconstructed_expval_terms, observable.coeffs)\n", - "\n", - "estimator = EstimatorV2()\n", - "exact_expval = (\n", - " estimator.run([(circuit, observable, [0.4] * len(circuit.parameters))])\n", - " .result()[0]\n", - " .data.evs\n", - ")\n", - "print(\n", - " f\"Reconstructed expectation value: {np.real(np.round(reconstructed_expval, 8))}\"\n", - ")\n", - "print(f\"Exact expectation value: {np.round(exact_expval, 8)}\")\n", - "print(\n", - " f\"Error in estimation: {np.real(np.round(reconstructed_expval-exact_expval, 8))}\"\n", - ")\n", - "print(\n", - " f\"Relative error in estimation: {np.real(np.round((reconstructed_expval-exact_expval) / exact_expval, 8))}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "64f44348-3ad1-4bf4-9a3a-cf0d73ca3431", - "metadata": {}, - "source": [ - "\n", - " To accurately reconstruct the expectation value, the coefficients of the original observable (which are different from the coefficients in the output of `generate_cutting_experiments()`) must be applied to the output of the reconstruction, since this information was lost when the cutting experiments were generated or when the observable was expanded.\n", - "\n", - " Typically these coefficients can be applied through `numpy.dot()` as shown above.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "1eaf95b7-7c95-4c65-9ab6-d2654bc2b988", - "metadata": {}, - "source": [ - "## Gate cutting to reduce circuit width\n", - "\n", - "This section demonstrates using gate cutting to reduce circuit width. Start with the same [`efficient_su2`](/docs/api/qiskit/qiskit.circuit.library.efficient_su2) but use \"linear\" entanglement." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "64010a14-8360-47e2-bb77-af9b2e0dbbfc", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Observable: SparsePauliOp(['ZZII', 'IZZI', 'IIZZ', 'XIXI', 'ZIZZ', 'IXIX'],\n", - " coeffs=[ 1.+0.j, 1.+0.j, -1.+0.j, 1.+0.j, 1.+0.j, 1.+0.j])\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "qc = efficient_su2(4, entanglement=\"linear\", reps=2)\n", - "qc.assign_parameters([0.4] * len(qc.parameters), inplace=True)\n", - "\n", - "\n", - "observable = SparsePauliOp([\"ZZII\", \"IZZI\", \"-IIZZ\", \"XIXI\", \"ZIZZ\", \"IXIX\"])\n", - "print(f\"Observable: {observable}\")\n", - "\n", - "qc.draw(\"mpl\", scale=0.8)" - ] - }, - { - "cell_type": "markdown", - "id": "65ddc1d5-b0c6-45e9-88e1-6df2616e3f96", - "metadata": {}, - "source": [ - "Then generate the *subcircuits* and *subobservables* you'll execute using the [`partition_problem()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#partition_problem) function. This function takes in the circuit, observable, and an optional partitioning scheme and returns the cut circuits and observables in the form of a dictionary.\n", - "\n", - "The partitioning is defined by a label string of the form `\"AABB\"` where each label in this string corresponds to the qubit in the same index of the `circuit` argument. Qubits sharing a common partition label are grouped together, and any non-local gates that span more than one partition will be cut.\n", - "\n", - "\n", - " The `observables` kwarg to `partition_problem` is of type [`PauliList`](/docs/api/qiskit/qiskit.quantum_info.PauliList). Observable term coefficients and phases are ignored during decomposition of the problem and execution of the subexperiments. They may be re-applied during reconstruction of the expectation value.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "a5454265-3785-4a54-b423-baf7815b97ec", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Sampling overhead: 81.0\n", - "Subobservables: {'A': PauliList(['II', 'ZI', 'ZZ', 'XI', 'ZZ', 'IX']), 'B': PauliList(['ZZ', 'IZ', 'II', 'XI', 'ZI', 'IX'])}\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "partitioned_problem = partition_problem(\n", - " circuit=qc, partition_labels=\"AABB\", observables=observable.paulis\n", - ")\n", - "subcircuits = partitioned_problem.subcircuits\n", - "subobservables = partitioned_problem.subobservables\n", - "bases = partitioned_problem.bases\n", - "\n", - "\n", - "print(f\"Sampling overhead: {np.prod([basis.overhead for basis in bases])}\")\n", - "print(f\"Subobservables: {subobservables}\")\n", - "subcircuits[\"A\"].draw(\"mpl\", scale=0.8)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "1c527720-0d06-48a1-88b6-9ff95a77a068", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "subcircuits[\"B\"].draw(\"mpl\", scale=0.8)" - ] - }, - { - "cell_type": "markdown", - "id": "8a03df45-252b-424f-9fe0-9748084f14c3", - "metadata": {}, - "source": [ - "The next step is then to use the subcircuits and subobservables to generate the *subexperiments* to be executed on a QPU using the [`generate_cutting_experiments`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#generate_cutting_experiments) method.\n", - "\n", - "To estimate the expectation value of the full-sized circuit, many subexperiments are generated from the decomposed gates' joint quasi-probability distribution and then executed on one or more QPUs. The number of samples to be taken from this distribution is controlled by the `num_samples` argument.\n", - "\n", - "The following code block generates the subexperiments and executes them using the `Sampler` primitive on a local simulator. (To run these on a QPU, change the `backend` to your chosen QPU resource.)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "1be6d145-4a18-4c41-bf59-d9b24d2ce024", - "metadata": {}, - "outputs": [], - "source": [ - "subexperiments, coefficients = generate_cutting_experiments(\n", - " circuits=subcircuits, observables=subobservables, num_samples=np.inf\n", - ")\n", - "\n", - "# Set a backend to use and transpile the subexperiments\n", - "backend = FakeManilaV2()\n", - "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=1, backend=backend\n", - ")\n", - "isa_subexperiments = {\n", - " label: pass_manager.run(partition_subexpts)\n", - " for label, partition_subexpts in subexperiments.items()\n", - "}\n", - "\n", - "# Submit each partition's subexperiments to the Qiskit Runtime Sampler\n", - "# primitive, in a single batch so that the jobs will run back-to-back.\n", - "with Batch(backend=backend) as batch:\n", - " sampler = SamplerV2(mode=batch)\n", - " jobs = {\n", - " label: sampler.run(subsystem_subexpts, shots=4096 * 3)\n", - " for label, subsystem_subexpts in isa_subexperiments.items()\n", - " }\n", - "\n", - "# Retrieve results\n", - "results = {label: job.result() for label, job in jobs.items()}" - ] - }, - { - "cell_type": "markdown", - "id": "64e762ad-0660-4c78-8ea7-fb9d226357d7", - "metadata": {}, - "source": [ - "Lastly, the expectation value of the full circuit is reconstructed using the [`reconstruct_expectation_values`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#reconstruct_expectation_values) method.\n", - "\n", - "The code block below reconstructs the results and compares them with the exact expectation value." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "b3cf1b65-df16-4bd4-a083-f65cec6c49dc", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Reconstructed expectation value: 0.53571896\n", - "Exact expectation value: 0.56254612\n", - "Error in estimation: -0.02682716\n", - "Relative error in estimation: -0.04768882\n" - ] - } - ], - "source": [ - "# Get expectation values for each observable term\n", - "reconstructed_expval_terms = reconstruct_expectation_values(\n", - " results,\n", - " coefficients,\n", - " subobservables,\n", - ")\n", - "\n", - "# Reconstruct final expectation value\n", - "reconstructed_expval = np.dot(reconstructed_expval_terms, observable.coeffs)\n", - "\n", - "\n", - "estimator = EstimatorV2()\n", - "exact_expval = (\n", - " estimator.run([(qc, observable, [0.4] * len(qc.parameters))])\n", - " .result()[0]\n", - " .data.evs\n", - ")\n", - "print(\n", - " f\"Reconstructed expectation value: {np.real(np.round(reconstructed_expval, 8))}\"\n", - ")\n", - "print(f\"Exact expectation value: {np.round(exact_expval, 8)}\")\n", - "print(\n", - " f\"Error in estimation: {np.real(np.round(reconstructed_expval-exact_expval, 8))}\"\n", - ")\n", - "print(\n", - " f\"Relative error in estimation: {np.real(np.round((reconstructed_expval-exact_expval) / exact_expval, 8))}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "faf4620d-6782-4fce-a99b-9e1d01f29951", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Read the [Get started with circuit cutting using wire cuts](/docs/guides/qiskit-addons-cutting-wires) guide.\n", - " - Read the arXiv paper on [circuit knitting with classical communication.](https://ieeexplore.ieee.org/document/10236453)\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": 2 -} diff --git a/docs/guides/qiskit-addons-cutting-wires.ipynb b/docs/guides/qiskit-addons-cutting-wires.ipynb deleted file mode 100644 index f8a3024b0af..00000000000 --- a/docs/guides/qiskit-addons-cutting-wires.ipynb +++ /dev/null @@ -1,565 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "1ce517c0-5dfd-4458-82f6-1a21f248603b", - "metadata": {}, - "source": [ - "---\n", - "title: Get started with wire cuts\n", - "description: A worked example of wire cutting using the circuit cutting addon to get started with the package\n", - "---\n", - "\n", - "\n", - "# Get started with circuit cutting using wire cuts" - ] - }, - { - "cell_type": "markdown", - "id": "fa227c38", - "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", - "qiskit-aer~=0.17\n", - "qiskit-addon-cutting~=0.10.0\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "334ee858", - "metadata": {}, - "source": [ - "This guide demonstrates a working example of wire cuts with the `qiskit-addon-cutting` package. It covers reconstructing expectation values of a seven-qubit circuit using wire cutting.\n", - "\n", - "A wire cut is represented in this package as a two-qubit [`Move`](/docs/api/qiskit-addon-cutting/instructions-move) instruction, which is defined as a reset of the second qubit the instruction acts on, followed by a swap of both qubits. This operation is equivalent to transferring the state of the first qubit to the second qubit, while simultaneously discarding the incoming state of the second qubit.\n", - "\n", - "The package is designed to be consistent with the way you must treat wire cuts when acting on physical qubits. For example, a wire cut might take the state of physical qubit $n$ and continue it as a physical qubit $m$ after the cut. You can think of \"instruction cutting\" as a unified framework for considering both wire and gate cuts within the same formalism (since a wire cut is just a cut [`Move`](/docs/api/qiskit-addon-cutting/instructions-move) instruction). Using this framework for wire cutting also allows for qubit re-use, which is explained in the section on [cutting wires manually](#cut-wires-using-the-low-level-move-instruction).\n", - "\n", - "The single-qubit [`CutWire`](/docs/api/qiskit-addon-cutting/instructions-cut-wire) instruction acts as a more abstracted, simpler interface for working with wire cuts. It allows you to denote where in the circuit a wire should be cut at a high level and have the circuit cutting addon insert the appropriate [`Move`](/docs/api/qiskit-addon-cutting/instructions-move) instructions for you.\n", - "\n", - "The following example demonstrates expectation value reconstruction after wire cutting. You will create a circuit with several non-local gates and define observables to estimate." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "b481ef2d-3912-4eac-9755-335e8f5db886", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 1, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import numpy as np\n", - "from qiskit import QuantumCircuit\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "from qiskit_ibm_runtime.fake_provider import FakeManilaV2\n", - "from qiskit_ibm_runtime import SamplerV2, Batch\n", - "from qiskit_aer.primitives import EstimatorV2\n", - "\n", - "from qiskit_addon_cutting.instructions import Move, CutWire\n", - "from qiskit_addon_cutting import (\n", - " partition_problem,\n", - " generate_cutting_experiments,\n", - " cut_wires,\n", - " expand_observables,\n", - " reconstruct_expectation_values,\n", - ")\n", - "\n", - "\n", - "qc_0 = QuantumCircuit(7)\n", - "for i in range(7):\n", - " qc_0.rx(np.pi / 4, i)\n", - "qc_0.cx(0, 3)\n", - "qc_0.cx(1, 3)\n", - "qc_0.cx(2, 3)\n", - "qc_0.cx(3, 4)\n", - "qc_0.cx(3, 5)\n", - "qc_0.cx(3, 6)\n", - "qc_0.cx(0, 3)\n", - "qc_0.cx(1, 3)\n", - "qc_0.cx(2, 3)\n", - "\n", - "# Define observable\n", - "observable = SparsePauliOp([\"ZIIIIII\", \"IIIZIII\", \"IIIIIIZ\"])\n", - "\n", - "# Draw circuit\n", - "qc_0.draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "d332ed5a-63e9-4862-9498-f86b0147607b", - "metadata": {}, - "source": [ - "## Cut wires using the high-level `CutWire` instruction\n", - "\n", - "Next, make wire cuts using the single-qubit [`CutWire`](/docs/api/qiskit-addon-cutting/instructions-cut-wire) instruction on qubit $q_3$. Once the subexperiments are prepared to be executed, use the [`cut_wires()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#cut_wires) function to transform `CutWire` to [`Move`](/docs/api/qiskit-addon-cutting/instructions-move) instructions on newly allocated qubits." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "9bac1915-316b-49d0-a1a1-145047679530", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "qc_1 = QuantumCircuit(7)\n", - "for i in range(7):\n", - " qc_1.rx(np.pi / 4, i)\n", - "qc_1.cx(0, 3)\n", - "qc_1.cx(1, 3)\n", - "qc_1.cx(2, 3)\n", - "qc_1.append(CutWire(), [3])\n", - "qc_1.cx(3, 4)\n", - "qc_1.cx(3, 5)\n", - "qc_1.cx(3, 6)\n", - "qc_1.append(CutWire(), [3])\n", - "qc_1.cx(0, 3)\n", - "qc_1.cx(1, 3)\n", - "qc_1.cx(2, 3)\n", - "\n", - "qc_1.draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "bcddcde7-9ed3-4718-a17f-1b555c4c2662", - "metadata": {}, - "source": [ - "\n", - " When a circuit is expanded through one or more wire cuts, the observable needs to be updated to account for the extra qubits that are introduced. The `qiskit-addon-cutting` package has a convenience function [`expand_observables()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#expand_observables), which takes `PauliList` objects and the original and expanded circuits as arguments, and returns a new `PauliList`.\n", - "\n", - " This returned `PauliList` will not contain any information about the original observable's coefficients, but these can be ignored until reconstruction of the final expectation value.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "d398b397-0167-4db9-97ae-6ea502dc43e3", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Expanded Observable: ['ZIIIIIIII', 'IIIZIIIII', 'IIIIIIIIZ']\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# Transform CutWire instructions to Move instructions\n", - "qc_2 = cut_wires(qc_1)\n", - "\n", - "# Expand the observable to match the new circuit size\n", - "expanded_observable = expand_observables(observable.paulis, qc_0, qc_2)\n", - "print(f\"Expanded Observable: {expanded_observable}\")\n", - "qc_2.draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "fcdcb972-beb7-4126-9720-861359aa6ae7", - "metadata": {}, - "source": [ - "### Partition the circuit and observable\n", - "\n", - "Now the problem can be separated into partitions. This is accomplished using the [`partition_problem()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#partition_problem) function with an optional set of partition labels to specify how to separate the circuit. Qubits sharing a common partition label are grouped together, and any non-local gates spanning more than one partition are cut.\n", - "\n", - "If no partition labels are provided, then the partitioning will be automatically determined based on the connectivity of the circuit. Read the next section on [cutting wires manually](#cut-wires-using-the-low-level-move-instruction) for more information on including partition labels." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "5fb034f2-da8a-4f4d-ab9b-c990593e04fc", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Subobservables to measure: \n", - "{0: PauliList(['IIIII', 'ZIIII', 'IIIIZ']), 1: PauliList(['ZIII', 'IIII', 'IIII'])}\n", - "\n", - "Sampling overhead: 256.0\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "partitioned_problem = partition_problem(\n", - " circuit=qc_2,\n", - " observables=expanded_observable,\n", - ")\n", - "subcircuits = partitioned_problem.subcircuits\n", - "subobservables = partitioned_problem.subobservables\n", - "bases = partitioned_problem.bases\n", - "\n", - "print(f\"Subobservables to measure: \\n{subobservables}\\n\")\n", - "print(f\"Sampling overhead: {np.prod([basis.overhead for basis in bases])}\")\n", - "subcircuits[0].draw(\"mpl\")" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "d0e86f81-7c7e-4ccf-951c-9cd039135dc9", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "subcircuits[1].draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "97c6c48c-30e5-4f43-b44c-23384ca0beff", - "metadata": {}, - "source": [ - "In this partitioning scheme, you have cut two wires, resulting in a sampling overhead of $4^4$." - ] - }, - { - "cell_type": "markdown", - "id": "5495f3ad-f4fe-4051-b5fe-67341179a58e", - "metadata": {}, - "source": [ - "### Generate subexperiments to execute and post-process results\n", - "\n", - "To estimate the expectation value of the full-sized circuit, several subexperiments are generated from the decomposed gates' joint quasi-probability distribution and then executed on one (or more) QPUs. The [`generate_cutting_experiments`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#generate_cutting_experiments) method does this by ingesting arguments for the `subcircuits` and `subobservables` dictionaries you created above, as well as for the number of samples to take from the distribution.\n", - "\n", - "\n", - " The `num_samples` argument specifies how many samples to draw from the quasi-probability distribution and determines the accuracy of the coefficients used for the reconstruction. Passing infinity (`np.inf`) ensures all coefficients are calculated exactly. Read the API docs on [generating weights](/docs/api/qiskit-addon-cutting/qpd#generate_qpd_weights) and [generating cutting experiments](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#generate_cutting_experiments) for more information.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "30257a7a-ad41-46d7-b4d6-c4bfa354ab28", - "metadata": {}, - "outputs": [], - "source": [ - "# Generate subexperiments\n", - "subexperiments, coefficients = generate_cutting_experiments(\n", - " circuits=subcircuits, observables=subobservables, num_samples=np.inf\n", - ")\n", - "\n", - "# Set a backend to use and transpile the subexperiments\n", - "backend = FakeManilaV2()\n", - "pass_manager = generate_preset_pass_manager(\n", - " optimization_level=1, backend=backend\n", - ")\n", - "isa_subexperiments = {\n", - " label: pass_manager.run(partition_subexpts)\n", - " for label, partition_subexpts in subexperiments.items()\n", - "}\n", - "\n", - "# Submit each partition's subexperiments to the Qiskit Runtime Sampler\n", - "# primitive, in a single batch so that the jobs will run back-to-back.\n", - "with Batch(backend=backend) as batch:\n", - " sampler = SamplerV2(mode=batch)\n", - " jobs = {\n", - " label: sampler.run(subsystem_subexpts, shots=2**12)\n", - " for label, subsystem_subexpts in isa_subexperiments.items()\n", - " }\n", - " # Retrieve results\n", - " results = {label: job.result() for label, job in jobs.items()}" - ] - }, - { - "cell_type": "markdown", - "id": "890ce542-0a74-451e-a3b2-ced3b35d62b3", - "metadata": {}, - "source": [ - "Lastly, the expectation value of the full circuit can be reconstructed using the [`reconstruct_expectation_values()`](/docs/api/qiskit-addon-cutting/qiskit-addon-cutting#reconstruct_expectation_values) method.\n", - "\n", - "\n", - "The code block below reconstructs the results and compares them with the exact expectation value." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "55ac9aef-494a-4834-b277-9fc4028137cd", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Reconstructed expectation value: 1.45965266\n", - "Exact expectation value: 1.59099026\n", - "Error in estimation: -0.1313376\n", - "Relative error in estimation: -0.08255085\n" - ] - } - ], - "source": [ - "reconstructed_expval_terms = reconstruct_expectation_values(\n", - " results,\n", - " coefficients,\n", - " subobservables,\n", - ")\n", - "# Apply the coefficients of the original observable\n", - "reconstructed_expval = np.dot(reconstructed_expval_terms, observable.coeffs)\n", - "\n", - "\n", - "# Compute the exact expectation value using the `qiskit_aer` package.\n", - "estimator = EstimatorV2()\n", - "exact_expval = estimator.run([(qc_0, observable)]).result()[0].data.evs\n", - "print(\n", - " f\"Reconstructed expectation value: {np.real(np.round(reconstructed_expval, 8))}\"\n", - ")\n", - "print(f\"Exact expectation value: {np.round(exact_expval, 8)}\")\n", - "print(\n", - " f\"Error in estimation: {np.real(np.round(reconstructed_expval-exact_expval, 8))}\"\n", - ")\n", - "print(\n", - " f\"Relative error in estimation: {np.real(np.round((reconstructed_expval-exact_expval) / exact_expval, 8))}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "2a27ea20-4064-4864-8a92-cd6c6cb84fa2", - "metadata": {}, - "source": [ - "\n", - " To accurately reconstruct the expectation value, the coefficients of the original observable (which are different from the output of `generate_cutting_experiments()`) must be applied to the output of the reconstruction, since this information was lost when the cutting experiments were generated or when the observable was expanded.\n", - "\n", - " Typically these coefficients can be applied through `numpy.dot()` as shown previously.\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "34609068-25a7-4aae-b786-836984d305d2", - "metadata": {}, - "source": [ - "## Cut wires using the low-level `Move` instruction\n", - "\n", - "One limitation of using the higher-level `CutWire` instruction is that it does not allow for qubit re-use. If this is desired for a cutting experiment, you can instead manually place [`Move`](/docs/api/qiskit-addon-cutting/instructions-move) instructions. However, because the `Move` instruction discards the state of the destination qubit, it is important that this qubit does not share any entanglement with the remainder of the system. Otherwise, the reset operation will cause the state of the circuit to partially collapse after the wire cut.\n", - "\n", - "The code block below performs a wire cut on qubit $q_3$ for the same example circuit as previously shown. The difference here is that you can reuse a qubit by reversing the `Move` operation where the second wire cut was made (however, this is not always possible and depends on the circuit being cut)." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "15461a2c-85a9-4cb2-a632-b9597ccbc4bd", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "qc_1 = QuantumCircuit(8)\n", - "for i in [*range(4), *range(5, 8)]:\n", - " qc_1.rx(np.pi / 4, i)\n", - "qc_1.cx(0, 3)\n", - "qc_1.cx(1, 3)\n", - "qc_1.cx(2, 3)\n", - "qc_1.append(Move(), [3, 4])\n", - "qc_1.cx(4, 5)\n", - "qc_1.cx(4, 6)\n", - "qc_1.cx(4, 7)\n", - "qc_1.append(Move(), [4, 3])\n", - "qc_1.cx(0, 3)\n", - "qc_1.cx(1, 3)\n", - "qc_1.cx(2, 3)\n", - "\n", - "# Expand observable\n", - "observable_expanded = SparsePauliOp([\"ZIIIIIII\", \"IIIIZIII\", \"IIIIIIIZ\"])\n", - "qc_1.draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "7b4f8998-4f30-4e93-84fe-957c658df678", - "metadata": {}, - "source": [ - "The circuit above can now be partitioned and cutting experiments generated. To explicitly specify how the circuit should be partitioned, you can add partition labels to the `partition_problem()` function. Qubits that share a common partition label are grouped together, and any non-local gates spanning more than one partition are cut. The keys of the dictionary output by `partition_problem()` will match those specified in the label string." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "2139745a-bdc3-40bd-bd6f-d26d2a5b5b14", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Subobservables to measure: \n", - "{'A': PauliList(['IIII', 'ZIII', 'IIIZ']), 'B': PauliList(['ZIII', 'IIII', 'IIII'])}\n", - "\n", - "Sampling overhead: 256.0\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "partitioned_problem = partition_problem(\n", - " circuit=qc_1,\n", - " partition_labels=\"AAAABBBB\",\n", - " observables=observable_expanded.paulis,\n", - ")\n", - "subcircuits = partitioned_problem.subcircuits\n", - "subobservables = partitioned_problem.subobservables\n", - "bases = partitioned_problem.bases\n", - "\n", - "print(f\"Subobservables to measure: \\n{subobservables}\\n\")\n", - "print(f\"Sampling overhead: {np.prod([basis.overhead for basis in bases])}\")\n", - "subcircuits[\"A\"].draw(\"mpl\")" - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "4aeb3f1f-a55e-49c4-a7bd-837132429ee1", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 10, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "subcircuits[\"B\"].draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "cb356463-966f-409f-af7b-eed6506e410f", - "metadata": {}, - "source": [ - "Now the cutting experiments can be generated and the expectation value reconstructed in the same way as the previous section.\n", - "\n", - "## Next steps\n", - "\n", - "\n", - " - Read the [Get started with circuit cutting using gate cuts](/docs/guides/qiskit-addons-cutting-gates) guide.\n", - " - Read the arXiv paper on [optimal wire cutting](https://arxiv.org/abs/2302.03366) to better understand the equivalence between wire cutting and gate cutting.\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": 2 -} diff --git a/docs/guides/qiskit-addons-cutting.mdx b/docs/guides/qiskit-addons-cutting.mdx deleted file mode 100644 index da8c024400d..00000000000 --- a/docs/guides/qiskit-addons-cutting.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Circuit cutting -description: Overview of the addon for circuit cutting to build utility-scale workloads ---- - -{/* cspell:ignore LOCC */} - -# Circuit cutting - -Circuit cutting is a technique to increase the size of circuits that can run on quantum hardware, at the cost of an additional sampling overhead. This addon implements this technique, in which a handful of gates, wires, or both are cut, resulting in smaller circuits that are better suited for execution on hardware. These smaller circuits are then executed, and the results of the original circuit are reconstructed through classical post-processing. However, the trade-off is that the overall number of shots must increase by a factor that is dependent on the number and type of cuts made (known as the sampling overhead). Circuit cutting can also be used to engineer gates between distant qubits which would otherwise require a large SWAP overhead. - -## Important terms - -- **Subcircuits**: The set of circuits resulting from cutting gates in a `QuantumCircuit` and then separating the disconnected qubit subsets into smaller circuits. These circuits contain [`SingleQubitQPDGate`](/docs/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate) objects and are used to instantiate each subexperiment. - -- **Subexperiment**: A term used to describe the unique circuit samples associated with a subcircuit, which are sent to a QPU for execution. - -## Install the circuit cutting package - -There are three ways to install the circuit cutting package: PyPI, building from source, and running within a containerized environment. It is recommended to install these packages in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies. - -### Install from PyPI - -The most straightforward way to install the `qiskit-addon-cutting` package is with PyPI: -```bash -pip install qiskit-addon-cutting -``` - -### Install from source - -
- -Click here to read how to install this package manually. - - -To contribute to this package or to install it manually, first clone the repository: - -```bash -git clone git@github.com:Qiskit/qiskit-addon-cutting.git -``` -and install the package with `pip`. To run the tutorials found in the package repository, install the notebook dependencies as well. Install the `dev` dependencies if you plan on developing in the repository. -```bash -pip install tox notebook -e '.[notebook-dependencies,dev]' -``` - -
- -### Use within Docker - -The dockerfile included in the addon repository can be used to build a Docker image. The included `compose.yaml` file allows you to use the Docker image with the following commands. - -
- -Click here to read how to use this package within Docker. - - -```bash -git clone git@github.com:Qiskit/qiskit-addon-cutting.git -cd qiskit-addon-cutting -docker compose build -docker compose up -``` - - If you are using `podman` and `podman-compose` instead of `docker`, the commands are: - ```bash - podman machine start - podman-compose --podman-pull-args short-name-mode="permissive" build - podman-compose up - ``` - - -Once the container is running, you should see a message similar to: -``` -notebook_1 | To access the server, open this file in a browser: -notebook_1 | file:///home/$USERNAME/.local/share/jupyter/runtime/jpserver-7-open.html -notebook_1 | Or copy and paste one of these URLs: -notebook_1 | http://e4a04564eb39:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec -notebook_1 | or http://127.0.0.1:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec -``` - -The *last* URL in this message will give you access to the Jupyter notebook interface. - -Additionally, the home directory includes a subdirectory named persistent-volume. All work you would like to save should be placed in this directory, as it is the only one that will be saved across different container runs. - - -
- -## Theoretical background - -In the circuit cutting process, there are two types of cuts: a **gate** or "space-like" cut, where a cut goes through a gate operating on two (or more) qubits, and a **wire** or "time-like" cut, which cuts directly through a qubit wire (essentially a single-qubit identity gate that has been cut into two pieces). - -The diagram below depicts an example of cutting gates so that the circuit can be split into two smaller pieces with fewer qubits. - -![Diagram of gate cutting by taking one larger circuit and cutting it into two smaller ones labeled "A" and "B"](/docs/images/guides/qiskit-addons/circuit-cutting-diagram.avif) - -There are three scenarios to consider when preparing a circuit cutting workflow, which center around the availability of classical communication between the circuit executions. The first is where only local operations (LO) are available, while the other two introduce classical communication between executions known as local operations and classical communication (LOCC). The LOCC scenarios are then grouped into either near-time, one-directional communication between circuit executions, or real-time, bi-directional communication (which you might see in a multi-QPU environment). - -While circuit cutting can be used to execute quantum circuits larger than what is possible on currently available hardware, it does come at a cost. Because the technique can be framed as a quasi-probability decomposition (QPD) problem, there is an exponential sampling overhead required in order to reconstruct the results. This overhead is the factor by which the overall number of shots must increase in order for the quasi-probability decomposition to result in the same amount of error, $\epsilon$, as you would get by executing the original circuit. Each cut gate contributes to this overhead, and the amount of overhead added depends on the type of gate that was cut (more details on the overhead sampling can be found in final appendix of [[1]](#references)). - -For example, a single cut CNOT gate incurs a sampling overhead of 9 [[2,6]](#references) and a circuit with $n$ wire cuts incurs a sampling overhead of $\mathcal{O}(16^n)$ when classical communication is not available (the LO scenario). This is reduced to $\mathcal{O}(4^n)$ when classical communication becomes available (LOCC scenario) [[4]](#references). However, wire cutting with classical communication (LOCC) is not supported by this package. - -Formally, the QPD problem of circuit cutting can be expressed as follows: - -$$ \mathcal{U} = \sum_i a_i \mathcal{F}_i,$$ - -where $\mathcal{U}$ is the quantum channel implementing the desired operation, and each $a_i$ is a real coefficient corresponding to a channel, $\mathcal{F}_i$, that is executable on hardware. - -The results equivalent to the desired channel $\mathcal{U}$ are obtained by first generating the coefficients, $a_i$, then executing subexperiments to obtain the outcomes of the different channels $\mathcal{F}_i$ in order to reconstruct the expectation values corresponding to $\mathcal{U}$. - -### A short example: cutting a RZZGate - -As a basic explicit example, consider the decomposition of a cut RZZGate (details can be found in [[2]](#references)). A quantum circuit that contains an RZZGate can be simulated by performing six subexperiments where the RZZGate has been replaced with only single-qubit operations (these are the $\mathcal{F}_i$'s from the equation above). The results of this circuit are reconstructed by combining the results of each subexperiment alongside a set of coefficients (the $a_i$'s from the equation above), which can be either positive or negative. - -For some chosen $\theta$ parameter for the RZZGate, the six subexperiments are as follows: -1. With coefficient $a_1 = \cos^2(\theta/2)$, do nothing ($I\otimes I$) -1. With coefficient $a_2 = \sin^2(\theta/2)$, perform a ZGate on each qubit ($Z\otimes Z$) -1. With coefficient $a_3 = -\sin(\theta)/2$, perform a projective measurement in the $Z$ basis on the first qubit and an $S$ on the second ($M_z\otimes S$). If the result of the measurement is $1$, flip the sign of that outcome's contribution during reconstruction. -1. With coefficient $a_4 = \sin(\theta)/2$, perform a projective measurement in the $Z$ basis on the first qubit and an $S^\dagger$ on the second ($M_z\otimes S^\dagger$). If the result of the measurement is 1, flip the sign of that outcome's contribution during reconstruction. -1. Same as 3. ($a_5=a_3$), but swap the qubits (perform $S\otimes M_z$ instead). -1. Same as 4. ($a_6=a_4$), but swap the qubits (perform $S^\dagger\otimes M_z$ instead). - -### Sampling overhead reference table - -The following table provides the sampling overhead factor for a variety of two-qubit instructions, provided that only a single instruction is cut. -| Instructions | KAK decomposition angles | Sampling overhead factor | -| --- | --- | --- | -| CSGate, CSdgGate, CSXGate | $\left(\pi/8, 0, 0\right)$ | $3+2\sqrt(2) \approx 2.828$ | -| CXGate, CYGate, CZGate, GHGate, ECRGate | $\left(\pi/4, 0, 0\right)$ | $3^2=9$ | -| iSwapGate, DCXGate | $\left(\pi/4, \pi/4, 0\right)$ | $7^2 = 49$ | -| SwapGate | $\left(\pi/4, \pi/4, \pi/4\right)$ | $7^2 = 49$ | -| RXXGate, RYYGate, RZZGate, RZXGate | $\left(\lvert\theta/2\rvert, 0, 0, \right)$ | $\left(1 + 2\lvert\sin(\theta)\rvert\right)^2$ | -| CRXGate, CRYGate, CRZGate, CPhaseGate | $\left(\lvert\theta/4\rvert, 0, 0\right)$ | $\left(1 + 2\lvert\sin(\theta/2)\rvert\right)^2$ | -| XXPlusYYGate, XXMinusYYGate | $\left(\vert\theta/4\rvert, \lvert\theta/4\rvert, 0\right)$ | $\left(1 + 4\lvert\sin(\theta/2)\rvert + 2\sin^2(\theta/2)\right)^2$ (independent of $\beta$) | -| Move (cut wire in the LO scenario) | N/A | $4^2 = 16$ | - -## Next steps - - - - [Get started with circuit cutting using gate cuts.](/docs/guides/qiskit-addons-cutting-gates) - - [Get started with circuit cutting using wire cuts.](/docs/guides/qiskit-addons-cutting-wires) - - - -## References - -[1] Christophe Piveteau, David Sutter, Circuit knitting with classical communication, https://arxiv.org/abs/2205.00016 - -[2] Kosuke Mitarai, Keisuke Fujii, Constructing a virtual two-qubit gate by sampling single-qubit operations, https://arxiv.org/abs/1909.07534 - -[3] Kosuke Mitarai, Keisuke Fujii, Overhead for simulating a non-local channel with local channels by quasiprobability sampling, https://arxiv.org/abs/2006.11174 - -[4] Lukas Brenner, Christophe Piveteau, David Sutter, Optimal wire cutting with classical communication, https://arxiv.org/abs/2302.03366 - -[5] K. Temme, S. Bravyi, and J. M. Gambetta, Error mitigation for short-depth quantum circuits, https://arxiv.org/abs/1612.02058 - -[6] Lukas Schmitt, Christophe Piveteau, David Sutter, Cutting circuits with multiple two-qubit unitaries, https://arxiv.org/abs/2312.11638 - -[7] Jun Zhang, Jiri Vala, K. Birgitta Whaley, Shankar Sastry, A geometric theory of non-local two-qubit operations, https://arxiv.org/abs/quant-ph/0209120 diff --git a/docs/guides/qiskit-addons-mpf-get-started.ipynb b/docs/guides/qiskit-addons-mpf-get-started.ipynb deleted file mode 100644 index eba32f02827..00000000000 --- a/docs/guides/qiskit-addons-mpf-get-started.ipynb +++ /dev/null @@ -1,413 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "0d234a52-9654-4ee1-bb23-f6705154c3b0", - "metadata": {}, - "source": [ - "---\n", - "title: Getting started with multi-product formulas (MPF)\n", - "description: Get started using the MPF addon using the time evolution of an Ising chain as an example\n", - "---\n", - "\n", - "\n", - "## Get started with Multi-product formulas (MPFs)" - ] - }, - { - "cell_type": "markdown", - "id": "c39cd6cd-bb4e-4e04-9f46-1e65ddf27047", - "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-addon-utils~=0.3.0\n", - "qiskit-addon-mpf~=0.3.0\n", - "scipy~=1.16.3\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "c8a99273-cf77-4f24-999e-9779c6c0c6b9", - "metadata": {}, - "source": [ - "This guide demonstrates how to use the `qiskit-addon-mpf` package, using the time evolution of an Ising model as an example. With this package, you can build a Multi-Product Formula (MPF) that can achieve lower Trotter error on observable measurements. The tools provided allow you to determine the weights of a chosen MPF, which can then be used to recombine the estimated expectation values from several time evolution circuits, each with a different number of Trotter steps.\n", - "\n", - "Begin by considering the Hamiltonian of an Ising model with 10 sites:\n", - "\n", - "$$ H_{\\text{Ising}} = \\sum_{i=1}^9 J_{i,(i+1)}Z_iZ_{i+1} + \\sum_{i=1}^{10} h_i X_i $$\n", - "\n", - "where $J_{i,(i+1)}$ is the coupling strength and $h_i$ is an external magnetic field strength. To set up the problem, the observable to measure will be the total magnetization of the system\n", - "\n", - "$$ \\langle M \\rangle = \\sum_{i=1}^{10} \\langle Z_i \\rangle. $$\n", - "\n", - "The code snippet below prepares the Hamiltonian of the Ising chain using the `qiskit-addon-utils` package, and defines the observable that will be measured." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "ef8405ef-e112-48e0-98a4-65343da2b7fd", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Hamiltonian:\n", - " SparsePauliOp(['IIIIIIIZZI', 'IIIIIZZIII', 'IIIZZIIIII', 'IZZIIIIIII', 'IIIIIIIIZZ', 'IIIIIIZZII', 'IIIIZZIIII', 'IIZZIIIIII', 'ZZIIIIIIII', 'IIIIIIIIIX', 'IIIIIIIIXI', 'IIIIIIIXII', 'IIIIIIXIII', 'IIIIIXIIII', 'IIIIXIIIII', 'IIIXIIIIII', 'IIXIIIIIII', 'IXIIIIIIII', 'XIIIIIIIII'],\n", - " coeffs=[1. +0.j, 1. +0.j, 1. +0.j, 1. +0.j, 1. +0.j, 1. +0.j, 1. +0.j, 1. +0.j,\n", - " 1. +0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j, 0.4+0.j,\n", - " 0.4+0.j, 0.4+0.j, 0.4+0.j])\n", - "\n", - "Observable:\n", - " SparsePauliOp(['IIIIIIIIIZ', 'IIIIIIIIZI', 'IIIIIIIZII', 'IIIIIIZIII', 'IIIIIZIIII', 'IIIIZIIIII', 'IIIZIIIIII', 'IIZIIIIIII', 'IZIIIIIIII', 'ZIIIIIIIII'],\n", - " coeffs=[0.05+0.j, 0.05+0.j, 0.05+0.j, 0.05+0.j, 0.05+0.j, 0.05+0.j, 0.05+0.j,\n", - " 0.05+0.j, 0.05+0.j, 0.05+0.j])\n" - ] - } - ], - "source": [ - "from qiskit.transpiler import CouplingMap\n", - "from qiskit.synthesis import SuzukiTrotter\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "from qiskit.primitives import StatevectorEstimator\n", - "from qiskit.providers.fake_provider import GenericBackendV2\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_addon_utils.problem_generators import (\n", - " generate_xyz_hamiltonian,\n", - " generate_time_evolution_circuit,\n", - ")\n", - "from qiskit_addon_mpf.costs import (\n", - " setup_exact_problem,\n", - " setup_sum_of_squares_problem,\n", - ")\n", - "from qiskit_addon_mpf.static import setup_static_lse\n", - "\n", - "from scipy.linalg import expm\n", - "import numpy as np\n", - "\n", - "# Generate some coupling map to use for this example\n", - "coupling_map = CouplingMap.from_line(10, bidirectional=False)\n", - "\n", - "# Get a qubit operator describing the Ising field model\n", - "hamiltonian = generate_xyz_hamiltonian(\n", - " coupling_map,\n", - " coupling_constants=(0.0, 0.0, 1.0),\n", - " ext_magnetic_field=(0.4, 0.0, 0.0),\n", - ")\n", - "print(f\"Hamiltonian:\\n {hamiltonian}\\n\")\n", - "\n", - "L = coupling_map.size()\n", - "observable = SparsePauliOp.from_sparse_list(\n", - " [(\"Z\", [i], 1 / L / 2) for i in range(L)], num_qubits=L\n", - ")\n", - "print(f\"Observable:\\n {observable}\")" - ] - }, - { - "cell_type": "markdown", - "id": "e4ab867e-9d04-49f5-891a-a01e0ddc98d7", - "metadata": {}, - "source": [ - "Next you prepare the MPF. The first choice to make is whether the coefficients will be static (time-independent) or dynamic; this tutorial uses a static MPF. The next choice to make is the set of $k_j$ values. This determines how many terms will be in the MPF, as well as how many Trotter steps each term uses to simulate the time evolution. The choice of $k_j$ values is heuristic, so you need to obtain your own set of \"good\" $k_j$ values. Read guidelines on finding a good set of values at the end of the [getting started page](/docs/guides/qiskit-addons-mpf#determine-mpf-coefficients).\n", - "\n", - "Then, once the $k_j$ values are determined, you can prepare the system of equations, $Ax=b$, to solve can be prepared. The matrix $A$ is also determined by the product formula to use. The choices here are its *order*, which is set to $2$ in this example, as well as whether or not the product formula should be *symmetric*, which is set to `True` for this example. The code snippet below selects a total time to evolve the system, the $k_j$ values to use, and the set of equations to solve using the [`qiskit_addon_mpf.static.setup_static_lse`](../api/qiskit-addon-mpf/static) method." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "a90e83b3-7314-4dd2-9f9a-86fd2d5e81ca", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "LSE(A=array([[1.00000000e+00, 1.00000000e+00, 1.00000000e+00],\n", - " [1.56250000e-02, 6.94444444e-03, 2.77008310e-03],\n", - " [2.44140625e-04, 4.82253086e-05, 7.67336039e-06]]), b=array([1., 0., 0.]))\n" - ] - } - ], - "source": [ - "time = 8.0\n", - "trotter_steps = (8, 12, 19)\n", - "\n", - "lse = setup_static_lse(trotter_steps, order=2, symmetric=True)\n", - "print(lse)" - ] - }, - { - "cell_type": "markdown", - "id": "0e01627b-27b8-4308-9023-4b006d73c9a5", - "metadata": {}, - "source": [ - "Once the linear system of equations has been instantiated, it can be solved either exactly or through an approximate model using a sum of squares (or the Frobenius norm for dynamic coefficients; see the [API reference](../api/qiskit-addon-mpf/costs) for more information). The choice to use an approximate model typically arises when the norm of the coefficients for the chosen set of $k_j$ values is deemed too high and a different set of $k_j$ values cannot be chosen. This guide demonstrates both to compare the results." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "d2f308be-2c13-475c-b9a7-390883a620bc", - "metadata": { - "tags": [ - "ignore-warnings" - ] - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Exact solution: [ 0.17239057 -1.19447005 2.02207947]\n", - "Approximate solution: [-0.40454257 0.57553173 0.8290123 ]\n" - ] - } - ], - "source": [ - "model_exact, coeffs_exact = setup_exact_problem(lse)\n", - "model_approx, coeffs_approx = setup_sum_of_squares_problem(\n", - " lse, max_l1_norm=3.0\n", - ")\n", - "model_exact.solve()\n", - "model_approx.solve()\n", - "print(f\"Exact solution: {coeffs_exact.value}\")\n", - "print(f\"Approximate solution: {coeffs_approx.value}\")" - ] - }, - { - "cell_type": "markdown", - "id": "c0706fcd-cf2e-473b-8d5f-11e469f6883b", - "metadata": {}, - "source": [ - "\n", - "\n", - "The `LSE` object also possesses an `LSE.solve()` method, which will solve the system of equations exactly. The reason that `setup_exact_problem()` is used in this guide is to demonstrate the interface provided by the other approximate methods.\n", - "\n", - "\n", - "\n", - "## Set up and execute Trotter circuits\n", - "\n", - "Now that the coefficients $x_j$ have been obtained, the last step is to generate the time evolution circuits for the order and chosen set of steps $k_j$ of the MPF. The `qiskit-addon-utils` package can accelerate this process." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "320332c1-d80e-4597-9eca-bc5e09fa9c58", - "metadata": {}, - "outputs": [], - "source": [ - "circuits = []\n", - "for k in trotter_steps:\n", - " circ = generate_time_evolution_circuit(\n", - " hamiltonian,\n", - " synthesis=SuzukiTrotter(order=2, reps=k),\n", - " time=time,\n", - " )\n", - " circuits.append(circ)" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "6edb8bb0-30ee-416e-9804-84372ca091cf", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "circuits[0].draw(\"mpl\", fold=-1)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "b2360c04-d2f8-4cfb-86c6-b05e71b9b708", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "circuits[1].draw(\"mpl\", fold=-1)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "2fbbe105-269e-4fb1-88b1-b0ba5acee229", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "circuits[2].draw(\"mpl\", fold=-1)" - ] - }, - { - "cell_type": "markdown", - "id": "b4eed205-0eee-477f-9b5e-a322779376e4", - "metadata": {}, - "source": [ - "Once these circuits have been constructed, you can then transpile and execute them using a QPU. For this example, we'll just use one of the noise-free simulators to demonstrate how the Trotter error is reduced." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "519129e7-c3b7-40bb-880f-f670eb5ebf82", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "[array(0.23799162), array(0.35754312), array(0.38649906)]\n" - ] - } - ], - "source": [ - "backend = GenericBackendV2(num_qubits=10)\n", - "transpiler = generate_preset_pass_manager(\n", - " optimization_level=2, backend=backend\n", - ")\n", - "\n", - "transpiled_circuits = [transpiler.run(circ) for circ in circuits]\n", - "\n", - "\n", - "estimator = StatevectorEstimator()\n", - "job = estimator.run([(circ, observable) for circ in transpiled_circuits])\n", - "result = job.result()\n", - "\n", - "mpf_evs = [res.data.evs for res in result]\n", - "print(mpf_evs)" - ] - }, - { - "cell_type": "markdown", - "id": "451861d9-10df-4ad7-b2ac-c956f9ef4458", - "metadata": {}, - "source": [ - "## Reconstruct results\n", - "\n", - "Now that the circuits have been executed, reconstructing the results is fairly straightforward. As mentioned in the [MPF overview](./qiskit-addons-mpf#theoretical-background) page, our observable is reconstructed through the weighted sum\n", - "\n", - "$$ \\langle M \\rangle = \\sum_j x_j \\langle M_j \\rangle. $$\n", - "\n", - "where $x_j$ are the coefficients we found and $\\langle M_j \\rangle$ is the estimation of the observable $\\sum_i \\langle Z_i \\rangle$ for each circuit. We can then compare the results we obtained with the exact value using the `scipy.linalg` package." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "58b3f6f2-a953-4591-8450-2217ba9dd717", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Exact value: 0.4006024248789992\n", - "PF with 19 steps: 0.3864990619977402\n", - "MPF using exact solution: 0.3954847855979902\n", - "MPF using approximate solution: 0.4299121425348959\n" - ] - } - ], - "source": [ - "exp_H = expm(-1j * time * hamiltonian.to_matrix())\n", - "initial_state = np.zeros(exp_H.shape[0])\n", - "initial_state[0] = 1.0\n", - "\n", - "time_evolved_state = exp_H @ initial_state\n", - "exact_obs = (\n", - " time_evolved_state.conj() @ observable.to_matrix() @ time_evolved_state\n", - ")\n", - "\n", - "\n", - "# Print out the different observable measurements\n", - "print(f\"Exact value: {exact_obs.real}\")\n", - "print(f\"PF with 19 steps: {mpf_evs[-1]}\")\n", - "print(f\"MPF using exact solution: {mpf_evs @ coeffs_exact.value}\")\n", - "print(f\"MPF using approximate solution: {mpf_evs @ coeffs_approx.value}\")" - ] - }, - { - "cell_type": "markdown", - "id": "61847af1-981e-4ee5-a475-08d5067456c5", - "metadata": {}, - "source": [ - "Here you can see that the MPF has reduced the Trotter error compared to the one obtained with just a single PF with $k_j=19$. However, the approximate model resulted in an expectation value that is worse than the exact model. This demonstrates the importance of using tight convergence criteria on the approximate model and finding a \"good\" set of $k_j$ values." - ] - } - ], - "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": 2 -} diff --git a/docs/guides/qiskit-addons-mpf.ipynb b/docs/guides/qiskit-addons-mpf.ipynb deleted file mode 100644 index dfc98b2e1bd..00000000000 --- a/docs/guides/qiskit-addons-mpf.ipynb +++ /dev/null @@ -1,149 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "67e54fee-28ed-4ebe-bcb8-715aa06721a1", - "metadata": {}, - "source": [ - "---\n", - "title: Multi-product formulas (MPF)\n", - "description: Overview page of the qiskit addon that generates multi-product formulas (MPF)\n", - "---\n", - "\n", - "\n", - "# Multi-product formulas (MPF)\n", - "{/* cspell:ignore Carrera, Multiproduct */}" - ] - }, - { - "cell_type": "markdown", - "id": "c1c8acff", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [ - "
\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", - "\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "b8446b77", - "metadata": {}, - "source": [ - "Multi-product formulas (MPF) can be used to more accurately simulate the dynamics of a quantum system, at the cost of increased circuit executions. This is a post-processing technique that mitigates the error of expectation values for time-evolved states.\n", - "\n", - "Classical computing is used to solve a system of linear equations that provides coefficients to a weighted combination of several circuit executions. Using this weighted combination can reduce the error associated with simulating time evolution, given a good selection of Trotter steps. The MPF tool will ingest a selection of data --- including the number of Trotter steps and the order of the Trotter approximation --- to prepare and solve (or approximate the solution of) the associated system of linear equations, which you can then use to post-process expectation value measurements of a time-evolved state." - ] - }, - { - "cell_type": "markdown", - "id": "1a2f529c-4983-447d-9923-a423b34e7215", - "metadata": {}, - "source": [ - "## Install the MPF package\n", - "\n", - "There are two ways to install the MPF package: via PyPI and building from source. It is recommended to install in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies.\n", - "\n", - "### Install from PyPI\n", - "\n", - "The most straightforward way to install the `qiskit-addon-mpf` package is via PyPI.\n", - "```bash\n", - "pip install qiskit-addon-mpf\n", - "```\n", - "\n", - "### Build from source\n", - "Users who wish to develop in the repository or who want to install it manually may do so by first cloning the repository:\n", - "```bash\n", - "git clone git@github.com:Qiskit/qiskit-addon-mpf.git\n", - "```\n", - "\n", - "and install the package via `pip`. The repository also contains a number of optional dependencies that enable certain features.\n", - "\n", - "Adjust the options to suit your needs.\n", - "```bash\n", - "pip install tox notebook -e '.[notebook-dependencies,dev]'\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "7ac19afa-954c-4c1d-b3b1-7871db85e8b4", - "metadata": {}, - "source": [ - "## Theoretical background\n", - "\n", - "MPFs can reduce the Trotter approximation error associated with simulating the dynamics of quantum systems through a weighted combination of several circuit executions. This weighted sum is defined as:\n", - "\n", - "$$ \\mu(t) = \\sum_j x_j\\rho_j^{k_j}\\left(\\frac{t}{k_j}\\right) + \\text{some remaining Trotter error}, $$\n", - "\n", - "where $x_j$ are the weighting coefficients, $\\rho_j^{k_j}$ is the density matrix that corresponds to the pure state obtained by evolving the initial state via a product formula $S^{k_j}$ approximating the time-evolution operator using $k_j$ Trotter steps, and $j$ indexes each product formula used in the sum.\n", - "\n", - "![Several circuits with a varying number of Trotter steps are used to compute the target observable](/docs/images/guides/qiskit-addons/mpf-diagram.avif)\n", - "\n", - "Generally, however, the goal of simulating quantum dynamics is to measure some observable $\\mathcal{O}(t)$, which is a function of time. When using MPFs, multiple circuits -- each using $k_j$ Trotter steps -- are executed to obtain several measurements of the target observable $\\mathcal{O}_{k_j}(t)$. The measurement of the target observable is then obtained by computing:\n", - "\n", - "$$ \\langle \\mathcal{O}(t) \\rangle = \\sum_j x_j(t) \\langle \\mathcal{O}_{k_j}(t) \\rangle. $$\n", - "\n", - "In essence, you can reduce the overall Trotter error by approximating the time-evolution operator using several product formulas with a variable number of Trotter steps instead of a single product formula. You construct a circuit for each term in the weighted sum, which evolves the system according to each of the $k_j$ number of Trotter steps. Each circuit is then executed separately on a QPU to reconstruct the results in a post-processing step. The utility of this technique can be viewed from two perspectives:\n", - "1. For a fixed number of Trotter steps that you execute, you can obtain results with a Trotter error that is smaller in total.\n", - "2. For a number of Trotter steps that result in deep circuits, you can use MPF to find several shorter-depth circuits to run, which results in a similar Trotter approximation error.\n", - "\n", - "\n", - "\n", - "## Determine MPF coefficients\n", - "\n", - "The core functionality of the `qiskit-addon-mpf` package lies in determining the MPF coefficients $x_j(t)$ (which may be time-dependent). The process to obtain each $x_j(t)$ involves solving a system of linear equations $Ax=b$ where $x$ is the vector of coefficients to be determined, $A$ is a matrix that depends on each of the $k_j$ and the product formula used $S$ (as in, the approximation order and number of Trotter steps), and $b$ is a vector of constraints. This system of equations can be solved either exactly or with an approximate model that minimizes the 1-norm of the coefficients. Additionally, the choice for each $k_j$ is a heuristic process, but can be bounded by the following constraints:\n", - "\n", - "1. The **largest** $k_j$ value is bounded by the highest depth of circuit that can be reliably executed\n", - "2. The **smallest** $k_j$ should satisfy $dt = t/k_j < 1$ since that is where the Trotter error is most well behaved\n", - "3. None of the coefficients $x_j$ should be close to $0$ since this would imply they don't contribute much to the MPF\n", - "4. Similarly, the coefficient associated with the largest $k_j$ value should not dominate, since this implies that you are using a single product formula\n", - "5. Lastly, the norm of the coefficients $x_j$ obtained should be small, as this indicates a well-conditioned MPF [1](#references)\n", - "\n", - "## Next steps\n", - "\n", - "\n", - " - Read the page on [getting started with MPF](/docs/guides/qiskit-addons-mpf-get-started).\n", - "\n", - "\n", - "## References\n", - "\n", - "1. A. Carrera Vazquez, D. J. Egger, D. Ochsner, and S. Wörner, [\"Well-conditioned multi-product formulas for hardware-friendly Hamiltonian simulation\"](https://quantum-journal.org/papers/q-2023-07-25-1067/), Quantum 7, 1067 (2023).\n", - "2. S. Zhuk, N. Robertson, and S. Bravyi, [\"Trotter error bounds and dynamic multi-product formulas for Hamiltonian simulation\"](https://journals.aps.org/prresearch/abstract/10.1103/PhysRevResearch.6.033309), Phys. Rev. Research 6, 033309 (2024).\n", - "3. N. Robertson, et al. [\"Tensor Network enhanced Dynamic Multiproduct Formulas\"](https://arxiv.org/abs/2407.17405v2), arXiv:2407.17405v2 [quant-ph]." - ] - } - ], - "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": 2 -} diff --git a/docs/guides/qiskit-addons-obp-get-started.ipynb b/docs/guides/qiskit-addons-obp-get-started.ipynb deleted file mode 100644 index 48850012044..00000000000 --- a/docs/guides/qiskit-addons-obp-get-started.ipynb +++ /dev/null @@ -1,536 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "2d697463-4d74-4761-b1d7-da8cea7cc308", - "metadata": {}, - "source": [ - "---\n", - "title: Get started with OBP\n", - "description: Get started using the operator backpropagation Qiskit addon (OBP)\n", - "---\n", - "\n", - "\n", - "# Get started with OBP" - ] - }, - { - "cell_type": "markdown", - "id": "62bcbefd", - "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", - "qiskit-addon-utils~=0.3.0\n", - "qiskit-addon-obp~=0.3.0\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "0b6244bb", - "metadata": {}, - "source": [ - "When you prepare a quantum workload with operator backpropagation (OBP), first you must make a selection of \"circuit slices\", and second, you should specify a truncation threshold or \"error budget\" to remove terms with small coefficients in the backpropagated operator as well as set an upper bound to the overall size of the backpropagated operator. During backpropagation, the number of terms in the operator of an $N$-qubit circuit will approach $4^N$ quickly in the worst-case scenario. This guide demonstrates the steps involved in applying OBP to a quantum workload.\n", - "\n", - "The main component of the `qiskit-addons-obp` package is the `backpropagate()` function. It ingests arguments for the final observable to reconstruct, a set of circuit slices to compute classically, and, optionally, a `TruncationErrorBudget` or `OperatorBudget` to provide constraints on the truncation that is done. Once these are specified, the classically computed backpropagated operator $O'$ is calculated iteratively by applying the gates from each slice, $s$, in the following way:\n", - "\n", - "$$ O'^{(s)} = \\mathcal{U}_{S-s+1}^\\dagger O'^{(s-1)} \\mathcal{U}_{S-s+1} $$\n", - "\n", - "where $S$ is the total number of slices and $\\mathcal{U}_{s}$ represents a single slice of the circuit. This example uses the `qiskit-addons-utils` package to prepare the circuit slices as well as generate the example circuit.\n", - "\n", - "\n", - "To begin, consider the time evolution of a Heisenberg XYZ chain. This Hamiltonian has the form\n", - "\n", - "$$ \\hat{H} = \\sum_{(j,k)} \\left( J_xX_jX_k + J_yY_jY_k + J_z Z_jZ_k \\right) + \\sum_{j} \\left(h_xX_j + h_yY_j + h_zZ_j\\right)$$\n", - "\n", - "and the expectation value to measure will be $\\langle Z_0 \\rangle$.\n", - "\n", - "The following code snippet generates the Hamiltonian in the form of a `SparsePauliOp` by using the `qiskit_addons_utils.problem_generators` module and a `CouplingMap`. Set the coupling constants to $J_x=\\pi/8$, $J_y=\\pi/4$, $J_z=\\pi/2$ and external magnetic fields to $h_x=\\pi/3$, $h_y=\\pi/6$, $h_z=\\pi/9$, and then generate a circuit that models its time evolution." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "5b4fd077-2d8f-46e8-9631-40cadbe07879", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 1, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import numpy as np\n", - "from qiskit.transpiler import CouplingMap\n", - "from qiskit.synthesis import LieTrotter\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2\n", - "from qiskit_ibm_runtime.fake_provider import FakeMelbourneV2\n", - "from qiskit.primitives import StatevectorEstimator\n", - "from qiskit.quantum_info import SparsePauliOp\n", - "from qiskit_addon_utils.problem_generators import (\n", - " generate_time_evolution_circuit,\n", - " generate_xyz_hamiltonian,\n", - ")\n", - "from qiskit_addon_utils.slicing import slice_by_gate_types\n", - "from qiskit_addon_obp.utils.simplify import OperatorBudget\n", - "from qiskit_addon_obp.utils.truncating import setup_budget\n", - "from qiskit_addon_obp import backpropagate\n", - "from qiskit_addon_utils.slicing import combine_slices\n", - "\n", - "\n", - "coupling_map = CouplingMap.from_heavy_hex(3, bidirectional=False)\n", - "\n", - "# Choose a 10-qubit linear chain on this coupling map\n", - "reduced_coupling_map = coupling_map.reduce(\n", - " [0, 13, 1, 14, 10, 16, 5, 12, 8, 18]\n", - ")\n", - "\n", - "# Get a qubit operator describing the Heisenberg XYZ model\n", - "hamiltonian = generate_xyz_hamiltonian(\n", - " reduced_coupling_map,\n", - " coupling_constants=(np.pi / 8, np.pi / 4, np.pi / 2),\n", - " ext_magnetic_field=(np.pi / 3, np.pi / 6, np.pi / 9),\n", - ")\n", - "\n", - "# we evolve for some time\n", - "circuit = generate_time_evolution_circuit(\n", - " hamiltonian, synthesis=LieTrotter(reps=2), time=0.2\n", - ")\n", - "\n", - "circuit.draw(\"mpl\")" - ] - }, - { - "cell_type": "markdown", - "id": "f6bcccef-263d-4cf2-81b3-141b99ffc860", - "metadata": {}, - "source": [ - "### Prepare inputs to backpropagate\n", - "\n", - "Next, generate the circuit slices for backpropagation. In general, the choice of how to slice can have an impact on how well backpropagation performs for a given problem. Here, group gates of the same type into slices using the `qiskit_addons_utils.slice_by_gate_types` function." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "af6efa03-22bd-4aa4-b17e-3e3f87cd0584", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Separated the circuit into 18 slices.\n" - ] - } - ], - "source": [ - "slices = slice_by_gate_types(circuit)\n", - "print(f\"Separated the circuit into {len(slices)} slices.\")" - ] - }, - { - "cell_type": "markdown", - "id": "10279a97-597d-44a0-b350-7a85cc58bf48", - "metadata": {}, - "source": [ - "Once the slices have been generated, specify an `OperatorBudget` to provide the `backpropagate()` function with a condition to stop backpropagating the operator and prevent the classical overhead from growing further. You can also specify a truncation error budget for each slice wherein Pauli terms with small coefficients will be truncated from each slice until the error budget is filled. Any leftover budget will then be added to the following slice's budget.\n", - "\n", - "Here, specify that backpropagation should stop when the number of qubit-wise commuting Pauli groups in the operator grows past $8$, and allocate an error budget of $0.005$ for each slice." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "5b853133-40e4-4549-9751-76cc03e87595", - "metadata": {}, - "outputs": [], - "source": [ - "op_budget = OperatorBudget(max_qwc_groups=8)\n", - "truncation_error_budget = setup_budget(max_error_per_slice=0.005)" - ] - }, - { - "cell_type": "markdown", - "id": "5488b302-2df5-4715-9af1-19c615d215c6", - "metadata": {}, - "source": [ - "### Backpropagate slices\n", - "\n", - "In this step you will define the final observable to measure and run the backpropagation across each slice. The `backpropagate()` function returns three outputs: the backpropagated observable, the remaining circuit slices that were not backpropagated (and which should be run on quantum hardware), and metadata about the backpropagation.\n", - "\n", - "Note that both the `OperatorBudget` and the `TruncationErrorBudget` are optional parameters for the `backpropagate()` method. In general, the best choice for both should be heuristically chosen and requires some amount of experimentation. In this example we will backpropagate both with and without a `TruncationErrorBudget`.\n", - "\n", - "\n", - " By default, `backpropagate()` uses the $L_1$ norm of the truncated coefficients to bound the total error incurred from truncation, but other $L_p$ can be used if you would like to modify how the truncation error is calculated.\n", - "" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "edb18b6e-8cca-4081-9909-baca7e82bf37", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Backpropagated 7 slices.\n", - "New observable has 18 terms, which can be combined into 8 groups.\n", - "After truncation, the error in our observable is bounded by 0.000e+00\n", - "Note that backpropagating one more slice would result in 27 terms across 12 groups.\n" - ] - } - ], - "source": [ - "# Specify a single-qubit observable\n", - "observable = SparsePauliOp(\"IIIIIIIIIZ\")\n", - "\n", - "# Backpropagate without the truncation error budget\n", - "backpropagated_observable, remaining_slices, metadata = backpropagate(\n", - " observable,\n", - " slices,\n", - " operator_budget=op_budget,\n", - ")\n", - "\n", - "# Recombine the slices remaining after backpropagation\n", - "bp_circuit = combine_slices(remaining_slices, include_barriers=True)\n", - "\n", - "print(f\"Backpropagated {metadata.num_backpropagated_slices} slices.\")\n", - "print(\n", - " f\"New observable has {len(backpropagated_observable.paulis)} terms, which can be combined into \"\n", - " f\"{len(backpropagated_observable.group_commuting(qubit_wise=True))} groups.\\n\"\n", - " f\"After truncation, the error in our observable is bounded by {metadata.accumulated_error(0):.3e}\"\n", - ")\n", - "print(\n", - " f\"Note that backpropagating one more slice would result in {metadata.backpropagation_history[-1].num_paulis[0]} terms \"\n", - " f\"across {metadata.backpropagation_history[-1].num_qwc_groups} groups.\"\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "243681df-1234-4b83-9139-16b2b8c88308", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The remaining circuit after backpropagation without truncation looks as follows:\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "print(\n", - " \"The remaining circuit after backpropagation without truncation looks as follows:\"\n", - ")\n", - "bp_circuit.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "bf66b2c0-ecd5-4657-9962-2d6dae8c63c0", - "metadata": {}, - "source": [ - "The below code snippets backpropagates the circuit *with* a truncation error budget." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "b1ea2012-21e2-4cb4-bc7f-f528bbb8a9cb", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Backpropagated 10 slices.\n", - "New observable has 19 terms, which can be combined into 8 groups.\n", - "After truncation, the error in our observable is bounded by 4.933e-02\n", - "Note that backpropagating one more slice would result in 27 terms across 13 groups.\n" - ] - } - ], - "source": [ - "# Backpropagate *with* the truncation error budget\n", - "backpropagated_observable_trunc, remaining_slices_trunc, metadata_trunc = (\n", - " backpropagate(\n", - " observable,\n", - " slices,\n", - " operator_budget=op_budget,\n", - " truncation_error_budget=truncation_error_budget,\n", - " )\n", - ")\n", - "\n", - "# Recombine the slices remaining after backpropagation\n", - "bp_circuit_trunc = combine_slices(\n", - " remaining_slices_trunc, include_barriers=True\n", - ")\n", - "\n", - "print(f\"Backpropagated {metadata_trunc.num_backpropagated_slices} slices.\")\n", - "print(\n", - " f\"New observable has {len(backpropagated_observable_trunc.paulis)} terms, which can be combined into \"\n", - " f\"{len(backpropagated_observable_trunc.group_commuting(qubit_wise=True))} groups.\\n\"\n", - " f\"After truncation, the error in our observable is bounded by {metadata_trunc.accumulated_error(0):.3e}\"\n", - ")\n", - "print(\n", - " f\"Note that backpropagating one more slice would result in {metadata_trunc.backpropagation_history[-1].num_paulis[0]} terms \"\n", - " f\"across {metadata_trunc.backpropagation_history[-1].num_qwc_groups} groups.\"\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "ab852775-229d-4652-9456-56c4dc8e628c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The remaining circuit after backpropagation with truncation looks as follows:\n" - ] - }, - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "print(\n", - " \"The remaining circuit after backpropagation with truncation looks as follows:\"\n", - ")\n", - "bp_circuit_trunc.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "aeb9995a-5530-4dbb-82f7-dca6abd798f0", - "metadata": {}, - "source": [ - "### Transpile and execute quantum workload\n", - "\n", - "Now that you have backpropagated the operator, you can execute the remaining portion of the circuit on a QPU. The quantum workload, using the Estimator, should include the `bp_circuit_trunc` circuit and must measure the backpropagated operator `backpropagated_observable`\n", - "\n", - "To demonstrate the effectiveness of OBP on its own, the following code snippet transpiles both the original and backpropagated circuit (with and without truncation) and simulates the circuits classically using the `StatevectorEstimator`." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "a04ff4e3-4a8c-4844-bcac-c4557c7e24fe", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Exact expectation value: 0.8854160687717517\n", - "Backpropagated expectation value without truncation: 0.8854160687717533\n", - "Backpropagated expectation value with truncation: 0.8850236647156081\n", - " - Expected Error for truncated observable: 4.933e-02\n", - " - Observed Error for truncated observable: 3.924e-04\n" - ] - } - ], - "source": [ - "# Specify a backend and a pass manager for transpilation\n", - "backend = FakeMelbourneV2()\n", - "# pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n", - "\n", - "\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=3)\n", - "\n", - "# Transpile original experiment\n", - "circuit_isa = pm.run(circuit)\n", - "observable_isa = observable.apply_layout(circuit_isa.layout)\n", - "\n", - "# Transpile backpropagated experiment without truncation\n", - "bp_circuit_isa = pm.run(bp_circuit)\n", - "bp_obs_isa = backpropagated_observable.apply_layout(bp_circuit_isa.layout)\n", - "\n", - "# Transpile the backpropagated experiment with truncated observable terms\n", - "bp_circuit_trunc_isa = pm.run(bp_circuit_trunc)\n", - "bp_obs_trunc_isa = backpropagated_observable_trunc.apply_layout(\n", - " bp_circuit_trunc_isa.layout\n", - ")\n", - "\n", - "\n", - "estimator = StatevectorEstimator()\n", - "\n", - "# Run the experiments using the exact statevector estimator\n", - "result_exact = (\n", - " estimator.run([(circuit, observable)]).result()[0].data.evs.item()\n", - ")\n", - "\n", - "result_bp = (\n", - " estimator.run([(bp_circuit_isa, bp_obs_isa)]).result()[0].data.evs.item()\n", - ")\n", - "result_bp_trunc = (\n", - " estimator.run([(bp_circuit_trunc_isa, bp_obs_trunc_isa)])\n", - " .result()[0]\n", - " .data.evs.item()\n", - ")\n", - "\n", - "print(f\"Exact expectation value: {result_exact}\")\n", - "print(f\"Backpropagated expectation value without truncation: {result_bp}\")\n", - "print(f\"Backpropagated expectation value with truncation: {result_bp_trunc}\")\n", - "print(\n", - " f\" - Expected Error for truncated observable: {metadata_trunc.accumulated_error(0):.3e}\"\n", - ")\n", - "print(\n", - " f\" - Observed Error for truncated observable: {abs(result_exact - result_bp_trunc):.3e}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "bdccc683-0fc3-4ce2-975b-3ff495247c66", - "metadata": {}, - "source": [ - "Lastly the following code snippet will transpile and execute the backpropagated circuit on a QPU (both with and without truncation)." - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "fb918a29-acb5-491a-8d7e-58fccd159a6a", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Exact expectation value: 0.8854160687717517\n", - "Backpropagated expectation value without truncation: 0.8790435084647706\n", - "Backpropagated expectation value with truncation: 0.8759838342768448\n", - " - Observed Error for observable without truncation: 6.373e-03\n", - " - Observed Error for truncated observable: 9.432e-03\n" - ] - } - ], - "source": [ - "# Specify a backend and a pass manager for transpilation\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy()\n", - "pm = generate_preset_pass_manager(backend=backend, optimization_level=3)\n", - "\n", - "# Transpile backpropagated experiment without truncation\n", - "bp_circuit_isa = pm.run(bp_circuit)\n", - "bp_obs_isa = backpropagated_observable.apply_layout(bp_circuit_isa.layout)\n", - "\n", - "# Transpile the backpropagated experiment with truncated observable terms\n", - "bp_circuit_trunc_isa = pm.run(bp_circuit_trunc)\n", - "bp_obs_trunc_isa = backpropagated_observable_trunc.apply_layout(\n", - " bp_circuit_trunc_isa.layout\n", - ")\n", - "\n", - "# Run the experiments using Estimator primitive\n", - "estimator = EstimatorV2(mode=backend)\n", - "\n", - "result_bp_qpu = (\n", - " estimator.run([(bp_circuit_isa, bp_obs_isa)]).result()[0].data.evs.item()\n", - ")\n", - "\n", - "result_bp_trunc_qpu = (\n", - " estimator.run([(bp_circuit_trunc_isa, bp_obs_trunc_isa)])\n", - " .result()[0]\n", - " .data.evs.item()\n", - ")\n", - "\n", - "print(f\"Exact expectation value: {result_exact}\")\n", - "print(f\"Backpropagated expectation value without truncation: {result_bp_qpu}\")\n", - "print(\n", - " f\"Backpropagated expectation value with truncation: {result_bp_trunc_qpu}\"\n", - ")\n", - "print(\n", - " f\" - Observed Error for observable without truncation: {abs(result_exact - result_bp_qpu):.3e}\"\n", - ")\n", - "print(\n", - " f\" - Observed Error for truncated observable: {abs(result_exact - result_bp_trunc_qpu):.3e}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "a56ecccf-d412-42bc-8bee-3a0e2f51ce2c", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - "- Try the tutorial on using [OBP to improve expectation values.](/docs/tutorials/operator-back-propagation)\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-addons-obp.mdx b/docs/guides/qiskit-addons-obp.mdx deleted file mode 100644 index 21acd1efc02..00000000000 --- a/docs/guides/qiskit-addons-obp.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Operator backpropagation (OBP) -description: Learn about the operator backpropagation addon to reduce the depth of quantum circuits ---- - -# Operator backpropagation (OBP) - -Operator backpropagation (OBP) is a technique to reduce circuit depth by trimming operations from its end at the cost of more operator measurements. There are a number of ways in which operator backpropagation can be performed, and this package uses a method based on Clifford perturbation theory [[1]](#references). - -As one propagates an operator further through a circuit, the size of the observable to measure grows exponentially. This results in both a classical and quantum resource overhead. However, for some circuits, the resulting distribution of additional Pauli observables is more concentrated than the worst-case exponential scaling. This implies that some terms in an observable with small coefficients can be truncated to reduce the quantum overhead. The error incurred by doing so can be controlled to find a suitable tradeoff between precision and efficiency. - -## Installation - -You can install the OBP package in one of two ways: via PyPI or building from source. Consider installing these packages in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies. - -### Install from PyPI - -The most straightforward way to install the `qiskit-addon-obp` package is via PyPI. - -```bash -pip install qiskit-addon-obp -``` - -### Build from source - -Users who wish to contribute to this package or who want to install it manually may do so by first cloning the repository: - -```bash -git clone git@github.com:Qiskit/qiskit-addon-obp.git -```_ - -and install the package via `pip`. The repository also contains example notebooks. If you plan on developing in the repository, install the `dev` dependencies. - -Adjust the options to suit your needs: - -```bash -pip install tox notebook -e '.[notebook-dependencies, dev]' -``` - -## Theoretical background - -The OBP procedure implemented in this package is described in detail in [[1]](#references). When using the Estimator primitive, the output of a quantum workload is the estimation of one or more expectation values $\langle O \rangle$ with respect to some state prepared using a QPU. This section summarizes the procedure. - -First, start by writing the expectation value measurement of an observable $O$ in terms of some initial state $|\psi\rangle$ and a quantum circuit $U_Q$: - -$$ \langle O \rangle_{U|\psi\rangle} = \langle\psi | U^\dagger O U |\psi \rangle. $$ - -To distribute this problem across both classical and quantum resources, split the circuit $U$ into two subcircuits, $U_C$ and $U_Q$, classically simulate the circuit $U_C$, then execute the circuit $U_Q$ on quantum hardware and use the results of the classical simulation to reconstruct the measurement of the observable $O$. - -![OBP diagram depicting splitting a circuit into two subcircuits, classically computing one of the subcircuits, then measuring the other circuit using quantum hardware](/docs/images/guides/qiskit-addons/obp-diagram.avif) - - -The subcircuit $U_C$ should be selected to be classically simulable and will compute the expectation value - -$$ \langle O' \rangle \equiv U_C^\dagger O U_C, $$ - -which is the version of the initial operator $O$ evolved through the circuit $U_C$. Once $O'$ has been determined, the quantum workload is prepared wherein the state $|\psi\rangle$ is initiated, has the circuit $U_Q$ applied to it, and then measures the expectation value $O'$. You can show that this is equivalent to measuring $\langle O \rangle$ by writing: - -$$ \langle \psi | U_Q^\dagger O' U_Q \psi \rangle = \langle \psi | U_Q^\dagger U_C^\dagger O U_CU_Q \psi \rangle = \langle\psi | U^\dagger O U |\psi \rangle = \langle O \rangle_{U|\psi\rangle}$$ - - -Lastly, in order to measure the expectation value $\langle O' \rangle$, we must require it to be decomposable into a sum of Pauli strings - -$$ O' = \sum_P c_P P, $$ - -where $c_P$ are real coefficients of the decomposition and $P$ is some Pauli string composed of $I$, $X$, $Y$, and $Z$ operators. This ensures that you can reconstruct the expectation value of $O$ by - -$$ \langle \psi | U_Q^\dagger O' |\psi \rangle = \sum_P c_P \langle \psi | U_Q^\dagger P U_Q | \psi \rangle. $$ - - -### Truncating terms - -This scheme offers a tradeoff between the required circuit depth of $U_Q$, the number of circuit executions on quantum hardware, and the amount of classical computing resources needed to compute $O'$. In general, as you choose to backpropagate further through a circuit, the number of Pauli strings to measure as well as the error-mitigation overhead both grow exponentially (alongside the classical resources needed to simulate $U_C$). - -Fortunately, the decomposition of $O'$ can often contain coefficients that are quite small and can be truncated from the final measurements used to reconstruct $O$ without incurring much error. The `qiskit-addon-obp` package possesses functionality to specify an error budget, which can automatically search for terms that can be truncated, to within some error tolerance. - - -### Clifford perturbation theory - -Lastly, the `qiskit-addon-obp` package approaches operator backpropagation based on Clifford perturbation theory. This method has the benefit that the overhead incurred by backpropagating various gates scales with the non-Cliffordness of $U_C$ (i.e. how much of U C is comprised of non-Clifford instructions). - -This approach to OBP begins by splitting the simulated circuit, $U_C$, into *slices*: - -$$ U_C = \prod_{s=1}^S \mathcal{U}_s = \mathcal{U}_S...\mathcal{U}_2\mathcal{U}_1, $$ - -where $S$ represents the total number of slices and $\mathcal{U}_s$ denotes a single slice of the circuit $U_C$. Each of these slices are then analytically applied in sequence to measure the back propagated operator $O'$ and may or may not contribute to the overall size of the sum, depending on if the slice is a Clifford vs non-Clifford operation. If an [error budget](../api/qiskit-addon-obp/utils-truncating#setup_budget) is allocated, truncation will then occur between the application of each slice. - - - -## Next steps - - - - [Get started with OBP.](/docs/guides/qiskit-addons-obp-get-started) - - Become familiar with the [error mitigation techniques](/docs/guides/error-mitigation-and-suppression-techniques) available in Qiskit Runtime. - - Read the tutorial on using [OBP to improve expectation values.](/docs/tutorials/operator-back-propagation) - - -## References - -[1] Fuller, Bryce, et al. "Improved Quantum Computation using Operator Backpropagation." [arXiv:2502.01897 \[quant-ph\]](https://arxiv.org/abs/2502.01897) (2025). \ No newline at end of file diff --git a/docs/guides/qiskit-addons-utils.ipynb b/docs/guides/qiskit-addons-utils.ipynb deleted file mode 100644 index ef802fd1fb6..00000000000 --- a/docs/guides/qiskit-addons-utils.ipynb +++ /dev/null @@ -1,477 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "872b8998-8cfa-4991-9658-f99716a84784", - "metadata": {}, - "source": [ - "---\n", - "title: Qiskit addon utilities\n", - "description: Get started with the Qiskit addon utilities to supplement your addon workloads\n", - "---\n", - "\n", - "\n", - "# Qiskit addon utilities" - ] - }, - { - "cell_type": "markdown", - "id": "0bed855a", - "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", - "qiskit-addon-utils~=0.3.0\n", - "```\n", - "
" - ] - }, - { - "cell_type": "markdown", - "id": "babf0aa2", - "metadata": {}, - "source": [ - "The Qiskit addon utilities package is a collection of functionalities to supplement workflows involving one or more Qiskit addons. For example, this package contains functions for creating Hamiltonians, generating Trotter time-evolution circuits, and slicing and combining quantum circuits.\n", - "\n", - "## Installation\n", - "\n", - "There are two ways to install the Qiskit addon utilities: PyPI and building from source. It is recommended to install these packages in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies.\n", - "\n", - "### Install from PyPI\n", - "\n", - "The most straightforward way to install the Qiskit addon utilities package is via PyPI.\n", - "\n", - "```bash\n", - "pip install 'qiskit-addon-utils'\n", - "```\n", - "\n", - "### Install from source\n", - "\n", - "
\n", - "\n", - "Click here to read how to install this package manually.\n", - "\n", - "\n", - "If you wish to contribute to this package or want to install it manually, first clone the repository:\n", - "\n", - "```bash\n", - "git clone git@github.com:Qiskit/qiskit-addon-utils.git\n", - "```\n", - "\n", - "and install the package via `pip`. If you plan to run the tutorials found in the package repository, install the notebook dependencies as well. If you plan to develop in the repository, install the `dev` dependencies.\n", - "```bash\n", - "pip install tox jupyterlab -e '.[notebook-dependencies,dev]'\n", - "```\n", - "
\n", - "\n", - "## Get started with utilities\n", - "\n", - "There are several modules within the `qiskit-addon-utils` package, including one for problem generation for simulating quantum systems, graph coloring to more efficiently place gates in a quantum circuit, and circuit slicing, which can help with [operator backpropagation](/docs/guides/qiskit-addons-obp). The following sections summarize each module. The package's [API documentation](/docs/api/qiskit-addon-utils) also contains helpful information.\n", - "\n", - "### Problem generation\n", - "\n", - "The contents of the [`qiskit_addon_utils.problem_generators`](../api/qiskit-addon-utils/problem-generators) module include:\n", - "\n", - "- A [`generate_xyz_hamiltonian()`](../api/qiskit-addon-utils/problem-generators#generate_xyz_hamiltonian) function, which generates a connectivity-aware `SparsePauliOp` representation of an Ising-type XYZ model:\n", - "\n", - "$$H = \\sum_{(j,k)\\in E} \\left(J_x X_jX_k + J_yY_jY_k + J_zZ_jZ_k\\right) + \\sum_{j\\in V} \\left(h_x X_j + h_y Y_j + h_z Z_j\\right) $$\n", - "- A [`generate_time_evolution_circuit()`](../api/qiskit-addon-utils/problem-generators#generate_time_evolution_circuit) function, which constructs a circuit modeling the time evolution of a given operator.\n", - "- Three different [`PauliOrderStrategy`](../api/qiskit-addon-utils/problem-generators#pauliorderstrategy) objects for enumerating between different Pauli string orderings. This is mostly helpful when used alongside graph coloring and can be used as arguments in both the `generate_xyz_hamiltonian()` and `generate_time_evolution_circuit()` functions.\n", - "\n", - "\n", - "\n", - "### Graph coloring\n", - "\n", - "The [`qiskit_addon_utils.coloring`](../api/qiskit-addon-utils/coloring) module is used to color the edges in a coupling map and use this coloring to more efficiently place gates in a quantum circuit. The purpose of this edge-colored coupling map is to find a set of edge colors such that no two edges of the same color share a common node. For a QPU, this means that gates along like-colored edges (qubit connections) can be run simultaneously and the circuit will execute faster.\n", - "\n", - "As a quick example, you can use the [`auto_color_edges()`](../api/qiskit-addon-utils/coloring#auto_color_edges) function to generate an edge coloring for a naive circuit executing a `CZGate` along each qubit connection. The code snippet below uses the `FakeSherbrooke` backend's coupling map, creates this naive circuit, then uses the `auto_color_edges()` function to create a more efficient equivalent circuit." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "dc37116f-1d7f-4675-bc45-11798ef9cc77", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "The circuit without using edge coloring has depth: 37\n", - "The circuit using edge coloring has depth: 3\n" - ] - } - ], - "source": [ - "from qiskit_ibm_runtime.fake_provider import FakeSherbrooke\n", - "from qiskit import QuantumCircuit\n", - "from qiskit_addon_utils.coloring import auto_color_edges\n", - "from qiskit_addon_utils.slicing import combine_slices, slice_by_depth\n", - "from collections import defaultdict\n", - "\n", - "backend = FakeSherbrooke()\n", - "coupling_map = backend.coupling_map\n", - "\n", - "# Create naive circuit\n", - "circuit = QuantumCircuit(backend.num_qubits)\n", - "for edge in coupling_map.graph.edge_list():\n", - " circuit.cz(edge[0], edge[1])\n", - "\n", - "\n", - "# Color the edges of the coupling map\n", - "coloring = auto_color_edges(coupling_map)\n", - "circuit_with_coloring = QuantumCircuit(backend.num_qubits)\n", - "\n", - "# Make a reverse coloring dict in order to make the circuit\n", - "color_to_edge = defaultdict(list)\n", - "for edge, color in coloring.items():\n", - " color_to_edge[color].append(edge)\n", - "\n", - "# Place edges in order of color\n", - "for edges in color_to_edge.values():\n", - " for edge in edges:\n", - " circuit_with_coloring.cz(edge[0], edge[1])\n", - "\n", - "print(f\"The circuit without using edge coloring has depth: {circuit.depth()}\")\n", - "print(\n", - " f\"The circuit using edge coloring has depth: {circuit_with_coloring.depth()}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "0e4d5579-56dc-4e87-be52-b39d0d12773f", - "metadata": {}, - "source": [ - "### Slicing\n", - "\n", - "Lastly, the [`qiskit-addon-utils.slicing`](../api/qiskit-addon-utils/slicing) module contains functions and transpiler passes to work with creating circuit \"slices\", time-like partitions of a [`QuantumCircuit`](../api/qiskit/qiskit.circuit.QuantumCircuit) spanning across all qubits. These slices are primarily used for [operator backpropagation](/docs/guides/qiskit-addons-obp-get-started). The main four ways a circuit can be sliced are by gate type, depth, coloring, or [`Barrier`](../api/qiskit/circuit#barrier) instructions. The output of these slicing functions returns a list of [`QuantumCircuit`](../api/qiskit/qiskit.circuit.QuantumCircuit) objects. Sliced circuits can also be recombined using the [`combine_slices()`](../api/qiskit-addon-utils/slicing#combine_slices) function. Read the module's [API reference](../api/qiskit-addon-utils/slicing) for more information.\n", - "\n", - "Below are a few examples of how to create these slices using the following circuit:" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "d5a5c53f-45d2-4cdc-86f3-221f179cdbea", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import numpy as np\n", - "from qiskit import QuantumCircuit\n", - "\n", - "num_qubits = 9\n", - "qc = QuantumCircuit(num_qubits)\n", - "qc.ry(np.pi / 4, range(num_qubits))\n", - "qubits_1 = [i for i in range(num_qubits) if i % 2 == 0]\n", - "qubits_2 = [i for i in range(num_qubits) if i % 2 == 1]\n", - "qc.cx(qubits_1[:-1], qubits_2)\n", - "qc.cx(qubits_2, qubits_1[1:])\n", - "qc.cx(qubits_1[-1], qubits_1[0])\n", - "qc.rx(np.pi / 4, range(num_qubits))\n", - "qc.rz(np.pi / 4, range(num_qubits))\n", - "qc.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "44e2b81d-9c41-46c7-aaec-b8448cd8abaa", - "metadata": {}, - "source": [ - "In the case where there is no clear way to exploit the structure of a circuit for operator backpropagation, you can partition the circuit into slices of a given depth." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "6d824d97-edc6-4c88-bcfa-428731393f83", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# Slice circuit into partitions of depth 1\n", - "slices = slice_by_depth(qc, 1)\n", - "\n", - "# Recombine slices in order to visualize the partitions together\n", - "combined_slices = combine_slices(slices, include_barriers=True)\n", - "combined_slices.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "53a4346a-34fd-42e9-9cd5-0a8c28d8d384", - "metadata": {}, - "source": [ - "In cases such as when executing Trotter circuits to model the dynamics of a quantum system, it may be advantageous to slice by gate type." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "d011c56e-d741-491a-8867-54952cb7b757", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from qiskit_addon_utils.slicing import slice_by_gate_types\n", - "\n", - "slices = slice_by_gate_types(qc)\n", - "\n", - "# Recombine slices in order to visualize the partitions together\n", - "combined_slices = combine_slices(slices, include_barriers=True)\n", - "combined_slices.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "57c844b5-cbe0-4369-80a6-57a2fc8840d9", - "metadata": {}, - "source": [ - "If your workload is designed to exploit the physical qubit connectivity of the QPU it will be run on, you can create slices based on edge coloring. The code snippet below will assign a three-coloring to circuit edges and slice the circuit with respect to the edge coloring. (Note: this only affects non-local gates. Single-qubit gates will be sliced by gate type)." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "41290d70-e116-4bd2-b9e7-d90aeaa852aa", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from qiskit_addon_utils.slicing import slice_by_coloring\n", - "\n", - "# Assign a color to each set of connected qubits\n", - "coloring = {}\n", - "for i in range(num_qubits - 1):\n", - " coloring[(i, i + 1)] = i % 3\n", - "coloring[(num_qubits - 1, 0)] = 2\n", - "\n", - "# Create a circuit with operations added in order of color\n", - "qc = QuantumCircuit(num_qubits)\n", - "qc.ry(np.pi / 4, range(num_qubits))\n", - "edges = [\n", - " edge for color in range(3) for edge in coloring if coloring[edge] == color\n", - "]\n", - "for edge in edges:\n", - " qc.cx(edge[0], edge[1])\n", - "qc.rx(np.pi / 4, range(num_qubits))\n", - "qc.rz(np.pi / 4, range(num_qubits))\n", - "\n", - "# Create slices by edge color\n", - "slices = slice_by_coloring(qc, coloring=coloring)\n", - "\n", - "# Recombine slices in order to visualize the partitions together\n", - "combined_slices = combine_slices(slices, include_barriers=True)\n", - "combined_slices.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "7c84e437-3a45-4c3f-9c8e-706b302672d4", - "metadata": {}, - "source": [ - "If you have a custom slicing strategy, you can instead place barriers in the circuit to delineate where it should be sliced and use the [`slice_by_barriers`](../api/qiskit-addon-utils/slicing#slice_by_barriers) function." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "5040a678-9d5f-4c8b-8a92-7de04c3fcfda", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 6, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "qc = QuantumCircuit(num_qubits)\n", - "qc.ry(np.pi / 4, range(num_qubits))\n", - "qc.barrier()\n", - "qubits_1 = [i for i in range(num_qubits) if i % 2 == 0]\n", - "qubits_2 = [i for i in range(num_qubits) if i % 2 == 1]\n", - "qc.cx(qubits_1[:-1], qubits_2)\n", - "qc.cx(qubits_2, qubits_1[1:])\n", - "qc.cx(qubits_1[-1], qubits_1[0])\n", - "qc.barrier()\n", - "qc.rx(np.pi / 4, range(num_qubits))\n", - "qc.rz(np.pi / 4, range(num_qubits))\n", - "qc.draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "8a20a531-61dd-4461-b482-ee3223b6223d", - "metadata": {}, - "source": [ - "Once the barriers are in place, you can examine each of the slices individually." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "b1106c2f-711c-4d30-b91a-ea05f47598d8", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "from qiskit_addon_utils.slicing import slice_by_barriers\n", - "\n", - "slices = slice_by_barriers(qc)\n", - "slices[0].draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "1afd2111-dd88-4e20-a137-f0c975e9d1bb", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "slices[1].draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "360ab773-df81-4975-bb19-cd5f34e69b29", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "slices[2].draw(\"mpl\", scale=0.6)" - ] - }, - { - "cell_type": "markdown", - "id": "81d9b18a-76ce-4660-a638-48c02723adde", - "metadata": {}, - "source": [ - "## Next steps\n", - "\n", - "\n", - " - Read through the overview of the [OBP addon.](/docs/guides/qiskit-addons-obp)\n", - " - Understand how the [SQD addon](/docs/guides/qiskit-addons-sqd) works.\n", - " - Familiarize yourself with the [AQC-Tensor addon.](/docs/guides/qiskit-addons-aqc)\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": 2 -} From 6b0b8036c8d257dc36e85f1680b2dc7b7721cb3d Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:36:12 -0500 Subject: [PATCH 017/118] delete images --- .../extracted-outputs/45abbabe-0289-4a09-aa99-89f70bdc535d-0.svg | 1 - .../extracted-outputs/e08edb92-da1f-4131-85f5-f89006f7a2dd-0.svg | 1 - .../extracted-outputs/1551c440-c158-478a-a8fe-86df834c59bd-1.svg | 1 - .../extracted-outputs/1c527720-0d06-48a1-88b6-9ff95a77a068-0.svg | 1 - .../extracted-outputs/64010a14-8360-47e2-bb77-af9b2e0dbbfc-1.svg | 1 - .../extracted-outputs/66dc0a14-ab51-4190-9cda-1c0373e91b9e-0.svg | 1 - .../extracted-outputs/a5454265-3785-4a54-b423-baf7815b97ec-1.svg | 1 - .../extracted-outputs/15461a2c-85a9-4cb2-a632-b9597ccbc4bd-0.svg | 1 - .../extracted-outputs/2139745a-bdc3-40bd-bd6f-d26d2a5b5b14-1.svg | 1 - .../extracted-outputs/4aeb3f1f-a55e-49c4-a7bd-837132429ee1-0.svg | 1 - .../extracted-outputs/5fb034f2-da8a-4f4d-ab9b-c990593e04fc-1.svg | 1 - .../extracted-outputs/9bac1915-316b-49d0-a1a1-145047679530-0.svg | 1 - .../extracted-outputs/b481ef2d-3912-4eac-9755-335e8f5db886-0.svg | 1 - .../extracted-outputs/d0e86f81-7c7e-4ccf-951c-9cd039135dc9-0.svg | 1 - .../extracted-outputs/d398b397-0167-4db9-97ae-6ea502dc43e3-1.svg | 1 - .../extracted-outputs/2fbbe105-269e-4fb1-88b1-b0ba5acee229-0.svg | 1 - .../extracted-outputs/6edb8bb0-30ee-416e-9804-84372ca091cf-0.svg | 1 - .../extracted-outputs/b2360c04-d2f8-4cfb-86c6-b05e71b9b708-0.svg | 1 - .../extracted-outputs/243681df-1234-4b83-9139-16b2b8c88308-1.svg | 1 - .../extracted-outputs/5b4fd077-2d8f-46e8-9631-40cadbe07879-0.svg | 1 - .../extracted-outputs/ab852775-229d-4652-9456-56c4dc8e628c-1.svg | 1 - .../extracted-outputs/1afd2111-dd88-4e20-a137-f0c975e9d1bb-0.svg | 1 - .../extracted-outputs/360ab773-df81-4975-bb19-cd5f34e69b29-0.svg | 1 - .../extracted-outputs/41290d70-e116-4bd2-b9e7-d90aeaa852aa-0.svg | 1 - .../extracted-outputs/5040a678-9d5f-4c8b-8a92-7de04c3fcfda-0.svg | 1 - .../extracted-outputs/6d824d97-edc6-4c88-bcfa-428731393f83-0.svg | 1 - .../extracted-outputs/b1106c2f-711c-4d30-b91a-ea05f47598d8-0.svg | 1 - .../extracted-outputs/d011c56e-d741-491a-8867-54952cb7b757-0.svg | 1 - .../extracted-outputs/d5a5c53f-45d2-4cdc-86f3-221f179cdbea-0.svg | 1 - 29 files changed, 29 deletions(-) delete mode 100644 public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/45abbabe-0289-4a09-aa99-89f70bdc535d-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/e08edb92-da1f-4131-85f5-f89006f7a2dd-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1551c440-c158-478a-a8fe-86df834c59bd-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1c527720-0d06-48a1-88b6-9ff95a77a068-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/64010a14-8360-47e2-bb77-af9b2e0dbbfc-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/66dc0a14-ab51-4190-9cda-1c0373e91b9e-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/a5454265-3785-4a54-b423-baf7815b97ec-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/15461a2c-85a9-4cb2-a632-b9597ccbc4bd-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/2139745a-bdc3-40bd-bd6f-d26d2a5b5b14-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/4aeb3f1f-a55e-49c4-a7bd-837132429ee1-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/5fb034f2-da8a-4f4d-ab9b-c990593e04fc-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/9bac1915-316b-49d0-a1a1-145047679530-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/b481ef2d-3912-4eac-9755-335e8f5db886-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d0e86f81-7c7e-4ccf-951c-9cd039135dc9-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d398b397-0167-4db9-97ae-6ea502dc43e3-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/2fbbe105-269e-4fb1-88b1-b0ba5acee229-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/6edb8bb0-30ee-416e-9804-84372ca091cf-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/b2360c04-d2f8-4cfb-86c6-b05e71b9b708-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/243681df-1234-4b83-9139-16b2b8c88308-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/5b4fd077-2d8f-46e8-9631-40cadbe07879-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/ab852775-229d-4652-9456-56c4dc8e628c-1.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/1afd2111-dd88-4e20-a137-f0c975e9d1bb-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/360ab773-df81-4975-bb19-cd5f34e69b29-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/41290d70-e116-4bd2-b9e7-d90aeaa852aa-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/5040a678-9d5f-4c8b-8a92-7de04c3fcfda-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/6d824d97-edc6-4c88-bcfa-428731393f83-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/b1106c2f-711c-4d30-b91a-ea05f47598d8-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d011c56e-d741-491a-8867-54952cb7b757-0.svg delete mode 100644 public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d5a5c53f-45d2-4cdc-86f3-221f179cdbea-0.svg diff --git a/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/45abbabe-0289-4a09-aa99-89f70bdc535d-0.svg b/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/45abbabe-0289-4a09-aa99-89f70bdc535d-0.svg deleted file mode 100644 index c71f2422e4a..00000000000 --- a/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/45abbabe-0289-4a09-aa99-89f70bdc535d-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/e08edb92-da1f-4131-85f5-f89006f7a2dd-0.svg b/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/e08edb92-da1f-4131-85f5-f89006f7a2dd-0.svg deleted file mode 100644 index cfa6cce5b2e..00000000000 --- a/public/docs/images/guides/qiskit-addons-aqc-get-started/extracted-outputs/e08edb92-da1f-4131-85f5-f89006f7a2dd-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1551c440-c158-478a-a8fe-86df834c59bd-1.svg b/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1551c440-c158-478a-a8fe-86df834c59bd-1.svg deleted file mode 100644 index ea1f67fc0c8..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1551c440-c158-478a-a8fe-86df834c59bd-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1c527720-0d06-48a1-88b6-9ff95a77a068-0.svg b/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1c527720-0d06-48a1-88b6-9ff95a77a068-0.svg deleted file mode 100644 index d937da3613f..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/1c527720-0d06-48a1-88b6-9ff95a77a068-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/64010a14-8360-47e2-bb77-af9b2e0dbbfc-1.svg b/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/64010a14-8360-47e2-bb77-af9b2e0dbbfc-1.svg deleted file mode 100644 index 057cfc8efdd..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/64010a14-8360-47e2-bb77-af9b2e0dbbfc-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/66dc0a14-ab51-4190-9cda-1c0373e91b9e-0.svg b/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/66dc0a14-ab51-4190-9cda-1c0373e91b9e-0.svg deleted file mode 100644 index be06e5701b7..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/66dc0a14-ab51-4190-9cda-1c0373e91b9e-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/a5454265-3785-4a54-b423-baf7815b97ec-1.svg b/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/a5454265-3785-4a54-b423-baf7815b97ec-1.svg deleted file mode 100644 index 30025a11389..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-gates/extracted-outputs/a5454265-3785-4a54-b423-baf7815b97ec-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/15461a2c-85a9-4cb2-a632-b9597ccbc4bd-0.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/15461a2c-85a9-4cb2-a632-b9597ccbc4bd-0.svg deleted file mode 100644 index 1e874806cf0..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/15461a2c-85a9-4cb2-a632-b9597ccbc4bd-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/2139745a-bdc3-40bd-bd6f-d26d2a5b5b14-1.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/2139745a-bdc3-40bd-bd6f-d26d2a5b5b14-1.svg deleted file mode 100644 index addb135904d..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/2139745a-bdc3-40bd-bd6f-d26d2a5b5b14-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/4aeb3f1f-a55e-49c4-a7bd-837132429ee1-0.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/4aeb3f1f-a55e-49c4-a7bd-837132429ee1-0.svg deleted file mode 100644 index 16c07bf1596..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/4aeb3f1f-a55e-49c4-a7bd-837132429ee1-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/5fb034f2-da8a-4f4d-ab9b-c990593e04fc-1.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/5fb034f2-da8a-4f4d-ab9b-c990593e04fc-1.svg deleted file mode 100644 index 747bc9d237f..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/5fb034f2-da8a-4f4d-ab9b-c990593e04fc-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/9bac1915-316b-49d0-a1a1-145047679530-0.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/9bac1915-316b-49d0-a1a1-145047679530-0.svg deleted file mode 100644 index 9ffa1a0bbec..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/9bac1915-316b-49d0-a1a1-145047679530-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/b481ef2d-3912-4eac-9755-335e8f5db886-0.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/b481ef2d-3912-4eac-9755-335e8f5db886-0.svg deleted file mode 100644 index e283c16f866..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/b481ef2d-3912-4eac-9755-335e8f5db886-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d0e86f81-7c7e-4ccf-951c-9cd039135dc9-0.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d0e86f81-7c7e-4ccf-951c-9cd039135dc9-0.svg deleted file mode 100644 index 05571f42598..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d0e86f81-7c7e-4ccf-951c-9cd039135dc9-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d398b397-0167-4db9-97ae-6ea502dc43e3-1.svg b/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d398b397-0167-4db9-97ae-6ea502dc43e3-1.svg deleted file mode 100644 index 2c73f545493..00000000000 --- a/public/docs/images/guides/qiskit-addons-cutting-wires/extracted-outputs/d398b397-0167-4db9-97ae-6ea502dc43e3-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/2fbbe105-269e-4fb1-88b1-b0ba5acee229-0.svg b/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/2fbbe105-269e-4fb1-88b1-b0ba5acee229-0.svg deleted file mode 100644 index 48a56f38581..00000000000 --- a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/2fbbe105-269e-4fb1-88b1-b0ba5acee229-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/6edb8bb0-30ee-416e-9804-84372ca091cf-0.svg b/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/6edb8bb0-30ee-416e-9804-84372ca091cf-0.svg deleted file mode 100644 index 89476d126ca..00000000000 --- a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/6edb8bb0-30ee-416e-9804-84372ca091cf-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/b2360c04-d2f8-4cfb-86c6-b05e71b9b708-0.svg b/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/b2360c04-d2f8-4cfb-86c6-b05e71b9b708-0.svg deleted file mode 100644 index e0c1a87f2d7..00000000000 --- a/public/docs/images/guides/qiskit-addons-mpf-get-started/extracted-outputs/b2360c04-d2f8-4cfb-86c6-b05e71b9b708-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/243681df-1234-4b83-9139-16b2b8c88308-1.svg b/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/243681df-1234-4b83-9139-16b2b8c88308-1.svg deleted file mode 100644 index 3380b038e8e..00000000000 --- a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/243681df-1234-4b83-9139-16b2b8c88308-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/5b4fd077-2d8f-46e8-9631-40cadbe07879-0.svg b/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/5b4fd077-2d8f-46e8-9631-40cadbe07879-0.svg deleted file mode 100644 index a56778c83d9..00000000000 --- a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/5b4fd077-2d8f-46e8-9631-40cadbe07879-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/ab852775-229d-4652-9456-56c4dc8e628c-1.svg b/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/ab852775-229d-4652-9456-56c4dc8e628c-1.svg deleted file mode 100644 index 84ee5928b4a..00000000000 --- a/public/docs/images/guides/qiskit-addons-obp-get-started/extracted-outputs/ab852775-229d-4652-9456-56c4dc8e628c-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/1afd2111-dd88-4e20-a137-f0c975e9d1bb-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/1afd2111-dd88-4e20-a137-f0c975e9d1bb-0.svg deleted file mode 100644 index 0a22299bce7..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/1afd2111-dd88-4e20-a137-f0c975e9d1bb-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/360ab773-df81-4975-bb19-cd5f34e69b29-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/360ab773-df81-4975-bb19-cd5f34e69b29-0.svg deleted file mode 100644 index dcb32ce02dd..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/360ab773-df81-4975-bb19-cd5f34e69b29-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/41290d70-e116-4bd2-b9e7-d90aeaa852aa-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/41290d70-e116-4bd2-b9e7-d90aeaa852aa-0.svg deleted file mode 100644 index 653b09ae0b8..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/41290d70-e116-4bd2-b9e7-d90aeaa852aa-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/5040a678-9d5f-4c8b-8a92-7de04c3fcfda-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/5040a678-9d5f-4c8b-8a92-7de04c3fcfda-0.svg deleted file mode 100644 index aeb73c12f2e..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/5040a678-9d5f-4c8b-8a92-7de04c3fcfda-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/6d824d97-edc6-4c88-bcfa-428731393f83-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/6d824d97-edc6-4c88-bcfa-428731393f83-0.svg deleted file mode 100644 index febacc87f04..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/6d824d97-edc6-4c88-bcfa-428731393f83-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/b1106c2f-711c-4d30-b91a-ea05f47598d8-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/b1106c2f-711c-4d30-b91a-ea05f47598d8-0.svg deleted file mode 100644 index e8cf20443a3..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/b1106c2f-711c-4d30-b91a-ea05f47598d8-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d011c56e-d741-491a-8867-54952cb7b757-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d011c56e-d741-491a-8867-54952cb7b757-0.svg deleted file mode 100644 index b4fd62aca3f..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d011c56e-d741-491a-8867-54952cb7b757-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d5a5c53f-45d2-4cdc-86f3-221f179cdbea-0.svg b/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d5a5c53f-45d2-4cdc-86f3-221f179cdbea-0.svg deleted file mode 100644 index f180758aede..00000000000 --- a/public/docs/images/guides/qiskit-addons-utils/extracted-outputs/d5a5c53f-45d2-4cdc-86f3-221f179cdbea-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file From 87fa79391003b78cce8a64230ee0a439b13c771f Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:38:32 -0500 Subject: [PATCH 018/118] move advanced techniques up --- docs/guides/_toc.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index b4e120d324a..9f710f555b0 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -289,6 +289,10 @@ } ] }, + { + "title": "Advanced techniques", + "url": "/docs/guides/addons" + }, { "title": "Create a provider", "url": "/docs/guides/create-a-provider" @@ -341,10 +345,6 @@ "url": "/docs/guides/qiskit-code-assistant-openai-api" } ] - }, - { - "title": "Advanced techniques", - "url": "/docs/guides/addons" } ], "collapsible": false From 5c8debed0a5e893d3392addff6c16d296ce60f2c Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:41:41 -0500 Subject: [PATCH 019/118] clean up some links --- docs/guides/tools-intro.mdx | 22 ---------------------- qiskit_bot.yaml | 20 -------------------- 2 files changed, 42 deletions(-) diff --git a/docs/guides/tools-intro.mdx b/docs/guides/tools-intro.mdx index c5006cd0938..68942655b2e 100644 --- a/docs/guides/tools-intro.mdx +++ b/docs/guides/tools-intro.mdx @@ -100,28 +100,6 @@ pip install qiskit-ibm-transpiler Qiskit addons are a collection of research capabilities for utility-scale algorithm discovery. These capabilities build upon Qiskit’s performant foundation of tools for creating and running quantum algorithms. Addons are modular software components that plug into a workflow to scale or design new quantum algorithms. To learn more about the set of available Qiskit addons and how to get started using them, visit the [documentation](/docs/guides/addons). -There are a number of addons depending on what research capability you are interested in. Each of them can be installed with pip. - -[Sample-based quantum diagonalization (SQD)](/docs/guides/qiskit-addons-sqd): -```bash -pip install qiskit-addon-sqd -``` - -[Approximate quantum compilation (AQC)](/docs/guides/qiskit-addons-aqc): -```bash -pip install qiskit-addon-aqc-tensor[quimb-jax] -``` - -[Operator backpropagation (OBP)](/docs/guides/qiskit-addons-obp): -```bash -pip install qiskit-addon-obp -``` - -[Multi-product formulas (MPF)](/docs/guides/qiskit-addons-mpf): -```bash -pip install qiskit-addon-mpf -``` - ## The Qiskit ecosystem Beyond Qiskit there are many open-source projects that use the "Qiskit" name but are not part of Qiskit itself; rather, they interface with Qiskit and can provide valuable additional functionality to supplement the core Qiskit workflow. Some of these projects are maintained by IBM Quantum teams, whereas others are supported by the broader open-source community. The Qiskit SDK is designed in a modular, extensible way to make it easy for developers to create projects like these that extend its capabilities. diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 0570b905ba2..be7629a2cab 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -262,10 +262,6 @@ notifications: "docs/guides/processor-types": - "`@lerongil`" - "@abbycross" - "docs/guides/qiskit-addons-obp": - - "@kaelynj" - "docs/guides/qiskit-addons-obp-get-started": - - "@kaelynj" "docs/guides/qiskit-code-assistant": - "cbjuan" - "@abbycross" @@ -497,22 +493,6 @@ notifications: - "@kaelynj" "docs/guides/qiskit-addons-sqd-get-started": - "@kaelynj" - "docs/guides/qiskit-addons-aqc": - - "@kaelynj" - "docs/guides/qiskit-addons-aqc-get-started": - - "@kaelynj" - "docs/guides/qiskit-addons-mpf": - - "@kaelynj" - "docs/guides/qiskit-addons-mpf-get-started": - - "@kaelynj" - "docs/guides/qiskit-addons-cutting": - - "@kaelynj" - "docs/guides/qiskit-addons-cutting-wires": - - "@kaelynj" - "docs/guides/qiskit-addons-cutting-gates": - - "@kaelynj" - "docs/guides/qiskit-addons-utils": - - "@kaelynj" "docs/guides/qiskit-code-assistant-openai-api": - "@cbjuan" "docs/guides/qiskit-function-templates": From 8efed204dde9d39bdb2c2620494e3bb8d1161597 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:45:30 -0500 Subject: [PATCH 020/118] experiment with composer docs placement --- docs/guides/_toc.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 9f710f555b0..8fe0ae3b35a 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -756,13 +756,9 @@ ], "collapsible": false }, - { - "title": "IBM Quantum Composer", - "url": "/docs/guides/composer" - }, { "title": "Additional resources", - "collapsible": true, + "collapsible": false, "children": [ { "title": "Support and FAQ", @@ -918,6 +914,10 @@ ] } ] + }, + { + "title": "IBM Quantum Composer", + "url": "/docs/guides/composer" } ] } \ No newline at end of file From f2eaa6abc05c99cb08e94b5c260fa27435330685 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Thu, 5 Feb 2026 12:49:16 -0500 Subject: [PATCH 021/118] unused images --- .../guides/qiskit-addons/aqc_diagram.avif | Bin 26086 -> 0 bytes .../qiskit-addons/circuit-cutting-diagram.avif | Bin 11105 -> 0 bytes .../guides/qiskit-addons/mpf-diagram.avif | Bin 20627 -> 0 bytes .../guides/qiskit-addons/obp-diagram.avif | Bin 71245 -> 0 bytes 4 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 public/docs/images/guides/qiskit-addons/aqc_diagram.avif delete mode 100644 public/docs/images/guides/qiskit-addons/circuit-cutting-diagram.avif delete mode 100644 public/docs/images/guides/qiskit-addons/mpf-diagram.avif delete mode 100644 public/docs/images/guides/qiskit-addons/obp-diagram.avif diff --git a/public/docs/images/guides/qiskit-addons/aqc_diagram.avif b/public/docs/images/guides/qiskit-addons/aqc_diagram.avif deleted file mode 100644 index 698f252b2f0e2e92408d102a033c16fafdda70a4..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 26086 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 diff --git a/public/docs/images/guides/qiskit-addons/circuit-cutting-diagram.avif b/public/docs/images/guides/qiskit-addons/circuit-cutting-diagram.avif deleted file mode 100644 index f9ad428fc54f78c5360106b7e5f008a020332035..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11105 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 diff --git a/public/docs/images/guides/qiskit-addons/mpf-diagram.avif b/public/docs/images/guides/qiskit-addons/mpf-diagram.avif deleted file mode 100644 index 4ff24b896b202455974ffea176b14fbf9e588415..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 20627 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 diff --git a/public/docs/images/guides/qiskit-addons/obp-diagram.avif b/public/docs/images/guides/qiskit-addons/obp-diagram.avif deleted file mode 100644 index 1f6a399db8ff11bf704b9d55285e94e6c810dcf7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 71245 zcmYJZV~}V~tTsBfZQHhO+qP}nwr$(CZSLV7+jIAO&Ufmjt2)V(PF7ZabX9i;0002T z%*E5e(9O~e;2-_RZ7t0hZ7mJ|>3|`&rY?s6;s1!x!o&h{wIz9S&#Zp zG5uf1{}N+h{Lk_K2me|A4;;31aB}!(%(Zkdw*SYGjqPom?2K(Z{zZoc01NmB!5F$R z3I{^q{1X9CES()p{}TWJKz#uKz$E_(|C0Bx{0{+y_&0GFx_Suzr@1=WaoIYUn*Yxv z#AR%0?7-#h>Fi=^>&*3UjirsHp_3<J+UO0BJlp$ifK6gU=D^{K?6 z0+ZlBg+k!z4q>-}+%8w4ZeoM)7V3WHDN{Db5IFIZR&htd82*yg_)R}4d-Mu0r`J&t z5@49tE|baSn!GAV0(CiyWnfQ8X-nlTjr%cfaplXYeX=h+aj`4??#5X>7Kh0$I$#wM^%J z04n)`Ji$mnW44d8H#jsCW%AcX`#s4k>C@?iq3u1MTp5z(n&Ohz+0bE5e_Hl*@xx4v zP45AU4SqG-39R6U>{JRp(wU)K!n+lb7n96p#v}L2zti%zc5uU$Oq# zDFf)tkSHT|0Nm1C6NVaXV+ovot>o|g%bj{ERd7krWp!hZ3|h^!oe@GT_Jxj7e)q@H zd@8;r&M*v?gg>xqKh?Fywn?ze8*F56yWJPU&23iMr5GK8202Wx0VnMLvL zQa*@|7UB2EI@F+%VuHHgb1W-LCrcS&$({NZ`VKh6d>2|;13I04Ftpjs8r0Zs)z;;{ zo5#s69_pSlIcZfa-z*RyJYoak)&yfov@M%x_COIi&7@Dfw-uboA&MvER#9jZK+b1S ze{)NtkHah{00k5EEz$E%-IOu7MHE^ zp|?LkjS8v$mFIe?pqb!Oq#CiK{fEM;0Jge$l+p4Lq#>^I@^i*6&W8 zw&1h+9X)$@#^Hp5N(vnr%G`|;L+X4=j*#W>M-^PtkayE)w}lmIxsBF0b%)OZ2=}G& zZ`!jlsxVwxVy+zXiITfB5Q~sB4XS6;28lNB#aeu|J?W1BFW(yGCATbT48^`<8Re%T zqTZVhX>_OM4+@BsUIKmaO2Nfjg{Sy=m_V_t5_)aiv&5q#j6p;$7ScSH5ptjrqa&E+ zU$SEE0E>6S^)oZKQ+pMBm(>EinC?3O|0f23DMcz)?PzqAOLYyM6`R1!)krT-pXJ zE+;_-L|&iw$-fK8T7u180)6&7=rQlU#7}fG7fzQYFtlWu!Kc=qb~3(q;j9@|d&Z~> z?A>zCIUf7Er{jGOyqH|Zxrir+gj@4NR66-gBFE=`)Hx{2RRJd}8~cQbn>6@VgU z%=X{COnSWz-2nrn`9T%_V=EBAtP7_Iq0T=3c3f+1Jbc zf%@^*-|7TO{&R+_bAMBQUzyczBvjVPsoU_FHT1-q5+;t*7#5!jD;_81Z4R#TT-sd) zpMX?rDV_RCQ;%V-LzOsk)n&hCv(Z6$YSE2Je-lXjg!+vv?)6i%bA7}PP)J-i7u#Tc z$>$9wYyIYRrtJ)xQR5pa(ZV88V#clxkx$;PaTFWksx}Srs4?bcqioF9J5D2$31O*={X#p3<4TX>%5td*SNgWmv#ODkEH1-1M zAbD%}yr!S|Oju8w>tTXOZOfItb9x)BF_$b@Z@MPNr&@o;q2onRlh9dmr##z9e3rREHs2J9vh6Aynem$`01DYcrT@>fT@u2Q}@x3yc2yxgR91j&s@Z=(0JOW36z zeWe?&5!Iuy=&PuKnA3WWJ|tb**GW0GC8E}uFE?Lje%UJPm+cdXPB|kHAtbWHt6#7H zoIr@F%MN3fC^Hr1g#Rti-0F~=6~M69@)_=eV?2I;Sxwn7b{aC<4ltAipM$rF+Rh}{ zH@ZI6Kj?ywEP{L;-i`?rB2o*vQjff@(a94Yw)Lk7349Pi4Umow-K^)Yo-UnM&Z$Ty zDVdhxF&8&6k%LE4Y(Kd>(ncE-$B?ow_)x+5-OVK_;H(6xvH7J*fJ;PfgfXRvQ}W3s zJsO=OpzKLQgI&el#MKMSA+h1d>p4+{6)VxeF)Dp@2k#Ci4%z6aDi{#-h5q63{8NvHKD7}iNq zX(1JDN;}83uQ*1IwQ(&e$k5@mG7$T>*;LwH1e^4DpQueNsnOv)pKW0_?9QzUL6nA|)a)8Q(TgqNi8X9rpG=7& z`fH3oC*!|Z#cxupF#n~k4z%o(DJ{lrDG&ju`Hi;G7s$U7`VR3D<*1)H%!ve3W6&k} zzVhV0)7<*HoB#8!M(E{77R8&SyerwE=f_Mf{0_P@=G(a0Zc15DVZ?(!N&IVG|sREjwp|@)E)}6Ce&A6VW2; zEMWQH_OnDj;dgKyx-SB*;Q+Tr>hHqE^%Fdyvk99apjhgOiyrT!e$n}?3+ohiy zj*oHC;N$C|3Mn;zTg*oQ=)0*%)*{eo%P$0gVqhi)B~kRU|{*56g*r zyLp(kC_2E5&Ng)ZoE%iN5#8+9^>A9o^c;-IOzzI+iQqEtt=HySE;5JNzF!MDfB%U{ znxXxf$y+26(fH>gKe>o4@?52Dq)v#hWHy5p=I3~ytLT$u5;R~DzNHBofmFn+$%#`k zy=(MbzJg!DL(<`C1SMXoNiAdlP?Ag$hPQuo-5$>tl9ppnkI1t1?t}>&`Bw zu4<0;6_IORZ%?Ap9~&@O$@Y4zC^fJSK~WOu%ZAy$!hH|yLH?GHaSfXHjtZe3d58ye z*{3sKiCKm;=HUo|rY)fMw*2K~4R^-i5MVVt+qO5x9v|T<3 z{L@jvUK6vCOPLF!%)bDw1+6UHMCuh-k`>G7^Pv;$zNG$=WLbfgIB~$BfW>iSqlR(P zRG%-9pG?@t0BPhi_1x_3Sz)YSy z?}=5L3H<^B#gqJ$HERqAuRoi00#hS9yl02YSeoRk8(h!qNBpo_rYSm_?G1uL2b*dP ze!WK89C?COa+r#dFkrw1v%ZNa+>T=V01khi=&(Eya7)>NvXLuG1^iftN?&quMM%-J z1SD8BC&K8~=Nw%Y!=<-sXZX!ZtVhS<3RwsH!q726L_8#Dsf1;!-$`@lq!_tLvjD!xZaA1boBzTc2j@36IMBfw481oV|KeVgSQH#1D{ z#jAV(OCAltBIR2NfG&*yrQn+H^nG$(k4P2|(j`w=cY8GdLlf)H-r;d_&B$K4;}(wBT%yt&r0M>5 z=e_4bm}FHG%E02=B0JknXSeeoCY;CDb-Re2MWHd2W{BZ?>Rb%4_Urrk z|29C1-j|Z9uT38P@p+AwMBeRdd1YPEFvdJ?!=lrRuxJ&3TX^kjcA0W{pm?df_X|7L zv^Yb+X27&}L1=H)XgTCY@RiZCjiy*{9~HCOu&?OEF8~(i=f>Uc+O5EdNEG~oM3?jO zrl&jsQPQSE@qZSvNdhzBHCWNI=RB4|-?+m8|FTHjH!ezG*51NE(Oe^6H zig>w1<}R?vq*atsSQ~~S=gz!QsDJr&e-7AV+1*mIHX}_S4z?u13Ea#*-Lrf;Rk8oI zP*lf=1;!PW{doRnz`0symG&8>CM(>F6v^n6AYv-gIV_&I!Bx`uRF6|z5;7>fJ=i87z|jjj$lXKNOzZy= z*&}(qZZqeX{-@1TS{%U421Mwd#h$XGtsP=OpE0D#CGbyl!Y0`BAy}FaX&=ap5-v4B zzz~2)L6lM;} z@Q%&Q=IRyB?l7}+I3~FqFQWbrR)|1iR zGRWW)+{7VM_*&`NIg_O8lmf{(sr&q^K9p%Wzh@Ltf#_A7)W^hz03xdS;LMKL)|3=C z6)XUKgBC-ZziN{Fb(P#vlwgnVOX2L!Sx9w!=m#?wpDavF?{pPp*VXT|@YGZGp(Asi zi6SoQQ{+W!-Wa+3a7R?P6whh!H<#S?wACh!pdcI9st*LdXcd`UafG^-?pFpv&D|iA zPw@|Ry!Ut(q2}sk001qmz-!pkMP-<(hEN+W2NF+BG!XJ7urVUaQD4>l8L1b{ z{ei=>Iw3wl7%O(2*F*r-hG3|An*$aesmlN)`wz3jFVz_350hiH_R2w6bgqLuQcVI< zGhR1u#f%AQg{M8$0aTl&nzr}3Izj{VD6xz1J-B80P9G`NAdq;%N-0#J1@&bE1#RM6 zo~qVUZ53?OO^tB1dsL;x%ZuDqd}83IXdD`O-XK!@S)`GQ_HXn^xIICW5<}-)FZ)@5 zT=t00jFO5Fw3V$7kWcVwP8V}4K6rnJ2nErgD6hA7bYIfc?bEPKGS}U3t{ZrWt+dhwJRGfsco+X6;=T8*z>Pz-Or>N}~p0M^o zA+U)pG+YD*!w^*CSI<6u)e{oA>E|y4z@$gY=N{=aaHPawRNO@>iumArzfn5cP(usT zuq?=rk}~t4ND93FBez$_2(FHexK(}2pbGt4inWMgU)(R$H03t=VIohsc%ZX%5}T`2 zO(5{UeK+Oa0FkgY?<13J5AX!hmL^~L5mWtbe^blm4+Uuj<6(zjlXjVmJJ3qOw|<>5 z*w38SMP1?uZ0ewxYU8t_>W4`6M9Jdj7c+;t6FU!s6hHwy4@?=#(@bq(CPgpM$7Uuv z+5MAH-i3@^K{ZpBqtOUe{UyvN2=P_zEadsP1yoi16}jG#-@)K=ciZyBlS2>nDf;o5 z{3)c>XE>sSE-%p}!0T<70wPd32zaEoWZf2^+c49<==WH?aA-{21~hpS82Z$m6E_re zYRr$)#`n>#joiAY(2gH)VTZ~M6$GcdAzeYZW(j9e!3{UwcXKlGYNDGbEn4J8RVW0B1=$BDx5dFqo?!{JaZ zIBn^M?Jo`^i7Oj3dllR~XCOx$O=U4Qzj212scoX`o>e%v=C% zd?RHcEuakEDnQABi9<8g5SWna<;Lecj-H+_^2>z=a>ky2d4PA@zYV&O%?HAmI}!XU zghG=eB%7@kZ1mDd0zI@{9`^k#0lvO|@vfpM8At78wHoIDvhH>m4oKnvVLms~U)3ic zDFAKCK2P4u{U*Rk&qq1-cf~hD_&&eAy1rpQ2zLqs?T&~`rQOo?(2a-0;z!)1zvUVJ zk_eaV!AC>PrY+A)m04Vnjg|S0Uz4`p|3Fee5*pM|H)U-MjK8#27H@C=Q8Mfs>i0nP zn>I(`H^Up)r_0p_HFWiYVm}UoDr18~aNGl{$7en-0$Vs0XKGFu&N-A!thM=n5)of%dUFeBSJnxCz zdk2nh0fJU?J7w+eQv(-lr<>Zl9zXrH(jXA&^;30rS<(o$e0TZNCh{3@8g#Koll+L> zAyYwbib*mL8R&VJZ%bf^cHxzha4cL?vj%7$3pg&%MD9>B^jvM^L7sr1 ztiMX>ys*Cu209t%=;W5s1%5?7TuM4*u0r_rmiwBbkc%lW&LVRaRIllEfto3a%GS zr&~3-dX$T{1;Atld>FIQ|K>*(`Ut{$VOd6m1gbv&^&Q4oSCz0uvLeta9sh+Pc7h1Q znDfO3#e@lh+|EWz-4849?TDFa;*=gA=bTcz8}SWXLZ-u}A!oQSZPihs;!o}O`_ozW zS)yz;c5{0Za&2lihaolO&)GKJEd1OmfJ%L;phW|)&?JU6n)gviNW(J)rmF@G;;cse zkSgxDiJh$^Q&Cj^ENY4!P+N%({fUPenwunUWM4V41{8WE2OZ}T*n#*>;bJ$m%L<7=>4i(4T`_&996FAE|D`_T@eCgGQ6i5W}$YvIh1wO4XP#)iu;arel0uQsZAvG)6I^TOi;5%IzJOsG|$_jVM7hVrZY_-RG!t8X-iF~H2?kwJ;5N+;E zLT;i4vx5BV_-&H2wQ;zJ^{GfBIInt+t6oY~a;TuzZ%s8+u!zFFh;H;l(lL&T)F9%) z5X`@eDF=jEu5Y67!|%W~1-0(p9&Zwz?-0g$Qdxk1?McG)N8geEHRPnZ2ge+;%851E z=Mt^+CamVl5c-~^=Z?80qkh19Zs^!guwtX#>)AGole!m1gkONZbu-pm!gNoP9AAB{ z=gB#mRK6iY?s@hv$CO9!Q4=RrJ0}FJ!0|MMpOm40>Uv{5mbh$auq!}Qdi$q@=cG}H zu~(LJBC|Sgx43g8@)-4sF?!j!sMnj|c4H zP_~nfJ-Y&fmn%7-YE({w*Xw=g7%KFEQoX;sIIW25yv)tuC*Ld%Q|Mm5U(z_&G%INF z#wX&o5Tn>G;{aj>kHihF2I@RUp`I#n#lQIl|F&7$`NUC@O{ zF(IER&_aEU0@li{`~2l=H}(Pzv4pQa?C6xJ)q%a1ytcrZq<672RJ-IBLLLg|gQ4`R zS+=|1O%IO(WT%ZjsWm8DWY29T^xlYi*h*{K*(=;+FxEm%yc8`9AX3kID-MhItdwWU z8C2AqQ1g#NfMIf9j;_tC=&!p^>OE0%tP85F5*TGldJMkHXt>8yphRTLkQ&(`eA8+9 z_JI&s4cv|1nyL<`)afy6O8O1Em7guS8X;noMqcWuuN!l*^=X^}Cy-QapL&^za4Wi? zWTKhNi(IuK{ZdQ*rJp7crIfqe%P~pEZVSmzq^&KosS-&q-bGlkV10f%+L^SS0(6p$ zt`A^jzYn+XOnw2suEHa=@B?gqm=v>j(p74dhUgr{;Nd!5$PdYH=8Qcd-Tt!KG2x|m zT?;Hg%Z*P{B0fM&&}8iMGeOww`sE4Pw^v}#4GGI+{ODeJSz;&EB&&BWi49)FNS0<` zko$nSyDG>`loEd-%&TS(jSDM9XtOhGf0%Kuwr$N{6l2AjdwJ1k+Iu4>P+se}j~akgEubS0yHB;ap~s>NJoQ zXF3Uh_yU{EL-^bQZQ-Syd%Rk*gQ97wjH1e?GT?%FmkxuGE{?AxZ-Df|;B( zN~4^9$-hDPxYofP)M~ITd-np22R3ym$jdXO^9ZgX#L4}>=6dUqUqCPH;0#TT3YXt)ZNk{V4Oln{)Hb7Pe7 zU64J1(qwGTBkE3NvlxI-|KNmR8R6RiUDzQj!nV1$S5A&_BA@u+>D?CEm%tFrW+q>{ zTynX{71%YQTezm?AB|zY%CG$3AAP}bP(evMPR3yRtU>n!D^P0lbGAe}@ z9>C%-)uU}X;PHMt2=qI!7GnZPKJ7%29CE>Povfbb0h{0Is;spUZ`+c-MsR|(R%)k( z3|Z(?8pNf_fCWgoU;Rdr`^wT`o=V5F(Scghk|-*_R%5_pt!j(pD|8*A=!!LY?5S-N zv`-cC+EslU_6tCW_nooKH1ZMYU!=QL-{P8foT?CLFTTfreua1wxdRc-6xEqc45wVl zpB9OUWZE?xtq-|lRm1GJ_1b44#pLaweTBHv;t91YAT%`KK8Ih)!4Pwt^k@{ddq^6E zlgt0`vM}c658oSUqcSQlQs6viA+-i2)8GwHQ8utIXKq(HCuHpXRcMg2fD7Dq92^SOYYpq_8rf;mx)-zlvERmoeLLlS^ zC+G?-6h)fx_wS^dQ&mG8D{@*)%&n8^)D0Gjb5xt2z)!0?iADWX2vPV z%B4fh%^t06Uhwv*k{j;5&Jpwb7Nra?ErDz{Vm$O4wgKzewCX=p^l^kg7&wp^bv<~`2t)rxex4&{12r`g%5nFE z4vRSG<->Ic`B;PSMYSf&boGM9VUwG(#N5my2kx0tD=hYR1*4LQr^7!6Nxy+-{~4`y z%GMw`-sD$F2~YQkU?~w0`*le5UN%QbKz8fkq03IYivJZm^p32bDgD(9u)26O@yvRs z?sM;iDFpVOdc4&64^&B66hd*C8EAp3OP7C-9XWCy)wa`c`8|0`b_PDY~rVT{nu?PQgxoq#K3GY z9j0b=&RTBIPS@VAzVD14t@fHZVx(4YA;&|qT#O*6YWm}_P{OHt4sh-Q;G$jsSb1*; zn4&h(D<|nz83n~re$}i(yXe7WA>2b?fT1ybK86@M(u?S@tsc^~KD;0J-QD&3N5%$*8AFiuS5di2i*PW`g2Dj7+ z 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 Date: Thu, 5 Feb 2026 16:25:25 -0600 Subject: [PATCH 022/118] Start adding new files --- docs/guides/estimator-input-output.ipynb | 689 ++++++++++++ docs/guides/estimator-options.ipynb | 496 +++++++++ docs/guides/executor-input-output.ipynb | 846 +++++++++++++++ docs/guides/executor-options.ipynb | 496 +++++++++ docs/guides/get-started-with-estimator.ipynb | 373 +++++++ docs/guides/get-started-with-executor.ipynb | 550 ++++++++++ docs/guides/get-started-with-sampler.ipynb | 326 ++++++ .../runtime-options-overview - estimator.mdx | 997 ++++++++++++++++++ .../runtime-options-overview - sampler.mdx | 420 ++++++++ docs/guides/sampler-input-output.ipynb | 685 ++++++++++++ docs/guides/sampler-options.ipynb | 441 ++++++++ 11 files changed, 6319 insertions(+) create mode 100644 docs/guides/estimator-input-output.ipynb create mode 100644 docs/guides/estimator-options.ipynb create mode 100644 docs/guides/executor-input-output.ipynb create mode 100644 docs/guides/executor-options.ipynb create mode 100644 docs/guides/get-started-with-estimator.ipynb create mode 100644 docs/guides/get-started-with-executor.ipynb create mode 100644 docs/guides/get-started-with-sampler.ipynb create mode 100644 docs/guides/runtime-options-overview - estimator.mdx create mode 100644 docs/guides/runtime-options-overview - sampler.mdx create mode 100644 docs/guides/sampler-input-output.ipynb create mode 100644 docs/guides/sampler-options.ipynb diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb new file mode 100644 index 00000000000..c90e4008915 --- /dev/null +++ b/docs/guides/estimator-input-output.ipynb @@ -0,0 +1,689 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "dbb193c8-d927-434c-a199-48de57c99694", + "metadata": {}, + "source": [ + "---\n", + "title: Estimator inputs and outputs\n", + "description: Understand the Estimator input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "---\n", + "\n", + "\n", + "# Estimator inputs and outputs" + ] + }, + { + "cell_type": "markdown", + "id": "33c719ad", + "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", + "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": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", + "metadata": {}, + "source": [ + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." + ] + }, + { + "cell_type": "markdown", + "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", + "metadata": {}, + "source": [ + "\n", + "## Overview of PUBs\n", + "\n", + "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "\n", + "### Estimator PUB\n", + "For the Estimator primitive, the format of the PUB should 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", + " If you have two commuting observables in different PUBs but with the same circuit, they will not be estimated using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB. To ensure that commuting observables are estimated using the same measurement, they must be grouped 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": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", + "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": null, + "id": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", + "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", + " 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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", + "metadata": {}, + "source": [ + "### 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", + "\n", + "Rules:\n", + "\n", + "* Input arrays do not need to have the same number of dimensions.\n", + " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", + " * The size of each dimension is the largest size of the corresponding dimension.\n", + " * Missing dimensions are assumed to have size one.\n", + "* Shape comparisons start with the rightmost dimension and continue to the left.\n", + "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", + "\n", + "Examples of array pairs that broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 1\n", + "A2 (2d array): 3 x 5\n", + "Result (2d array): 3 x 5\n", + "\n", + "\n", + "A1 (3d array): 11 x 2 x 7\n", + "A2 (3d array): 11 x 1 x 7\n", + "Result (3d array): 11 x 2 x 7\n", + "```\n", + "\n", + "Examples of array pairs that do not broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 5\n", + "A2 (1d array): 3\n", + "\n", + "A1 (2d array): 2 x 1\n", + "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", + "```\n", + "\n", + "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", + "\n", + "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", + "\n", + "\n", + "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", + "\n", + " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", + "\n", + " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", + "\n", + " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", + "\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\")" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", + "metadata": {}, + "outputs": [], + "source": [ + "# Broadcast single observable\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Zip\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = [\n", + " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", + "] # shape (5,)\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Outer/Product\n", + "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", + "observables = [\n", + " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", + "] # shape (4, 1)\n", + "# >> pub result has shape (4, 6)\n", + "\n", + "# Standard nd generalization\n", + "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", + "observables = [\n", + " [\n", + " [SparsePauliOp([\"XII\"])],\n", + " [SparsePauliOp([\"IXI\"])],\n", + " [SparsePauliOp([\"IIX\"])],\n", + " ],\n", + " [\n", + " [SparsePauliOp([\"ZII\"])],\n", + " [SparsePauliOp([\"IZI\"])],\n", + " [SparsePauliOp([\"IIZ\"])],\n", + " ],\n", + "] # shape (2, 3, 1)\n", + "# >> pub result has shape (2, 3, 6)" + ] + }, + { + "cell_type": "markdown", + "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", + "metadata": {}, + "source": [ + "\n", + "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", + "\n", + "```text\n", + "a = SparsePauliOp(\"Z\") # shape ()\n", + "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", + "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "```\n", + "\n", + "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", + "\n", + "```text\n", + "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", + "```\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", + "metadata": {}, + "source": [ + "## Overview of primitive outputs\n", + "\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator.\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 `PubResults`, one corresponding to each PUB).\n", + "\n", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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", + "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", + "\n", + "### Estimator output\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", + "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", + "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", + " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", + " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", + " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", + " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", + " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", + " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", + " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", + " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", + " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", + " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", + " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", + " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", + " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", + " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", + " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", + " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", + " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", + " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", + " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", + " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", + " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", + " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", + " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", + " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", + " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", + " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", + " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", + " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", + " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", + " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", + " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", + " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", + " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", + " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", + " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", + " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", + " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", + " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", + " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", + " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", + " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", + " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", + " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", + " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", + " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", + " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", + " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", + " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", + " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", + " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", + "print(\n", + " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", + "metadata": {}, + "source": [ + "#### 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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", + "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": 5, + "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", + "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": "markdown", + "id": "a65c6078-c5c2-4087-b57a-5680148ce333", + "metadata": {}, + "source": [ + "#### Leveraging `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": 7, + "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", + "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", + " [1]\n", + " [1]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [1]]\n", + "\n", + "The shape of register `beta` is (4096, 2).\n", + "The bytes in register `beta`, shot by shot:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " ...\n", + " [ 0 0]\n", + " [ 1 224]\n", + " [ 1 255]]\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", + " [7]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [7]]\n", + "\n", + "The shape of `beta` after shot-wise slicing is (5, 2).\n", + "The bytes in `beta` after shot-wise slicing:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " [ 1 128]\n", + " [ 1 255]]\n", + "\n", + "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", + " coeffs=[1.+0.j])` is: 0.068359375\n", + "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", + " coeffs=[1.+0.j])` is: 0.06396484375\n", + "\n", + "The shape of the merged results is (4096, 2).\n", + "The bytes of the merged results:\n", + "[[ 1 15]\n", + " [ 1 239]\n", + " [ 3 239]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 192]\n", + " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", + "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": 8, + "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", + "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},\")" + ] + } + ], + "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-options.ipynb b/docs/guides/estimator-options.ipynb new file mode 100644 index 00000000000..fbc6e813388 --- /dev/null +++ b/docs/guides/estimator-options.ipynb @@ -0,0 +1,496 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "8bbb8d7d-bcd5-4092-9df1-9930c67b17bc", + "metadata": {}, + "source": [ + "---\n", + "title: Options\n", + "description: Specify options when building with the Estimator primitive.\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", + "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": "8fdcbe4a", + "metadata": {}, + "source": [ + "You can use options to customize the Estimator 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`](/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", + "- 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/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb new file mode 100644 index 00000000000..b5c24c629a2 --- /dev/null +++ b/docs/guides/executor-input-output.ipynb @@ -0,0 +1,846 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "dbb193c8-d927-434c-a199-48de57c99694", + "metadata": {}, + "source": [ + "---\n", + "title: Primitive inputs and outputs\n", + "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "---\n", + "\n", + "\n", + "# Primitive inputs and outputs" + ] + }, + { + "cell_type": "markdown", + "id": "33c719ad", + "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", + "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": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", + "metadata": {}, + "source": [ + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Sampler and Estimator primitives, which execute 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 Sampler or Estimator primitives." + ] + }, + { + "cell_type": "markdown", + "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", + "metadata": {}, + "source": [ + "\n", + "## Overview of PUBs\n", + "\n", + "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "\n", + "### Estimator PUB\n", + "For the Estimator primitive, the format of the PUB should 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", + " If you have two commuting observables in different PUBs but with the same circuit, they will not be estimated using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB. To ensure that commuting observables are estimated using the same measurement, they must be grouped 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\n", + "\n", + "### Sampler PUB\n", + "For the Sampler primitive, the format of the PUB tuple contains 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": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", + "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": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", + "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", + " EstimatorV2 as Estimator,\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", + "\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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", + "metadata": {}, + "source": [ + "### 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", + "\n", + "Rules:\n", + "\n", + "* Input arrays do not need to have the same number of dimensions.\n", + " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", + " * The size of each dimension is the largest size of the corresponding dimension.\n", + " * Missing dimensions are assumed to have size one.\n", + "* Shape comparisons start with the rightmost dimension and continue to the left.\n", + "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", + "\n", + "Examples of array pairs that broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 1\n", + "A2 (2d array): 3 x 5\n", + "Result (2d array): 3 x 5\n", + "\n", + "\n", + "A1 (3d array): 11 x 2 x 7\n", + "A2 (3d array): 11 x 1 x 7\n", + "Result (3d array): 11 x 2 x 7\n", + "```\n", + "\n", + "Examples of array pairs that do not broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 5\n", + "A2 (1d array): 3\n", + "\n", + "A1 (2d array): 2 x 1\n", + "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", + "```\n", + "\n", + "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", + "\n", + "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", + "\n", + "\n", + "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", + "\n", + " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", + "\n", + " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", + "\n", + " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", + "\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\")" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", + "metadata": {}, + "outputs": [], + "source": [ + "# Broadcast single observable\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Zip\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = [\n", + " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", + "] # shape (5,)\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Outer/Product\n", + "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", + "observables = [\n", + " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", + "] # shape (4, 1)\n", + "# >> pub result has shape (4, 6)\n", + "\n", + "# Standard nd generalization\n", + "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", + "observables = [\n", + " [\n", + " [SparsePauliOp([\"XII\"])],\n", + " [SparsePauliOp([\"IXI\"])],\n", + " [SparsePauliOp([\"IIX\"])],\n", + " ],\n", + " [\n", + " [SparsePauliOp([\"ZII\"])],\n", + " [SparsePauliOp([\"IZI\"])],\n", + " [SparsePauliOp([\"IIZ\"])],\n", + " ],\n", + "] # shape (2, 3, 1)\n", + "# >> pub result has shape (2, 3, 6)" + ] + }, + { + "cell_type": "markdown", + "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", + "metadata": {}, + "source": [ + "\n", + "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", + "\n", + "```text\n", + "a = SparsePauliOp(\"Z\") # shape ()\n", + "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", + "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "```\n", + "\n", + "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", + "\n", + "```text\n", + "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", + "```\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", + "metadata": {}, + "source": [ + "## Overview of primitive outputs\n", + "\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", + "\n", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", + "\n", + "\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", + " \n", + " ```\n", + " └── PrimitiveResult\n", + " ├── PubResult[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", + " ├── PubResult[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", + "\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", + "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", + "\n", + "### Estimator output\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", + "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", + "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", + " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", + " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", + " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", + " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", + " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", + " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", + " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", + " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", + " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", + " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", + " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", + " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", + " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", + " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", + " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", + " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", + " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", + " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", + " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", + " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", + " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", + " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", + " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", + " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", + " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", + " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", + " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", + " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", + " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", + " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", + " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", + " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", + " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", + " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", + " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", + " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", + " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", + " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", + " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", + " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", + " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", + " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", + " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", + " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", + " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", + " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", + " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", + " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", + " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", + " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", + "print(\n", + " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", + "metadata": {}, + "source": [ + "#### 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": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", + "metadata": {}, + "source": [ + "### Sampler output\n", + "\n", + "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", + "\n", + "The `BitArray` class is a container for ordered shot data. In more detail, 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", + "\n", + "As a first example, let us look at the following ten-qubit circuit:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "5c787874-1125-4381-b55e-7663caa92ec8", + "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 254]\n", + " [ 0 0]\n", + " [ 3 255]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 255]\n", + " [ 0 0]]\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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", + "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": 5, + "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", + "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": 6, + "id": "4602925e-c69d-45b2-9e06-fe8bffe0a797", + "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": "a65c6078-c5c2-4087-b57a-5680148ce333", + "metadata": {}, + "source": [ + "#### Leveraging `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": 7, + "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", + "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", + " [1]\n", + " [1]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [1]]\n", + "\n", + "The shape of register `beta` is (4096, 2).\n", + "The bytes in register `beta`, shot by shot:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " ...\n", + " [ 0 0]\n", + " [ 1 224]\n", + " [ 1 255]]\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", + " [7]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [7]]\n", + "\n", + "The shape of `beta` after shot-wise slicing is (5, 2).\n", + "The bytes in `beta` after shot-wise slicing:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " [ 1 128]\n", + " [ 1 255]]\n", + "\n", + "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", + " coeffs=[1.+0.j])` is: 0.068359375\n", + "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", + " coeffs=[1.+0.j])` is: 0.06396484375\n", + "\n", + "The shape of the merged results is (4096, 2).\n", + "The bytes of the merged results:\n", + "[[ 1 15]\n", + " [ 1 239]\n", + " [ 3 239]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 192]\n", + " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", + "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": 8, + "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", + "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": "2f26ff75-e1ba-45ef-97c1-c5dde36400cf", + "metadata": {}, + "source": [ + "For Sampler jobs, you can also review the result metadata to understand when certain data was run; this is called the [_execution span._](monitor-job#execution-spans)" + ] + } + ], + "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/executor-options.ipynb b/docs/guides/executor-options.ipynb new file mode 100644 index 00000000000..a74eed5b995 --- /dev/null +++ b/docs/guides/executor-options.ipynb @@ -0,0 +1,496 @@ +{ + "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", + "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": "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/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb new file mode 100644 index 00000000000..dff6624185f --- /dev/null +++ b/docs/guides/get-started-with-estimator.ipynb @@ -0,0 +1,373 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", + "metadata": {}, + "source": [ + "---\n", + "title: Get started with estimator\n", + "description: How to use the Estimator primitive in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Get started with the Estimator primitive\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", + "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": "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_torino\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", + " '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', 3826), ('sx', 1601), ('cz', 968)])\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: d5k96c4jt3vs73ds5smg\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: 25.8930784649363\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": "ec04840d-5fa1-4716-b585-48aa371f67d4", + "metadata": {}, + "source": [ + "\n", + "## Get started with Estimator\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 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", + "```" + ] + }, + { + "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.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 backend primitive interfaces expose custom [`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.](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 [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-executor.ipynb b/docs/guides/get-started-with-executor.ipynb new file mode 100644 index 00000000000..fec408ad56e --- /dev/null +++ b/docs/guides/get-started-with-executor.ipynb @@ -0,0 +1,550 @@ +{ + "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", + "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": "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_torino\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", + " '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', 3826), ('sx', 1601), ('cz', 968)])\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: d5k96c4jt3vs73ds5smg\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: 25.8930784649363\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', 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 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.](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: 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": "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.](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..670010d42f5 --- /dev/null +++ b/docs/guides/get-started-with-sampler.ipynb @@ -0,0 +1,326 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", + "metadata": {}, + "source": [ + "---\n", + "title: Get started with Sampler\n", + "description: How to use the Sampler primitive 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", + "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": [ + "\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', 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 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.](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: 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": "ec04840d-5fa1-4716-b585-48aa371f67d4", + "metadata": {}, + "source": [ + "\n", + "## Get started with Sampler\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", + "\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: 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) \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.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) `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.](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) 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/runtime-options-overview - estimator.mdx b/docs/guides/runtime-options-overview - estimator.mdx new file mode 100644 index 00000000000..4e5f7a068ef --- /dev/null +++ b/docs/guides/runtime-options-overview - estimator.mdx @@ -0,0 +1,997 @@ +--- +title: Introduction to options +description: Available options for building with Qiskit Runtime primitives +in_page_toc_min_heading_level: 2 +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 + + +### 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. + + +### 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. + + +## 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. + + + +
+ +### `default_shots` + + +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) +
+ +
+ +### `default_precision` + + +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) +
+ +
+ +### `dynamical_decoupling` + + +Control dynamical decoupling error mitigation settings. + +[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling) +
+ +#### `dynamical_decoupling.enable` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ +#### `dynamical_decoupling.extra_slack_distribution` + + +**Choices**: `middle`, `edges` + +**Default**: `middle` +
+ +
+ +#### `dynamical_decoupling.scheduling_method` + + +Choices: `asap`, `alap` +Default: `alap` +
+ +
+ +#### `dynamical_decoupling.sequence_type` + + +Choices: `XX`, `XpXm`, `XY4` +Default: `XX` +
+ +
+ +#### `dynamical_decoupling.skip_reset_qubits` + + +Choices: `True`, `False` +Default: `False` +
+ +
+ + +
+ +### `environment` + + +[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment) +
+ +#### `environment.callback` + + +Callable function that receives the `Job ID` and `Job result`. + +**Choices**: None + +**Default**: None +
+ +
+ +#### `environment.job_tags` + + +List of tags. + +**Choices**: None + +**Default**: None +
+ +
+ +#### `environment.log_level` + + +**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL + +**Default**: WARNING +
+ +
+ +#### `environment.private` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ + +
+ +### `execution` + + +[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution) +
+ +#### `execution.init_qubits` + +Whether to reset the qubits to the ground state for each shot. + +**Choices**: `True`, `False` + +**Default**: `True` +
+ +
+ +#### `execution.rep_delay` + +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` +
+ +
+ + +
+ +### `max_execution_time` + +**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) +
+ +
+ +### `resilience` + +Advanced resilience options to fine tune the resilience strategy. + +[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience) +
+ +#### `resilience.layer_noise_learning` + + +Options for learning layer noise. + +[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options) +
+ +
+ +##### `resilience.layer_noise_learning.layer_pair_depths` + + +**Choices**: list[int] of 2-10 values in the range [0, 200] + +**Default**: `(0, 1, 2, 4, 16, 32)` + +
+ +
+ +##### `resilience.layer_noise_learning.max_layers_to_learn` + + +**Choices**: None, Integer >= 1 + +**Default**: `4` + +
+ +
+ +##### `resilience.layer_noise_learning.num_randomizations` + + +**Choices**: Integer >= 1 + +**Default**: `32` + +
+ +
+ +##### `resilience.layer_noise_learning.shots_per_randomization` + + +**Choices**: Integer >= 1 + +**Default**: `128` + +
+ +
+ +#### `resilience.layer_noise_model` + + +**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]` + +**Default**: None + +
+ +
+ +#### `resilience.measure_mitigation` + + +**Choices**: `True`, `False` + +**Default**: `True` + +
+ +
+ +#### `resilience.measure_noise_learning` + + +Options for measurement noise learning. + +[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options) +
+ +
+ +##### `resilience.measure_noise_learning.num_randomizations` + + +**Choices**: Integer >= 1 + +**Default**: `32` + +
+ +
+ +##### `resilience.measure_noise_learning.shots_per_randomization` + + +**Choices**: Integer, `auto` + +**Default**: `auto` + +
+ +
+ +#### `resilience.pec_mitigation` + + +**Choices**: `True`, `False` + +**Default**: `False` + +
+ +
+ +#### `resilience.pec` + + +Probabilistic error cancellation mitigation options. + +[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options) +
+ +
+ +##### `resilience.pec.max_overhead` + + +**Choices**: `None`, Integer >= 1 + + +**Default**: `100` + +
+ +
+ +##### `resilience.pec.noise_gain` + + +**Choices**: `auto`, float in the range [0, 1] + +**Default**: `auto` + +
+ +
+ +#### `resilience.zne_mitigation` + + +**Choices**: `True`, `False` + +**Default**: `False` + +
+ +
+ +#### `resilience.zne` + + +[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options) +
+ +
+ +##### `resilience.zne.amplifier` + + +**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea` + +**Default**: `gate_folding` + +
+
+ +##### `resilience.zne.extrapolated_noise_factors` + + +**Choices**: List of floats + +**Default**: `[0, *noise_factors]` + +
+ +
+ +##### `resilience.zne.extrapolator` + + +**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback` + +**Default**: `(exponential, linear)` + +
+ +
+ +##### `resilience.zne.noise_factors` + + +**Choices**: List of floats; each float >= 1 + +**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise + +
+ +
+ + +
+ +### `resilience_level` + + +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) +
+ +
+ +### `seed_estimator` + + +**Choices**: Integer + +**Default**: None + +[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator) +
+
+ +### `simulator` + + +Options to pass when simulating a backend + +[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) +
+ +#### `simulator.basis_gates` + + +**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) + +
+ +
+ +#### `simulator.coupling_map` + + +**Choices**: List of directed two-qubit interactions + +**Default**: None, which implies no connectivity constraints (full connectivity). + +
+ +
+ +#### `simulator.noise_model` + + +**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation + +**Default**: None + +
+ +
+ +#### `simulator.seed_simulator` + + +**Choices**: Integer + +**Default**: None + +
+ +
+ + +
+ +### `twirling` + + +Twirling options + +[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) +
+ +#### `twirling.enable_gates` + + +**Choices**: True, False + +**Default**: False + +
+ +
+ +#### `twirling.enable_measure` + + +**Choices**: True, False + +**Default**: True + +
+ +
+ +#### `twirling.num_randomizations` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.shots_per_randomization` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.strategy` + + +**Choices**: `active`, `active-circuit`, `active-accum`, `all` + +**Default**: `active-accum` + +
+ +
+ + +
+ +### `experimental` + + +Experimental options, when available. + +
+ + + + + +
+ +### `default_shots` + + +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) +
+ +
+ +### `dynamical_decoupling` + + +Control dynamical decoupling error mitigation settings. + +[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) +
+ +#### `dynamical_decoupling.enable` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ +#### `dynamical_decoupling.extra_slack_distribution` + + +**Choices**: `middle`, `edges` + +**Default**: `middle` +
+ +
+ +#### `dynamical_decoupling.scheduling_method` + + +Choices: `asap`, `alap` +Default: `alap` +
+ +
+ +#### `dynamical_decoupling.sequence_type` + + +Choices: `XX`, `XpXm`, `XY4` +Default: `XX` +
+ +
+ +#### `dynamical_decoupling.skip_reset_qubits` + + +Choices: `True`, `False` +Default: `False` +
+ +
+ + +
+ +### `environment` + +[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) +
+ +#### `environment.job_tags` + + +List of tags. + +**Choices**: None + +**Default**: None +
+ +
+ +#### `environment.log_level` + + +**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL + +**Default**: WARNING +
+ +
+ +#### `environment.private` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ + +
+ +### `execution` + +[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) +
+ +#### `execution.init_qubits` + +Whether to reset the qubits to the ground state for each shot. + +**Choices**: `True`, `False` + +**Default**: `True` +
+ +
+ +#### `execution.rep_delay` + +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` +
+
+ +#### `execution.meas_type` + + +**Choices**: `classified`, `kerneled`, `avg_kerneled` + +**Default**: `classified` +
+ +
+ + +
+ +### `max_execution_time` + +**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) +
+ +
+ +### `simulator` + + +Options to pass when simulating a backend + +[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) +
+ +#### `simulator.basis_gates` + + +**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) + +
+ +
+ +#### `simulator.coupling_map` + + +**Choices**: List of directed two-qubit interactions + +**Default**: None, which implies no connectivity constraints (full connectivity). + +
+ +
+ +#### `simulator.noise_model` + + +**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation + +**Default**: None + +
+ +
+ +#### `simulator.seed_simulator` + + +**Choices**: Integer + +**Default**: None + +
+ +
+ + +
+ +### `twirling` + + +Twirling options + +[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) +
+ +#### `twirling.enable_gates` + + +**Choices**: True, False + +**Default**: False + +
+ +
+ +#### `twirling.enable_measure` + + +**Choices**: True, False + +**Default**: False + +
+ +
+ +#### `twirling.num_randomizations` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.shots_per_randomization` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.strategy` + + +**Choices**: `active`, `active-circuit`, `active-accum`, `all` + +**Default**: `active-accum` + +
+ +
+ + +
+ +### `experimental` + + +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: + - Can be used with gate twirling for non-conditional gates. + - 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: + - Can be used with dynamic circuits with non-conditional gates. + - 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 + + + + +## 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). + diff --git a/docs/guides/runtime-options-overview - sampler.mdx b/docs/guides/runtime-options-overview - sampler.mdx new file mode 100644 index 00000000000..5c569ab7741 --- /dev/null +++ b/docs/guides/runtime-options-overview - sampler.mdx @@ -0,0 +1,420 @@ +--- +title: Introduction to options +description: Available options for building with Qiskit Runtime primitives +in_page_toc_min_heading_level: 2 +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 + + +### 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. + + +### 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. + + +## 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. + - [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. + + + +
+ +### `default_shots` + + +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) +
+ +
+ +### `dynamical_decoupling` + + +Control dynamical decoupling error mitigation settings. + +[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) +
+ +#### `dynamical_decoupling.enable` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ +#### `dynamical_decoupling.extra_slack_distribution` + + +**Choices**: `middle`, `edges` + +**Default**: `middle` +
+ +
+ +#### `dynamical_decoupling.scheduling_method` + + +Choices: `asap`, `alap` +Default: `alap` +
+ +
+ +#### `dynamical_decoupling.sequence_type` + + +Choices: `XX`, `XpXm`, `XY4` +Default: `XX` +
+ +
+ +#### `dynamical_decoupling.skip_reset_qubits` + + +Choices: `True`, `False` +Default: `False` +
+ +
+ + +
+ +### `environment` + +[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) +
+ +#### `environment.job_tags` + + +List of tags. + +**Choices**: None + +**Default**: None +
+ +
+ +#### `environment.log_level` + + +**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL + +**Default**: WARNING +
+ +
+ +#### `environment.private` + + +**Choices**: `True`, `False` + +**Default**: `False` +
+ +
+ + +
+ +### `execution` + +[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) +
+ +#### `execution.init_qubits` + +Whether to reset the qubits to the ground state for each shot. + +**Choices**: `True`, `False` + +**Default**: `True` +
+ +
+ +#### `execution.rep_delay` + +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` +
+
+ +#### `execution.meas_type` + + +**Choices**: `classified`, `kerneled`, `avg_kerneled` + +**Default**: `classified` +
+ +
+ + +
+ +### `max_execution_time` + +**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) +
+ +
+ +### `simulator` + + +Options to pass when simulating a backend + +[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) +
+ +#### `simulator.basis_gates` + + +**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) + +
+ +
+ +#### `simulator.coupling_map` + + +**Choices**: List of directed two-qubit interactions + +**Default**: None, which implies no connectivity constraints (full connectivity). + +
+ +
+ +#### `simulator.noise_model` + + +**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation + +**Default**: None + +
+ +
+ +#### `simulator.seed_simulator` + + +**Choices**: Integer + +**Default**: None + +
+ +
+ + +
+ +### `twirling` + + +Twirling options + +[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) +
+ +#### `twirling.enable_gates` + + +**Choices**: True, False + +**Default**: False + +
+ +
+ +#### `twirling.enable_measure` + + +**Choices**: True, False + +**Default**: False + +
+ +
+ +#### `twirling.num_randomizations` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.shots_per_randomization` + + +**Choices**: `auto`, Integer >= 1 + +**Default**: `auto` + +
+ +
+ +#### `twirling.strategy` + + +**Choices**: `active`, `active-circuit`, `active-accum`, `all` + +**Default**: `active-accum` + +
+ +
+ + +
+ +### `experimental` + + +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: + - Can be used with gate twirling for non-conditional gates. + - 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: + - Can be used with dynamic circuits with non-conditional gates. + - 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 + + + + + + +## Next steps + + + - 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). + diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb new file mode 100644 index 00000000000..fa8b0f3d12f --- /dev/null +++ b/docs/guides/sampler-input-output.ipynb @@ -0,0 +1,685 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "dbb193c8-d927-434c-a199-48de57c99694", + "metadata": {}, + "source": [ + "---\n", + "title: Primitive inputs and outputs\n", + "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "---\n", + "\n", + "\n", + "# Primitive inputs and outputs" + ] + }, + { + "cell_type": "markdown", + "id": "33c719ad", + "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", + "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": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", + "metadata": {}, + "source": [ + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the Sampler primitive, which execute 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 Sampler primitives." + ] + }, + { + "cell_type": "markdown", + "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", + "metadata": {}, + "source": [ + "\n", + "## Overview of PUBs\n", + "\n", + "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "\n", + "### Sampler PUB\n", + "For the Sampler primitive, the format of the PUB tuple contains 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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", + "metadata": {}, + "source": [ + "### 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", + "\n", + "Rules:\n", + "\n", + "* Input arrays do not need to have the same number of dimensions.\n", + " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", + " * The size of each dimension is the largest size of the corresponding dimension.\n", + " * Missing dimensions are assumed to have size one.\n", + "* Shape comparisons start with the rightmost dimension and continue to the left.\n", + "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", + "\n", + "Examples of array pairs that broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 1\n", + "A2 (2d array): 3 x 5\n", + "Result (2d array): 3 x 5\n", + "\n", + "A1 (3d array): 11 x 2 x 7\n", + "A2 (3d array): 11 x 1 x 7\n", + "Result (3d array): 11 x 2 x 7\n", + "```\n", + "\n", + "Examples of array pairs that do not broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 5\n", + "A2 (1d array): 3\n", + "\n", + "A1 (2d array): 2 x 1\n", + "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", + "```\n", + "\n", + "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", + "\n", + "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", + "\n", + " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", + "\n", + " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", + "\n", + " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", + "\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\")" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", + "metadata": {}, + "outputs": [], + "source": [ + "# Broadcast single observable\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Zip\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = [\n", + " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", + "] # shape (5,)\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Outer/Product\n", + "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", + "observables = [\n", + " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", + "] # shape (4, 1)\n", + "# >> pub result has shape (4, 6)\n", + "\n", + "# Standard nd generalization\n", + "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", + "observables = [\n", + " [\n", + " [SparsePauliOp([\"XII\"])],\n", + " [SparsePauliOp([\"IXI\"])],\n", + " [SparsePauliOp([\"IIX\"])],\n", + " ],\n", + " [\n", + " [SparsePauliOp([\"ZII\"])],\n", + " [SparsePauliOp([\"IZI\"])],\n", + " [SparsePauliOp([\"IIZ\"])],\n", + " ],\n", + "] # shape (2, 3, 1)\n", + "# >> pub result has shape (2, 3, 6)" + ] + }, + { + "cell_type": "markdown", + "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", + "metadata": {}, + "source": [ + "\n", + "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", + "\n", + "```text\n", + "a = SparsePauliOp(\"Z\") # shape ()\n", + "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", + "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "```\n", + "\n", + "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", + "\n", + "```text\n", + "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", + "```\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", + "metadata": {}, + "source": [ + "## Overview of primitive outputs\n", + "\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", + "\n", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", + "\n", + " ```\n", + " └── PrimitiveResult\n", + " ├── PubResult[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", + " ├── PubResult[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` 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", + "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\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": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", + "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", + " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", + " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", + " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", + " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", + " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", + " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", + " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", + " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", + " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", + " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", + " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", + " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", + " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", + " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", + " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", + " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", + " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", + " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", + " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", + " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", + " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", + " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", + " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", + " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", + " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", + " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", + " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", + " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", + " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", + " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", + " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", + " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", + " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", + " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", + " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", + " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", + " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", + " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", + " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", + " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", + " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", + " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", + " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", + " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", + " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", + " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", + " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", + " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", + " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", + " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", + "print(\n", + " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", + "metadata": {}, + "source": [ + "### Sampler output\n", + "\n", + "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", + "\n", + "The `BitArray` class is a container for ordered shot data. In more detail, 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", + "\n", + "As a first example, let us look at the following ten-qubit circuit:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "5c787874-1125-4381-b55e-7663caa92ec8", + "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 254]\n", + " [ 0 0]\n", + " [ 3 255]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 255]\n", + " [ 0 0]]\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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", + "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": 5, + "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", + "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": 6, + "id": "4602925e-c69d-45b2-9e06-fe8bffe0a797", + "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": "a65c6078-c5c2-4087-b57a-5680148ce333", + "metadata": {}, + "source": [ + "#### Leveraging `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": 7, + "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", + "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", + " [1]\n", + " [1]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [1]]\n", + "\n", + "The shape of register `beta` is (4096, 2).\n", + "The bytes in register `beta`, shot by shot:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " ...\n", + " [ 0 0]\n", + " [ 1 224]\n", + " [ 1 255]]\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", + " [7]\n", + " ...\n", + " [0]\n", + " [0]\n", + " [7]]\n", + "\n", + "The shape of `beta` after shot-wise slicing is (5, 2).\n", + "The bytes in `beta` after shot-wise slicing:\n", + "[[ 0 135]\n", + " [ 0 247]\n", + " [ 1 247]\n", + " [ 1 128]\n", + " [ 1 255]]\n", + "\n", + "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", + " coeffs=[1.+0.j])` is: 0.068359375\n", + "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", + " coeffs=[1.+0.j])` is: 0.06396484375\n", + "\n", + "The shape of the merged results is (4096, 2).\n", + "The bytes of the merged results:\n", + "[[ 1 15]\n", + " [ 1 239]\n", + " [ 3 239]\n", + " ...\n", + " [ 0 0]\n", + " [ 3 192]\n", + " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", + "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": 8, + "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", + "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": "2f26ff75-e1ba-45ef-97c1-c5dde36400cf", + "metadata": {}, + "source": [ + "You can also review the result metadata to understand when certain data was run; this is called the [_execution span._](monitor-job#execution-spans)" + ] + } + ], + "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-options.ipynb b/docs/guides/sampler-options.ipynb new file mode 100644 index 00000000000..835217464e8 --- /dev/null +++ b/docs/guides/sampler-options.ipynb @@ -0,0 +1,441 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "8bbb8d7d-bcd5-4092-9df1-9930c67b17bc", + "metadata": {}, + "source": [ + "---\n", + "title: Options\n", + "description: Specify options when building with the Sampler primitive.\n", + "---\n", + "\n", + "\n", + "# Sampler 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", + "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": "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", + "- 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 `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", + "`SamplerV2` and `EstimatorV2` have separate options classes. See [`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` 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": 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`. 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" + ] + }, + { + "cell_type": "markdown", + "id": "52024f25-74ef-445a-9df8-d76da4ec7a32", + "metadata": {}, + "source": [ + "#### Shots\n", + "\n", + "The `SamplerV2.run` method accepts two arguments: a list of PUBs, each of which can specify a PUB-specific value for shots, and a shots keyword argument. These shot values are a part of the Sampler execution interface, and are independent of the Runtime Sampler's options. They take precedence over any values specified as options in order to comply with the Sampler abstraction.\n", + "\n", + "However, if `shots` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the shots value from the options is used, most notably `default_shots`.\n", + "\n", + "To summarize, this is the order of precedence for specifying shots in the Sampler, for any particular PUB:\n", + "\n", + "1. If the PUB specifies shots, use that value.\n", + "2. If the `shots` keyword argument is specified in `run`, use that value.\n", + "3. If `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", + "## 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", + "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 `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 +} From 7d5a20fa587afca6a5c0ad431fdb74e552cc20c1 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 09:52:53 -0500 Subject: [PATCH 023/118] maybe "with primitives"? --- docs/guides/_toc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 8fe0ae3b35a..68f87cf66ac 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -357,7 +357,7 @@ "url": "/docs/guides/hello-world" }, { - "title": "Execute on hardware", + "title": "Execute with primitives", "children": [ { "title": "Primitives examples", From 7fce910119c1727f67df0424faebbab612833a43 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:34:33 -0500 Subject: [PATCH 024/118] update all broken links to point to github.io docs --- docs/guides/addons.mdx | 31 ++++++------------- ...assical-feedforward-and-control-flow.ipynb | 2 +- ...tion-template-hamiltonian-simulation.ipynb | 6 ++-- docs/guides/qiskit-function-templates.mdx | 2 +- ...antum-compilation-for-time-evolution.ipynb | 2 +- .../tutorials/operator-back-propagation.ipynb | 2 +- .../tutorials/qedma-2d-ising-with-qesem.ipynb | 4 +-- 7 files changed, 18 insertions(+), 31 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 27595092790..33b6056e44d 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -9,26 +9,23 @@ description: Understand the Qiskit addon tools, which help you build utility-gra Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These capabilities build on Qiskit's performant foundation of tools for creating and running quantum algorithms. They are provided as modular software components that can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. -Many of these addons are also powered by the `qiskit-addon-utils` package. You can find more information about this supplemental package in [this topic](/docs/guides/qiskit-addons-utils). - -## Addons for mapping - +Many of these addons are also powered by the `qiskit-addon-utils` package. For more information, see the [documentation](https://qiskit.github.io/qiskit-addon-utils/) for this supplemental package. - -## Addons for optimizing workloads - - - -## Addons for error mitigation - -## Addons for post-processing - - \n", " You can use the [`BitArray`](https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.primitives.BitArray#expectation_values) primitive attribute to compute the expectation values of the provided observables.\n", " \n", - "2. Execute one basis change circuit per partition (whichever basis change needs to be done for each partition). See the Measurement bases addon utility [`measurement_bases` module](https://github.com/Qiskit/qiskit-addon-utils/blob/38ea05431f2e9830adf4ec9265f6d19758a32096/qiskit_addon_utils/exp_vals/measurement_bases.py) for more information. [Get started with utilities.](/docs/guides/qiskit-addons-utils#get-started-with-utilities)\n", + "2. Execute one basis change circuit per partition (whichever basis change needs to be done for each partition). See the Measurement bases addon utility [`measurement_bases` module](https://qiskit.github.io/qiskit-addon-utils/apidocs/qiskit_addon_utils.exp_vals.html#qiskit_addon_utils.exp_vals.get_measurement_bases) for more information. For more information, see the [documentation](https://qiskit.github.io/qiskit-addon-utils/) for the Qiskit addon utilities package.\n", "3. Add back together the results for each partition." ] }, diff --git a/docs/guides/function-template-hamiltonian-simulation.ipynb b/docs/guides/function-template-hamiltonian-simulation.ipynb index 5d7aa7c6887..5785425ca23 100644 --- a/docs/guides/function-template-hamiltonian-simulation.ipynb +++ b/docs/guides/function-template-hamiltonian-simulation.ipynb @@ -29,7 +29,7 @@ "id": "b51e81bf-0bbf-4f64-af1e-87fcb443d997", "metadata": {}, "source": [ - "This template encapsulates a workflow to simulate the time evolution of an initial state against a user defined spin-based Hamiltonian and returns a set of specified expectation values using the [AQC addon](./qiskit-addons-aqc).\n", + "This template encapsulates a workflow to simulate the time evolution of an initial state against a user defined spin-based Hamiltonian and returns a set of specified expectation values using the [AQC-Tensor](https://qiskit.github.io/qiskit-addon-aqc-tensor/) Qiskit addon.\n", "\n", "This template is structured as a Qiskit pattern with the following steps:\n", "\n", @@ -55,9 +55,9 @@ "source": [ "## Write the function template\n", "\n", - "First, write a function template for Hamiltonian simulation that uses the [AQC-Tensor Qiskit addon](/docs/guides/qiskit-addons-aqc) to map the problem description to a reduced-depth circuit for execution on hardware.\n", + "First, write a function template for Hamiltonian simulation that uses the [AQC-Tensor Qiskit addon](https://qiskit.github.io/qiskit-addon-aqc-tensor/) to map the problem description to a reduced-depth circuit for execution on hardware.\n", "\n", - "Throughout, the code is saved to `./source_files/template_hamiltonian_simulation.py`. This file is the function template you can upload to and run remotely with Qiskit Serverless." + "Throughout, the code is saved to `./source_files/template_hamiltonian_simulation.py`. This file is the function template you can upload to and run remotely with Qiskit Serverless." ] }, { diff --git a/docs/guides/qiskit-function-templates.mdx b/docs/guides/qiskit-function-templates.mdx index 9babf353d5d..a2dd9ffcf45 100644 --- a/docs/guides/qiskit-function-templates.mdx +++ b/docs/guides/qiskit-function-templates.mdx @@ -15,7 +15,7 @@ There are two types of templates: ## Template implementations -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](./qiskit-addons-aqc) and a chemistry template for electronic structure with the implicit solvent model using the [SQD Qiskit addon](./qiskit-addons-sqd). +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) diff --git a/docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb b/docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb index f3af19dd581..9ea79755449 100644 --- a/docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb +++ b/docs/tutorials/approximate-quantum-compilation-for-time-evolution.ipynb @@ -26,7 +26,7 @@ "\n", "This tutorial demonstrates how to implement **Approximate Quantum Compilation** using tensor networks (AQC-Tensor) with Qiskit to enhance quantum circuit performance. We apply AQC-Tensor within the context of a Trotterized time evolution to reduce circuit depth while maintaining simulation accuracy, following the Qiskit framework for state preparation and optimization. You will learn how to create a low-depth ansatz circuit from an initial Trotter circuit, optimize it with tensor networks, and prepare it for quantum hardware execution.\n", "\n", - "The primary objective is to simulate time evolution for a model Hamiltonian with a reduced circuit depth. This is achieved using the **AQC-Tensor** Qiskit addon, [qiskit-addon-aqc-tensor](https://github.com/Qiskit/qiskit-addon-aqc-tensor), which leverages tensor networks, specifically matrix product states (MPS), to compress and optimize the initial circuit. Through iterative adjustments, the compressed ansatz circuit maintains fidelity to the original circuit while staying feasible for near-term quantum hardware. More details can be found in the corresponding [docs](/docs/guides/qiskit-addons-aqc) with a [simple example](/docs/guides/qiskit-addons-aqc-get-started) to get started.\n", + "The primary objective is to simulate time evolution for a model Hamiltonian with a reduced circuit depth. This is achieved using the **AQC-Tensor** Qiskit addon, [qiskit-addon-aqc-tensor](https://github.com/Qiskit/qiskit-addon-aqc-tensor), which leverages tensor networks, specifically matrix product states (MPS), to compress and optimize the initial circuit. Through iterative adjustments, the compressed ansatz circuit maintains fidelity to the original circuit while staying feasible for near-term quantum hardware. See the [documentation](https://qiskit.github.io/qiskit-addon-aqc-tensor/) for more information.\n", "\n", "Approximate Quantum Compilation is particularly advantageous in quantum simulations that exceed hardware coherence times, as it allows complex simulations to be performed more efficiently. This tutorial guides you through the AQC-Tensor workflow setup in Qiskit, covering initialization of a Hamiltonian, generation of Trotter circuits, and transpilation of the final optimized circuit for a target device." ] diff --git a/docs/tutorials/operator-back-propagation.ipynb b/docs/tutorials/operator-back-propagation.ipynb index 48b6c7ebe50..a6bb9039c99 100644 --- a/docs/tutorials/operator-back-propagation.ipynb +++ b/docs/tutorials/operator-back-propagation.ipynb @@ -40,7 +40,7 @@ "source": [ "## Background\n", "\n", - "Operator backpropagation is a technique which involves absorbing operations from the end of a quantum circuit into the measured observable, generally reducing the depth of the circuit at the cost of additional terms in the observable. The goal is to backpropagate as much of the circuit as possible without allowing the observable to grow too large. A Qiskit-based implementation is available in the OBP Qiskit addon, more details can be found in the corresponding [docs](/docs/guides/qiskit-addons-obp) with a [simple example](/docs/guides/qiskit-addons-obp-get-started) to get started.\n", + "Operator backpropagation is a technique which involves absorbing operations from the end of a quantum circuit into the measured observable, generally reducing the depth of the circuit at the cost of additional terms in the observable. The goal is to backpropagate as much of the circuit as possible without allowing the observable to grow too large. A Qiskit-based implementation is available in the OBP Qiskit addon. Read the corresponding [documentation](https://qiskit.github.io/qiskit-addon-obp/) for more information.\n", "\n", "Consider an example circuit for which an observable $O = \\sum_P c_P P$ is to be measured, where $P$ are Paulis and $c_P$ are coefficients. Let us denote the circuit as a single unitary $U$ which can be logically partitioned into $U = U_C U_Q$ as shown in the figure below.\n", "\n", diff --git a/docs/tutorials/qedma-2d-ising-with-qesem.ipynb b/docs/tutorials/qedma-2d-ising-with-qesem.ipynb index 77b09b652f9..9adb0b831fb 100644 --- a/docs/tutorials/qedma-2d-ising-with-qesem.ipynb +++ b/docs/tutorials/qedma-2d-ising-with-qesem.ipynb @@ -52,7 +52,7 @@ "* Estimate the expected QPU runtime for full error mitigation using QESEM's analytical and empirical time estimation features.\n", "* Construct and simulate the 2D tilted-field Ising model circuit using hardware-inspired qubit layouts and gate layers.\n", "* Visualize device qubit connectivity and selected subgraphs for your experiment.\n", - "* Demonstrate the use of [operator backpropagation (OBP)](/docs/guides/qiskit-addons-obp) to reduce circuit depth. This technique trims operations from the circuit end at the cost of more operator measurements.\n", + "* Demonstrate the use of [operator backpropagation (OBP)](https://qiskit.github.io/qiskit-addon-obp/) to reduce circuit depth. This technique trims operations from the circuit end at the cost of more operator measurements.\n", "* Perform unbiased error mitigation (EM) for multiple observables simultaneously by using QESEM, comparing ideal, noisy, and mitigated results.\n", "* Analyze and plot the impact of error mitigation on magnetization across different circuit depths.\n", "\n", @@ -808,7 +808,7 @@ "id": "75dbab74", "metadata": {}, "source": [ - "Now we will use operator backpropagation (OBP). (See the [OBP](/docs/guides/qiskit-addons-obp) guide for more details on the OBP Qiskit addon.) We will create a function that generates the circuit slices for backpropagation:" + "Now we will use operator backpropagation (OBP). (See the [OBP](https://qiskit.github.io/qiskit-addon-obp/) documentation for more details on the OBP Qiskit addon.) We will create a function that generates the circuit slices for backpropagation:" ] }, { From 051051d7cef55cd269a34a09f858871c79d8ac23 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 10:40:36 -0500 Subject: [PATCH 025/118] Update notebook-testing.toml --- scripts/config/notebook-testing.toml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 25461e174fc..6333c8d3d75 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -36,11 +36,6 @@ notebooks = [ "docs/guides/operators-overview.ipynb", "docs/guides/plot-quantum-states.ipynb", "docs/guides/primitives-rest-api.ipynb", - "docs/guides/qiskit-addons-aqc-get-started.ipynb", - "docs/guides/qiskit-addons-cutting-wires.ipynb", - "docs/guides/qiskit-addons-mpf-get-started.ipynb", - "docs/guides/qiskit-addons-mpf.ipynb", - "docs/guides/qiskit-addons-utils.ipynb", "docs/guides/quick-start.ipynb", "docs/guides/repetition-rate-execution.ipynb", "docs/guides/represent-quantum-computers.ipynb", @@ -84,7 +79,6 @@ notebooks = [ "docs/guides/get-started-with-primitives.ipynb", "docs/guides/ibm-circuit-function.ipynb", "docs/guides/primitives-examples.ipynb", - "docs/guides/qiskit-addons-obp-get-started.ipynb", "docs/guides/qiskit-addons-sqd-get-started.ipynb", "docs/guides/multiverse-computing-singularity.ipynb", "docs/guides/qunova-chemistry.ipynb", @@ -104,7 +98,6 @@ notebooks = [ "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 - "docs/guides/qiskit-addons-cutting-gates.ipynb", # 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 From 3cdd7dac984aaa58367a375804d75e7fffc8a4cc Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 12:27:21 -0500 Subject: [PATCH 026/118] group together for quicker scan --- docs/guides/addons.mdx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 33b6056e44d..87dc4a1b61b 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -1,11 +1,11 @@ --- -title: Qiskit addons +title: Advanced techniques - Qiskit addons description: Understand the Qiskit addon tools, which help you build utility-grade quantum workflows. --- {/* cspell:ignore lightcones */} -# Qiskit addons +# Advanced techniques - Qiskit addons Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These capabilities build on Qiskit's performant foundation of tools for creating and running quantum algorithms. They are provided as modular software components that can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. @@ -35,9 +35,8 @@ Many of these addons are also powered by the `qiskit-addon-utils` package. For m analyticsName="Documentation page: Optimization mapper" linkText="Browse documentation" /> - - + - - + - - + Date: Fri, 6 Feb 2026 11:57:53 -0600 Subject: [PATCH 027/118] More new files --- docs/guides/estimator-examples.ipynb | 425 ++++++++++++++++ docs/guides/executor-examples.ipynb | 706 +++++++++++++++++++++++++++ docs/guides/sampler-examples.ipynb | 371 ++++++++++++++ docs/guides/sampler-options.ipynb | 68 +-- 4 files changed, 1522 insertions(+), 48 deletions(-) create mode 100644 docs/guides/estimator-examples.ipynb create mode 100644 docs/guides/executor-examples.ipynb create mode 100644 docs/guides/sampler-examples.ipynb diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb new file mode 100644 index 00000000000..23874ddff90 --- /dev/null +++ b/docs/guides/estimator-examples.ipynb @@ -0,0 +1,425 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1f4a2ec4-3595-4300-8f9e-092b0ef9b444", + "metadata": {}, + "source": [ + "---\n", + "title: Examples\n", + "description: Practical examples of using Estimator 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", + "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": "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", + "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.13582342954159593\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.4873096446700508\n", + ">>> Standard errors for PUB 0: 1.3528950031716114\n", + ">>> Expectation values for PUB 1: -0.00390625\n", + ">>> Standard errors for PUB 1: 0.015347884419435263\n", + ">>> Expectation values for PUB 2: -0.02001953125\n", + ">>> Standard errors for PUB 2: 0.013797455737635134\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.0455093 0.98152862 0.82113463 0.60354133 0.29572641 0.01149883\n", + " -0.33110743 -0.60560522 -0.83322315 -0.96531231 -1.0257549 -0.95853095\n", + " -0.81081517 -0.61091237 -0.30221293 0.0035381 0.31371176 0.61061753\n", + " 0.83646641 0.97091431 1.03135689]\n", + " [ 0.03390682 0.31194271 0.620937 0.87391133 0.96973494 1.03872794\n", + " 0.94260949 0.82378821 0.56344283 0.28688115 -0.04570049 -0.37474403\n", + " -0.64540887 -0.87803912 -0.97887504 -1.03577952 -0.97268336 -0.83970967\n", + " -0.59705481 -0.29867482 0.0380346 ]\n", + " [ 0.00265358 -0.32992806 -0.59646512 -0.80934096 -0.96737621 -1.00128302\n", + " -0.94673728 -0.82703147 -0.59705481 -0.31341692 -0.00117937 0.29985419\n", + " 0.59469607 0.78486908 0.93346939 0.97622146 0.94732696 0.81199454\n", + " 0.60914332 0.28393273 -0.00678136]\n", + " [ 0.99656555 0.93553328 0.78398456 0.55872536 0.29749546 -0.04511081\n", + " -0.33523522 -0.62889773 -0.82201916 -0.95351864 -1.02634458 -0.96796589\n", + " -0.82054495 -0.57553135 -0.30103356 0.00265358 0.3104685 0.59705481\n", + " 0.83322315 0.94437854 0.99214292]]\n", + ">>> Standard errors: [[0.014353 0.01441151 0.01620648 0.0195418 0.019762 0.01515649\n", + " 0.02102523 0.02112359 0.0148494 0.01119219 0.01576623 0.01245824\n", + " 0.01239832 0.01501273 0.01821305 0.01776286 0.01500156 0.01635231\n", + " 0.01577367 0.01315371 0.01089558]\n", + " [0.01352805 0.01627835 0.01247646 0.01287866 0.01570182 0.01060924\n", + " 0.01590468 0.01620303 0.01530626 0.01619973 0.01918078 0.01379676\n", + " 0.01564971 0.01377673 0.01454324 0.01242184 0.01252201 0.01396738\n", + " 0.01326188 0.0145736 0.01795044]\n", + " [0.02029376 0.01610892 0.0161542 0.0157785 0.01385665 0.01113743\n", + " 0.01375237 0.01380922 0.0145974 0.01759484 0.01594193 0.02111719\n", + " 0.01521368 0.01365888 0.01188512 0.01353009 0.01195674 0.01446547\n", + " 0.01660987 0.01511225 0.01880871]\n", + " [0.01105161 0.01164476 0.01329858 0.01439545 0.01888747 0.01629201\n", + " 0.01405852 0.01406643 0.01088709 0.01275198 0.01281432 0.01333301\n", + " 0.01268483 0.01443594 0.01495655 0.01715532 0.01822699 0.01508936\n", + " 0.01435528 0.01340555 0.01295649]]\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.08045977011494253\n", + " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", + " > Another Expectation value: 0.02127659574468085\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": "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/executor-examples.ipynb b/docs/guides/executor-examples.ipynb new file mode 100644 index 00000000000..e3dc5e4afa1 --- /dev/null +++ b/docs/guides/executor-examples.ipynb @@ -0,0 +1,706 @@ +{ + "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", + "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": "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.13582342954159593\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.4873096446700508\n", + ">>> Standard errors for PUB 0: 1.3528950031716114\n", + ">>> Expectation values for PUB 1: -0.00390625\n", + ">>> Standard errors for PUB 1: 0.015347884419435263\n", + ">>> Expectation values for PUB 2: -0.02001953125\n", + ">>> Standard errors for PUB 2: 0.013797455737635134\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.0455093 0.98152862 0.82113463 0.60354133 0.29572641 0.01149883\n", + " -0.33110743 -0.60560522 -0.83322315 -0.96531231 -1.0257549 -0.95853095\n", + " -0.81081517 -0.61091237 -0.30221293 0.0035381 0.31371176 0.61061753\n", + " 0.83646641 0.97091431 1.03135689]\n", + " [ 0.03390682 0.31194271 0.620937 0.87391133 0.96973494 1.03872794\n", + " 0.94260949 0.82378821 0.56344283 0.28688115 -0.04570049 -0.37474403\n", + " -0.64540887 -0.87803912 -0.97887504 -1.03577952 -0.97268336 -0.83970967\n", + " -0.59705481 -0.29867482 0.0380346 ]\n", + " [ 0.00265358 -0.32992806 -0.59646512 -0.80934096 -0.96737621 -1.00128302\n", + " -0.94673728 -0.82703147 -0.59705481 -0.31341692 -0.00117937 0.29985419\n", + " 0.59469607 0.78486908 0.93346939 0.97622146 0.94732696 0.81199454\n", + " 0.60914332 0.28393273 -0.00678136]\n", + " [ 0.99656555 0.93553328 0.78398456 0.55872536 0.29749546 -0.04511081\n", + " -0.33523522 -0.62889773 -0.82201916 -0.95351864 -1.02634458 -0.96796589\n", + " -0.82054495 -0.57553135 -0.30103356 0.00265358 0.3104685 0.59705481\n", + " 0.83322315 0.94437854 0.99214292]]\n", + ">>> Standard errors: [[0.014353 0.01441151 0.01620648 0.0195418 0.019762 0.01515649\n", + " 0.02102523 0.02112359 0.0148494 0.01119219 0.01576623 0.01245824\n", + " 0.01239832 0.01501273 0.01821305 0.01776286 0.01500156 0.01635231\n", + " 0.01577367 0.01315371 0.01089558]\n", + " [0.01352805 0.01627835 0.01247646 0.01287866 0.01570182 0.01060924\n", + " 0.01590468 0.01620303 0.01530626 0.01619973 0.01918078 0.01379676\n", + " 0.01564971 0.01377673 0.01454324 0.01242184 0.01252201 0.01396738\n", + " 0.01326188 0.0145736 0.01795044]\n", + " [0.02029376 0.01610892 0.0161542 0.0157785 0.01385665 0.01113743\n", + " 0.01375237 0.01380922 0.0145974 0.01759484 0.01594193 0.02111719\n", + " 0.01521368 0.01365888 0.01188512 0.01353009 0.01195674 0.01446547\n", + " 0.01660987 0.01511225 0.01880871]\n", + " [0.01105161 0.01164476 0.01329858 0.01439545 0.01888747 0.01629201\n", + " 0.01405852 0.01406643 0.01088709 0.01275198 0.01281432 0.01333301\n", + " 0.01268483 0.01443594 0.01495655 0.01715532 0.01822699 0.01508936\n", + " 0.01435528 0.01340555 0.01295649]]\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.08045977011494253\n", + " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", + " > Another Expectation value: 0.02127659574468085\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: ['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": "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: ['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 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: ['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 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: ['1101100010101100001001110000100011110011000010110000010000001011000110000110010100011000101111011110010101101001000101010100010', '0010100100011100001011111101001010010000010010000100000011001010001110101011010000100011001010000101110101110110010000110001110', '1011000110110011011010001111001011111000011111111010010010011000000110000001000101001111001000010110000000011101010000111101101', '0101000010000101001011111010110011101000100101010011001000010000011010000010101000000001000100010100011100101001000101001011000', '1101010101011100000001100110111001000100110011110001110011000000110100011011100000010000001100001101011000000001010101001101001', '1111100011111010000000100011100110101000010101100100000110000110001011100000000101010110011110010010000100011110000010101010100', '1011011100110001000110100100110010101101110010100010011100001000001100010101101110010101100000001110000000111001001000000100010', '0100011011110111010010111011101010111010010011011110011001000010101110100100111010110001101100110001010100000101001000000111001', '0001110001110000001011101101010001001110000010100001000101100100110111001011100000101010011100011001110011100100000000010110001', '1010110110111000001100011100000100101000000001111110110010000110011100100100100010000101111110100110010010010101001011001000011']\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: ['0100010001111001111010000100101010011010000100010110100100010010010110001010101010000000110000010000001100100011000110101000001', '1101000100010000011100110101001110101100001000000000101001110110110010110110010010011100010000010001011000011100100000100000000', '1111101010100011010100000100010101111110011000000000010000010000101001010001100000100000100010000001100111000000111000111010000', '0101111100000110010101101100101110101011010100001001110101100010111100110011100001110101000000001000000000101000100000001000000', '1101001000000000011000010100111110101111001001110011100001100100100100000011110001001000001000010101111100001001110010110011100', '1100001000110110000111110110010010000100001000001001100011110001111100100101110010010111010010101100001010101011100100001010010', '0001001100010000000101101101101111000011101100101000111010000000000010010111011000100000011010100000100011100010110010010000001', '1010101100000000011000111101000011100101000110110000111111000001100010001110000101111111110110000000000000001000000010001110000', '1111111001001001001100010000101110110100001011011100010001100000100001010100111011000110100011110000001010101000010000000011000', '1011011010101100010101100001001000000010110001101000100001111010000100011100000000100111001001000001001001101000001000100000000']\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/sampler-examples.ipynb b/docs/guides/sampler-examples.ipynb new file mode 100644 index 00000000000..ca77579f111 --- /dev/null +++ b/docs/guides/sampler-examples.ipynb @@ -0,0 +1,371 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1f4a2ec4-3595-4300-8f9e-092b0ef9b444", + "metadata": {}, + "source": [ + "---\n", + "title: Examples\n", + "description: Practical examples of using the Sampler primitives in Qiskit Runtime.\n", + "---\n", + "\n", + "\n", + "# Sampler 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", + "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": "12aea3c7-37a1-4a6b-b944-587669aa6611", + "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": "a5a561b3-3819-4f9e-bb64-4c27267e0e96", + "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": "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: ['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 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: ['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 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: ['1101100010101100001001110000100011110011000010110000010000001011000110000110010100011000101111011110010101101001000101010100010', '0010100100011100001011111101001010010000010010000100000011001010001110101011010000100011001010000101110101110110010000110001110', '1011000110110011011010001111001011111000011111111010010010011000000110000001000101001111001000010110000000011101010000111101101', '0101000010000101001011111010110011101000100101010011001000010000011010000010101000000001000100010100011100101001000101001011000', '1101010101011100000001100110111001000100110011110001110011000000110100011011100000010000001100001101011000000001010101001101001', '1111100011111010000000100011100110101000010101100100000110000110001011100000000101010110011110010010000100011110000010101010100', '1011011100110001000110100100110010101101110010100010011100001000001100010101101110010101100000001110000000111001001000000100010', '0100011011110111010010111011101010111010010011011110011001000010101110100100111010110001101100110001010100000101001000000111001', '0001110001110000001011101101010001001110000010100001000101100100110111001011100000101010011100011001110011100100000000010110001', '1010110110111000001100011100000100101000000001111110110010000110011100100100100010000101111110100110010010010101001011001000011']\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: ['0100010001111001111010000100101010011010000100010110100100010010010110001010101010000000110000010000001100100011000110101000001', '1101000100010000011100110101001110101100001000000000101001110110110010110110010010011100010000010001011000011100100000100000000', '1111101010100011010100000100010101111110011000000000010000010000101001010001100000100000100010000001100111000000111000111010000', '0101111100000110010101101100101110101011010100001001110101100010111100110011100001110101000000001000000000101000100000001000000', '1101001000000000011000010100111110101111001001110011100001100100100100000011110001001000001000010101111100001001110010110011100', '1100001000110110000111110110010010000100001000001001100011110001111100100101110010010111010010101100001010101011100100001010010', '0001001100010000000101101101101111000011101100101000111010000000000010010111011000100000011010100000100011100010110010010000001', '1010101100000000011000111101000011100101000110110000111111000001100010001110000101111111110110000000000000001000000010001110000', '1111111001001001001100010000101110110100001011011100010001100000100001010100111011000110100011110000001010101000010000000011000', '1011011010101100010101100001001000000010110001101000100001111010000100011100000000100111001001000001001001101000001000100000000']\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/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 835217464e8..afada4a9089 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -48,7 +48,7 @@ "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", + "You can use options to customize the 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", @@ -75,30 +75,30 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "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", + "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 = EstimatorOptions(\n", + "options = SamplerOptions(\n", " resilience_level=2,\n", " resilience={\"zne_mitigation\": True, \"zne\": {\"noise_factors\": [1, 3, 5]}},\n", ")\n", "\n", "# or...\n", - "options = EstimatorOptions()\n", + "options = SamplerOptions()\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)" + "sampler = Sampler(mode=backend, options=options)" ] }, { @@ -113,19 +113,19 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "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", + "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", - "estimator = Estimator(\n", + "sampler = Sampler(\n", " backend,\n", " options={\n", " \"resilience_level\": 2,\n", @@ -151,24 +151,24 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "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", + "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", "\n", "service = QiskitRuntimeService()\n", "backend = service.least_busy(operational=True, simulator=False)\n", "\n", - "estimator = Estimator(mode=backend)\n", + "sampler = Sampler(mode=backend)\n", "\n", "# Setting options after primitive initialization\n", "# This uses auto-complete.\n", - "estimator.options.default_shots = 4000\n", + "sampler.options.default_shots = 4000\n", "# This does bulk update.\n", - "estimator.options.update(\n", + "sampler.options.update(\n", " default_shots=4000, resilience={\"zne_mitigation\": True}\n", ")" ] @@ -347,20 +347,20 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": null, "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", + "from qiskit_ibm_runtime import SamplerV2 as Sampler\n", "\n", "service = QiskitRuntimeService()\n", "backend = service.least_busy(operational=True, simulator=False)\n", "\n", - "estimator = Estimator(mode=backend)\n", + "sampler = Sampler(mode=backend)\n", "\n", - "estimator.options.max_execution_time = 2500" + "sampler.options.max_execution_time = 2500" ] }, { @@ -371,35 +371,7 @@ "\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" + "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 SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default." ] }, { From d5cc2bd1d581668216c8ab350d98d18c18e07654 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 13:48:47 -0500 Subject: [PATCH 028/118] capabilities in a table - one possibility --- docs/guides/addons.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 87dc4a1b61b..930055116ef 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -7,9 +7,16 @@ description: Understand the Qiskit addon tools, which help you build utility-gra # Advanced techniques - Qiskit addons -Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These capabilities build on Qiskit's performant foundation of tools for creating and running quantum algorithms. They are provided as modular software components that can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. +Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These modular software components can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. Many of these addons are powered by the `qiskit-addon-utils` package. See the [Qiskit addon utilities documentation](https://qiskit.github.io/qiskit-addon-utils/) for more information. -Many of these addons are also powered by the `qiskit-addon-utils` package. For more information, see the [documentation](https://qiskit.github.io/qiskit-addon-utils/) for this supplemental package. +This table lists Qiskit addons with their research capabilities. A description of each addon follows the table. + +| Capability | | +| --- | --- | +| Mapping | [AQC-Tensor](https://qiskit.github.io/qiskit-addon-aqc-tensor/), [MPF](https://qiskit.github.io/qiskit-addon-mpf/), [Optimization Mapper](https://qiskit.github.io/qiskit-addon-opt-mapper/) | +| Optimizing | [OBP](https://qiskit.github.io/qiskit-addon-obp/), [Circuit cutting](https://qiskit.github.io/qiskit-addon-cutting) | +| Error mitigation | [M3](https://qiskit.github.io/qiskit-addon-mpf/), [SLC](https://qiskit.github.io/qiskit-addon-slc/), [PNA](https://qiskit.github.io/qiskit-addon-pna/) | +| Post-processing | [SQD](/docs/guides/qiskit-addons-sqd-get-started), [SQD for HPC](https://qiskit.github.io/qiskit-addon-sqd-hpc/), [Dice eigensolver](https://qiskit.github.io/qiskit-addon-dice-solver/) | Date: Fri, 6 Feb 2026 13:06:52 -0600 Subject: [PATCH 029/118] update TOC --- docs/guides/_toc.json | 155 ++++++++++++++++++++++++++++++------------ 1 file changed, 111 insertions(+), 44 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 68f87cf66ac..9c5b0172d5b 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -216,25 +216,9 @@ ] }, { - "title": "Primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/primitives" - }, - { - "title": "Get started with primitives", - "url": "/docs/guides/get-started-with-primitives" - }, - { - "title": "Primitive inputs and outputs", - "url": "/docs/guides/primitive-input-output" - }, - { - "title": "Exact simulation with Qiskit SDK primitives", - "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" - } - ] + "title": "Exact simulation with Qiskit SDK primitives", + "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" + }, { "title": "Debugging", @@ -360,13 +344,117 @@ "title": "Execute with primitives", "children": [ { - "title": "Primitives examples", - "url": "/docs/guides/primitives-examples" + "title": "Introduction to primitives", + "url": "/docs/guides/primitives" + }, + { + "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": "Examples", + "url": "/docs/guides/estimator-examples" + }, + { + "title": "BackendEstimator", + "url": "/docs/guides/estimator-rest-api" + }, + { + "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": "Examples", + "url": "/docs/guides/sampler-examples" + }, + { + "title": "BackendSampler", + "url": "/docs/guides/sampler-rest-api" + }, + { + "title": "REST API", + "url": "/docs/guides/sampler-rest-api" + } + ] + }, + { + "title": "Executor", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-executor" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/executor-input-output" + }, + { + "title": "Options", + "url": "/docs/guides/executor-options" + }, + { + "title": "Examples", + "url": "/docs/guides/executor-examples" + }, + { + "title": "BackendExecutor", + "url": "/docs/guides/executor-rest-api" + }, + { + "title": "REST API", + "url": "/docs/guides/executor-rest-api" + } + ] + }, + { + "title": "Manage noise", + "children": [ + { + "title": "Error mitigation and suppression", + "url": "/docs/guides/error-mitigation-and-suppression-techniques" }, { - "title": "Primitives with REST API", - "url": "/docs/guides/primitives-rest-api" + "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": "Directed execution model (beta)", "url": "/docs/guides/directed-execution-model" @@ -422,27 +510,6 @@ } ] }, - { - "title": "Manage noise", - "children": [ - { - "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": [ From 471e1b834955865b561c6e354d7d7be824fd53e0 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Fri, 6 Feb 2026 15:30:28 -0500 Subject: [PATCH 030/118] Update addons.mdx --- docs/guides/addons.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 930055116ef..258536fbf93 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -13,10 +13,10 @@ This table lists Qiskit addons with their research capabilities. A description o | Capability | | | --- | --- | -| Mapping | [AQC-Tensor](https://qiskit.github.io/qiskit-addon-aqc-tensor/), [MPF](https://qiskit.github.io/qiskit-addon-mpf/), [Optimization Mapper](https://qiskit.github.io/qiskit-addon-opt-mapper/) | -| Optimizing | [OBP](https://qiskit.github.io/qiskit-addon-obp/), [Circuit cutting](https://qiskit.github.io/qiskit-addon-cutting) | -| Error mitigation | [M3](https://qiskit.github.io/qiskit-addon-mpf/), [SLC](https://qiskit.github.io/qiskit-addon-slc/), [PNA](https://qiskit.github.io/qiskit-addon-pna/) | -| Post-processing | [SQD](/docs/guides/qiskit-addons-sqd-get-started), [SQD for HPC](https://qiskit.github.io/qiskit-addon-sqd-hpc/), [Dice eigensolver](https://qiskit.github.io/qiskit-addon-dice-solver/) | +| Map | [AQC-Tensor](https://qiskit.github.io/qiskit-addon-aqc-tensor/), [Multi-product formulas](https://qiskit.github.io/qiskit-addon-mpf/), [Optimization Mapper](https://qiskit.github.io/qiskit-addon-opt-mapper/) | +| Optimize | [Operator backpropagation](https://qiskit.github.io/qiskit-addon-obp/), [Circuit cutting](https://qiskit.github.io/qiskit-addon-cutting) | +| Error mitigation | [Matrix-free Measurement Mitigation](https://qiskit.github.io/qiskit-addon-mpf/), [Shaded lightcones](https://qiskit.github.io/qiskit-addon-slc/), [Propagated noise absorption](https://qiskit.github.io/qiskit-addon-pna/) | +| Post-process | [Sample-based quantum diagonalization](/docs/guides/qiskit-addons-sqd-get-started), [SQD for HPC](https://qiskit.github.io/qiskit-addon-sqd-hpc/), [Dice eigensolver](https://qiskit.github.io/qiskit-addon-dice-solver/) | Date: Mon, 9 Feb 2026 16:00:59 -0600 Subject: [PATCH 031/118] Start adding executor input --- docs/guides/directed-execution-model.mdx | 12 +- docs/guides/estimator-examples.ipynb | 4 +- docs/guides/executor-examples.ipynb | 85 +-- docs/guides/executor-input-output.ipynb | 903 ++++------------------- docs/guides/sampler-examples.ipynb | 2 +- 5 files changed, 180 insertions(+), 826 deletions(-) diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index d3310d7f54f..2fe2161001d 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -1,5 +1,5 @@ --- -title: Directed execution model (beta) +title: Directed execution model description: Use this composable, explicit execution model with your utility-scale experiments to fine-tune error mitigation and other techniques. --- @@ -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. @@ -41,21 +41,17 @@ The following tools can be used together to implement an error mitigation techni ![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 pair tells the [Executor primitive](#executor) 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. 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. ### NoiseLearnerV3 diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb index 23874ddff90..5ce83396218 100644 --- a/docs/guides/estimator-examples.ipynb +++ b/docs/guides/estimator-examples.ipynb @@ -7,11 +7,11 @@ "source": [ "---\n", "title: Examples\n", - "description: Practical examples of using Estimator primitives in Qiskit Runtime.\n", + "description: Practical examples of using Estimator primitive in Qiskit Runtime.\n", "---\n", "\n", "\n", - "# Primitives examples" + "# Estimator examples" ] }, { diff --git a/docs/guides/executor-examples.ipynb b/docs/guides/executor-examples.ipynb index e3dc5e4afa1..e7bcdaab00a 100644 --- a/docs/guides/executor-examples.ipynb +++ b/docs/guides/executor-examples.ipynb @@ -6,12 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Primitives examples\n", - "description: Practical examples of using primitives in Qiskit Runtime.\n", + "title: Examples\n", + "description: Practical examples of using the Executor primitve in Qiskit Runtime.\n", "---\n", "\n", "\n", - "# Primitives examples" + "# Executor examples" ] }, { @@ -58,64 +58,49 @@ "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", + "The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up.](install-qiskit)\n", "\n", "### Run a single experiment\n", "\n", - "Use Estimator to determine the expectation value of a single circuit-observable pair." + "Consider a circuit that generates a three-qubit GHZ state, rotates\n", + "the qubits around the Pauli-Z axis, and measures the qubits in the computational basis. We show how\n", + "to add this circuit to a `QuantumProgram`, optionally randomizing its content with twirling\n", + "gates, and execute the program by using the `Executor` class." ] }, { "cell_type": "code", - "execution_count": 1, - "id": "24573866-7cf2-40e1-b61c-a2bdcecb759b", + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > Expectation value: -0.13582342954159593\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], + "outputs": [], "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", + "from qiskit.circuit import Parameter, QuantumCircuit\n", + "from qiskit_ibm_runtime import QiskitRuntimeService, Executor\n", + "\n", + "# Generate the circuit\n", + "circuit = QuantumCircuit(3)\n", + "circuit.h(0)\n", + "circuit.h(1)\n", + "circuit.cz(0, 1)\n", + "circuit.h(1)\n", + "circuit.h(2)\n", + "circuit.cz(1, 2)\n", + "circuit.h(2)\n", + "circuit.rz(Parameter(\"theta\"), 0)\n", + "circuit.rz(Parameter(\"phi\"), 1)\n", + "circuit.rz(Parameter(\"lam\"), 2)\n", + "circuit.measure_all()\n", "\n", + "# Initialize the service and choose a backend\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}\")" + "backend = service.least_busy(operational=True, simulator=False)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The inputs to the `Executor` are `QuantumProgram`s. For full details, see [Executor input and output.](/docs/guides/executor-input-output)" ] }, { diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb index b5c24c629a2..8c1109c50a7 100644 --- a/docs/guides/executor-input-output.ipynb +++ b/docs/guides/executor-input-output.ipynb @@ -6,22 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Primitive inputs and outputs\n", - "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "title: Inputs and outputs\n", + "description: Understand the inputs and outputs to the Executor primitive\n", "---\n", "\n", "\n", - "# Primitive inputs and outputs" - ] - }, - { - "cell_type": "markdown", - "id": "33c719ad", - "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", - "" + "# Executor inputs and outputs" ] }, { @@ -63,761 +53,144 @@ }, { "cell_type": "markdown", - "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", "metadata": {}, "source": [ - "\n", - "## Overview of PUBs\n", - "\n", - "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", - "\n", - "### Estimator PUB\n", - "For the Estimator primitive, the format of the PUB should 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", - " If you have two commuting observables in different PUBs but with the same circuit, they will not be estimated using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB. To ensure that commuting observables are estimated using the same measurement, they must be grouped 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\n", - "\n", - "### Sampler PUB\n", - "For the Sampler primitive, the format of the PUB tuple contains 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": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", - "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": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", - "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", - " EstimatorV2 as Estimator,\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", - "\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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "### 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", + "The inputs to the Executor: Quantum Programs\n", + "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n", "\n", - "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", - "metadata": {}, - "source": [ - "## Overview of primitive outputs\n", - "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", - "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", - "\n", - "\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", - " \n", - " ```\n", - " └── PrimitiveResult\n", - " ├── PubResult[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", - " ├── PubResult[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", - "\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", - "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", - "\n", - "### Estimator output\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", - "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", - "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", - " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", - " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", - " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", - " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", - " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", - " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", - " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", - " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", - " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", - " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", - " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", - " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", - " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", - " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", - " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", - " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", - " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", - " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", - " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", - " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", - " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", - " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", - " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", - " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", - " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", - " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", - " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", - " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", - " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", - " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", - " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", - " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", - " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", - " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", - " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", - " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", - " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", - " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", - " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", - " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", - " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", - " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", - " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", - " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", - " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", - " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", - " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", - " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", - " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", - " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", - "print(\n", - " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", - "metadata": {}, - "source": [ - "#### 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": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", - "metadata": {}, - "source": [ - "### Sampler output\n", - "\n", - "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", - "\n", - "The `BitArray` class is a container for ordered shot data. In more detail, 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", - "\n", - "As a first example, let us look at the following ten-qubit circuit:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "5c787874-1125-4381-b55e-7663caa92ec8", - "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 254]\n", - " [ 0 0]\n", - " [ 3 255]\n", - " ...\n", - " [ 0 0]\n", - " [ 3 255]\n", - " [ 0 0]]\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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", - "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": 5, - "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", - "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": 6, - "id": "4602925e-c69d-45b2-9e06-fe8bffe0a797", - "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": "a65c6078-c5c2-4087-b57a-5680148ce333", - "metadata": {}, - "source": [ - "#### Leveraging `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": 7, - "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", - "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", - " [1]\n", - " [1]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [1]]\n", - "\n", - "The shape of register `beta` is (4096, 2).\n", - "The bytes in register `beta`, shot by shot:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " ...\n", - " [ 0 0]\n", - " [ 1 224]\n", - " [ 1 255]]\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", - " [7]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [7]]\n", - "\n", - "The shape of `beta` after shot-wise slicing is (5, 2).\n", - "The bytes in `beta` after shot-wise slicing:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " [ 1 128]\n", - " [ 1 255]]\n", - "\n", - "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", - " coeffs=[1.+0.j])` is: 0.068359375\n", - "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", - " coeffs=[1.+0.j])` is: 0.06396484375\n", - "\n", - "The shape of the merged results is (4096, 2).\n", - "The bytes of the merged results:\n", - "[[ 1 15]\n", - " [ 1 239]\n", - " [ 3 239]\n", - " ...\n", - " [ 0 0]\n", - " [ 3 192]\n", - " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", - "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": 8, - "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", - "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": "2f26ff75-e1ba-45ef-97c1-c5dde36400cf", - "metadata": {}, - "source": [ - "For Sampler jobs, you can also review the result metadata to understand when certain data was run; this is called the [_execution span._](monitor-job#execution-spans)" + "A :class:`~.QuantumProgram` is an iterable of\n", + ":class:`~.qiskit_ibm_runtime.quantum_program.QuantumProgramItem`\\s. Each of these items represents a\n", + "different task for the :class:`~.Executor` to perform. Typically, each item owns:\n", + "\n", + "* a :class:`~qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n", + "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n", + "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with a\n", + " :class:`~samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n", + "\n", + "Let us take a closer look at each of these items and how to add them to a :class:`~.QuantumProgram`\\.\n", + "\n", + "In the cell below, we initialize a :class:`~.QuantumProgram` and specify that we wish to perform ``1024``\n", + "shots for every configuration of each item in the program. Next, we append a version of our target circuit with set parameters,\n", + "transpiled according to the backend's ISA.\n", + "\n", + ".. code-block:: python\n", + "\n", + " from qiskit.transpiler import generate_preset_pass_manager\n", + " from qiskit_ibm_runtime.quantum_program import QuantumProgram\n", + "\n", + " # Initialize an empty program\n", + " program = QuantumProgram(shots=1024)\n", + "\n", + " # Initialize circuit to generate and measure GHZ state\n", + " circuit = QuantumCircuit(3)\n", + " circuit.h(0)\n", + " circuit.h(1)\n", + " circuit.cz(0, 1)\n", + " circuit.h(1)\n", + " circuit.h(2)\n", + " circuit.cz(1, 2)\n", + " circuit.h(2)\n", + " circuit.rz(0.1, 0)\n", + " circuit.rz(0.2, 1)\n", + " circuit.rz(0.3, 2)\n", + " circuit.measure_all()\n", + "\n", + " # Transpile the circuit\n", + " preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + " isa_circuit = preset_pass_manager.run(circuit)\n", + "\n", + " # Append the circuit to the program\n", + " program.append_circuit_item(isa_circuit)\n", + "\n", + "We proceed to append a second item that contains a parametrized :class:`~qiskit.circuit.QuantumCircuit`\n", + "and an array containing ``10`` sets of parameter values. This amounts to a circuit task requiring a total\n", + "of ``10240`` shots (namely ``1024`` per set of parameter values).\n", + "\n", + ".. code-block:: python\n", + "\n", + " from qiskit.circuit import Parameter\n", + " import numpy as np\n", + "\n", + " # Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", + " # axis, and measure it\n", + " circuit = QuantumCircuit(3)\n", + " circuit.h(0)\n", + " circuit.h(1)\n", + " circuit.cz(0, 1)\n", + " circuit.h(1)\n", + " circuit.h(2)\n", + " circuit.cz(1, 2)\n", + " circuit.h(2)\n", + " circuit.rz(Parameter(\"theta\"), 0)\n", + " circuit.rz(Parameter(\"phi\"), 1)\n", + " circuit.rz(Parameter(\"lam\"), 2)\n", + " circuit.measure_all()\n", + "\n", + " # Transpile the circuit\n", + " isa_circuit = preset_pass_manager.run(circuit)\n", + "\n", + " # Append the circuit and the parameter value to the program\n", + " program.append_circuit_item(\n", + " isa_circuit,\n", + " circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values\n", + " )\n", + "\n", + "Finally, in the next cell we append a parametrized :class:`~qiskit.circuit.QuantumCircuit` and a\n", + ":class:`~samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n", + "parameters for the given circuit. As part of the :class:`~samplomatic.samplex.Samplex` arguments,\n", + "we provide ``10`` sets of parameters for the parametric gates in the original circuit.\n", + "Additionally, we use the ``shape`` request argument to request an extension of the implicit shape\n", + "defined by the :class:`~samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", + "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and\n", + "to arrange the randomized parameter sets in an array of be arranged in an array of shape\n", + "``(2, 14, 10)``.\n", + "\n", + " We refer the reader to :mod:`~samplomatic` and its documentation for more details on the\n", + " :class:`~samplomatic.samplex.Samplex` and its arguments.\n", + "\n", + ".. code-block:: python\n", + "\n", + " from samplomatic import build\n", + " from samplomatic.transpiler import generate_boxing_pass_manager\n", + "\n", + " # Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", + " # axis, and measure it\n", + " circuit = QuantumCircuit(3)\n", + " circuit.h(0)\n", + " circuit.h(1)\n", + " circuit.cz(0, 1)\n", + " circuit.h(1)\n", + " circuit.h(2)\n", + " circuit.cz(1, 2)\n", + " circuit.h(2)\n", + " circuit.rz(Parameter(\"theta\"), 0)\n", + " circuit.rz(Parameter(\"phi\"), 1)\n", + " circuit.rz(Parameter(\"lam\"), 2)\n", + " circuit.measure_all()\n", + "\n", + " # Transpile the circuit, additionally grouping gates and measurements into annotated boxes\n", + " preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + " preset_pass_manager.post_scheduling = generate_boxing_pass_manager(\n", + " enable_gates=True,\n", + " enable_measures=True,\n", + " )\n", + " boxed_circuit = preset_pass_manager.run(circuit)\n", + "\n", + " # Build the template and the samplex\n", + " template, samplex = build(boxed_circuit)\n", + "\n", + " # Append the template and samplex as a samplex item\n", + " program.append_samplex_item(\n", + " template,\n", + " samplex=samplex,\n", + " samplex_arguments={ \n", + " # the arguments required by the samplex.sample method\n", + " \"parameter_values\": np.random.rand(10, 3),\n", + " },\n", + " shape=(2, 14, 10),\n", + " )\n", + "\n", + "Now that we have populated our :class:`~.QuantumProgram`, we can proceed with execution." ] } ], diff --git a/docs/guides/sampler-examples.ipynb b/docs/guides/sampler-examples.ipynb index ca77579f111..c290106594f 100644 --- a/docs/guides/sampler-examples.ipynb +++ b/docs/guides/sampler-examples.ipynb @@ -7,7 +7,7 @@ "source": [ "---\n", "title: Examples\n", - "description: Practical examples of using the Sampler primitives in Qiskit Runtime.\n", + "description: Practical examples of using the Sampler primitive in Qiskit Runtime.\n", "---\n", "\n", "\n", From e85bdd4eb661935e0eb4565c537cb8052edb5d68 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 10 Feb 2026 16:47:51 -0600 Subject: [PATCH 032/118] More updates --- docs/guides/_toc.json | 4 + docs/guides/directed-execution-model.mdx | 2 +- docs/guides/estimator-input-output.ipynb | 311 +---------------------- docs/guides/executor-input-output.ipynb | 42 ++- docs/guides/primitives.ipynb | 21 +- docs/guides/pubs.ipynb | 203 +++++++++++++++ docs/guides/sampler-input-output.ipynb | 284 +-------------------- 7 files changed, 257 insertions(+), 610 deletions(-) create mode 100644 docs/guides/pubs.ipynb diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 9c5b0172d5b..d78a2d39034 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -347,6 +347,10 @@ "title": "Introduction to primitives", "url": "/docs/guides/primitives" }, + { + "title": "Introduction to PUBs", + "url": "/docs/guides/ppubs" + }, { "title": "Estimator", "children": [ diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index 2fe2161001d..2d99cc6d45c 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -52,7 +52,7 @@ To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/sam 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. -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. +The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) 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. ### NoiseLearnerV3 diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index c90e4008915..6cef30217e6 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -6,24 +6,14 @@ "metadata": {}, "source": [ "---\n", - "title: Estimator inputs and outputs\n", - "description: Understand the Estimator input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "title: Inputs and outputs\n", + "description: Understand the Estimator input and output format of Estimator primitives\n", "---\n", "\n", "\n", "# Estimator inputs and outputs" ] }, - { - "cell_type": "markdown", - "id": "33c719ad", - "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", @@ -58,21 +48,16 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." ] }, { "cell_type": "markdown", - "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", "metadata": {}, "source": [ - "\n", - "## Overview of PUBs\n", - "\n", - "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "## Estimator inputs\n", "\n", - "### Estimator PUB\n", - "For the Estimator primitive, the format of the PUB should contain at most four values:\n", + "The inputs to the Estimator primitive are [PUBs.](/docs/guides/pubs) For the Estimator primitive, the format of the PUB should 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", @@ -84,7 +69,6 @@ }, { "cell_type": "markdown", - "id": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", "metadata": {}, "source": [ "---\n", @@ -95,7 +79,6 @@ { "cell_type": "code", "execution_count": null, - "id": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", "metadata": {}, "outputs": [], "source": [ @@ -172,137 +155,12 @@ "result = job.result()" ] }, - { - "cell_type": "markdown", - "id": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "### 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", - "\n", - "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, { "cell_type": "markdown", "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", "metadata": {}, "source": [ - "## Overview of primitive outputs\n", + "## Overview of Estimator outputs\n", "\n", "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator.\n", "\n", @@ -462,163 +320,6 @@ "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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", - "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": 5, - "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", - "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": "markdown", - "id": "a65c6078-c5c2-4087-b57a-5680148ce333", - "metadata": {}, - "source": [ - "#### Leveraging `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": 7, - "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", - "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", - " [1]\n", - " [1]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [1]]\n", - "\n", - "The shape of register `beta` is (4096, 2).\n", - "The bytes in register `beta`, shot by shot:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " ...\n", - " [ 0 0]\n", - " [ 1 224]\n", - " [ 1 255]]\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", - " [7]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [7]]\n", - "\n", - "The shape of `beta` after shot-wise slicing is (5, 2).\n", - "The bytes in `beta` after shot-wise slicing:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " [ 1 128]\n", - " [ 1 255]]\n", - "\n", - "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", - " coeffs=[1.+0.j])` is: 0.068359375\n", - "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", - " coeffs=[1.+0.j])` is: 0.06396484375\n", - "\n", - "The shape of the merged results is (4096, 2).\n", - "The bytes of the merged results:\n", - "[[ 1 15]\n", - " [ 1 239]\n", - " [ 3 239]\n", - " ...\n", - " [ 0 0]\n", - " [ 3 192]\n", - " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb index 8c1109c50a7..e58e01254c7 100644 --- a/docs/guides/executor-input-output.ipynb +++ b/docs/guides/executor-input-output.ipynb @@ -7,7 +7,7 @@ "source": [ "---\n", "title: Inputs and outputs\n", - "description: Understand the inputs and outputs to the Executor primitive\n", + "description: Understand the inputs and outputs to the Executor primitive.\n", "---\n", "\n", "\n", @@ -45,31 +45,29 @@ }, { "cell_type": "markdown", - "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Sampler and Estimator primitives, which execute 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 Sampler or Estimator primitives." + "The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The inputs to the Executor: Quantum Programs\n", - "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n", + "## Quantum programs\n", "\n", - "A :class:`~.QuantumProgram` is an iterable of\n", - ":class:`~.qiskit_ibm_runtime.quantum_program.QuantumProgramItem`\\s. Each of these items represents a\n", - "different task for the :class:`~.Executor` to perform. Typically, each item owns:\n", + "The input to Executor primitives is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a \n", + "`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`. Each of these items represents a\n", + "different task for the Executor to perform. Typically, each item owns:\n", "\n", - "* a :class:`~qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n", - "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n", - "* or a parametrized :class:`~qiskit.circuit.QuantumCircuit`, together with a\n", - " :class:`~samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n", + "* a `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n", + "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n", + "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with a\n", + " `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n", "\n", - "Let us take a closer look at each of these items and how to add them to a :class:`~.QuantumProgram`\\.\n", + "Let us take a closer look at each of these items and how to add them to a `QuantumProgram`\\.\n", "\n", - "In the cell below, we initialize a :class:`~.QuantumProgram` and specify that we wish to perform ``1024``\n", + "In the cell below, we initialize a `QuantumProgram` and specify that we wish to perform ``1024``\n", "shots for every configuration of each item in the program. Next, we append a version of our target circuit with set parameters,\n", "transpiled according to the backend's ISA.\n", "\n", @@ -102,7 +100,7 @@ " # Append the circuit to the program\n", " program.append_circuit_item(isa_circuit)\n", "\n", - "We proceed to append a second item that contains a parametrized :class:`~qiskit.circuit.QuantumCircuit`\n", + "We proceed to append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit`\n", "and an array containing ``10`` sets of parameter values. This amounts to a circuit task requiring a total\n", "of ``10240`` shots (namely ``1024`` per set of parameter values).\n", "\n", @@ -135,18 +133,18 @@ " circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values\n", " )\n", "\n", - "Finally, in the next cell we append a parametrized :class:`~qiskit.circuit.QuantumCircuit` and a\n", - ":class:`~samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n", - "parameters for the given circuit. As part of the :class:`~samplomatic.samplex.Samplex` arguments,\n", + "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a\n", + "`samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n", + "parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n", "we provide ``10`` sets of parameters for the parametric gates in the original circuit.\n", "Additionally, we use the ``shape`` request argument to request an extension of the implicit shape\n", - "defined by the :class:`~samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", + "defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and\n", "to arrange the randomized parameter sets in an array of be arranged in an array of shape\n", "``(2, 14, 10)``.\n", "\n", - " We refer the reader to :mod:`~samplomatic` and its documentation for more details on the\n", - " :class:`~samplomatic.samplex.Samplex` and its arguments.\n", + " We refer the reader to :mod`~samplomatic` and its documentation for more details on the\n", + " `samplomatic.samplex.Samplex` and its arguments.\n", "\n", ".. code-block:: python\n", "\n", @@ -190,7 +188,7 @@ " shape=(2, 14, 10),\n", " )\n", "\n", - "Now that we have populated our :class:`~.QuantumProgram`, we can proceed with execution." + "Now that we have populated our `QuantumProgram`, we can proceed with execution." ] } ], diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 033f9cc5333..7052cee60c0 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -49,7 +49,7 @@ "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", + "The beta release of a new execution model ([Directed execution model](/docs/guides/directed-execution-model)) is now available. This model provides more flexibility when customizing your error mitigation workflow. The [Executor primitive](#executor) is part of this model, but is very different from the Estimator and Sampler primatives. Most of the information in this topic applies to those primitives.\n", "\n", "\n", "\n", @@ -264,6 +264,18 @@ ")" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "### Executor (beta)\n", + "\n", + "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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model.mdx)\n", + "\n", + "The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) for more information." + ] + }, { "cell_type": "markdown", "id": "02dbbc7d-76e7-4a89-8739-ba7f3a5a05b8", @@ -272,11 +284,10 @@ "## Next steps\n", "\n", "\n", - " - Read [Get started with primitives](get-started-with-primitives) to implement primitives in your work.\n", - " - Review detailed [primitives examples.](primitives-examples)\n", + " - Read [Get started with Estimator,](get-started-with-estimator) [Get started with Sampler,](get-started-with-sampler) and [Get started with Executor,](get-started-with-executor) to implement primitives in your work.\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", - " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", + " - See the [EstimatorV2 API reference](/docs/api/qiskit-ibm-runtime/estimator-v2), [SamplerV2 API reference](/docs/api/qiskit-ibm-runtime/sampler-v2), and [Executor API reference.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.Executor.html)\n", + " - Read [Migrate to V2 primitives.](/docs/guides/v2-primitives)\n", "" ] } diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb new file mode 100644 index 00000000000..9f2668b8581 --- /dev/null +++ b/docs/guides/pubs.ipynb @@ -0,0 +1,203 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "dbb193c8-d927-434c-a199-48de57c99694", + "metadata": {}, + "source": [ + "---\n", + "title: Introduction to PUBs\n", + "description: Understand what Primitive Unified Blocs are, and how to use them as input to Sampler and Estimator primitives.\n", + "---\n", + "\n", + "\n", + "# Introduction to Primitive Unified Blocs" + ] + }, + { + "cell_type": "markdown", + "id": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", + "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": "61903cfe-d221-4137-8324-9f0d3c1b517d", + "metadata": {}, + "source": [ + "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "92e5f627-e4e9-433b-8fce-e25dff68bdef", + "metadata": {}, + "source": [ + "### 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", + "\n", + "Rules:\n", + "\n", + "* Input arrays do not need to have the same number of dimensions.\n", + " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", + " * The size of each dimension is the largest size of the corresponding dimension.\n", + " * Missing dimensions are assumed to have size one.\n", + "* Shape comparisons start with the rightmost dimension and continue to the left.\n", + "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", + "\n", + "Examples of array pairs that broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 1\n", + "A2 (2d array): 3 x 5\n", + "Result (2d array): 3 x 5\n", + "\n", + "\n", + "A1 (3d array): 11 x 2 x 7\n", + "A2 (3d array): 11 x 1 x 7\n", + "Result (3d array): 11 x 2 x 7\n", + "```\n", + "\n", + "Examples of array pairs that do not broadcast:\n", + "\n", + "```text\n", + "A1 (1d array): 5\n", + "A2 (1d array): 3\n", + "\n", + "A1 (2d array): 2 x 1\n", + "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", + "```\n", + "\n", + "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", + "\n", + "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", + "\n", + "\n", + "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", + "\n", + " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", + "\n", + " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", + "\n", + " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", + "\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\")" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", + "metadata": {}, + "outputs": [], + "source": [ + "# Broadcast single observable\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Zip\n", + "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", + "observables = [\n", + " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", + "] # shape (5,)\n", + "# >> pub result has shape (5,)\n", + "\n", + "# Outer/Product\n", + "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", + "observables = [\n", + " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", + "] # shape (4, 1)\n", + "# >> pub result has shape (4, 6)\n", + "\n", + "# Standard nd generalization\n", + "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", + "observables = [\n", + " [\n", + " [SparsePauliOp([\"XII\"])],\n", + " [SparsePauliOp([\"IXI\"])],\n", + " [SparsePauliOp([\"IIX\"])],\n", + " ],\n", + " [\n", + " [SparsePauliOp([\"ZII\"])],\n", + " [SparsePauliOp([\"IZI\"])],\n", + " [SparsePauliOp([\"IIZ\"])],\n", + " ],\n", + "] # shape (2, 3, 1)\n", + "# >> pub result has shape (2, 3, 6)" + ] + }, + { + "cell_type": "markdown", + "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", + "metadata": {}, + "source": [ + "\n", + "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", + "\n", + "```text\n", + "a = SparsePauliOp(\"Z\") # shape ()\n", + "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", + "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "```\n", + "\n", + "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", + "\n", + "```text\n", + "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", + "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", + "```\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-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index fa8b0f3d12f..d8a110180ae 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -6,22 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Primitive inputs and outputs\n", - "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", + "title: Inputs and outputs\n", + "description: Understand the input and output format of Sampler primitives\n", "---\n", "\n", "\n", - "# Primitive inputs and outputs" - ] - }, - { - "cell_type": "markdown", - "id": "33c719ad", - "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", - "" + "# Sampler inputs and outputs" ] }, { @@ -58,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the Sampler primitive, which execute 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 Sampler primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." ] }, { @@ -66,281 +56,21 @@ "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", "metadata": {}, "source": [ - "\n", - "## Overview of PUBs\n", - "\n", - "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", + "## Input\n", "\n", - "### Sampler PUB\n", - "For the Sampler primitive, the format of the PUB tuple contains at most three values:\n", + "The input to the Sampler primitive is a [PUB](/docs/guides/pubs) tuple that contains 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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "### 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", - "metadata": {}, - "source": [ - "## Overview of primitive outputs\n", - "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", - "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", - "\n", - " ```\n", - " └── PrimitiveResult\n", - " ├── PubResult[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", - " ├── PubResult[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` 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", - "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\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": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", - "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", - " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", - " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", - " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", - " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", - " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", - " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", - " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", - " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", - " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", - " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", - " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", - " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", - " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", - " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", - " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", - " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", - " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", - " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", - " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", - " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", - " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", - " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", - " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", - " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", - " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", - " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", - " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", - " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", - " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", - " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", - " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", - " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", - " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", - " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", - " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", - " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", - " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", - " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", - " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", - " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", - " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", - " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", - " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", - " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", - " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", - " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", - " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", - " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", - " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", - " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", - "print(\n", - " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", - ")" - ] - }, { "cell_type": "markdown", "id": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", "metadata": {}, "source": [ - "### Sampler output\n", + "## Output\n", "\n", "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", "\n", From 2b0062b61de2f8c7b94fff28b59d0c539bac2794 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 10:24:49 -0600 Subject: [PATCH 033/118] Add titles to allowlists --- docs/guides/executor-input-output.ipynb | 280 +++++++++++++----------- scripts/config/allowLists.ts | 12 + 2 files changed, 163 insertions(+), 129 deletions(-) diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb index e58e01254c7..1b924ac4fec 100644 --- a/docs/guides/executor-input-output.ipynb +++ b/docs/guides/executor-input-output.ipynb @@ -56,137 +56,159 @@ "source": [ "## Quantum programs\n", "\n", - "The input to Executor primitives is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a \n", - "`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`. Each of these items represents a\n", - "different task for the Executor to perform. Typically, each item owns:\n", - "\n", - "* a `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates;\n", - "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with an array of parameter values;\n", - "* or a parametrized `qiskit.circuit.QuantumCircuit`, together with a\n", - " `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values.\n", - "\n", - "Let us take a closer look at each of these items and how to add them to a `QuantumProgram`\\.\n", - "\n", - "In the cell below, we initialize a `QuantumProgram` and specify that we wish to perform ``1024``\n", - "shots for every configuration of each item in the program. Next, we append a version of our target circuit with set parameters,\n", - "transpiled according to the backend's ISA.\n", - "\n", - ".. code-block:: python\n", - "\n", - " from qiskit.transpiler import generate_preset_pass_manager\n", - " from qiskit_ibm_runtime.quantum_program import QuantumProgram\n", - "\n", - " # Initialize an empty program\n", - " program = QuantumProgram(shots=1024)\n", - "\n", - " # Initialize circuit to generate and measure GHZ state\n", - " circuit = QuantumCircuit(3)\n", - " circuit.h(0)\n", - " circuit.h(1)\n", - " circuit.cz(0, 1)\n", - " circuit.h(1)\n", - " circuit.h(2)\n", - " circuit.cz(1, 2)\n", - " circuit.h(2)\n", - " circuit.rz(0.1, 0)\n", - " circuit.rz(0.2, 1)\n", - " circuit.rz(0.3, 2)\n", - " circuit.measure_all()\n", - "\n", - " # Transpile the circuit\n", - " preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", - " isa_circuit = preset_pass_manager.run(circuit)\n", - "\n", - " # Append the circuit to the program\n", - " program.append_circuit_item(isa_circuit)\n", - "\n", - "We proceed to append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit`\n", - "and an array containing ``10`` sets of parameter values. This amounts to a circuit task requiring a total\n", - "of ``10240`` shots (namely ``1024`` per set of parameter values).\n", - "\n", - ".. code-block:: python\n", - "\n", - " from qiskit.circuit import Parameter\n", - " import numpy as np\n", - "\n", - " # Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", - " # axis, and measure it\n", - " circuit = QuantumCircuit(3)\n", - " circuit.h(0)\n", - " circuit.h(1)\n", - " circuit.cz(0, 1)\n", - " circuit.h(1)\n", - " circuit.h(2)\n", - " circuit.cz(1, 2)\n", - " circuit.h(2)\n", - " circuit.rz(Parameter(\"theta\"), 0)\n", - " circuit.rz(Parameter(\"phi\"), 1)\n", - " circuit.rz(Parameter(\"lam\"), 2)\n", - " circuit.measure_all()\n", - "\n", - " # Transpile the circuit\n", - " isa_circuit = preset_pass_manager.run(circuit)\n", - "\n", - " # Append the circuit and the parameter value to the program\n", - " program.append_circuit_item(\n", - " isa_circuit,\n", - " circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values\n", - " )\n", - "\n", - "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a\n", - "`samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of\n", - "parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n", - "we provide ``10`` sets of parameters for the parametric gates in the original circuit.\n", - "Additionally, we use the ``shape`` request argument to request an extension of the implicit shape\n", - "defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", - "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and\n", - "to arrange the randomized parameter sets in an array of be arranged in an array of shape\n", - "``(2, 14, 10)``.\n", + "The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a \n", + "[`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a\n", + "different task for the Executor to perform. Typically, each item owns one of the following options:\n", + "\n", + "* A `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates\n", + "* A parametrized `qiskit.circuit.QuantumCircuit` with an array of parameter values\n", + "* A parametrized `qiskit.circuit.QuantumCircuit` with a `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values\n", + "\n", + "Each of these items, including instructions to add them to a `QuantumProgram` is explained in more detail below.\n", + "\n", + "The following cell initializes a `QuantumProgram` and specifies to perform 1024 shots for every configuration of each item in the program. Then a version of the target circuit with set parameters, transpiled according to the backend's ISA, is appended." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.transpiler import generate_preset_pass_manager\n", + "from qiskit_ibm_runtime.quantum_program import QuantumProgram\n", + "\n", + "# Initialize an empty program\n", + "program = QuantumProgram(shots=1024)\n", + "\n", + "# Initialize circuit to generate and measure GHZ state\n", + "circuit = QuantumCircuit(3)\n", + "circuit.h(0)\n", + "circuit.h(1)\n", + "circuit.cz(0, 1)\n", + "circuit.h(1)\n", + "circuit.h(2)\n", + "circuit.cz(1, 2)\n", + "circuit.h(2)\n", + "circuit.rz(0.1, 0)\n", + "circuit.rz(0.2, 1)\n", + "circuit.rz(0.3, 2)\n", + "circuit.measure_all()\n", + "\n", + "# Transpile the circuit\n", + "preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + "isa_circuit = preset_pass_manager.run(circuit)\n", + "\n", + "# Append the circuit to the program\n", + "program.append_circuit_item(isa_circuit)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (namely 1024 per set of parameter values).\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit.circuit import Parameter\n", + "import numpy as np\n", + "\n", + "# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", + "# axis, and measure it\n", + "circuit = QuantumCircuit(3)\n", + "circuit.h(0)\n", + "circuit.h(1)\n", + "circuit.cz(0, 1)\n", + "circuit.h(1)\n", + "circuit.h(2)\n", + "circuit.cz(1, 2)\n", + "circuit.h(2)\n", + "circuit.rz(Parameter(\"theta\"), 0)\n", + "circuit.rz(Parameter(\"phi\"), 1)\n", + "circuit.rz(Parameter(\"lam\"), 2)\n", + "circuit.measure_all()\n", + "\n", + "# Transpile the circuit\n", + "isa_circuit = preset_pass_manager.run(circuit)\n", + "\n", + "# Append the circuit and the parameter value to the program\n", + "program.append_circuit_item(\n", + " isa_circuit,\n", + " circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n", + "we provide ``10`` sets of parameters for the parametric gates in the original circuit. Additionally, we use the ``shape`` request argument to request an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", + "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape ``(2, 14, 10)``.\n", "\n", " We refer the reader to :mod`~samplomatic` and its documentation for more details on the\n", - " `samplomatic.samplex.Samplex` and its arguments.\n", - "\n", - ".. code-block:: python\n", - "\n", - " from samplomatic import build\n", - " from samplomatic.transpiler import generate_boxing_pass_manager\n", - "\n", - " # Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", - " # axis, and measure it\n", - " circuit = QuantumCircuit(3)\n", - " circuit.h(0)\n", - " circuit.h(1)\n", - " circuit.cz(0, 1)\n", - " circuit.h(1)\n", - " circuit.h(2)\n", - " circuit.cz(1, 2)\n", - " circuit.h(2)\n", - " circuit.rz(Parameter(\"theta\"), 0)\n", - " circuit.rz(Parameter(\"phi\"), 1)\n", - " circuit.rz(Parameter(\"lam\"), 2)\n", - " circuit.measure_all()\n", - "\n", - " # Transpile the circuit, additionally grouping gates and measurements into annotated boxes\n", - " preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", - " preset_pass_manager.post_scheduling = generate_boxing_pass_manager(\n", - " enable_gates=True,\n", - " enable_measures=True,\n", - " )\n", - " boxed_circuit = preset_pass_manager.run(circuit)\n", - "\n", - " # Build the template and the samplex\n", - " template, samplex = build(boxed_circuit)\n", - "\n", - " # Append the template and samplex as a samplex item\n", - " program.append_samplex_item(\n", - " template,\n", - " samplex=samplex,\n", - " samplex_arguments={ \n", - " # the arguments required by the samplex.sample method\n", - " \"parameter_values\": np.random.rand(10, 3),\n", - " },\n", - " shape=(2, 14, 10),\n", - " )\n", + " `samplomatic.samplex.Samplex` and its arguments.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from samplomatic import build\n", + "from samplomatic.transpiler import generate_boxing_pass_manager\n", + "\n", + "# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", + "# axis, and measure it\n", + "circuit = QuantumCircuit(3)\n", + "circuit.h(0)\n", + "circuit.h(1)\n", + "circuit.cz(0, 1)\n", + "circuit.h(1)\n", + "circuit.h(2)\n", + "circuit.cz(1, 2)\n", + "circuit.h(2)\n", + "circuit.rz(Parameter(\"theta\"), 0)\n", + "circuit.rz(Parameter(\"phi\"), 1)\n", + "circuit.rz(Parameter(\"lam\"), 2)\n", + "circuit.measure_all()\n", + "\n", + "# Transpile the circuit, additionally grouping gates and measurements into annotated boxes\n", + "preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + "preset_pass_manager.post_scheduling = generate_boxing_pass_manager(\n", + " enable_gates=True,\n", + " enable_measures=True,\n", + ")\n", + "boxed_circuit = preset_pass_manager.run(circuit)\n", + "\n", + "# Build the template and the samplex\n", + "template, samplex = build(boxed_circuit)\n", + "\n", + "# Append the template and samplex as a samplex item\n", + "program.append_samplex_item(\n", + " template,\n", + " samplex=samplex,\n", + " samplex_arguments={ \n", + " # the arguments required by the samplex.sample method\n", + " \"parameter_values\": np.random.rand(10, 3),\n", + " },\n", + " shape=(2, 14, 10),\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ "\n", "Now that we have populated our `QuantumProgram`, we can proceed with execution." ] diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index d32df5572a5..5fa22ba6099 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -22,6 +22,18 @@ 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/executor-examples.ipynb", + "docs/guides/executor-input-output.ipynb", + "docs/guides/get-started-with-sampler.ipynb", + "docs/guides/pubs.ipynb", + "docs/guides/sampler-examples.ipynb", + "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", From 40c9339e46b2e4b49ed97ab0994293d07f8d7772 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Wed, 11 Feb 2026 11:48:00 -0500 Subject: [PATCH 034/118] remove temporary table --- docs/guides/addons.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/guides/addons.mdx b/docs/guides/addons.mdx index 258536fbf93..06c0bd83acd 100644 --- a/docs/guides/addons.mdx +++ b/docs/guides/addons.mdx @@ -9,15 +9,6 @@ description: Understand the Qiskit addon tools, which help you build utility-gra Qiskit addons are a collection of research capabilities for enabling algorithm discovery at the utility scale. These modular software components can plug into a [workflow](/docs/guides/intro-to-patterns) to scale or design new quantum algorithms. Many of these addons are powered by the `qiskit-addon-utils` package. See the [Qiskit addon utilities documentation](https://qiskit.github.io/qiskit-addon-utils/) for more information. -This table lists Qiskit addons with their research capabilities. A description of each addon follows the table. - -| Capability | | -| --- | --- | -| Map | [AQC-Tensor](https://qiskit.github.io/qiskit-addon-aqc-tensor/), [Multi-product formulas](https://qiskit.github.io/qiskit-addon-mpf/), [Optimization Mapper](https://qiskit.github.io/qiskit-addon-opt-mapper/) | -| Optimize | [Operator backpropagation](https://qiskit.github.io/qiskit-addon-obp/), [Circuit cutting](https://qiskit.github.io/qiskit-addon-cutting) | -| Error mitigation | [Matrix-free Measurement Mitigation](https://qiskit.github.io/qiskit-addon-mpf/), [Shaded lightcones](https://qiskit.github.io/qiskit-addon-slc/), [Propagated noise absorption](https://qiskit.github.io/qiskit-addon-pna/) | -| Post-process | [Sample-based quantum diagonalization](/docs/guides/qiskit-addons-sqd-get-started), [SQD for HPC](https://qiskit.github.io/qiskit-addon-sqd-hpc/), [Dice eigensolver](https://qiskit.github.io/qiskit-addon-dice-solver/) | - Date: Wed, 11 Feb 2026 12:41:14 -0600 Subject: [PATCH 035/118] spelling --- docs/guides/executor-examples.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/executor-examples.ipynb b/docs/guides/executor-examples.ipynb index e7bcdaab00a..390bfdb6b04 100644 --- a/docs/guides/executor-examples.ipynb +++ b/docs/guides/executor-examples.ipynb @@ -7,7 +7,7 @@ "source": [ "---\n", "title: Examples\n", - "description: Practical examples of using the Executor primitve in Qiskit Runtime.\n", + "description: Practical examples of using the Executor primitive in Qiskit Runtime.\n", "---\n", "\n", "\n", From 1fd3f361a70a9be065c47b5f1d9bfad0496a8aea Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 12:51:43 -0600 Subject: [PATCH 036/118] Update qiskit_bot.yaml --- qiskit_bot.yaml | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index be7629a2cab..228bd24c310 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -143,6 +143,50 @@ notifications: - "@frankharkins" - "@abbycross" - "`@mtreinish`" + "docs/guides/estimator-examples.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/estimator-input-output.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/estimator-options.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/executor-examples.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/executor-input-output.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/get-started-with-sampler.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/pubs.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-examples.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-input-output.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/sampler-options.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" + "docs/guides/get-started-with-estimator.ipynb": + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/get-started-with-primitives": - "@ElePT" - "@jyu00" From 9d1f115d893209c7f3c1ad4fadff0025fe3c95a7 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 13:05:15 -0600 Subject: [PATCH 037/118] Update qiskit_bot.yaml --- qiskit_bot.yaml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 228bd24c310..0f9512a5d43 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -143,47 +143,47 @@ notifications: - "@frankharkins" - "@abbycross" - "`@mtreinish`" - "docs/guides/estimator-examples.ipynb": + "docs/guides/estimator-examples": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/estimator-input-output.ipynb": + "docs/guides/estimator-input-output": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/estimator-options.ipynb": + "docs/guides/estimator-options": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/executor-examples.ipynb": + "docs/guides/executor-examples": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/executor-input-output.ipynb": + "docs/guides/executor-input-output": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/get-started-with-sampler.ipynb": + "docs/guides/get-started-with-sampler": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/pubs.ipynb": + "docs/guides/pubs": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/sampler-examples.ipynb": + "docs/guides/sampler-examples": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/sampler-input-output.ipynb": + "docs/guides/sampler-input-output": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/sampler-options.ipynb": + "docs/guides/sampler-options": - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/get-started-with-estimator.ipynb": + "docs/guides/get-started-with-estimator": - "@abbycross" - "@beckykd" - "@jyu00" From af56691e15c25d5ab05bfc14feff49f5c4f0a99f Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 13:19:53 -0600 Subject: [PATCH 038/118] no spaces in file names --- ...x => runtime-options-overview-estimator.mdx} | 0 ...mdx => runtime-options-overview-sampler.mdx} | 0 qiskit_bot.yaml | 17 +++++++++++++++++ 3 files changed, 17 insertions(+) rename docs/guides/{runtime-options-overview - estimator.mdx => runtime-options-overview-estimator.mdx} (100%) rename docs/guides/{runtime-options-overview - sampler.mdx => runtime-options-overview-sampler.mdx} (100%) diff --git a/docs/guides/runtime-options-overview - estimator.mdx b/docs/guides/runtime-options-overview-estimator.mdx similarity index 100% rename from docs/guides/runtime-options-overview - estimator.mdx rename to docs/guides/runtime-options-overview-estimator.mdx diff --git a/docs/guides/runtime-options-overview - sampler.mdx b/docs/guides/runtime-options-overview-sampler.mdx similarity index 100% rename from docs/guides/runtime-options-overview - sampler.mdx rename to docs/guides/runtime-options-overview-sampler.mdx diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 0f9512a5d43..bd5aca30785 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -131,6 +131,23 @@ notifications: - "abbycross" - "@jyu00" - "@beckykd" + "docs/guides/executor-options": + - "abbycross" + - "@jyu00" + - "@beckykd" + "docs/guides/get-started-with-executor": + - "abbycross" + - "@jyu00" + - "@beckykd" + "docs/guides/runtime-options-overview-estimator": + - "abbycross" + - "@jyu00" + - "@beckykd" + "docs/guides/runtime-options-overview-sampler": + - "abbycross" + - "@jyu00" + - "@beckykd" + "docs/guides/fair-share-scheduler": - "`@lerongil`" - "@jyu00" From 4eefc167a458837ed2e9ecab757829e2f809bd4e Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 13:50:09 -0600 Subject: [PATCH 039/118] fix links --- docs/guides/directed-execution-model.mdx | 2 +- docs/guides/primitives.ipynb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index 2d99cc6d45c..7c2b0e238d1 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -52,7 +52,7 @@ To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/sam 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. -The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) 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. +The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output) 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. ### NoiseLearnerV3 diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 7052cee60c0..92c9171c45b 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -271,9 +271,9 @@ "\n", "### Executor (beta)\n", "\n", - "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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model.mdx)\n", + "The Executor Qiskit Runtime primitive 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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model)\n", "\n", - "The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output.ipynb) for more information." + "The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output) for more information." ] }, { From 66c630e17a478f05e3f5aea0fb29b9f4de3153c4 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 11 Feb 2026 16:52:04 -0600 Subject: [PATCH 040/118] input and output --- docs/guides/estimator-input-output.ipynb | 7 +- docs/guides/get-started-with-estimator.ipynb | 16 +- docs/guides/get-started-with-primitives.ipynb | 550 ------------ docs/guides/get-started-with-sampler.ipynb | 17 +- docs/guides/primitive-input-output.ipynb | 846 ------------------ docs/guides/runtime-options-overview.mdx | 2 +- docs/guides/sampler-input-output.ipynb | 102 +++ 7 files changed, 115 insertions(+), 1425 deletions(-) delete mode 100644 docs/guides/get-started-with-primitives.ipynb delete mode 100644 docs/guides/primitive-input-output.ipynb diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 6cef30217e6..a8bfa449452 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -55,7 +55,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Estimator inputs\n", + "## Inputs\n", "\n", "The inputs to the Estimator primitive are [PUBs.](/docs/guides/pubs) For the Estimator primitive, the format of the PUB should contain at most four values:\n", "- A single `QuantumCircuit`, which may contain one or more [`Parameter`](/docs/api/qiskit/qiskit.circuit.Parameter) objects\n", @@ -160,7 +160,7 @@ "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", "metadata": {}, "source": [ - "## Overview of Estimator outputs\n", + "## Output\n", "\n", "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator.\n", "\n", @@ -197,9 +197,6 @@ "\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", - "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", - "\n", - "### Estimator output\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", diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index dff6624185f..51382bec60d 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -6,18 +6,13 @@ "metadata": {}, "source": [ "---\n", - "title: Get started with estimator\n", + "title: Get started\n", "description: How to use the Estimator primitive in Qiskit Runtime.\n", "---\n", "\n", "\n", "# Get started with the Estimator primitive\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", "" @@ -75,11 +70,10 @@ "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", + "## Steps to use the Estimator primitive\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", @@ -285,7 +279,7 @@ "metadata": {}, "source": [ "\n", - "## Get started with Estimator\n", + "## Get started with the Estimator backend primitive\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", @@ -300,7 +294,7 @@ "id": "9d78f323-1c58-4360-8880-59179c8a14b7", "metadata": {}, "source": [ - "### Example: BackendEstimator\n", + "### Example:\n", "\n", "```python\n", "from qiskit.primitives import BackendEstimatorV2\n", diff --git a/docs/guides/get-started-with-primitives.ipynb b/docs/guides/get-started-with-primitives.ipynb deleted file mode 100644 index fec408ad56e..00000000000 --- a/docs/guides/get-started-with-primitives.ipynb +++ /dev/null @@ -1,550 +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", - "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": "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_torino\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", - " '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', 3826), ('sx', 1601), ('cz', 968)])\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: d5k96c4jt3vs73ds5smg\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: 25.8930784649363\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', 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 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.](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: 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": "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.](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 index 670010d42f5..f29e1a6364d 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -6,17 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Get started with Sampler\n", + "title: Get started\n", "description: How to use the Sampler primitive 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", + "# Get started with the Sampler primitive\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", @@ -75,9 +70,7 @@ "id": "64e2e09f-8528-4088-897b-1529b451ab1e", "metadata": {}, "source": [ - "\n", - "## Get started with Sampler\n", - "\n", + "## Steps to use the Sampler primitive\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", @@ -239,7 +232,7 @@ "metadata": {}, "source": [ "\n", - "## Get started with Sampler\n", + "## Get started with the Sampler backend primitive\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", @@ -254,7 +247,7 @@ "id": "9d78f323-1c58-4360-8880-59179c8a14b7", "metadata": {}, "source": [ - "### Example: BackendSampler\n", + "### Example:\n", "\n", "```python\n", "from qiskit.primitives import BackendSamplerV2\n", diff --git a/docs/guides/primitive-input-output.ipynb b/docs/guides/primitive-input-output.ipynb deleted file mode 100644 index b5c24c629a2..00000000000 --- a/docs/guides/primitive-input-output.ipynb +++ /dev/null @@ -1,846 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "dbb193c8-d927-434c-a199-48de57c99694", - "metadata": {}, - "source": [ - "---\n", - "title: Primitive inputs and outputs\n", - "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", - "---\n", - "\n", - "\n", - "# Primitive inputs and outputs" - ] - }, - { - "cell_type": "markdown", - "id": "33c719ad", - "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", - "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": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", - "metadata": {}, - "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Sampler and Estimator primitives, which execute 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 Sampler or Estimator primitives." - ] - }, - { - "cell_type": "markdown", - "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", - "metadata": {}, - "source": [ - "\n", - "## Overview of PUBs\n", - "\n", - "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", - "\n", - "### Estimator PUB\n", - "For the Estimator primitive, the format of the PUB should 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", - " If you have two commuting observables in different PUBs but with the same circuit, they will not be estimated using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB. To ensure that commuting observables are estimated using the same measurement, they must be grouped 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\n", - "\n", - "### Sampler PUB\n", - "For the Sampler primitive, the format of the PUB tuple contains 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": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", - "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": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", - "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", - " EstimatorV2 as Estimator,\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", - "\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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "### 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", - "\n", - "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", - "metadata": {}, - "source": [ - "## Overview of primitive outputs\n", - "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", - "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", - "\n", - "\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", - " \n", - " ```\n", - " └── PrimitiveResult\n", - " ├── PubResult[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", - " ├── PubResult[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", - "\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", - "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", - "\n", - "### Estimator output\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", - "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", - "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.00948597 0.12163221 0.29100944 0.40535344 0.46625814 0.54716103\n", - " 0.57690846 0.59809047 0.5784682 0.50924868 0.4579837 0.40035644\n", - " 0.37174056 0.32887613 0.25850853 0.26396412 0.25852429 0.26074166\n", - " 0.29282485 0.34388535 0.37368314 0.43562138 0.46912323 0.51955146\n", - " 0.54430185 0.55467261 0.5162183 0.52744696 0.47261781 0.42613541\n", - " 0.35400013 0.33217125 0.29600426 0.27561903 0.25307754 0.25672088\n", - " 0.28783701 0.36612701 0.40433263 0.44428286 0.51028376 0.55034507\n", - " 0.55979913 0.57160124 0.54127534 0.49753533 0.42942659 0.32552331\n", - " 0.20215918 0.04303087 -0.08115732 -0.18473659 -0.34015892 -0.44489319\n", - " -0.49112115 -0.54588034 -0.60601287 -0.55869218 -0.53353861 -0.51628053\n", - " -0.44978534 -0.38090252 -0.32481576 -0.28832245 -0.27057547 -0.26542929\n", - " -0.27054473 -0.29367389 -0.31531828 -0.38462352 -0.40276794 -0.47168997\n", - " -0.48548191 -0.5382924 -0.52716406 -0.53277032 -0.50776933 -0.48512907\n", - " -0.44335198 -0.38756463 -0.34438156 -0.29199194 -0.2729216 -0.24602918\n", - " -0.23527174 -0.3019153 -0.35159518 -0.38303379 -0.42434541 -0.47743033\n", - " -0.54652609 -0.5877912 -0.59175701 -0.57386895 -0.56416812 -0.48022381\n", - " -0.3853372 -0.2639702 -0.12030502 0.02081148]\n", - " [ 0.00581765 0.0552677 0.15998546 0.20725389 0.25452232 0.34178711\n", - " 0.39196437 0.47050268 0.50031815 0.527952 0.57231161 0.64066903\n", - " 0.72429779 0.77011181 0.78174711 0.86610308 0.88646487 0.91337151\n", - " 0.94245978 0.98100173 0.97372966 1.00936279 1.01881647 1.0544496\n", - " 1.01954368 1.03699664 0.99845469 1.03845105 1.00936279 1.00354513\n", - " 0.95409508 0.95264067 0.91264431 0.91846196 0.8355604 0.80283611\n", - " 0.77956549 0.74102354 0.69520953 0.64575948 0.58976457 0.53231524\n", - " 0.43996 0.3956004 0.32069812 0.27706572 0.22470684 0.16653032\n", - " 0.07272066 -0.00218162 -0.05817653 -0.06253977 -0.15853104 -0.25015908\n", - " -0.28506499 -0.34251432 -0.44359604 -0.44432324 -0.53158804 -0.60285429\n", - " -0.637033 -0.67630215 -0.71266249 -0.76793019 -0.81519862 -0.86464867\n", - " -0.90173621 -0.93155168 -0.9337333 -0.98245614 -0.99627307 -1.01518044\n", - " -1.01590764 -1.04863194 -1.00499955 -1.02827016 -1.01663485 -1.0108172\n", - " -1.02317971 -0.97518407 -0.96500318 -0.94682302 -0.901009 -0.87846559\n", - " -0.79556404 -0.84937733 -0.78101991 -0.73811472 -0.65521316 -0.57667485\n", - " -0.59921825 -0.49813653 -0.44577766 -0.36505772 -0.33524225 -0.25888556\n", - " -0.21161713 -0.12289792 -0.03781474 0.00654486]\n", - " [ 0.01315429 0.18799671 0.42203343 0.603453 0.67799397 0.75253494\n", - " 0.76185256 0.72567827 0.65661825 0.49054535 0.3436558 0.16004385\n", - " 0.01918334 -0.11235955 -0.26473006 -0.33817484 -0.36941628 -0.39188819\n", - " -0.35681008 -0.29323102 -0.22636339 -0.13812003 -0.08057002 -0.01534667\n", - " 0.06906002 0.07234859 0.03398191 0.01644286 -0.06412716 -0.15127432\n", - " -0.24609482 -0.28829816 -0.32063579 -0.3672239 -0.32940532 -0.28939435\n", - " -0.20389148 -0.00876953 0.11345574 0.24280625 0.43080296 0.5683749\n", - " 0.67963826 0.74760208 0.76185256 0.71800493 0.63414634 0.48451631\n", - " 0.3315977 0.08824335 -0.10413812 -0.30693341 -0.52178679 -0.6396273\n", - " -0.69717731 -0.74924637 -0.76842971 -0.67306111 -0.53548918 -0.42970677\n", - " -0.26253768 -0.08550288 0.06303097 0.19128528 0.27404768 0.33379008\n", - " 0.36064675 0.34420389 0.30309674 0.2132091 0.19073719 0.07180049\n", - " 0.04494382 -0.02795286 -0.04932858 -0.03727049 0.00109619 0.04055906\n", - " 0.13647575 0.20005481 0.27624007 0.36283913 0.3551658 0.38640723\n", - " 0.32502055 0.24554673 0.07782954 -0.02795286 -0.19347767 -0.3781858\n", - " -0.49383393 -0.67744588 -0.73773637 -0.78268019 -0.793094 -0.70156207\n", - " -0.55905728 -0.40504248 -0.20279529 0.0350781 ]]\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", - "print(\n", - " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", - "metadata": {}, - "source": [ - "#### 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": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", - "metadata": {}, - "source": [ - "### Sampler output\n", - "\n", - "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", - "\n", - "The `BitArray` class is a container for ordered shot data. In more detail, 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", - "\n", - "As a first example, let us look at the following ten-qubit circuit:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "5c787874-1125-4381-b55e-7663caa92ec8", - "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 254]\n", - " [ 0 0]\n", - " [ 3 255]\n", - " ...\n", - " [ 0 0]\n", - " [ 3 255]\n", - " [ 0 0]]\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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", - "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": 5, - "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Counts: {'1111111110': 199, '0000000000': 1337, '1111111111': 1052, '1111111000': 33, '1110000000': 65, '1100100000': 2, '1100000000': 25, '0010001110': 1, '0000000011': 30, '1111111011': 58, '1111111010': 25, '0000000110': 7, '0010000001': 11, '0000000001': 179, '1110111110': 6, '1111110000': 33, '1111101111': 49, '1110111111': 40, '0000111010': 2, '0100000000': 35, '0000000010': 51, '0000100000': 31, '0110000000': 7, '0000001111': 22, '1111111100': 24, '1011111110': 5, '0001111111': 58, '0000111111': 24, '1111101110': 10, '0000010001': 5, '0000001001': 2, '0011111111': 38, '0000001000': 11, '1111100000': 34, '0111111111': 45, '0000000100': 18, '0000000101': 2, '1011111111': 11, '1110000001': 13, '1101111000': 1, '0010000000': 52, '0000010000': 17, '0000011111': 15, '1110100001': 1, '0111111110': 9, '0000000111': 19, '1101111111': 15, '1111110111': 17, '0011111110': 5, '0001101110': 1, '0111111011': 6, '0100001000': 2, '0010001111': 1, '1111011000': 1, '0000111110': 4, '0011110010': 1, '1110111100': 2, '1111000000': 8, '1111111101': 27, '0000011110': 6, '0001000000': 5, '1111010000': 3, '0000011011': 4, '0001111110': 9, '1111011110': 6, '1110001111': 2, '0100000001': 7, '1110111011': 3, '1111101101': 2, '1101111110': 5, '1110000010': 7, '0111111000': 1, '1110111000': 1, '0000100001': 2, '1110100000': 6, '1000000001': 2, '0001011111': 1, '0000010111': 1, '1011111100': 1, '0111110000': 5, '0110111111': 2, '0010000010': 1, '0001111100': 4, '0011111001': 2, '1111110011': 1, '1110000011': 5, '0000001011': 8, '0100000010': 3, '1111011111': 13, '0010111000': 2, '0100111110': 1, '1111101000': 2, '1110110000': 2, '1100000001': 1, '0001110000': 3, '1011101111': 2, '1111000001': 2, '1111110001': 8, '1111110110': 4, '1100000010': 3, '0011000000': 2, '1110011111': 3, '0011101111': 3, '0010010000': 2, '0000100010': 1, '1100001110': 1, '0001111011': 4, '1010000000': 3, '0000001110': 5, '0000001010': 2, '0011111011': 4, '0100100000': 2, '1111110100': 1, '1111100011': 3, '0000110110': 1, '0001111101': 2, '1111100001': 2, '1000000000': 5, '0010000011': 3, '0010011111': 3, '0100001111': 1, '0100000111': 1, '1011101110': 1, '0011110111': 1, '1100000111': 1, '1100111111': 3, '0001111010': 1, '1101111011': 1, '0111111100': 2, '0100000110': 2, '0100000011': 2, '0001101111': 3, '0001000001': 1, '1111110010': 1, '0010100000': 1, '0011100000': 4, '1010001111': 1, '0101111111': 2, '1111101001': 1, '1110111101': 1, '0000011101': 1, '1110001000': 2, '0001111001': 1, '0101000000': 1, '1111111001': 5, '0001110111': 2, '0000111001': 1, '0100001011': 1, '0000010011': 1, '1011110111': 1, '0011110001': 1, '0000001100': 2, '0111010111': 1, '0001101011': 1, '1110010000': 2, '1110000100': 1, '0010111111': 3, '0111011100': 1, '1010001000': 1, '0000101110': 1, '0011111100': 2, '0000111100': 2, '1110011110': 1, '0011111000': 2, '0110100000': 1, '1001101111': 1, '1011000000': 1, '1101000000': 1, '1110001011': 1, '1110110111': 1, '0110111110': 1, '0011011111': 1, '0111100000': 1, '0000110111': 1, '0000010010': 2, '1111101100': 2, '1111011101': 1, '1101100000': 1, '0010111110': 1, '1101101110': 1, '1111001111': 1, '1101111100': 1, '1011111010': 1, '0001100000': 1, '1101110111': 1, '1100001011': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", - "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": 6, - "id": "4602925e-c69d-45b2-9e06-fe8bffe0a797", - "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": "a65c6078-c5c2-4087-b57a-5680148ce333", - "metadata": {}, - "source": [ - "#### Leveraging `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": 7, - "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", - "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", - " [1]\n", - " [1]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [1]]\n", - "\n", - "The shape of register `beta` is (4096, 2).\n", - "The bytes in register `beta`, shot by shot:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " ...\n", - " [ 0 0]\n", - " [ 1 224]\n", - " [ 1 255]]\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", - " [7]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [7]]\n", - "\n", - "The shape of `beta` after shot-wise slicing is (5, 2).\n", - "The bytes in `beta` after shot-wise slicing:\n", - "[[ 0 135]\n", - " [ 0 247]\n", - " [ 1 247]\n", - " [ 1 128]\n", - " [ 1 255]]\n", - "\n", - "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", - " coeffs=[1.+0.j])` is: 0.068359375\n", - "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", - " coeffs=[1.+0.j])` is: 0.06396484375\n", - "\n", - "The shape of the merged results is (4096, 2).\n", - "The bytes of the merged results:\n", - "[[ 1 15]\n", - " [ 1 239]\n", - " [ 3 239]\n", - " ...\n", - " [ 0 0]\n", - " [ 3 192]\n", - " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", - "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": 8, - "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", - "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": "2f26ff75-e1ba-45ef-97c1-c5dde36400cf", - "metadata": {}, - "source": [ - "For Sampler jobs, you can also review the result metadata to understand when certain data was run; this is called the [_execution span._](monitor-job#execution-spans)" - ] - } - ], - "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/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 4e5f7a068ef..ad9379a9b80 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -1,7 +1,7 @@ --- 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 --- diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index d8a110180ae..67961272ac7 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -65,6 +65,77 @@ "- (Optionally) a number of shots to measure the circuit with" ] }, + { + "cell_type": "markdown", + "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": null, + "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", + " EstimatorV2 as Estimator,\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 estimator 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": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", @@ -72,6 +143,37 @@ "source": [ "## Output\n", "\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", + "\n", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", + "\n", + "```\n", + " └── PrimitiveResult\n", + " ├── PubResult[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", + " ├── PubResult[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` 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", "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", "\n", "The `BitArray` class is a container for ordered shot data. In more detail, 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", From 6584252192f887d6b8f87127c8ef7673a60449a4 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 09:49:03 -0600 Subject: [PATCH 041/118] remove from qiskit-bot --- qiskit_bot.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index bd5aca30785..61e3ec10175 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -204,9 +204,6 @@ notifications: - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/get-started-with-primitives": - - "@ElePT" - - "@jyu00" "docs/guides/ha-dr": - "@abbycross" - "@beckykd" From c132cd00d3de1b57175204e08f93d57638abeb6d Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 09:51:41 -0600 Subject: [PATCH 042/118] Update qiskit_bot.yaml --- qiskit_bot.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 61e3ec10175..d3681da7929 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -450,8 +450,6 @@ notifications: - "@jyu00" - "@ElePT" - "@beckykd" - "docs/guides/primitive-input-output": - - "@kaelynj" "docs/guides/primitives-rest-api": - "@born-2learn" - "@HuangJunye" From 3ec09907897db544c52c9a2b99103a8d83b9000b Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 11:27:12 -0600 Subject: [PATCH 043/118] links --- docs/guides/algorithmiq-tem.ipynb | 2 +- docs/guides/ibm-circuit-function.ipynb | 2 +- docs/guides/primitives-rest-api.ipynb | 2 +- docs/guides/primitives.ipynb | 8 ++++---- docs/guides/pubs.ipynb | 19 ++++++++++++++++--- .../q-ctrl-performance-management.ipynb | 2 +- .../exploring-uncertainty-with-qiskit.ipynb | 2 +- 7 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 24edd1f9b6d..720196de840 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -284,7 +284,7 @@ "\n", "Name | Type | Description | Required | Default | Example\n", "-- | -- | -- | -- | -- | --\n", - "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", + "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", "\n", diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index f92930fcb33..f6e1ca5df72 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -206,7 +206,7 @@ "| Name | Type | Description | Required | Default | Example |\n", "|-----------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------|------------------------------------------|\n", "| backend_name | str | Name of the backend to make the query. | Yes | N/A | `ibm_fez` |\n", - "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/primitive-input-output#overview-of-pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", + "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", "| options | dict | Input options. See the **Options** section for more details. | No | See the **Options** section for details. | `{\"optimization_level\": 3}` |\n", "| instance | str | The cloud resource name of the instance to use in that format. | No | One is randomly picked if your account has access to multiple instances. | `CRN` |" ] diff --git a/docs/guides/primitives-rest-api.ipynb b/docs/guides/primitives-rest-api.ipynb index b55036b1888..a5755e68443 100644 --- a/docs/guides/primitives-rest-api.ipynb +++ b/docs/guides/primitives-rest-api.ipynb @@ -567,7 +567,7 @@ "\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", + " 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/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", diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 92c9171c45b..f037af45876 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -134,7 +134,7 @@ "\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", + "The input is an array of [PUBs.](/docs/guides/pubs) Each PUB is in the format:\n", "\n", "(``, ``, ``, ``),\n", "\n", @@ -142,7 +142,7 @@ "\n", "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) that contains the computed expectation values per pair, and their standard errors, in `PubResult` form. Each `PubResult` contains both data and metadata.\n", "\n", - "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive inputs and outputs](primitive-input-output#broadcasting-rules) topic.\n", + "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive inputs and outputs](pubs#broadcasting-rules) topic.\n", "\n", "Example:" ] @@ -221,13 +221,13 @@ "\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", + "The input is one or more [PUBs,](/docs/guides/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.\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](pubs#broadcasting-rules) for full details.\n", "\n", "Example:" ] diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 9f2668b8581..4841222e5ad 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -48,8 +48,9 @@ "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", "metadata": {}, "source": [ - "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", - "\n" + "The Estimator and Sampler primitives help you efficiently define vectorized workloads by using a data structure known as a _Primitive Unified Bloc (PUB)_. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the `run()` method for the primitives, which execute 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 Sampler or Estimator primitives.\n", + "\n", + "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting." ] }, { @@ -57,7 +58,7 @@ "id": "92e5f627-e4e9-433b-8fce-e25dff68bdef", "metadata": {}, "source": [ - "### Broadcasting rules\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", "\n", @@ -176,6 +177,18 @@ "```\n", "" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next Steps\n", + "\n", + "\n", + "- Learn about [Estimator input and output](/docs/guides/estimator-input-output) in depth.\n", + "- Learn about [Sampler input and output](/docs/guides/sampler-input-output) in depth.\n", + "" + ] } ], "metadata": { diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 93f519074fd..3b3339ebb9f 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -362,7 +362,7 @@ "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/primitive-input-output#estimator-pub)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", - "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./primitive-input-output#broadcasting-rules) as the `QiskitRuntime` primitives.\n", + "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./pubs#broadcasting-rules) as the `QiskitRuntime` primitives.\n", "- (Optional) A target precision for expectation values to estimate.\n", "- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": }`.\n", "\n", diff --git a/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb b/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb index f75ccc52593..a2c2f9f0844 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/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." ] From eb7d975a8536ad16947c647aa38d7a59aeac92f7 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 15:16:53 -0600 Subject: [PATCH 044/118] run hello world --- docs/guides/hello-world.ipynb | 63 +++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 17 deletions(-) diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index 5ad3ecee93b..f57c658fc4e 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -150,7 +150,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 1, "id": "930ca3b6", "metadata": { "tags": [] @@ -158,8 +158,9 @@ "outputs": [ { "data": { + "image/png": "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", "text/plain": [ - "\"Output" + "
" ] }, "execution_count": 1, @@ -258,14 +259,27 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, "id": "9a901271", "metadata": {}, "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "qiskit_runtime_service.__init__:WARNING:2026-02-12 15:13:28,878: Instance was not set at service instantiation. Free and trial plan instances will be prioritized. Based on the following filters: (tags: None, region: us-east, eu-de), and available plans: (internal, premium), the available account instances are: Documentation premium fleet, Documentation internal fleet, Documentation premium fleet, Documentation internal fleet. If you need a specific instance set it explicitly either by using a saved account with a saved default instance or passing it in directly to QiskitRuntimeService().\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:13:30,477: Loading instance: Documentation premium fleet, plan: premium\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:13:32,148: Loading instance: Documentation internal fleet, plan: internal\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:13:32,814: Loading instance: Documentation premium fleet, plan: premium\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:13:35,878: Loading instance: Documentation internal fleet, plan: internal\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:13:43,207: Using instance: Documentation premium fleet, plan: premium\n" + ] + }, { "data": { + "image/png": "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", "text/plain": [ - "\"Output" + "
" ] }, "execution_count": 3, @@ -307,7 +321,7 @@ "name": "stdout", "output_type": "stream", "text": [ - ">>> Job ID: d5k96q4jt3vs73ds5tgg\n" + ">>> Job ID: d67452cvpe6c73ab5ir0\n" ] } ], @@ -425,7 +439,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 7, "id": "87143fcc", "metadata": { "tags": [] @@ -433,8 +447,9 @@ "outputs": [ { "data": { + "image/png": "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FJgebtTQ7iNHjsjcuXN1p2A1pHvVqlXeTsN5eXl6BJXHsGHD5I033pCHHnpIHnzwQT2Jnxop1adPHxO/CwAAECpMn+cm2Pw9zw0AAAitz2/TZygGAADwJ8INAACwFcINAACwFcINAACwFdNHSwWbp/+0v9eYAgAAgeP53G7OOKiwCzelpaX6ayCWYAAAAIH/HFejpk4n7IaCqxmQDxw4IAkJCeJwOPz63J51q/bt28cw8wDiOgcH15nrbDe8p619nVVcUcGmU6dOPvPfNSbsam7UBenSpUtAX0P9MJlDJ/C4zsHBdeY62w3vaete5zPV2HjQoRgAANgK4QYAANgK4caPYmJiZN68eforAofrHBxcZ66z3fCeDp/rHHYdigEAgL1RcwMAAGyFcAMAAGyFcAMAAGyFcAMAAGyFcHOOfv7zn8u4ceNkzZo1eqbjpm5XXnmlf39iYXytXS6XDBs2TH7yk5/43F9cXKxnw5wzZ45pZbS65ryPc3Nz9faWLVvMLq5lNec9zHUO7Pv4iiuuOO05a9eubfHP2e5czXgfv/feexIdHS2bN2/2Oeepp56S1NRUyc/PD2wh1WgpnL1JkyYZN910k1FZWWkcPHiwwe3FF180HA6H8eabb3J5/XStlW3bthmtWrUy/vSnP3nvv/POO42+ffvqnwXOTXPex3v27FEjK40vv/ySy9wCZ3oPc50D+z4uLCxscP/evXuNPn36GAMHDjROnDjB+7sZmvO7eMqUKcZFF11kVFRU6P1vv/3WiI2NNZYvX24EGuHGDx+4p/ruu++MhIQEY86cOS352aCJa/3MM88YycnJxoEDB4x33nnHiIqKMrZs2cL18rNT38d86PrP6d7DXGf/as7v46lTpxppaWnGvn37/Pzq9vbMGX4Xl5SUGN26dTNmzpxpVFdX6/B46623BqVshBs/h5tjx44ZmZmZxtixYw23293Snw8audbqul5xxRXGVVddZbRv39545JFHuE5+1tj7mA9d/znde5jr7D/N+X28ZMkSIzo62vjkk0/8+Mrhwd2M38WrV682IiMjjZ/+9KdGhw4djIKCgqCULewWzgz0iuO33367REZGyuuvv+73VcdRS13XF154QS688EK5+OKLZdasWVwaP+J9HHi8h0Pjfbxu3Tq5//775fnnn9d9SOD/9/GoUaPklltukeXLl8uKFSskJSVFgoEOxX704IMPSk5Ojvz973+XhIQEfz41TvHqq69KXFyc7NmzR3788Ueujx/xPg4O3sPmvo/z8vL0h+7dd98tU6dODXBpwvd9vH//flm1apU+Jzs7O2jlItz4iUqlv//97/XXzMxMfz0tGrFhwwZ5+umn5Z///KcMHjxYpkyZoppXuVZ+wPs4OHgPm/s+PnHihNx8881y0UUXyeLFiwNcmvB+H0+bNk0GDBigz1G1PEEbjRaUxi+b9wNRo0fi4uKMJ5980uxi2f5al5WV6Tb0++67z9s/oXXr1sbzzz9vcimt70zvY/qC+MeZ3sNc55Zpzu/j22+/3cjIyDCOHDnSwlcLX2XN+F388ssv687cubm5ev/ee+81unfvbhw/fjzg5SPctPADV/3nUL3Br7/++kaHIB4+fNi/P7EwDze//vWvjZ49e+r/WB5Lly7V/6nUfy6cm+a8j/nQ9Y8zvYe5zoF9Hz/xxBN6VM+qVasaPae8vNwvP+dwfx/n5ubqYKOG4Xuoc3v06KFDTqARblr4gbts2TI990dTN/UfDf651mvWrDGcTqeRnZ3d4JxrrrnGGDVqFCPUzlFz3sd86LZcc97Du3fvZj6hAL6PVY3N6c557bXXWvpjtr01zXgfq5vaPpV6jHqseo5Acqh/gtMABgAAEHh0KAYAALZCuAEAALZCuAEAALZCuAEAALZCuAEAALZCuAEAALZCuAEAALZCuAEAALZCuAHgdxkZGZZdkPCKK66Q+++/37bfHxAOCDcAzsq+ffvkrrvukk6dOkl0dLR069ZNpk+fLoWFhVxJACGBcAOg2Xbv3i0DBw6UHTt2yJ///GfZuXOnLF26VFavXi1Dhw6Vo0ePmnI1XS6XuN1uU14bQOgh3ABotl/96le6tuZf//qXjBw5Urp27SrXXXedfPjhh7J//36ZM2eO99zS0lKZMGGCxMfHS+fOnWXJkiXe+9SSdr/97W/142NiYnQt0K9//Wvv/ZWVlfKb3/xGP049fsiQIbJmzRrv/cuWLZM2bdrIypUrpXfv3vo5/vd//1diY2OlqKjIp8yqVmnUqFF6W9UuqTKp542Li5OLL75Yh7RT1dTUyL333itJSUmSmpoqDz/8sC5zU9RrTp06Vdq1ayeJiYn69b766ivv/Wr7yiuvlISEBH3/gAED5IsvvuCdBwQI4QZAs6hamffff19++ctfSqtWrXzuS0tLkzvuuENWrFjhDQFPPvmk9OvXT7788kuZNWuWDhkffPCBvu9vf/ubPP300/Liiy/qWqB33nlHBw0PFSxycnJk+fLl8vXXX8utt94q1157rT7Xo7y8XBYuXKhDzbfffqtfXwUe9dz1a3RUmdR9SkVFhQ4W7777rmzdulXuvvtuufPOO2Xjxo0+388f/vAHiYyM1MefeeYZWbRokX6dpqjyHT58WP7v//5PNm3aJJdeeqlcddVV3pos9fpdunSRzz//XN+vrkdUVBTvPCBQArrmOADb+PTTT1VqMd5+++1G71+0aJG+/9ChQ0a3bt2Ma6+91uf+8ePHG9ddd53efuqpp4xevXoZVVVVDZ5n7969htPpNPbv3+9z/KqrrjJmz56tt1977TX9Wlu2bPE5Z/r06caoUaO8+++//74RExNjHDt2rMnv64YbbjD+8z//07s/cuRI48ILLzTcbrf32MyZM/UxD/X9Pf3003o7OzvbSExMNCoqKnyet0ePHsaLL76otxMSEoxly5Y1WQYA/kXNDYCz/YOoWeepPjin7n///ffemo4TJ05I9+7dZdq0afL222/rpiDlm2++0TUuvXr1ktatW3tva9eulV27dnmfTzWP9e3b1+c1VA2Jar46cOCA3n/99dflhhtu0DU6inreRx55RNcStW3bVj+vqo3Ky8vzeZ7LLrtMHA6HT9lVrZF6/KlUk9Px48clJSXFp7x79uzxlnfGjBm62Wr06NHy+OOP+3wfAPwvMgDPCcCGevbsqT/wVUC5+eabG9yvjicnJ+t+J2eSnp4u27Zt0311VFOVaupSzVgqwKig4HQ6dfON+lqfCg0eqmmsfgBRBg0aJD169NDNWb/4xS90aFL9czzUa6hmJjWMWwUc1Z9HDfuuqqo6x6siurwdO3b06RPk4QlVqn/R7bffrpvDVNPVvHnzdBkbu44AWo5wA6BZVM3E1VdfLc8//7w88MADPv1u8vPzdS3JxIkTvYHj008/9Xm82r/wwgu9++rxY8eO1TfVUfmCCy7QtTaXXHKJriFRfViysrLO+qejam9UWVQfl4iICF1z4/HJJ5/ITTfdJD/72c/0vhphtX37dt0pub7PPvusQdkzMzMbhC1F9a9R37/qo6Pmv2mKqolSN3XtVKfm1157jXADBAjNUgCa7bnnntMjmcaMGSPr1q3Tc96sWrVKhx41AunRRx/1CRJPPPGEDg9qpNRf/vIX3alYUbUpr7zyiu7Uq4aX/+lPf9JhR82ZowKACigqKL311lu6eUd17F2wYIGu+TgT9djNmzfrstxyyy16JJWHCiiqpmjDhg26puk//uM/5NChQw2eQzVTqaYkVbukRlM9++yz3rKfSjU1qWarcePG6VFkubm5+vnVyDE1Iko1v6kO0qpmZ+/evfq6qI7F9YMeAD/zcx8eADaXm5trTJo0yejQoYMRFRVlpKenG/fdd59RUFDg0+F2/vz5xq233mrExcUZaWlpxjPPPOO9X3VKHjJkiO6IGx8fb1x22WXGhx9+6L1fdTSeO3eukZGRoV+jY8eOxs0332x8/fXX3g7FSUlJTZZx8ODBusPxRx995HO8sLDQuOmmm4zWrVsb7du3Nx566CFj4sSJ+lj9DsW//OUvjXvuuUeXLzk52XjwwQd9OhjX71CslJSU6GvQqVMn7zW54447jLy8PKOystK47bbb9LHo6Gh9zr333mucOHGiRT8HAE1zqH/8HZgAAADMQrMUAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAAAQO/l/a+m/xMkLkVAAAAAASUVORK5CYII=", "text/plain": [ - "\"Output" + "
" ] }, "metadata": {}, @@ -501,7 +516,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 9, "id": "2ac02692", "metadata": {}, "outputs": [], @@ -540,7 +555,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 10, "id": "863a4ec9", "metadata": {}, "outputs": [ @@ -576,10 +591,23 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 11, "id": "428f05e7", "metadata": {}, - "outputs": [], + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "qiskit_runtime_service.__init__:WARNING:2026-02-12 15:14:20,967: Instance was not set at service instantiation. Free and trial plan instances will be prioritized. Based on the following filters: (tags: None, region: us-east, eu-de), and available plans: (internal, premium), the available account instances are: Documentation premium fleet, Documentation internal fleet, Documentation premium fleet, Documentation internal fleet. If you need a specific instance set it explicitly either by using a saved account with a saved default instance or passing it in directly to QiskitRuntimeService().\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:14:22,654: Loading instance: Documentation premium fleet, plan: premium\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:14:24,066: Loading instance: Documentation internal fleet, plan: internal\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:14:24,842: Loading instance: Documentation premium fleet, plan: premium\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:14:27,405: Loading instance: Documentation internal fleet, plan: internal\n", + "qiskit_runtime_service.backends:WARNING:2026-02-12 15:14:33,485: Using instance: Documentation premium fleet, plan: premium\n" + ] + } + ], "source": [ "service = QiskitRuntimeService()\n", "\n", @@ -604,7 +632,7 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 12, "id": "3aaa5025", "metadata": {}, "outputs": [], @@ -628,7 +656,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "d5k9mmqvcahs73a1ni3g\n" + "d6745f4vpe6c73ab5j6g\n" ] } ], @@ -651,14 +679,15 @@ }, { "cell_type": "code", - "execution_count": null, + "execution_count": 14, "id": "de91ebd0", "metadata": {}, "outputs": [ { "data": { + "image/png": "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", "text/plain": [ - "\"Output" + "
" ] }, "metadata": {}, @@ -712,7 +741,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -726,7 +755,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.14.2" }, "widgets": { "application/vnd.jupyter.widget-state+json": { From 0497b8ca55b6f439dc2bebf5120f027d188f1111 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 15:58:51 -0600 Subject: [PATCH 045/118] fix links --- docs/api/qiskit-ibm-runtime/release-notes.mdx | 2 +- docs/guides/get-started-with-estimator.ipynb | 2 +- docs/guides/get-started-with-executor.ipynb | 93 +------------------ docs/guides/get-started-with-sampler.ipynb | 2 +- docs/guides/ibm-circuit-function.ipynb | 6 +- docs/guides/monitor-job.ipynb | 2 +- docs/guides/noise-learning.ipynb | 2 +- docs/guides/pubs.ipynb | 2 +- .../q-ctrl-performance-management.ipynb | 4 +- docs/guides/qedma-qesem.ipynb | 2 +- docs/guides/repetition-rate-execution.ipynb | 3 +- docs/guides/tools-intro.mdx | 2 +- docs/guides/v2-primitives.mdx | 2 +- docs/tutorials/dc-hex-ising.ipynb | 2 +- ...ror-mitigation-with-qiskit-functions.ipynb | 4 +- .../tutorials/operator-back-propagation.ipynb | 2 +- .../vqe.ipynb | 2 +- 17 files changed, 26 insertions(+), 108 deletions(-) diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index ec684740a07..a297a4039b0 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -907,7 +907,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)) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 51382bec60d..5577474aa4e 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -314,7 +314,7 @@ "### Similarities and differences between backend and Runtime primitives\n", "\n", "- The inputs to and outputs from [`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", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) 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", diff --git a/docs/guides/get-started-with-executor.ipynb b/docs/guides/get-started-with-executor.ipynb index fec408ad56e..5a0f2589cae 100644 --- a/docs/guides/get-started-with-executor.ipynb +++ b/docs/guides/get-started-with-executor.ipynb @@ -6,21 +6,12 @@ "metadata": {}, "source": [ "---\n", - "title: Get started with primitives\n", - "description: How to use the Estimator and Sampler primitives in Qiskit Runtime.\n", + "title: Get started\n", + "description: How to use the Executor primitive 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", - "" + "# Get started with the Executor primitive" ] }, { @@ -30,15 +21,7 @@ "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", - "" + "The Executor primitive is part of the directed execution model, which provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information." ] }, { @@ -75,10 +58,8 @@ "id": "bafa61f0-c049-4ee6-ac76-a0ed97e67caf", "metadata": {}, "source": [ - "\n", - "## Get started with Estimator\n", + "## Steps to get started with Executor\n", "\n", - "{/*Verified the v2 examples 2/29/24 - updated 10/29/24*/}\n", "\n", "### 1. Initialize the account\n", "\n", @@ -442,70 +423,6 @@ ")" ] }, - { - "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", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index f29e1a6364d..1194ca5da2f 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -267,7 +267,7 @@ "### 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) \n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [Primitive inputs and outputs](primitive-input-output) for details.\n", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) for details.\n", "However, there can be differences in the fields of the returned metadata.\n", "\n", "- The [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) class requires a backend that supports the `memory` option.\n", diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index f6e1ca5df72..d9bf66df04d 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -35,7 +35,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](./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,7 +49,7 @@ "\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 Runtime Estimator](./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)" ] @@ -153,7 +153,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/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index ae1341e081f..b3a45d4686b 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -226,7 +226,7 @@ "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", + "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/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", "Example:" ] diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index 6d2a57e7b26..bb44f7953b1 100644 --- a/docs/guides/noise-learning.ipynb +++ b/docs/guides/noise-learning.ipynb @@ -53,7 +53,7 @@ "\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](./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." ] }, { diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 4841222e5ad..75882c032a5 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -109,7 +109,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/pubs/broadcasting.svg \"Visual representation of broadcasting\")" ] }, { diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 3b3339ebb9f..6263b53fac5 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -359,7 +359,7 @@ "| backend_name| `str` | The name of the backend | No | The least busy backend that your instance has access to | `\"ibm_fez\"` |\n", "| options| `dict` | Input options; see Options section for more details | No | See the Options section for details | `{\"default_shots\": 2048}` |\n", "\n", - "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/primitive-input-output#estimator-pub)):**\n", + "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/estimator-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./pubs#broadcasting-rules) as the `QiskitRuntime` primitives.\n", @@ -673,7 +673,7 @@ "| backend_name| `str` | The name of the backend | No | The least busy backend that your instance has access to | `\"ibm_fez\"` |\n", "| options| `dict` | Input options; see Options section for more details | No | See the Options section for details | `{\"default_shots\": 2048}` |\n", "\n", - "**`QctrlSamplerPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/primitive-input-output#sampler-pub)):**\n", + "**`QctrlSamplerPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/sampler-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- (Optional) A collection of parameter values to bind the circuit against.\n", "- (Optional) An integer representing the shot count, or a dictionary of runtime options containing the shot count. For example: `(circ, None, 123)` or `(circ, None, {\"shots\": 123})`.\n", diff --git a/docs/guides/qedma-qesem.ipynb b/docs/guides/qedma-qesem.ipynb index 1c56f89be65..14533062294 100644 --- a/docs/guides/qedma-qesem.ipynb +++ b/docs/guides/qedma-qesem.ipynb @@ -244,7 +244,7 @@ "\n", "| Name | Type | Description | Required | Default | Example |\n", "| -----| ------| ------------| -------- | ------- | -------- |\n", - "| `pubs` | [EstimatorPubLike](/docs/guides/primitive-input-output) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", + "| `pubs` | [EstimatorPubLike](/docs/guides/pubs) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", "| `backend_name`| string|Name of the backend to use |No | QESEM will get least busy device reported by IBM| `\"ibm_fez\"`|\n", "| `instance` | string| The cloud resource name of the instance to use in that format | No | N/A | `“CRN”` |\n", "| `options` | dictionary |Input options. See **Options** section for more details. | No | See the **Options** section for details. | `{ default_precision = 0.03, \"max_execution_time\" = 3600, \"transpilation_level\" = 0}` |\n", diff --git a/docs/guides/repetition-rate-execution.ipynb b/docs/guides/repetition-rate-execution.ipynb index 829173968bd..4b18501e46e 100644 --- a/docs/guides/repetition-rate-execution.ipynb +++ b/docs/guides/repetition-rate-execution.ipynb @@ -100,7 +100,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.](./get-started-with-primitives)\n", + " - Review how to [get started with Estimator.](./get-started-with-estimator)\n", + " - Review how to [get started with Sampler.](./get-started-with-sampler)\n", "" ] } diff --git a/docs/guides/tools-intro.mdx b/docs/guides/tools-intro.mdx index 68942655b2e..84c467dd30f 100644 --- a/docs/guides/tools-intro.mdx +++ b/docs/guides/tools-intro.mdx @@ -43,7 +43,7 @@ Benchmarking is important for comparing the relative performance of quantum soft ## Qiskit Runtime -Qiskit Runtime is a 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 the Qiskit primitives for IBM Quantum hardware. To get started with Qiskit Runtime primitives, visit the [documentation](./get-started-with-primitives). +Qiskit Runtime is a 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 the Qiskit primitives for IBM Quantum hardware. To get started with Qiskit Runtime primitives, visit the [documentation](./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](./configure-error-mitigation) page. diff --git a/docs/guides/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index f45ea336202..a6f05414661 100644 --- a/docs/guides/v2-primitives.mdx +++ b/docs/guides/v2-primitives.mdx @@ -1207,6 +1207,6 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}") - 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 details about [Primitive inputs and outputs.](/docs/guides/pubs) - Experiment with the [CHSH Inequality](/docs/tutorials/chsh-inequality) tutorial. diff --git a/docs/tutorials/dc-hex-ising.ipynb b/docs/tutorials/dc-hex-ising.ipynb index 5946142516a..d2b047381b1 100644 --- a/docs/tutorials/dc-hex-ising.ipynb +++ b/docs/tutorials/dc-hex-ising.ipynb @@ -877,7 +877,7 @@ "metadata": {}, "source": [ "### Transpilation for dynamic circuits\n", - "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/primitive-input-output) (PUBs) as the Sampler primitive input." + "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/pubs) (PUBs) as the Sampler primitive input." ] }, { diff --git a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb index 238761a1c3d..f6e8e4cf825 100644 --- a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb +++ b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb @@ -24,7 +24,7 @@ "id": "34260848-be4c-45f7-914f-9d9bcc2be504", "metadata": {}, "source": [ - "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/primitive-input-output) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", + "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/pubs) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", "\n", "Visit the documentation for an [introduction to Qiskit Functions](/docs/guides/functions) and learn how to get started with the [IBM Circuit function](/docs/guides/ibm-circuit-function)." ] @@ -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/operator-back-propagation.ipynb b/docs/tutorials/operator-back-propagation.ipynb index a6bb9039c99..9e466e8fbdb 100644 --- a/docs/tutorials/operator-back-propagation.ipynb +++ b/docs/tutorials/operator-back-propagation.ipynb @@ -546,7 +546,7 @@ "id": "8b4487c1-b1e6-4ae8-b02d-c8bf980ad19b", "metadata": {}, "source": [ - "We create the Primitive Unified Bloc (PUB) for each of the three cases." + "We create the Primitive Unified Bloc (PUB) for each of the three cases." ] }, { diff --git a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb index ccac5f505ab..bd6140e7a42 100644 --- a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb +++ b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb @@ -354,7 +354,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/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", From e6d258987ca51079f400915d14a76c4ad9584901 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 16:15:48 -0600 Subject: [PATCH 046/118] squeaky --- docs/guides/estimator-input-output.ipynb | 6 ++--- docs/guides/executor-examples.ipynb | 4 +++- docs/guides/executor-input-output.ipynb | 27 ++++++++++++++-------- docs/guides/get-started-with-sampler.ipynb | 2 +- docs/guides/hello-world.ipynb | 4 ++-- docs/guides/primitives.ipynb | 1 + docs/guides/pubs.ipynb | 1 + docs/guides/sampler-input-output.ipynb | 3 ++- scripts/config/allowLists.ts | 1 + 9 files changed, 32 insertions(+), 17 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index a8bfa449452..16dcc3eee43 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -53,6 +53,7 @@ }, { "cell_type": "markdown", + "id": "9c77dcb7-6210-4883-99b6-c19c46a83efc", "metadata": {}, "source": [ "## Inputs\n", @@ -69,6 +70,7 @@ }, { "cell_type": "markdown", + "id": "0874f9bd-1ce1-44fe-9a8c-3abcc6bed806", "metadata": {}, "source": [ "---\n", @@ -79,18 +81,16 @@ { "cell_type": "code", "execution_count": null, + "id": "0fbd9fbd-be9c-4986-aac6-ba9f3b8ec3fd", "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", diff --git a/docs/guides/executor-examples.ipynb b/docs/guides/executor-examples.ipynb index 390bfdb6b04..b4f4b93dc6d 100644 --- a/docs/guides/executor-examples.ipynb +++ b/docs/guides/executor-examples.ipynb @@ -71,11 +71,12 @@ { "cell_type": "code", "execution_count": null, + "id": "98a09369-9a50-4c21-b35b-62a77df3c4e2", "metadata": {}, "outputs": [], "source": [ "from qiskit.circuit import Parameter, QuantumCircuit\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, Executor\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", "# Generate the circuit\n", "circuit = QuantumCircuit(3)\n", @@ -98,6 +99,7 @@ }, { "cell_type": "markdown", + "id": "09655fc3-c7a6-4448-99ca-48635faf5bef", "metadata": {}, "source": [ "The inputs to the `Executor` are `QuantumProgram`s. For full details, see [Executor input and output.](/docs/guides/executor-input-output)" diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb index 1b924ac4fec..5f0f965ef33 100644 --- a/docs/guides/executor-input-output.ipynb +++ b/docs/guides/executor-input-output.ipynb @@ -45,6 +45,7 @@ }, { "cell_type": "markdown", + "id": "a4800a7e-9db5-47cf-aaf9-e69c2c6e1b5e", "metadata": {}, "source": [ "The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer." @@ -52,11 +53,12 @@ }, { "cell_type": "markdown", + "id": "eba624e4-093c-491d-b503-1b91ce54d434", "metadata": {}, "source": [ "## Quantum programs\n", "\n", - "The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a \n", + "The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a\n", "[`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a\n", "different task for the Executor to perform. Typically, each item owns one of the following options:\n", "\n", @@ -72,6 +74,7 @@ { "cell_type": "code", "execution_count": null, + "id": "401d4d84-28f4-4ad0-9f8f-751ebf21f612", "metadata": {}, "outputs": [], "source": [ @@ -96,7 +99,9 @@ "circuit.measure_all()\n", "\n", "# Transpile the circuit\n", - "preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + "preset_pass_manager = generate_preset_pass_manager(\n", + " backend=backend, optimization_level=0\n", + ")\n", "isa_circuit = preset_pass_manager.run(circuit)\n", "\n", "# Append the circuit to the program\n", @@ -105,15 +110,16 @@ }, { "cell_type": "markdown", + "id": "f49d211f-36b4-489d-9e0e-d10aab5e195f", "metadata": {}, "source": [ - "\n", - "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (namely 1024 per set of parameter values).\n" + "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (namely 1024 per set of parameter values)." ] }, { "cell_type": "code", "execution_count": null, + "id": "882d8ada-4ec2-4d50-b498-c51a9d185d6f", "metadata": {}, "outputs": [], "source": [ @@ -147,20 +153,21 @@ }, { "cell_type": "markdown", + "id": "6d79baa5-046d-427a-91bd-7d2f1a178a97", "metadata": {}, "source": [ - "\n", "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n", "we provide ``10`` sets of parameters for the parametric gates in the original circuit. Additionally, we use the ``shape`` request argument to request an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape ``(2, 14, 10)``.\n", "\n", " We refer the reader to :mod`~samplomatic` and its documentation for more details on the\n", - " `samplomatic.samplex.Samplex` and its arguments.\n" + " `samplomatic.samplex.Samplex` and its arguments." ] }, { "cell_type": "code", "execution_count": null, + "id": "3602ecd1-8d23-48af-9612-4891472775bf", "metadata": {}, "outputs": [], "source": [ @@ -183,7 +190,9 @@ "circuit.measure_all()\n", "\n", "# Transpile the circuit, additionally grouping gates and measurements into annotated boxes\n", - "preset_pass_manager = generate_preset_pass_manager(backend=backend, optimization_level=0)\n", + "preset_pass_manager = generate_preset_pass_manager(\n", + " backend=backend, optimization_level=0\n", + ")\n", "preset_pass_manager.post_scheduling = generate_boxing_pass_manager(\n", " enable_gates=True,\n", " enable_measures=True,\n", @@ -197,7 +206,7 @@ "program.append_samplex_item(\n", " template,\n", " samplex=samplex,\n", - " samplex_arguments={ \n", + " samplex_arguments={\n", " # the arguments required by the samplex.sample method\n", " \"parameter_values\": np.random.rand(10, 3),\n", " },\n", @@ -207,9 +216,9 @@ }, { "cell_type": "markdown", + "id": "165509d7-2137-49ac-ba77-4c75ba6508dd", "metadata": {}, "source": [ - "\n", "Now that we have populated our `QuantumProgram`, we can proceed with execution." ] } diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index 1194ca5da2f..1147904ae30 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -266,7 +266,7 @@ "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) \n", + "- The inputs to and outputs from [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2)\n", "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) for details.\n", "However, there can be differences in the fields of the returned metadata.\n", "\n", diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index f57c658fc4e..e46b071351a 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -741,7 +741,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -755,7 +755,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.2" + "version": "3" }, "widgets": { "application/vnd.jupyter.widget-state+json": { diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index f037af45876..7c746244ac3 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -266,6 +266,7 @@ }, { "cell_type": "markdown", + "id": "9aca0e26-ab6e-42be-af3e-c92f881b5fbb", "metadata": {}, "source": [ "\n", diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 75882c032a5..0e55842e131 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -180,6 +180,7 @@ }, { "cell_type": "markdown", + "id": "9d2e7be3-082c-4a8a-b29b-54349fa5fba9", "metadata": {}, "source": [ "## Next Steps\n", diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 67961272ac7..78184e084ca 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -67,6 +67,7 @@ }, { "cell_type": "markdown", + "id": "331708ea-5fbd-468f-940e-ea09c7aae46a", "metadata": {}, "source": [ "---\n", @@ -77,6 +78,7 @@ { "cell_type": "code", "execution_count": null, + "id": "16409c22-5d8d-459a-908e-eb9f6178d075", "metadata": {}, "outputs": [], "source": [ @@ -92,7 +94,6 @@ "\n", "from qiskit_ibm_runtime import (\n", " QiskitRuntimeService,\n", - " EstimatorV2 as Estimator,\n", " SamplerV2 as Sampler,\n", ")\n", "\n", diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index 5fa22ba6099..8b5e245ab38 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -34,6 +34,7 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/sampler-input-output.ipynb", "docs/guides/sampler-options.ipynb", "docs/guides/get-started-with-estimator.ipynb", + "docs/guides/get-started-with-executor.ipynb", "docs/guides/external-providers-primitives-v2.mdx", "docs/guides/create-a-provider.mdx", "docs/guides/local-simulators.mdx", From 0733815c1003378e6f9d585cdfb8f51a97ba3bd8 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 16:32:01 -0600 Subject: [PATCH 047/118] fix links and image --- docs/guides/hello-world.ipynb | 6 +++--- docs/guides/q-ctrl-performance-management.ipynb | 4 ++-- ...ple-based-krylov-quantum-diagonalization.ipynb | 2 +- .../primitive-input-output/broadcasting.svg | 3 --- public/docs/images/guides/pubs/broadcasting.avif | Bin 0 -> 657 bytes 5 files changed, 6 insertions(+), 9 deletions(-) delete mode 100644 public/docs/images/guides/primitive-input-output/broadcasting.svg create mode 100644 public/docs/images/guides/pubs/broadcasting.avif diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index e46b071351a..52d4d082761 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -212,7 +212,7 @@ "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 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 (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`." ] @@ -306,7 +306,7 @@ "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#sampler)" + "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/primitives#sampler)" ] }, { @@ -434,7 +434,7 @@ "\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)" ] }, { diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 6263b53fac5..9d97e291a3d 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -69,7 +69,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/pubs)." ] }, { @@ -307,7 +307,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):" ] }, { diff --git a/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb b/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb index 60a4bc25c3f..24efffc9c49 100644 --- a/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb +++ b/docs/tutorials/sample-based-krylov-quantum-diagonalization.ipynb @@ -406,7 +406,7 @@ "id": "a3304e1b-9c7c-4212-8744-d1c62292eced", "metadata": {}, "source": [ - "Now that we have created the circuits, we can optimize them for a target hardware. We pick the least busy QPU with at least 127 qubits. Check out the [Qiskit IBM® Runtime docs](/docs/guides/get-started-with-primitives#get-started-with-sampler) for more information." + "Now that we have created the circuits, we can optimize them for a target hardware. We pick the least busy QPU with at least 127 qubits. Check out the [Qiskit IBM® Runtime docs](/docs/guides/get-started-with-sampler) for more information." ] }, { 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/public/docs/images/guides/pubs/broadcasting.avif b/public/docs/images/guides/pubs/broadcasting.avif new file mode 100644 index 0000000000000000000000000000000000000000..e1f059942c07e05cdcfb8f63b7df2eea7bdd4234 GIT binary patch literal 657 zcmZQzV30{GsVqn=%S>Ycg51nBLl8SRGZDyVY|TwANd$=lfnr8VP7#F3z)+BxTmoam zXug8Xl3Xx{5lEV3=Hw@XcrFeMObj3q2F8^T8pvz`iU9$WE?gu9$hFAK%mX_EEGr7+ zq=J5 zE-lKl$}LDu2NOhUYC8@c^RzNkGIhlz?l~##41sUKVl+P^41v7wJfdRtO z$i&RTz{J|h%*NCX6q3p;N`?3xXdzI04oDF=bUx&!B$fyf1agKsfnGgeW zpT$FlFDGAJn62ckeCwj^PcyBJa~psDI@NK~T-GE-{bRd=Qj5vQa~o&syHBvruGBi7 zahrYOPmlCj4mt>&95VszvB zFXMweT$}cJT`}SKv*PngDN~>u*dcDXViYdKz-Qs`<%7W8b)r@oPxkMN_&O^tSk7|J zA%(f!CTsJ>p2wK~;1^#cETKN@<|SRve%qez-VYl-MXD^~^_qC=nS6k6TTEDF=dLnt S>zNuhj2u$7*=rs)Ndf>}j=2>8 literal 0 HcmV?d00001 From a4a993c87af8a8eb8c4b6651c5d1c542bd811b9f Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 12 Feb 2026 16:37:46 -0600 Subject: [PATCH 048/118] change to avif --- docs/guides/pubs.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 0e55842e131..3136859aeb7 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -109,7 +109,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/pubs/broadcasting.svg \"Visual representation of broadcasting\")" + "![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs/broadcasting.avif \"Visual representation of broadcasting\")" ] }, { From ba68516507393917ac2a9070440a6a2ac28daffd Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 13 Feb 2026 08:26:15 -0600 Subject: [PATCH 049/118] squeaky --- docs/guides/hello-world.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index 52d4d082761..314027fbe54 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -741,7 +741,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -755,7 +755,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3" + "version": "3.14.2" }, "widgets": { "application/vnd.jupyter.widget-state+json": { From 3e0e3a502b3ed0e164924e15d716e3ff8578ad1d Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 13 Feb 2026 11:09:28 -0600 Subject: [PATCH 050/118] rest api files --- docs/guides/_toc.json | 12 - docs/guides/estimator-examples.ipynb | 14 +- ...est-api.ipynb => estimator-rest-api.ipynb} | 265 +------ docs/guides/primitives-examples.ipynb | 706 ------------------ docs/guides/sampler-examples.ipynb | 10 - docs/guides/sampler-rest-api.ipynb | 386 ++++++++++ qiskit_bot.yaml | 8 +- 7 files changed, 413 insertions(+), 988 deletions(-) rename docs/guides/{primitives-rest-api.ipynb => estimator-rest-api.ipynb} (61%) delete mode 100644 docs/guides/primitives-examples.ipynb create mode 100644 docs/guides/sampler-rest-api.ipynb diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index d78a2d39034..51cc3d01504 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -371,10 +371,6 @@ "url": "/docs/guides/estimator-examples" }, { - "title": "BackendEstimator", - "url": "/docs/guides/estimator-rest-api" - }, - { "title": "REST API", "url": "/docs/guides/estimator-rest-api" } @@ -400,10 +396,6 @@ "url": "/docs/guides/sampler-examples" }, { - "title": "BackendSampler", - "url": "/docs/guides/sampler-rest-api" - }, - { "title": "REST API", "url": "/docs/guides/sampler-rest-api" } @@ -429,10 +421,6 @@ "url": "/docs/guides/executor-examples" }, { - "title": "BackendExecutor", - "url": "/docs/guides/executor-rest-api" - }, - { "title": "REST API", "url": "/docs/guides/executor-rest-api" } diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb index 5ce83396218..0592a2d6bdd 100644 --- a/docs/guides/estimator-examples.ipynb +++ b/docs/guides/estimator-examples.ipynb @@ -7,23 +7,13 @@ "source": [ "---\n", "title: Examples\n", - "description: Practical examples of using Estimator primitive in Qiskit Runtime.\n", + "description: Practical examples of using the Estimator primitive in Qiskit Runtime.\n", "---\n", "\n", "\n", "# Estimator 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", @@ -58,7 +48,7 @@ "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", + "The examples in this section illustrate some common ways to use Estimator. 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", diff --git a/docs/guides/primitives-rest-api.ipynb b/docs/guides/estimator-rest-api.ipynb similarity index 61% rename from docs/guides/primitives-rest-api.ipynb rename to docs/guides/estimator-rest-api.ipynb index a5755e68443..6bc8c934600 100644 --- a/docs/guides/primitives-rest-api.ipynb +++ b/docs/guides/estimator-rest-api.ipynb @@ -6,14 +6,14 @@ "metadata": {}, "source": [ "---\n", - "title: Primitives with REST API\n", - "description: How to use the Sampler and Estimator primitives with Qiskit Runtime REST API.\n", + "title: 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", - "# Primitives with REST API" + "# Estimator with the REST API" ] }, { @@ -31,23 +31,20 @@ "id": "3d9ef591-91fd-4a49-a065-5e2cda4d41be", "metadata": {}, "source": [ - "The steps in this topic describe how to run and configure primitive workloads with REST API, and demonstrate how to invoke them in any program of your choice.\n", + "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", - "\n", - "## Estimator primitive with REST API\n", - "\n", - "### 1. Initialize the account\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", + "## 2. Create a QASM circuit\n", "\n", "You need at least one circuit as the input to the Estimator primitive.\n", "\n", @@ -68,7 +65,7 @@ "\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", + "## 3. Run the quantum circuit using the Estimator V2 API\n", "\n", "\n", "\n", @@ -113,7 +110,7 @@ "\n", "\n", "\n", - "### 4. Check job status and get results\n", + "## 4. Check job status and get results\n", "\n", "Next, pass the `job_id` to the API:\n", "\n", @@ -142,7 +139,7 @@ "[{'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", + "## 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", @@ -150,12 +147,9 @@ "\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](./error-mitigation-and-suppression-techniques) topic.\n", "\n", + "### TREX + ZNE\n", "\n", - "\n", - "\n", - " \n", - "\n", - " ```python\n", + "```python\n", "import requests\n", "\n", "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", @@ -199,11 +193,9 @@ " print(f\"Error: {response.status_code}\")\n", "```\n", "\n", - " \n", - "\n", - " \n", + "### Dynamical Decoupling\n", "\n", - " ```python\n", + "```python\n", "import requests\n", "\n", "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", @@ -245,11 +237,9 @@ " print(f\"Error: {response.status_code}\")\n", "```\n", "\n", - " \n", + "### Twirling\n", "\n", - " \n", - "\n", - " ```python\n", + "```python\n", "import requests\n", "\n", "url = 'https://quantum.cloud.ibm.com/api/v1/jobs'\n", @@ -292,219 +282,7 @@ " print(f\"Error: {response.status_code}\")\n", "```\n", "\n", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "\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", - "\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. 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:\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", - "\n", - "The code snippets given below assume that the `qasm_string` has been transpiled to a new string `resulting_qasm`.\n", - "\n", - "\n", - "### 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", - "\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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm],[resulting_qasm,None,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(\"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-942fb30edced\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", - "# Get results for the first PUB\n", - "counts=res_dict['results'][0]['data']['c']['samples']\n", - "\n", - "print(counts[:20])\n", - "```\n", - "Output\n", - "```text\n", - "['0x3', '0x0', '0x2', '0x1', '0x0', '0x3', '0x0', '0x3', '0x1', '0x2', '0x2', '0x0', '0x2', '0x0', '0x3', '0x3', '0x2', '0x0', '0x1', '0x0']\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", - "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](./error-mitigation-and-suppression-techniques) topic.\n", - "\n", - "\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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", - " \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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", - "\n", - " \n", - "\n", - "\n", - "\n", - "\n", - "## Sampler primitive with REST API and parameterized circuits\n", + "## Parameterized circuits\n", "\n", "### 1. Initialize the account\n", "\n", @@ -563,12 +341,7 @@ "print(qasm_str)\n", "```\n", "\n", - "### 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/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", + "### 5. Run the quantum circuit using Estimator V2 API\n", "\n", "\n", "```python\n", @@ -586,7 +359,7 @@ " }\n", "\n", "job_input = {\n", - " 'program_id': 'sampler',\n", + " 'program_id': 'estimator',\n", " \"backend\": backend,\n", " \"params\": {\n", " # Choose one option: direct parameter transfer or through a dictionary\n", @@ -648,10 +421,8 @@ "\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](./transpile) section.\n", - " - [Migrate to the Qiskit Runtime V2 primitives.](/docs/guides/v2-primitives)\n", "" ] } diff --git a/docs/guides/primitives-examples.ipynb b/docs/guides/primitives-examples.ipynb deleted file mode 100644 index e3dc5e4afa1..00000000000 --- a/docs/guides/primitives-examples.ipynb +++ /dev/null @@ -1,706 +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", - "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": "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.13582342954159593\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.4873096446700508\n", - ">>> Standard errors for PUB 0: 1.3528950031716114\n", - ">>> Expectation values for PUB 1: -0.00390625\n", - ">>> Standard errors for PUB 1: 0.015347884419435263\n", - ">>> Expectation values for PUB 2: -0.02001953125\n", - ">>> Standard errors for PUB 2: 0.013797455737635134\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.0455093 0.98152862 0.82113463 0.60354133 0.29572641 0.01149883\n", - " -0.33110743 -0.60560522 -0.83322315 -0.96531231 -1.0257549 -0.95853095\n", - " -0.81081517 -0.61091237 -0.30221293 0.0035381 0.31371176 0.61061753\n", - " 0.83646641 0.97091431 1.03135689]\n", - " [ 0.03390682 0.31194271 0.620937 0.87391133 0.96973494 1.03872794\n", - " 0.94260949 0.82378821 0.56344283 0.28688115 -0.04570049 -0.37474403\n", - " -0.64540887 -0.87803912 -0.97887504 -1.03577952 -0.97268336 -0.83970967\n", - " -0.59705481 -0.29867482 0.0380346 ]\n", - " [ 0.00265358 -0.32992806 -0.59646512 -0.80934096 -0.96737621 -1.00128302\n", - " -0.94673728 -0.82703147 -0.59705481 -0.31341692 -0.00117937 0.29985419\n", - " 0.59469607 0.78486908 0.93346939 0.97622146 0.94732696 0.81199454\n", - " 0.60914332 0.28393273 -0.00678136]\n", - " [ 0.99656555 0.93553328 0.78398456 0.55872536 0.29749546 -0.04511081\n", - " -0.33523522 -0.62889773 -0.82201916 -0.95351864 -1.02634458 -0.96796589\n", - " -0.82054495 -0.57553135 -0.30103356 0.00265358 0.3104685 0.59705481\n", - " 0.83322315 0.94437854 0.99214292]]\n", - ">>> Standard errors: [[0.014353 0.01441151 0.01620648 0.0195418 0.019762 0.01515649\n", - " 0.02102523 0.02112359 0.0148494 0.01119219 0.01576623 0.01245824\n", - " 0.01239832 0.01501273 0.01821305 0.01776286 0.01500156 0.01635231\n", - " 0.01577367 0.01315371 0.01089558]\n", - " [0.01352805 0.01627835 0.01247646 0.01287866 0.01570182 0.01060924\n", - " 0.01590468 0.01620303 0.01530626 0.01619973 0.01918078 0.01379676\n", - " 0.01564971 0.01377673 0.01454324 0.01242184 0.01252201 0.01396738\n", - " 0.01326188 0.0145736 0.01795044]\n", - " [0.02029376 0.01610892 0.0161542 0.0157785 0.01385665 0.01113743\n", - " 0.01375237 0.01380922 0.0145974 0.01759484 0.01594193 0.02111719\n", - " 0.01521368 0.01365888 0.01188512 0.01353009 0.01195674 0.01446547\n", - " 0.01660987 0.01511225 0.01880871]\n", - " [0.01105161 0.01164476 0.01329858 0.01439545 0.01888747 0.01629201\n", - " 0.01405852 0.01406643 0.01088709 0.01275198 0.01281432 0.01333301\n", - " 0.01268483 0.01443594 0.01495655 0.01715532 0.01822699 0.01508936\n", - " 0.01435528 0.01340555 0.01295649]]\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.08045977011494253\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", - " > Another Expectation value: 0.02127659574468085\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: ['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": "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: ['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 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: ['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 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: ['1101100010101100001001110000100011110011000010110000010000001011000110000110010100011000101111011110010101101001000101010100010', '0010100100011100001011111101001010010000010010000100000011001010001110101011010000100011001010000101110101110110010000110001110', '1011000110110011011010001111001011111000011111111010010010011000000110000001000101001111001000010110000000011101010000111101101', '0101000010000101001011111010110011101000100101010011001000010000011010000010101000000001000100010100011100101001000101001011000', '1101010101011100000001100110111001000100110011110001110011000000110100011011100000010000001100001101011000000001010101001101001', '1111100011111010000000100011100110101000010101100100000110000110001011100000000101010110011110010010000100011110000010101010100', '1011011100110001000110100100110010101101110010100010011100001000001100010101101110010101100000001110000000111001001000000100010', '0100011011110111010010111011101010111010010011011110011001000010101110100100111010110001101100110001010100000101001000000111001', '0001110001110000001011101101010001001110000010100001000101100100110111001011100000101010011100011001110011100100000000010110001', '1010110110111000001100011100000100101000000001111110110010000110011100100100100010000101111110100110010010010101001011001000011']\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: ['0100010001111001111010000100101010011010000100010110100100010010010110001010101010000000110000010000001100100011000110101000001', '1101000100010000011100110101001110101100001000000000101001110110110010110110010010011100010000010001011000011100100000100000000', '1111101010100011010100000100010101111110011000000000010000010000101001010001100000100000100010000001100111000000111000111010000', '0101111100000110010101101100101110101011010100001001110101100010111100110011100001110101000000001000000000101000100000001000000', '1101001000000000011000010100111110101111001001110011100001100100100100000011110001001000001000010101111100001001110010110011100', '1100001000110110000111110110010010000100001000001001100011110001111100100101110010010111010010101100001010101011100100001010010', '0001001100010000000101101101101111000011101100101000111010000000000010010111011000100000011010100000100011100010110010010000001', '1010101100000000011000111101000011100101000110110000111111000001100010001110000101111111110110000000000000001000000010001110000', '1111111001001001001100010000101110110100001011011100010001100000100001010100111011000110100011110000001010101000010000000011000', '1011011010101100010101100001001000000010110001101000100001111010000100011100000000100111001001000001001001101000001000100000000']\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/sampler-examples.ipynb b/docs/guides/sampler-examples.ipynb index c290106594f..c352509c215 100644 --- a/docs/guides/sampler-examples.ipynb +++ b/docs/guides/sampler-examples.ipynb @@ -14,16 +14,6 @@ "# Sampler 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", diff --git a/docs/guides/sampler-rest-api.ipynb b/docs/guides/sampler-rest-api.ipynb new file mode 100644 index 00000000000..c1fb013d061 --- /dev/null +++ b/docs/guides/sampler-rest-api.ipynb @@ -0,0 +1,386 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0998165a-381f-4561-a79a-bf584aed9687", + "metadata": {}, + "source": [ + "---\n", + "title: REST API\n", + "description: How to use the Sampler primitive with the Qiskit Runtime REST API.\n", + "---\n", + "\n", + "\n", + "{/* cspell:ignore IIZII, XIZZZ, accum */}\n", + "\n", + "# Sampler with the REST API\n", + "\n", + "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", + "" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 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", + "\n", + "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)\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:\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", + "\n", + "The code snippets given below assume that the `qasm_string` has been transpiled to a new string `resulting_qasm`.\n", + "\n", + "\n", + "## 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). `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.\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", + "job_input = {\n", + " 'program_id': 'sampler',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [[resulting_qasm],[resulting_qasm,None,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(\"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-942fb30edced\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", + "# Get results for the first PUB\n", + "counts=res_dict['results'][0]['data']['c']['samples']\n", + "\n", + "print(counts[:20])\n", + "```\n", + "Output\n", + "```text\n", + "['0x3', '0x0', '0x2', '0x1', '0x0', '0x3', '0x0', '0x3', '0x1', '0x2', '0x2', '0x0', '0x2', '0x0', '0x3', '0x3', '0x2', '0x0', '0x1', '0x0']\n", + "```\n", + "\n", + "## 5. Work with Qiskit 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](./error-mitigation-and-suppression-techniques) topic.\n", + "\n", + "### Dynamical decoupling \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", + "job_input = {\n", + " 'program_id': 'sampler',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", + "```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", + "job_input = {\n", + " 'program_id': 'sampler',\n", + " \"backend\": backend,\n", + " \"params\": {\n", + " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", + "\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 Sampler V2 API\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': 'sampler',\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](./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/qiskit_bot.yaml b/qiskit_bot.yaml index d3681da7929..8ab1f3521e4 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -450,7 +450,13 @@ notifications: - "@jyu00" - "@ElePT" - "@beckykd" - "docs/guides/primitives-rest-api": + "docs/guides/sampler-rest-api": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" + - "@kaelynj" + "docs/guides/estimator-rest-api": - "@born-2learn" - "@HuangJunye" - "@pacomf" From 19ba71b4f84bc3d943240e55af22bc297057b0c5 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 16 Feb 2026 13:23:00 -0600 Subject: [PATCH 051/118] delete --- docs/guides/primitive-input-output.ipynb | 870 ----------------------- 1 file changed, 870 deletions(-) delete mode 100644 docs/guides/primitive-input-output.ipynb diff --git a/docs/guides/primitive-input-output.ipynb b/docs/guides/primitive-input-output.ipynb deleted file mode 100644 index 20d724462a9..00000000000 --- a/docs/guides/primitive-input-output.ipynb +++ /dev/null @@ -1,870 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "dbb193c8-d927-434c-a199-48de57c99694", - "metadata": {}, - "source": [ - "---\n", - "title: Primitive inputs and outputs\n", - "description: Understand the input and output format (including Primitive Unified Blocs or PUBs) of the primitives\n", - "---\n", - "\n", - "\n", - "# Primitive inputs and outputs" - ] - }, - { - "cell_type": "markdown", - "id": "33c719ad", - "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": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", - "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": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", - "metadata": {}, - "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Sampler and Estimator primitives, which execute 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 Sampler or Estimator primitives." - ] - }, - { - "cell_type": "markdown", - "id": "61903cfe-d221-4137-8324-9f0d3c1b517d", - "metadata": {}, - "source": [ - "\n", - "## Overview of PUBs\n", - "\n", - "When invoking a primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting -- the rules of which are described in a [following section](#broadcasting-rules).\n", - "\n", - "### Estimator PUB\n", - "For the Estimator primitive, the format of the PUB should 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", - " If you have two commuting observables in different PUBs but with the same circuit, they will not be estimated using the same measurement. Each PUB represents a different basis for measurement, and therefore, separate measurements are required for each PUB. To ensure that commuting observables are estimated using the same measurement, they must be grouped 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\n", - "\n", - "### Sampler PUB\n", - "For the Sampler primitive, the format of the PUB tuple contains 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": "a2dbc9bd-32d3-4351-979f-fbb4e36a5185", - "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": "f9235c64-5dfc-42bd-b864-17f2bcdf77b9", - "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", - " EstimatorV2 as Estimator,\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", - "\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": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "### 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", - "\n", - "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, - { - "cell_type": "markdown", - "id": "7a17dce0-1383-49c6-b9e4-46bf9a887fa6", - "metadata": {}, - "source": [ - "## Overview of primitive outputs\n", - "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\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 `PubResults`, one corresponding to each PUB).\n", - "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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:\n", - "\n", - "\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", - " \n", - " ```\n", - " └── PrimitiveResult\n", - " ├── PubResult[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", - " ├── PubResult[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", - "\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", - "Each `PubResult` possesses different formats and attributes based on the type of primitive that was used for the job. The specifics are explained below.\n", - "\n", - "### Estimator output\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", - "The below code snippet describes the `PrimitiveResult` (and associated `PubResult`) format for the job created above." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "960a78c7-3602-4c69-bdfa-18fd8ba993b6", - "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", - "[[ 2.61033270e-02 1.57811793e-01 2.73279631e-01 3.93154219e-01\n", - " 4.96978109e-01 5.64403131e-01 6.19015829e-01 5.87020956e-01\n", - " 5.81015744e-01 5.18313721e-01 4.86919628e-01 4.55922267e-01\n", - " 3.71964943e-01 2.99230087e-01 2.64673154e-01 2.26049005e-01\n", - " 2.50840594e-01 2.50338632e-01 2.87999744e-01 3.27494353e-01\n", - " 4.00758673e-01 4.51181323e-01 4.97859419e-01 5.38267572e-01\n", - " 5.69627751e-01 5.95433163e-01 5.70124764e-01 5.45724958e-01\n", - " 4.93744904e-01 4.38633730e-01 4.09916094e-01 3.02101254e-01\n", - " 2.86314557e-01 2.42592498e-01 2.24368037e-01 2.29529558e-01\n", - " 2.43252670e-01 3.20078025e-01 3.72117472e-01 4.32522899e-01\n", - " 4.71819874e-01 5.30908613e-01 5.83558738e-01 5.98398709e-01\n", - " 5.99607412e-01 5.46381986e-01 4.62289906e-01 3.50374667e-01\n", - " 2.40835776e-01 8.49414507e-02 -2.53415820e-02 -1.57631761e-01\n", - " -3.23568818e-01 -3.97950727e-01 -5.08237247e-01 -5.63735254e-01\n", - " -5.91936080e-01 -5.97432186e-01 -5.73211680e-01 -5.18990765e-01\n", - " -4.81090229e-01 -4.56660727e-01 -3.58717022e-01 -3.51148725e-01\n", - " -2.71202881e-01 -2.74871169e-01 -2.82607405e-01 -3.13729622e-01\n", - " -3.33342086e-01 -3.55340797e-01 -4.05858046e-01 -4.63932962e-01\n", - " -4.73146851e-01 -5.10671744e-01 -5.23830746e-01 -5.25307668e-01\n", - " -5.09966466e-01 -4.80614136e-01 -4.45589155e-01 -3.90413078e-01\n", - " -3.41992596e-01 -2.92493388e-01 -2.85495613e-01 -2.55897617e-01\n", - " -2.92314819e-01 -2.89891172e-01 -3.22990249e-01 -4.00687528e-01\n", - " -4.59942182e-01 -4.93605370e-01 -5.76605338e-01 -5.69945074e-01\n", - " -6.10879936e-01 -5.87897830e-01 -5.62457430e-01 -4.83199261e-01\n", - " -3.95323033e-01 -2.92337152e-01 -1.47252983e-01 -1.15860182e-02]\n", - " [ 4.61647727e-02 8.87784091e-02 1.04403409e-01 2.07386364e-01\n", - " 2.53551136e-01 3.44460227e-01 3.99857955e-01 4.20454545e-01\n", - " 4.88636364e-01 5.41193182e-01 5.93750000e-01 7.03125000e-01\n", - " 7.45028409e-01 7.59943182e-01 8.03977273e-01 8.38778409e-01\n", - " 8.92755682e-01 8.95596591e-01 9.63778409e-01 9.73011364e-01\n", - " 1.00639205e+00 1.03693182e+00 1.01988636e+00 1.04687500e+00\n", - " 1.03764205e+00 1.06178977e+00 1.04687500e+00 1.06178977e+00\n", - " 1.00781250e+00 1.02556818e+00 1.01207386e+00 9.28267045e-01\n", - " 9.36789773e-01 8.75710227e-01 8.40909091e-01 8.21022727e-01\n", - " 7.62784091e-01 7.79119318e-01 6.88210227e-01 6.42045455e-01\n", - " 5.81676136e-01 5.55397727e-01 4.72301136e-01 4.48153409e-01\n", - " 3.76420455e-01 3.25994318e-01 2.23721591e-01 1.32812500e-01\n", - " 7.74147727e-02 7.10227273e-04 -1.27840909e-02 -9.44602273e-02\n", - " -1.84659091e-01 -2.10937500e-01 -2.94744318e-01 -3.57954545e-01\n", - " -4.10511364e-01 -4.80823864e-01 -5.31250000e-01 -5.44744318e-01\n", - " -6.27130682e-01 -7.14488636e-01 -7.08096591e-01 -8.06107955e-01\n", - " -7.96164773e-01 -8.72159091e-01 -9.16193182e-01 -9.75142045e-01\n", - " -9.73721591e-01 -9.83664773e-01 -1.01988636e+00 -1.02343750e+00\n", - " -1.04900568e+00 -1.05539773e+00 -1.03338068e+00 -1.05610795e+00\n", - " -1.04190341e+00 -1.03977273e+00 -1.04332386e+00 -9.82954545e-01\n", - " -9.94318182e-01 -9.57386364e-01 -9.24715909e-01 -8.91335227e-01\n", - " -8.80681818e-01 -8.42329545e-01 -7.68465909e-01 -7.46448864e-01\n", - " -7.09517045e-01 -5.99431818e-01 -6.07244318e-01 -5.00000000e-01\n", - " -4.63778409e-01 -3.70028409e-01 -3.22443182e-01 -2.50710227e-01\n", - " -1.97443182e-01 -1.56250000e-01 -7.31534091e-02 -3.19602273e-02]\n", - " [ 6.04188122e-03 2.26845177e-01 4.42155853e-01 5.78922073e-01\n", - " 7.40405081e-01 7.84346035e-01 8.38173704e-01 7.53587367e-01\n", - " 6.73395125e-01 4.95434260e-01 3.80089255e-01 2.08719533e-01\n", - " -1.09852386e-03 -1.61483007e-01 -2.74630965e-01 -3.86680398e-01\n", - " -3.91074494e-01 -3.94919327e-01 -3.87778922e-01 -3.18022657e-01\n", - " -2.04874700e-01 -1.34569173e-01 -2.41675249e-02 2.96601442e-02\n", - " 1.01613457e-01 1.29076553e-01 9.33745280e-02 2.96601442e-02\n", - " -2.03226914e-02 -1.48300721e-01 -1.92241675e-01 -3.24064538e-01\n", - " -3.64160659e-01 -3.90525232e-01 -3.92173018e-01 -3.61963611e-01\n", - " -2.76278750e-01 -1.38963268e-01 5.60247168e-02 2.23000343e-01\n", - " 3.61963611e-01 5.06419499e-01 6.94816341e-01 7.48644010e-01\n", - " 8.22794370e-01 7.66769653e-01 7.00858222e-01 5.67936835e-01\n", - " 4.04256780e-01 1.69172674e-01 -3.78990731e-02 -2.20803296e-01\n", - " -4.62478544e-01 -5.84963955e-01 -7.21730175e-01 -7.69515963e-01\n", - " -7.73360796e-01 -7.14040508e-01 -6.15173361e-01 -4.93237212e-01\n", - " -3.35049777e-01 -1.98832818e-01 -9.33745280e-03 1.03810505e-01\n", - " 2.53759011e-01 3.22416752e-01 3.50978373e-01 3.47682801e-01\n", - " 3.07037418e-01 2.72983179e-01 2.08170271e-01 9.55715757e-02\n", - " 1.02711981e-01 3.40542396e-02 -1.42808102e-02 5.49261929e-03\n", - " 2.19704772e-02 7.85444559e-02 1.52145554e-01 2.02128390e-01\n", - " 3.10332990e-01 3.72399588e-01 3.53724682e-01 3.79539993e-01\n", - " 2.96052180e-01 2.62547202e-01 1.22485410e-01 -5.49261929e-02\n", - " -2.10367319e-01 -3.87778922e-01 -5.45966358e-01 -6.39890148e-01\n", - " -7.57981462e-01 -8.05767250e-01 -8.02471679e-01 -7.15688294e-01\n", - " -5.93202884e-01 -4.28424305e-01 -2.21352558e-01 8.78819087e-03]]\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", - "print(\n", - " f\"The expectation values measured from this PUB are: \\n{result[0].data.evs}\"\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", - "metadata": {}, - "source": [ - "#### 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": "df8faff8-4558-4f72-bd80-8615ce1ce3c5", - "metadata": {}, - "source": [ - "### Sampler output\n", - "\n", - "When a Sampler job is completed successfully, the returned [`PrimitiveResult`](/docs/api/qiskit/qiskit.primitives.PrimitiveResult) object contains a list of [`SamplerPubResult`](/docs/api/qiskit/qiskit.primitives.SamplerPubResult)s, one per PUB. The data bins of these `SamplerPubResult` objects are dict-like objects that contain one `BitArray` per `ClassicalRegister` in the circuit.\n", - "\n", - "The `BitArray` class is a container for ordered shot data. In more detail, 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", - "\n", - "As a first example, let us look at the following ten-qubit circuit:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "5c787874-1125-4381-b55e-7663caa92ec8", - "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", - "[[ 0 128]\n", - " [ 0 128]\n", - " [ 3 255]\n", - " ...\n", - " [ 3 255]\n", - " [ 2 1]\n", - " [ 3 128]]\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": "c8f3cd8f-4f43-448b-b8bc-870c3b03797f", - "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": 5, - "id": "d152f7ca-daf3-4c24-9595-10d077de8f08", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Counts: {'0010000000': 79, '1111111111': 999, '1111111010': 11, '1111000000': 11, '0000000000': 1404, '0000000001': 160, '0000100000': 27, '1111111110': 181, '0010000001': 5, '0001111111': 65, '1111100001': 3, '1110111111': 30, '1111111101': 16, '1111111100': 29, '1101100000': 3, '0100000000': 54, '0010111111': 3, '0000000010': 54, '0010111110': 1, '0000000011': 29, '0100000110': 1, '0111111111': 45, '1111100000': 33, '1100000000': 43, '1111110111': 25, '1111111011': 49, '1111111000': 8, '1011111111': 54, '0000001000': 10, '0000001111': 38, '0001110000': 3, '1011111110': 11, '0011111110': 12, '0000010000': 20, '0010111011': 1, '1111010000': 3, '0000011111': 18, '0110000000': 6, '0000000111': 25, '1110000000': 66, '1111011111': 7, '1101111111': 15, '0000000100': 14, '1011111011': 5, '1100011111': 2, '1111101111': 31, '1111110000': 35, '0000110000': 4, '1111101110': 10, '0111000111': 1, '0010011110': 1, '0111111110': 10, '0011111111': 43, '0000100001': 2, '0010000111': 1, '0000011110': 4, '0100000011': 1, '1110100000': 3, '1100000111': 2, '0101111111': 3, '0000001011': 4, '0000000110': 10, '0011101111': 2, '0010000100': 2, '1110110111': 2, '1011100000': 1, '0000111110': 6, '1001111111': 2, '0001101111': 6, '1110000001': 7, '1101111110': 6, '0000001110': 8, '0111101111': 3, '1111110010': 2, '1111110101': 2, '1110001111': 1, '0001111110': 9, '1100111111': 5, '1110001000': 4, '0001111011': 2, '1111111001': 3, '1111110110': 4, '1110000010': 2, '0010000011': 1, '1010001000': 1, '0001000000': 5, '0010000110': 1, '1111101000': 3, '1100000010': 2, '1000000000': 6, '0010001011': 1, '1100010000': 1, '0100001111': 2, '1111110001': 7, '0111110000': 1, '1111100111': 1, '0000011101': 1, '1111101001': 1, '0100000001': 1, '1111000111': 2, '0110000111': 1, '1111101100': 3, '0001111010': 2, '0110111111': 2, '1100000001': 3, '1010111111': 2, '0111100000': 1, '1100000011': 1, '0000010111': 1, '0010001111': 1, '0111000000': 2, '1010000000': 2, '1011110000': 2, '1101101110': 1, '1111100110': 1, '0000111111': 13, '1110110010': 1, '0000100011': 1, '1110110000': 1, '0100011111': 1, '0000010110': 1, '0000001100': 1, '1110111110': 6, '0101111110': 1, '0001011111': 1, '1101111011': 1, '0111111100': 1, '0100011110': 2, '1101110000': 1, '0001111101': 1, '1101011111': 1, '1101000000': 1, '1110000011': 1, '0010010001': 1, '0100111110': 1, '1110101110': 1, '1110110001': 1, '0011101100': 1, '1000000011': 2, '0011110111': 2, '0100000100': 2, '0100100000': 1, '1011101111': 1, '0100000010': 1, '0010100001': 1, '0100111111': 1, '0010000010': 2, '0100101111': 1, '1111100011': 2, '1111110100': 1, '0000011011': 2, '1110010000': 1, '1001110111': 1, '1110000101': 1, '0100000111': 3, '0011110000': 1, '1110010001': 1, '0001111100': 2, '0100010000': 1, '1111100010': 1, '1110111101': 1, '0000010001': 3, '0000101110': 1, '0000111011': 1, '1110000111': 1, '0011111101': 1, '0011111010': 1, '1111011110': 4, '1110101111': 1, '1111101011': 1, '0001111000': 1, '0000010010': 1, '0000101111': 1, '0001110111': 2, '1101110111': 1, '0111111011': 1, '0010111100': 1, '1110111011': 1, '0000111000': 1, '1011111101': 1, '0000011000': 1, '0000100100': 1, '0110000001': 1, '1111101101': 1, '0111111101': 1, '0101101011': 1, '1011110011': 1, '0100001000': 1, '1111001111': 1, '0000001010': 1, '1011111100': 1, '1100100000': 1, '1111110011': 1, '1000000001': 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": "514e0ac0-b42e-4f26-b608-c223dfed7915", - "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": 6, - "id": "4602925e-c69d-45b2-9e06-fe8bffe0a797", - "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": "a65c6078-c5c2-4087-b57a-5680148ce333", - "metadata": {}, - "source": [ - "#### Leveraging `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": 7, - "id": "3802cf7e-4d71-4e1f-88f5-3beb294fc163", - "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", - "[[0]\n", - " [0]\n", - " [0]\n", - " ...\n", - " [0]\n", - " [0]\n", - " [1]]\n", - "\n", - "The shape of register `beta` is (4096, 2).\n", - "The bytes in register `beta`, shot by shot:\n", - "[[ 0 64]\n", - " [ 0 0]\n", - " [ 0 0]\n", - " ...\n", - " [ 0 1]\n", - " [ 0 0]\n", - " [ 1 255]]\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", - "[[0]\n", - " [0]\n", - " [0]\n", - " ...\n", - " [1]\n", - " [0]\n", - " [7]]\n", - "\n", - "The shape of `beta` after shot-wise slicing is (5, 2).\n", - "The bytes in `beta` after shot-wise slicing:\n", - "[[ 0 64]\n", - " [ 0 0]\n", - " [ 0 0]\n", - " [ 0 123]\n", - " [ 1 255]]\n", - "\n", - "Exp. val. for observable `SparsePauliOp(['ZZZZZZZZZ'],\n", - " coeffs=[1.+0.j])` is: 0.0751953125\n", - "Exp. val. for observable `SparsePauliOp(['IIIIIIIIZ'],\n", - " coeffs=[1.+0.j])` is: 0.07666015625\n", - "\n", - "The shape of the merged results is (4096, 2).\n", - "The bytes of the merged results:\n", - "[[ 0 128]\n", - " [ 0 0]\n", - " [ 0 0]\n", - " ...\n", - " [ 0 2]\n", - " [ 0 0]\n", - " [ 3 255]]\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": "f5840476-04ec-4d3b-bdb9-d166ccd8cd11", - "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": 8, - "id": "68268c70-d76a-47b9-af6d-5cfe7966abae", - "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": "2f26ff75-e1ba-45ef-97c1-c5dde36400cf", - "metadata": {}, - "source": [ - "For Sampler jobs, you can also review the result metadata to understand when certain data was run; this is called the [_execution span._](monitor-job#execution-spans)" - ] - } - ], - "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 -} From 50c7b1f354e5f88026a7228d43e3173f88a8b556 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 16 Feb 2026 13:34:29 -0600 Subject: [PATCH 052/118] title mismatches are ok --- scripts/config/allowLists.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index 8b5e245ab38..373e3322612 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -26,11 +26,14 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/estimator-examples.ipynb", "docs/guides/estimator-input-output.ipynb", "docs/guides/estimator-options.ipynb", + "docs/guides/estimator-rest-api.ipynb", "docs/guides/executor-examples.ipynb", "docs/guides/executor-input-output.ipynb", + "docs/guides/executor-rest-api.ipynb", "docs/guides/get-started-with-sampler.ipynb", "docs/guides/pubs.ipynb", "docs/guides/sampler-examples.ipynb", + "docs/guides/sampler-rest-api.ipynb", "docs/guides/sampler-input-output.ipynb", "docs/guides/sampler-options.ipynb", "docs/guides/get-started-with-estimator.ipynb", From 1a7017300e471ace9d62e87248f81ef23ee0f263 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 16 Feb 2026 16:18:40 -0600 Subject: [PATCH 053/118] Add broadcasting topics --- docs/guides/_toc.json | 10 +- docs/guides/broadcasting.mdx | 52 ++++ docs/guides/directed-execution-model.mdx | 2 +- docs/guides/estimator-broadcasting.mdx | 83 ++++++ docs/guides/executor-broadcasting.mdx | 312 +++++++++++++++++++++++ docs/guides/executor-examples.ipynb | 12 +- docs/guides/executor-input-output.ipynb | 4 +- docs/guides/pubs.ipynb | 126 +-------- qiskit_bot.yaml | 24 ++ scripts/config/allowLists.ts | 3 + 10 files changed, 488 insertions(+), 140 deletions(-) create mode 100644 docs/guides/broadcasting.mdx create mode 100644 docs/guides/estimator-broadcasting.mdx create mode 100644 docs/guides/executor-broadcasting.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index c357c5559e6..0b4983297a5 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -349,7 +349,11 @@ }, { "title": "Introduction to PUBs", - "url": "/docs/guides/ppubs" + "url": "/docs/guides/pubs" + }, + { + "title": "Introduction to broadcasting", + "url": "/docs/guides/broadcasting" }, { "title": "Estimator", @@ -363,6 +367,10 @@ "url": "/docs/guides/estimator-input-output" }, { + "title": "Broadcasting", + "url": "/docs/guides/estimator-broadcasting" + }, + { "title": "Options", "url": "/docs/guides/estimator-options" }, diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx new file mode 100644 index 00000000000..89befc0a7e9 --- /dev/null +++ b/docs/guides/broadcasting.mdx @@ -0,0 +1,52 @@ +--- +title: Broadcasting +description: How the Executor handles array inputs and outputs using broadcasting semantics + +--- + +# Executor broadcasting semantics +This guide explains how the executor handles array inputs and outputs using broadcasting semantics. +Understanding these concepts will help you efficiently sweep over parameter values, combine +multiple experimental configurations, and interpret the shape of returned data. + +## Quick start example + +Before explaining the details, here's a simple example that demonstrates the core idea. The following example sets up a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item. The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs. + +```python +import numpy as np +from qiskit.circuit import Parameter, QuantumCircuit +from qiskit_ibm_runtime.quantum_program import QuantumProgram + +# A circuit with 3 parameters +circuit = QuantumCircuit(3) +circuit.rx(Parameter("a"), 0) +circuit.rx(Parameter("b"), 1) +circuit.rx(Parameter("c"), 2) +circuit.measure_all() + +# 5 different parameter configurations (shape: 5 configurations × 3 parameters) +parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3) + +program = QuantumProgram(shots=1024) +program.append(circuit, circuit_arguments=parameter_values) + +# Run and get results +result = executor.run(program).result() + +# result is a list with one entry per program item +# result[0] is a dict mapping classical register names to data arrays +# Output bool arrays have shape (5, 1024, 3) +# 5 = number of parameter configurations +# 1024 = number of shots +# 3 = bits in the classical register +result[0]["meas"] +``` + + + +## Next steps + + + - + diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index 7c2b0e238d1..66ae63463af 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -52,7 +52,7 @@ To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/sam 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. -The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output) 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. +The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to [Get started with Executor](/docs/guides/get-started-executor) for more information. ### NoiseLearnerV3 diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx new file mode 100644 index 00000000000..af76dffb53a --- /dev/null +++ b/docs/guides/estimator-broadcasting.mdx @@ -0,0 +1,83 @@ +--- +title: Broadcasting +description: How the Estimator handles array inputs and outputs using broadcasting semantics + +--- + +# Executor broadcasting semantics +When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics. + +Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: + + +Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates. + +- *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array. + +- *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array. + +- *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output. + +- *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. + +![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs/broadcasting.avif "Visual representation of broadcasting") + +```python +# Broadcast single observable +parameter_values = np.random.uniform(size=(5,)) # shape (5,) +observables = SparsePauliOp("ZZZ") # shape () +# >> pub result has shape (5,) + +# Zip +parameter_values = np.random.uniform(size=(5,)) # shape (5,) +observables = [ + SparsePauliOp(pauli) for pauli in ["III", "XXX", "YYY", "ZZZ", "XYZ"] +] # shape (5,) +# >> pub result has shape (5,) + +# Outer/Product +parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6) +observables = [ + [SparsePauliOp(pauli)] for pauli in ["III", "XXX", "YYY", "ZZZ"] +] # shape (4, 1) +# >> pub result has shape (4, 6) + +# Standard nd generalization +parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6) +observables = [ + [ + [SparsePauliOp(["XII"])], + [SparsePauliOp(["IXI"])], + [SparsePauliOp(["IIX"])], + ], + [ + [SparsePauliOp(["ZII"])], + [SparsePauliOp(["IZI"])], + [SparsePauliOp(["IIZ"])], + ], +] # shape (2, 3, 1) +# >> pub result has shape (2, 3, 6) +``` + + +Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape: + +```text +a = SparsePauliOp("Z") # shape () +b = SparsePauliOp("IIIIZXYIZ") # shape () +c = SparsePauliOp.from_list(["XX", "XY", "IZ"]) # shape () +``` + +The following lists of operators, while equivalent in terms of information contained, have different shapes: + +```text +list1 = SparsePauliOp.from_list(["XX", "XY", "IZ"]) # shape () +list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] # shape (3, ) +``` + + +## Next steps + + + - See the [broadcasting guide](/docs/guides/broadcasting) for an overview of broadcasting. + diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx new file mode 100644 index 00000000000..d4555a7ace7 --- /dev/null +++ b/docs/guides/executor-broadcasting.mdx @@ -0,0 +1,312 @@ +--- +title: Broadcasting +description: How the Executor handles array inputs and outputs using broadcasting semantics + +--- + +# Executor broadcasting semantics +The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine +multiple experimental configurations, and interpret the shape of returned data. + +## Quick start example + +This example demonstrates the core idea. It creates a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item. + +The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs. + +```python +import numpy as np +from qiskit.circuit import Parameter, QuantumCircuit +from qiskit_ibm_runtime.quantum_program import QuantumProgram + +# A circuit with 3 parameters +circuit = QuantumCircuit(3) +circuit.rx(Parameter("a"), 0) +circuit.rx(Parameter("b"), 1) +circuit.rx(Parameter("c"), 2) +circuit.measure_all() + +# 5 different parameter configurations (shape: 5 configurations × 3 parameters) +parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3) + +program = QuantumProgram(shots=1024) +program.append(circuit, circuit_arguments=parameter_values) + +# Run and get results +result = executor.run(program).result() + +# result is a list with one entry per program item +# result[0] is a dict mapping classical register names to data arrays +# Output bool arrays have shape (5, 1024, 3) +# 5 = number of parameter configurations +# 1024 = number of shots +# 3 = bits in the classical register +result[0]["meas"] +``` + +## Intrinsic and extrinsic axes + +Broadcasting only applies to _extrinsic_ axes. The intrinsic axes are always preserved as specified. + +- **Intrinsic axes** (rightmost): Determined by the data type. For example, if your circuit + has three parameters, then parameter values require three numbers, giving an intrinsic shape + of ``(3,)``. + +- **Extrinsic axes** (leftmost): Your sweep dimensions. These define how many configurations you + want to run. + +| Input type | Intrinsic shape | Example full shape | +|:----------------------------------------:|:---------------:|:---------------------------------------------------:| +| Parameter values (n parameters) | (n,) | (5, 3) for five configurations and three parameters | +| Scalar inputs (for example, noise scale) | () | (4,) for four configurations | +| Observables (if applicable) | varies | Depends on observable type | + +### Example + +Consider a circuit with two parameters that you want to sweep over a 4x3 grid of configurations, varying both parameter values and a noise scale factor: + +```python +import numpy as np + +# Parameter values: 4 configurations along axis 0, intrinsic shape (2,) +# Full shape: (4, 1, 2) - the "1" allows broadcasting with noise_scale +parameter_values = np.array([ + [[0.1, 0.2]], + [[0.3, 0.4]], + [[0.5, 0.6]], + [[0.7, 0.8]], +]) # shape (4, 1, 2) + +# Noise scale: 3 configurations, intrinsic shape () (scalar) +# Full shape: (3,) +noise_scale = np.array([0.8, 1.0, 1.2]) # shape (3,) + +# Extrinsic shapes: (4, 1) and (3,) → broadcast to (4, 3) +# Result: 12 total configurations in a 4×3 grid + +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": parameter_values, + "noise_scale.mod_ref1": noise_scale, + }, +) +``` + +The shapes are as follows: + +| Input | Full shape | Extrinsic shape | Intrinsic shape | +|:------------------:|:----------:|:---------------:|:---------------:| +| `parameter_values` | (4, 1, 2) | (4, 1) | (2,) | +| `noise_scale` | (3,) | (3,) | () | +| Broadcast | None | (4, 3) | None | + +## Output array shapes + +Output arrays follow the same extrinsic/intrinsic pattern: + +- **Extrinsic shape:** Matches the broadcast shape of all inputs +- **Intrinsic shape:** Determined by the output type + +The most common output is bitstring data from measurements, which is +formatted as an array of boolean values: + +| Output type | Intrinsic shape | Description | +|:-----------------------:|:----------------------:|:--------------------------------:| +| Classical register data | (num_shots, creg_size) | Bitstring data from measurements | +| Expectation values | () or (n_obs,) | Scalar or per-observable | + +### Example + +If you provide inputs with extrinsic shapes ``(4, 1)`` and ``(3,)``, the broadcast extrinsic +shape is ``(4, 3)``. For a circuit with 1024 shots and a 3-bit classical register: + +```python +# Input extrinsic shapes: (4, 1) and (3,) → (4, 3) +# Output for classical register "meas": +# extrinsic: (4, 3) +# intrinsic: (1024, 3) - shots × bits +# full shape: (4, 3, 1024, 3) + +result = executor.run(program).result() +meas_data = result[0]["meas"] # result[0] for first program item +print(meas_data.shape) # (4, 3, 1024, 3) + +# Access a specific configuration +config_2_1 = meas_data[2, 1, :, :] # shape (1024, 3) +``` + + +Each configuration receives the full shot count specified in the quantum program. Shots are **not** divided among configurations. For example, if you request 1024 shots and have 10 configurations, each configuration runs 1024 shots (10,240 total shots executed). + + +## Randomization and the ``shape`` parameter + +When using a [samplex,](/docs/guides/directed-execution-model) each element of the extrinsic shape corresponds to an independent circuit +execution. The samplex typically injects randomness (for example, twirling gates) into each +execution, so even without explicitly requesting multiple randomizations, each element naturally +receives its own random realization. + +The ``shape`` parameter lets you augment the extrinsic shape for the item, effectively letting you +add axes that correspond specifically to randomizing the same configuration many times. It must be +broadcastable from the shape implicit in your ``samplex_arguments``. Axes where ``shape`` exceeds +the implicit shape enumerate additional independent randomizations. + +### No explicit randomization axes + +If you omit ``shape`` (or set it to match your input shapes), you get one execution per +input configuration. Each execution is still randomized by the samplex, but with only a +single random realization you don't benefit from averaging over multiple randomizations. + + +If you're used to enabling twirling with a simple flag like ``twirling=True``, +the Executor requires you to explicitly request multiple randomizations with the ``shape`` argument to +allow your post-processing routines to get the benefits of averaging over multiple +randomizations. A single randomization (the default when ``shape`` is omitted) applies +random gates but typically offers no advantage over running the base circuit without +randomization. + + +The following example demonstrates the default behavior: + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + # shape defaults to (10,) - one randomized execution per config +) +# Output shape for "meas": (10, num_shots, creg_size) +``` + +### Single randomization axis + +To run multiple randomizations per configuration, extend the shape with additional axes. +For example, the following code runs 20 randomizations for each of 10 parameter configurations: + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + shape=(20, 10), # 20 randomizations × 10 configurations +) +# Output shape for "meas": (20, 10, num_shots, creg_size) +``` + +### Multiple randomization axes + +You can organize randomizations into a multi-dimensional grid. This is useful for structured +analysis, for example, separating randomizations by type or grouping them for statistical processing. + +Here, the input extrinsic shape ``(10,)`` broadcasts to the requested shape ``(2, 14, 10)``, +with axes 0 and 1 filled by independent randomizations. + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + shape=(2, 14, 10), # 2×14=28 randomizations per configuration, 10 configurations +) +# Output shape for "meas": (2, 14, 10, num_shots, creg_size) +``` + +### How `shape` and input shapes interact + +The ``shape`` parameter must be broadcastable *from* your input extrinsic shapes. This means: + +- Input shapes with size-1 dimensions can expand to match ``shape``. +- Input shapes must align from the right with ``shape``. +- Axes in ``shape`` that exceed the input dimensions enumerate randomizations. + +Note that ``shape`` can contain size-1 dimensions +that expand to match input dimensions, as is illustrated in the last row of the following table. + +Examples: + +| Input extrinsic | shape | Result | +|:---------------:|:----------:|:-----------------------------------------------------------------:| +| (10,) | (10,) | 10 configurations, 1 randomization each | +| (10,) | (5, 10) | 10 configurations, 5 randomizations each | +| (10,) | (2, 3, 10) | 10 configurations, 2×3=6 randomizations each | +| (4, 1) | (4, 5) | 4 configurations, 5 randomizations each | +| (4, 3) | (2, 4, 3) | 4×3=12 configurations, 2 randomizations each | +| (4, 3) | (2, 1, 3) | 4×3=12 configurations, 2 randomizations each (the 1 expands to 4) | + + + +### Indexing into results + +With randomization axes, you can index into specific randomization/parameter combinations: + +```python +# Using shape=(2, 14, 10) with input extrinsic shape (10,) +result = executor.run(program).result() +meas_data = result[0]["meas"] # shape (2, 14, 10, 1024, 3) + +# Get all shots for randomization (0, 7) and parameter config 3 +specific = meas_data[0, 7, 3, :, :] # shape (1024, 3) + +# Average over all randomizations for parameter config 5 on bit 2 +averaged = meas_data[:, :, 5, :, 2].mean(axis=(0, 1)) +``` + +## Common patterns + +### Sweeping a single parameter +To sweep one parameter while holding others fixed: + +```python + + # Circuit has 3 parameters, sweep first one over 20 values + sweep_values = np.linspace(0, 2*np.pi, 20) + fixed_values = [0.5, 0.3] + + parameter_values = np.column_stack([ + sweep_values, + np.full(20, fixed_values[0]), + np.full(20, fixed_values[1]), + ]) # shape (20, 3) +``` + +### Creating a 2D grid sweep +To create a grid over two parameters: + +```python + +# Sweep param 0 over 10 values, param 1 over 8 values, param 2 fixed +p0 = np.linspace(0, np.pi, 10)[:, np.newaxis, np.newaxis] # (10, 1, 1) +p1 = np.linspace(0, np.pi, 8)[np.newaxis, :, np.newaxis] # (1, 8, 1) +p2 = np.array([[[0.5]]]) # (1, 1, 1) + +parameter_values = np.broadcast_arrays(p0, p1, p2) +parameter_values = np.stack(parameter_values, axis=-1).squeeze() # (10, 8, 3) + +# Extrinsic shape: (10, 8), intrinsic shape: (3,) +``` + +### Combining multiple inputs + +When combining inputs with different intrinsic shapes, align extrinsic dimensions using +size-1 axes: + +```python +# 4 parameter configurations, 3 noise scales → 4×3 = 12 total configurations +parameter_values = np.random.rand(4, 1, 2) # extrinsic (4, 1), intrinsic (2,) +noise_scale = np.array([0.8, 1.0, 1.2]) # extrinsic (3,), intrinsic () + +# Broadcasted extrinsic shape: (4, 3) +``` +## Next steps + + + - Review the overview of [broadcasting.](/docs/guides/broadcasting) + diff --git a/docs/guides/executor-examples.ipynb b/docs/guides/executor-examples.ipynb index b1067701334..dad2bed3080 100644 --- a/docs/guides/executor-examples.ipynb +++ b/docs/guides/executor-examples.ipynb @@ -14,16 +14,6 @@ "# Executor 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", @@ -58,7 +48,7 @@ "id": "bae32e60", "metadata": {}, "source": [ - "The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up.](install-qiskit)\n", + "The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up](install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model)\n", "\n", "### Run a single experiment\n", "\n", diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb index 5f0f965ef33..abf622fd6f1 100644 --- a/docs/guides/executor-input-output.ipynb +++ b/docs/guides/executor-input-output.ipynb @@ -68,7 +68,7 @@ "\n", "Each of these items, including instructions to add them to a `QuantumProgram` is explained in more detail below.\n", "\n", - "The following cell initializes a `QuantumProgram` and specifies to perform 1024 shots for every configuration of each item in the program. Then a version of the target circuit with set parameters, transpiled according to the backend's ISA, is appended." + "The following cell initializes a `QuantumProgram` and specifies that it should run 1024 shots for every configuration of each item in the program. Then it appends a version of the target circuit with set parameters, transpiled according to the backend's ISA." ] }, { @@ -113,7 +113,7 @@ "id": "f49d211f-36b4-489d-9e0e-d10aab5e195f", "metadata": {}, "source": [ - "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (namely 1024 per set of parameter values)." + "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (1024 per set of parameter values)." ] }, { diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 3136859aeb7..841270eb2a6 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -53,131 +53,6 @@ "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting." ] }, - { - "cell_type": "markdown", - "id": "92e5f627-e4e9-433b-8fce-e25dff68bdef", - "metadata": {}, - "source": [ - "## 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", - "\n", - "Rules:\n", - "\n", - "* Input arrays do not need to have the same number of dimensions.\n", - " * The resulting array will have the same number of dimensions as the input array with the largest dimension.\n", - " * The size of each dimension is the largest size of the corresponding dimension.\n", - " * Missing dimensions are assumed to have size one.\n", - "* Shape comparisons start with the rightmost dimension and continue to the left.\n", - "* Two dimensions are compatible if their sizes are equal or if one of them is 1.\n", - "\n", - "Examples of array pairs that broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 1\n", - "A2 (2d array): 3 x 5\n", - "Result (2d array): 3 x 5\n", - "\n", - "\n", - "A1 (3d array): 11 x 2 x 7\n", - "A2 (3d array): 11 x 1 x 7\n", - "Result (3d array): 11 x 2 x 7\n", - "```\n", - "\n", - "Examples of array pairs that do not broadcast:\n", - "\n", - "```text\n", - "A1 (1d array): 5\n", - "A2 (1d array): 3\n", - "\n", - "A1 (2d array): 2 x 1\n", - "A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5.\n", - "```\n", - "\n", - "`EstimatorV2` returns one expectation value estimate for each element of the broadcasted shape.\n", - "\n", - "Here are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows:\n", - "\n", - "\n", - "Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates.\n", - "\n", - " - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array.\n", - "\n", - " - *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array.\n", - "\n", - " - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output.\n", - "\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/pubs/broadcasting.avif \"Visual representation of broadcasting\")" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "3cdc6e07-cc70-494b-84ef-f74585b6a201", - "metadata": {}, - "outputs": [], - "source": [ - "# Broadcast single observable\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = SparsePauliOp(\"ZZZ\") # shape ()\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Zip\n", - "parameter_values = np.random.uniform(size=(5,)) # shape (5,)\n", - "observables = [\n", - " SparsePauliOp(pauli) for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\", \"XYZ\"]\n", - "] # shape (5,)\n", - "# >> pub result has shape (5,)\n", - "\n", - "# Outer/Product\n", - "parameter_values = np.random.uniform(size=(1, 6)) # shape (1, 6)\n", - "observables = [\n", - " [SparsePauliOp(pauli)] for pauli in [\"III\", \"XXX\", \"YYY\", \"ZZZ\"]\n", - "] # shape (4, 1)\n", - "# >> pub result has shape (4, 6)\n", - "\n", - "# Standard nd generalization\n", - "parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6)\n", - "observables = [\n", - " [\n", - " [SparsePauliOp([\"XII\"])],\n", - " [SparsePauliOp([\"IXI\"])],\n", - " [SparsePauliOp([\"IIX\"])],\n", - " ],\n", - " [\n", - " [SparsePauliOp([\"ZII\"])],\n", - " [SparsePauliOp([\"IZI\"])],\n", - " [SparsePauliOp([\"IIZ\"])],\n", - " ],\n", - "] # shape (2, 3, 1)\n", - "# >> pub result has shape (2, 3, 6)" - ] - }, - { - "cell_type": "markdown", - "id": "a376cc24-04f3-43a6-921b-543f74ee72ca", - "metadata": {}, - "source": [ - "\n", - "Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape:\n", - "\n", - "```text\n", - "a = SparsePauliOp(\"Z\") # shape ()\n", - "b = SparsePauliOp(\"IIIIZXYIZ\") # shape ()\n", - "c = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "```\n", - "\n", - "The following lists of operators, while equivalent in terms of information contained, have different shapes:\n", - "\n", - "```text\n", - "list1 = SparsePauliOp.from_list([\"XX\", \"XY\", \"IZ\"]) # shape ()\n", - "list2 = [SparsePauliOp(\"XX\"), SparsePauliOp(\"XY\"), SparsePauliOp(\"IZ\")] # shape (3, )\n", - "```\n", - "" - ] - }, { "cell_type": "markdown", "id": "9d2e7be3-082c-4a8a-b29b-54349fa5fba9", @@ -188,6 +63,7 @@ "\n", "- Learn about [Estimator input and output](/docs/guides/estimator-input-output) in depth.\n", "- Learn about [Sampler input and output](/docs/guides/sampler-input-output) in depth.\n", + "- Learn about [broadcasting.](/docs/guides/broadcasting)\n", "" ] } diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index f3e82abd69f..6154146617d 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -450,12 +450,36 @@ notifications: - "@jyu00" - "@ElePT" - "@beckykd" + "docs/guides/executor-broadcasting": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" + - "@kaelynj" + "docs/guides/estimator-broadcasting": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" + - "@kaelynj" + "docs/guides/broadcasting": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" + - "@kaelynj" "docs/guides/sampler-rest-api": - "@born-2learn" - "@HuangJunye" - "@pacomf" - "@Bagherpoor" - "@kaelynj" + "docs/guides/executor-rest-api": + - "@born-2learn" + - "@HuangJunye" + - "@pacomf" + - "@Bagherpoor" + - "@kaelynj" "docs/guides/estimator-rest-api": - "@born-2learn" - "@HuangJunye" diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index 373e3322612..3605a229621 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -29,6 +29,9 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/estimator-rest-api.ipynb", "docs/guides/executor-examples.ipynb", "docs/guides/executor-input-output.ipynb", + "docs/guides/executor-broadcasting.mdx", + "docs/guides/estimator-broadcasting.mdx", + "docs/guides/broadcasting.mdx", "docs/guides/executor-rest-api.ipynb", "docs/guides/get-started-with-sampler.ipynb", "docs/guides/pubs.ipynb", From c79086a2c760ae0ef4f3a37751b3cde86ddd55ca Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 17 Feb 2026 12:46:27 -0600 Subject: [PATCH 054/118] change the files to mdx that won't pass ci --- docs/guides/executor-examples.ipynb | 692 -------------------- docs/guides/executor-examples.mdx | 312 +++++++++ docs/guides/executor-input-output.ipynb | 248 ------- docs/guides/executor-input-output.mdx | 141 ++++ docs/guides/executor-options.ipynb | 496 -------------- docs/guides/executor-options.mdx | 15 + docs/guides/get-started-with-executor.ipynb | 467 ------------- docs/guides/get-started-with-executor.mdx | 45 ++ scripts/config/allowLists.ts | 6 +- 9 files changed, 516 insertions(+), 1906 deletions(-) delete mode 100644 docs/guides/executor-examples.ipynb create mode 100644 docs/guides/executor-examples.mdx delete mode 100644 docs/guides/executor-input-output.ipynb create mode 100644 docs/guides/executor-input-output.mdx delete mode 100644 docs/guides/executor-options.ipynb create mode 100644 docs/guides/executor-options.mdx delete mode 100644 docs/guides/get-started-with-executor.ipynb create mode 100644 docs/guides/get-started-with-executor.mdx diff --git a/docs/guides/executor-examples.ipynb b/docs/guides/executor-examples.ipynb deleted file mode 100644 index dad2bed3080..00000000000 --- a/docs/guides/executor-examples.ipynb +++ /dev/null @@ -1,692 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "1f4a2ec4-3595-4300-8f9e-092b0ef9b444", - "metadata": {}, - "source": [ - "---\n", - "title: Examples\n", - "description: Practical examples of using the Executor primitive in Qiskit Runtime.\n", - "---\n", - "\n", - "\n", - "# Executor examples" - ] - }, - { - "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", - "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": "bae32e60", - "metadata": {}, - "source": [ - "The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up](install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model)\n", - "\n", - "### Run a single experiment\n", - "\n", - "Consider a circuit that generates a three-qubit GHZ state, rotates\n", - "the qubits around the Pauli-Z axis, and measures the qubits in the computational basis. We show how\n", - "to add this circuit to a `QuantumProgram`, optionally randomizing its content with twirling\n", - "gates, and execute the program by using the `Executor` class." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "98a09369-9a50-4c21-b35b-62a77df3c4e2", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " > Expectation value: 0.22341568206229862\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" - ] - } - ], - "source": [ - "from qiskit.circuit import Parameter, QuantumCircuit\n", - "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "\n", - "# Generate the circuit\n", - "circuit = QuantumCircuit(3)\n", - "circuit.h(0)\n", - "circuit.h(1)\n", - "circuit.cz(0, 1)\n", - "circuit.h(1)\n", - "circuit.h(2)\n", - "circuit.cz(1, 2)\n", - "circuit.h(2)\n", - "circuit.rz(Parameter(\"theta\"), 0)\n", - "circuit.rz(Parameter(\"phi\"), 1)\n", - "circuit.rz(Parameter(\"lam\"), 2)\n", - "circuit.measure_all()\n", - "\n", - "# Initialize the service and choose a backend\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(operational=True, simulator=False)" - ] - }, - { - "cell_type": "markdown", - "id": "09655fc3-c7a6-4448-99ca-48635faf5bef", - "metadata": {}, - "source": [ - "The inputs to the `Executor` are `QuantumProgram`s. For full details, see [Executor input and output.](/docs/guides/executor-input-output)" - ] - }, - { - "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.32345013477088946\n", - ">>> Standard errors for PUB 0: 0.6699759406700503\n", - ">>> Expectation values for PUB 1: -0.06611570247933884\n", - ">>> Standard errors for PUB 1: 0.9963717541237429\n", - ">>> Expectation values for PUB 2: -1.027027027027027\n", - ">>> Standard errors for PUB 2: 0.5749927616830978\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.06711015 1.02462229 0.86305279 0.62488953 0.33325515 -0.00896003\n", - " -0.33007578 -0.6569722 -0.86218569 -1.00699127 -1.07260178 -1.01652936\n", - " -0.84628887 -0.61275014 -0.34655067 0.00202323 0.3451055 0.65176961\n", - " 0.88357414 1.02202099 1.08069471]\n", - " [ 0.02023232 0.36013522 0.67142386 0.90582969 1.03936298 1.09630249\n", - " 1.02375519 0.83848498 0.61506241 0.29134535 -0.02312265 -0.38557014\n", - " -0.68269615 -0.88415221 -1.03242618 -1.07462501 -1.01479516 -0.84657791\n", - " -0.60032172 -0.34134807 0.0375743 ]\n", - " [-0.00375743 -0.32227189 -0.61043788 -0.8595844 -0.99514091 -1.06768822\n", - " -1.00207771 -0.86016246 -0.61535144 -0.31128863 -0.00722583 0.3162022\n", - " 0.5783552 0.83472755 0.96190211 1.0543927 0.96219114 0.83183722\n", - " 0.61477337 0.3109996 0.00578066]\n", - " [ 1.05121333 0.97808796 0.82807979 0.60841465 0.28643179 0.00202323\n", - " -0.35955716 -0.61650757 -0.87403605 -1.01017063 -1.03907394 -0.97201827\n", - " -0.82576753 -0.64078635 -0.29018922 0.01445165 0.36562685 0.64309862\n", - " 0.86102956 1.00612417 1.02751262]]\n", - ">>> Standard errors: [[0.01151455 0.01208591 0.01437305 0.01516832 0.0175964 0.02196652\n", - " 0.01407821 0.0179169 0.01534837 0.01405067 0.01089256 0.01482019\n", - " 0.0127782 0.01559765 0.01899503 0.02237809 0.01864773 0.01283165\n", - " 0.01698008 0.01143013 0.01067652]\n", - " [0.01432111 0.01709397 0.01150002 0.01003802 0.010944 0.00986028\n", - " 0.01161247 0.01432245 0.01283955 0.01825252 0.019398 0.01419018\n", - " 0.01259648 0.01302725 0.01243832 0.01190624 0.01041912 0.01420004\n", - " 0.01569825 0.0116058 0.01704668]\n", - " [0.02015936 0.0163317 0.01978364 0.01280742 0.01147035 0.01264482\n", - " 0.01325134 0.01607193 0.01720284 0.01827317 0.02058534 0.01883573\n", - " 0.01762105 0.01550781 0.01177672 0.01275283 0.01256003 0.01172175\n", - " 0.0177283 0.01362507 0.01842915]\n", - " [0.01300432 0.01140395 0.01500555 0.0166804 0.01416201 0.01593217\n", - " 0.01642975 0.01516331 0.0105868 0.0109708 0.01353272 0.01250455\n", - " 0.01388045 0.01405231 0.01362199 0.01635518 0.01937697 0.01092389\n", - " 0.01281015 0.01259024 0.01080734]]\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: -1.4598540145985401\n", - " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n", - " > Another Expectation value: -0.783068783068783\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: ['1100110110101001110011101111010011011000000011001000010010010000000000100000000100001001101001111001110011100001110000010010001', '1110011011100000011110111010110100100001000000001110110100001110100001101100010101110001100001101001000101001101000000001010010', '1110001110011101010000110011111011000001000101101000010000011110000000001101010011010011001001100000111000000000100010101011101', '1000010100001000101010010000000110111111101001001111001010101100101111010011000000110010000000110010010001000010000000011000000', '1110010001000101110101001010101111000000110010000011100001100110101000010111010001000100110010000100011101001110000001010010001', '0001110001100111100001101101010110001110000100101010011110011001100100110110110100010111100000001001010110100010001001010001000', '0001100100000010001011011110101110101100111001101011100110111100100000010100010101101000000001000010110011001010101000000000000', '0010010010010100100100110010100001000000000000010110010110100110011101000001110011000011011011100000100101000011111011100011110', '1011001010110010101101000100100001110100010001111010101111010000000000001010000101011001000000100101010011100011000001011001000', '1001010001101101111101000010000110100001111001001011010011000000010100000000010001000001100000111100000010010100100010111001100']\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: ['0101110010001111101011000010000011000011100101001000111001000110101001100000000100000110010001000010110100111111001000101111001', '0110001110000000011110001110011001011111001101011100101010100110100111000010101110010100100010000000101101110100001110000000000', '0010100100010011000010000011101110101100010001001100011000000011011011101110101001111110001001000000100000001000100010001111110', '0011010011110111100100011010000111000010111001000000000000101100100100000000111101101100111110010101001000100000101000000101011', '0100100101010111010011110111111100101011011101000110100100110000000011111000001000011110000110010100000100000111010000000000100', '1011000101011010000000010110111111000001011010101101011001111001010110010100000100001100010000010000110100000010010000110000010', '0110110101001000010010111011100100001100110010111001100011101100011000010100010000011111001110100011011110000111010000100000000', '0010010111010000110101001101110111010100001010001110010000111100000110101010000000010000011101000000000001000101101000000010101', '1111001111000000010010110111100000010011011101110101110100111000000111000010000000001001010001100000001010001111001001001001001', '0000001010111001010000110110001011010000001100000000001000000011000001010100110100110100100011100111101001000111100011000110100']\n", - " > First ten results for pub 1: ['0001111100010100010111000011011111000100001111010010101000000010010011000000000001100010001000000101101100011011100000000100100', '1011001000101011100011101001100111101100001101100000000010101111101101010001000010000110100000000000100010010010000010001001001', '1000000100000010111010011111001011101000101101010011000101010000000010010010000000100010100101000111001001111000010011001000100', '0100111000111011100110100010000011100110000100110000011101110110101110100011100110000100001100100111001100001000010011000000100', '1000100000101011101000100101000000001110000000000001111100010101110100000000000011001010011100000010001000100000111101000001110', '0110100000100001011000001011100111110000101011111000001010000001111000000001000001100100000111001010100010100000000000100000100', '0010110000111000110100000110000111111100011101001000110100110110000001110000100111000000001110001100111000011110000101111010000', '0010001000101000001010000111011100101000110011110100010001100010110100101010001100100001100001111110111001000001000001000010001', '1010100000010111110101111111011011110110010011010001100000010011011000100011101100010000000110100000111100000000101101000110100', '1111001101000100010010110101000001100010010101101100111001101011010000000110111000000100000110000001101000101010011111001100100']\n", - " > First ten results for pub 2: ['1010101001001110010111111111010101011000111000101011100011010000001011011011010001101100100010101000011000100001101111110001000', '1100010011000001010100001001010011101001000110000000110000000010101001101001001110000010000001000101100011110110100100000110110', '0011001011011011011110000101011100100100011100000111001010101001101000111100100011100110001010010010100101011100001011010000001', '0000111110010111000100000001000101001011010110001001000001100111101000100000000111000000000000010001011111000100010111110101000', '1101110110110000011000001110111011000001010010111110111010001010001100101010101110110000110011010100010001111100000100100101000', '1101000000001101010000000100000000101001000000000100110011110101100000111010100101100000110001010110001000001000100100110000000', '0100011001111111110110001110001000011101000110100000001100000000001000110010001100011011100000000111001010000010000111111000111', '0111001101001000110110001001010101010100000000011000011111100011100010001110000100010111111000100100100101000001000010101100010', '1000000111110000101010000001101010110001000100000000011001101001010100111001000000000000001010100100000010101101110000010010010', '0110001011111001101001101111011101011001000010101011110101110011010001011101000010111000001000010010000010000001010100000100101']\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: ['1110001001011111101111010101101110101110000101100010101100001101101100001000000010111111111001100100111001100000001000101011101', '0001001110111001000010010110110111110111100000100011000111011100110011001000001011011110011011000111110001110010100001000000000', '0000100100110011000000011000010001101010100000100011111110101111010110111101100110100000011000110100001000110001001101000010111', '0010000000010111101001010011101000110000110000100000010000111011010101001001101110111010110011100010111010011100111010111011111', '0001100101010111000000110111110010000110101101100011000001000011010100011001101101001001000000100110110100100010110010101100001', '0000111111001001011000100101100100111000000001111001001110010011010000010011101000011000010011110110110101111011000101000000101', '1111100000101000010000000011100100100110100101011111010111101010010000001011100110101111100100111000001001100010011110000000100', '1100011000100110000010011000111011111010000001100001000101101010100011001000011110111101100110010101111011111100111001010010001', '0101001100111100001110100000110001000000100101000001100010111001111001101011100010010101101101111101001001001011011001010000101', '0001100101101011001011101001000001011010000100110001001100001001100000001100101010001110011010000001011100011011101110010100100']\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: ['1000001010111001110000111111100010001010101001001000010000000101101110111100110111001110010010111010010001001110010110000000000', '1010000100010101101000110100100111101110100101010010110000110000010110011000110111010110000001010111100000000000001000001101000', '1010101111110101010001111101000010011001111001110000110010000100000010000000000101111110101011100000000001000110101010110001100', '0001000100000010001011111101110011000010011001100100101101100011000111100010010100010110000000010011010000000011101010000100000', '0010110111011011001110000000101000000100010101010100010000101101000011010011001101000110110110001000100000111110011101100111000', '0001111111001110001010001000110011000001001100101110100000000011110110000000101000010011000001101010111100000001000101000001101', '1010111111000000001000010001111111100100110000010010101000001110111011000010101010010100000000110100110110000110100100101000010', '1111010110011100001100000001100010100000000101101100000100000101000100000101000111100011100101111010011010000011000001000001010', '0010011001100001000000111101100001001100000101101110101010000000010000001001010010011110001000011100011001000000000110000000100', '1000110110100111001111001000101010111000011011110000010010000011010110110100000011000000001110110110010101111011010100011100001']\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: ['1100111001001110001001001010001000111000100001010000000011010100101100001100001101010100010001000001011101110000000000010001000', '1100001010011111100101011000100000010010011100110100011011000110000011010010010100010000000111011001000001001001000000010011100', '1010101001101100101101111110000011101010000100001001001111000100001001100100000100011001000101100010101000100100101100000100001', '1110110010101001110000111100001010011101111110001000000111000001011011000011001001001011001000111100011000001111100100100101001', '0101011001001101111100010100000000010001010000110110010010111000010100001001101100000101010000100100110111011001010100111100110', '0000111000100110001100111010111011011000000010001011011111010000010110100011100100110101011100001001011010000001000001010010100', '1111100000001110111100101011001110100010001110000101010111011010100011110100110000000100011000001010101110100000110000100100001', '0011001000101001101011000110100110011110000101000001001010100000100100011110000101011101000100000010101101011011000000010110000', '0000010001100111000110011010100101001000101110110000101011100000001000110010101100001101100100000001010000000000101100010100001', '1100101000000101001010001001100111011000101010001100111110110000101001110100000000001100000000000000000000000000001011110101010']\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/executor-examples.mdx b/docs/guides/executor-examples.mdx new file mode 100644 index 00000000000..d4555a7ace7 --- /dev/null +++ b/docs/guides/executor-examples.mdx @@ -0,0 +1,312 @@ +--- +title: Broadcasting +description: How the Executor handles array inputs and outputs using broadcasting semantics + +--- + +# Executor broadcasting semantics +The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine +multiple experimental configurations, and interpret the shape of returned data. + +## Quick start example + +This example demonstrates the core idea. It creates a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item. + +The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs. + +```python +import numpy as np +from qiskit.circuit import Parameter, QuantumCircuit +from qiskit_ibm_runtime.quantum_program import QuantumProgram + +# A circuit with 3 parameters +circuit = QuantumCircuit(3) +circuit.rx(Parameter("a"), 0) +circuit.rx(Parameter("b"), 1) +circuit.rx(Parameter("c"), 2) +circuit.measure_all() + +# 5 different parameter configurations (shape: 5 configurations × 3 parameters) +parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3) + +program = QuantumProgram(shots=1024) +program.append(circuit, circuit_arguments=parameter_values) + +# Run and get results +result = executor.run(program).result() + +# result is a list with one entry per program item +# result[0] is a dict mapping classical register names to data arrays +# Output bool arrays have shape (5, 1024, 3) +# 5 = number of parameter configurations +# 1024 = number of shots +# 3 = bits in the classical register +result[0]["meas"] +``` + +## Intrinsic and extrinsic axes + +Broadcasting only applies to _extrinsic_ axes. The intrinsic axes are always preserved as specified. + +- **Intrinsic axes** (rightmost): Determined by the data type. For example, if your circuit + has three parameters, then parameter values require three numbers, giving an intrinsic shape + of ``(3,)``. + +- **Extrinsic axes** (leftmost): Your sweep dimensions. These define how many configurations you + want to run. + +| Input type | Intrinsic shape | Example full shape | +|:----------------------------------------:|:---------------:|:---------------------------------------------------:| +| Parameter values (n parameters) | (n,) | (5, 3) for five configurations and three parameters | +| Scalar inputs (for example, noise scale) | () | (4,) for four configurations | +| Observables (if applicable) | varies | Depends on observable type | + +### Example + +Consider a circuit with two parameters that you want to sweep over a 4x3 grid of configurations, varying both parameter values and a noise scale factor: + +```python +import numpy as np + +# Parameter values: 4 configurations along axis 0, intrinsic shape (2,) +# Full shape: (4, 1, 2) - the "1" allows broadcasting with noise_scale +parameter_values = np.array([ + [[0.1, 0.2]], + [[0.3, 0.4]], + [[0.5, 0.6]], + [[0.7, 0.8]], +]) # shape (4, 1, 2) + +# Noise scale: 3 configurations, intrinsic shape () (scalar) +# Full shape: (3,) +noise_scale = np.array([0.8, 1.0, 1.2]) # shape (3,) + +# Extrinsic shapes: (4, 1) and (3,) → broadcast to (4, 3) +# Result: 12 total configurations in a 4×3 grid + +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": parameter_values, + "noise_scale.mod_ref1": noise_scale, + }, +) +``` + +The shapes are as follows: + +| Input | Full shape | Extrinsic shape | Intrinsic shape | +|:------------------:|:----------:|:---------------:|:---------------:| +| `parameter_values` | (4, 1, 2) | (4, 1) | (2,) | +| `noise_scale` | (3,) | (3,) | () | +| Broadcast | None | (4, 3) | None | + +## Output array shapes + +Output arrays follow the same extrinsic/intrinsic pattern: + +- **Extrinsic shape:** Matches the broadcast shape of all inputs +- **Intrinsic shape:** Determined by the output type + +The most common output is bitstring data from measurements, which is +formatted as an array of boolean values: + +| Output type | Intrinsic shape | Description | +|:-----------------------:|:----------------------:|:--------------------------------:| +| Classical register data | (num_shots, creg_size) | Bitstring data from measurements | +| Expectation values | () or (n_obs,) | Scalar or per-observable | + +### Example + +If you provide inputs with extrinsic shapes ``(4, 1)`` and ``(3,)``, the broadcast extrinsic +shape is ``(4, 3)``. For a circuit with 1024 shots and a 3-bit classical register: + +```python +# Input extrinsic shapes: (4, 1) and (3,) → (4, 3) +# Output for classical register "meas": +# extrinsic: (4, 3) +# intrinsic: (1024, 3) - shots × bits +# full shape: (4, 3, 1024, 3) + +result = executor.run(program).result() +meas_data = result[0]["meas"] # result[0] for first program item +print(meas_data.shape) # (4, 3, 1024, 3) + +# Access a specific configuration +config_2_1 = meas_data[2, 1, :, :] # shape (1024, 3) +``` + + +Each configuration receives the full shot count specified in the quantum program. Shots are **not** divided among configurations. For example, if you request 1024 shots and have 10 configurations, each configuration runs 1024 shots (10,240 total shots executed). + + +## Randomization and the ``shape`` parameter + +When using a [samplex,](/docs/guides/directed-execution-model) each element of the extrinsic shape corresponds to an independent circuit +execution. The samplex typically injects randomness (for example, twirling gates) into each +execution, so even without explicitly requesting multiple randomizations, each element naturally +receives its own random realization. + +The ``shape`` parameter lets you augment the extrinsic shape for the item, effectively letting you +add axes that correspond specifically to randomizing the same configuration many times. It must be +broadcastable from the shape implicit in your ``samplex_arguments``. Axes where ``shape`` exceeds +the implicit shape enumerate additional independent randomizations. + +### No explicit randomization axes + +If you omit ``shape`` (or set it to match your input shapes), you get one execution per +input configuration. Each execution is still randomized by the samplex, but with only a +single random realization you don't benefit from averaging over multiple randomizations. + + +If you're used to enabling twirling with a simple flag like ``twirling=True``, +the Executor requires you to explicitly request multiple randomizations with the ``shape`` argument to +allow your post-processing routines to get the benefits of averaging over multiple +randomizations. A single randomization (the default when ``shape`` is omitted) applies +random gates but typically offers no advantage over running the base circuit without +randomization. + + +The following example demonstrates the default behavior: + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + # shape defaults to (10,) - one randomized execution per config +) +# Output shape for "meas": (10, num_shots, creg_size) +``` + +### Single randomization axis + +To run multiple randomizations per configuration, extend the shape with additional axes. +For example, the following code runs 20 randomizations for each of 10 parameter configurations: + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + shape=(20, 10), # 20 randomizations × 10 configurations +) +# Output shape for "meas": (20, 10, num_shots, creg_size) +``` + +### Multiple randomization axes + +You can organize randomizations into a multi-dimensional grid. This is useful for structured +analysis, for example, separating randomizations by type or grouping them for statistical processing. + +Here, the input extrinsic shape ``(10,)`` broadcasts to the requested shape ``(2, 14, 10)``, +with axes 0 and 1 filled by independent randomizations. + +```python +program.append( + template, + samplex=samplex, + samplex_arguments={ + "parameter_values": np.random.rand(10, 3), # extrinsic (10,) + }, + shape=(2, 14, 10), # 2×14=28 randomizations per configuration, 10 configurations +) +# Output shape for "meas": (2, 14, 10, num_shots, creg_size) +``` + +### How `shape` and input shapes interact + +The ``shape`` parameter must be broadcastable *from* your input extrinsic shapes. This means: + +- Input shapes with size-1 dimensions can expand to match ``shape``. +- Input shapes must align from the right with ``shape``. +- Axes in ``shape`` that exceed the input dimensions enumerate randomizations. + +Note that ``shape`` can contain size-1 dimensions +that expand to match input dimensions, as is illustrated in the last row of the following table. + +Examples: + +| Input extrinsic | shape | Result | +|:---------------:|:----------:|:-----------------------------------------------------------------:| +| (10,) | (10,) | 10 configurations, 1 randomization each | +| (10,) | (5, 10) | 10 configurations, 5 randomizations each | +| (10,) | (2, 3, 10) | 10 configurations, 2×3=6 randomizations each | +| (4, 1) | (4, 5) | 4 configurations, 5 randomizations each | +| (4, 3) | (2, 4, 3) | 4×3=12 configurations, 2 randomizations each | +| (4, 3) | (2, 1, 3) | 4×3=12 configurations, 2 randomizations each (the 1 expands to 4) | + + + +### Indexing into results + +With randomization axes, you can index into specific randomization/parameter combinations: + +```python +# Using shape=(2, 14, 10) with input extrinsic shape (10,) +result = executor.run(program).result() +meas_data = result[0]["meas"] # shape (2, 14, 10, 1024, 3) + +# Get all shots for randomization (0, 7) and parameter config 3 +specific = meas_data[0, 7, 3, :, :] # shape (1024, 3) + +# Average over all randomizations for parameter config 5 on bit 2 +averaged = meas_data[:, :, 5, :, 2].mean(axis=(0, 1)) +``` + +## Common patterns + +### Sweeping a single parameter +To sweep one parameter while holding others fixed: + +```python + + # Circuit has 3 parameters, sweep first one over 20 values + sweep_values = np.linspace(0, 2*np.pi, 20) + fixed_values = [0.5, 0.3] + + parameter_values = np.column_stack([ + sweep_values, + np.full(20, fixed_values[0]), + np.full(20, fixed_values[1]), + ]) # shape (20, 3) +``` + +### Creating a 2D grid sweep +To create a grid over two parameters: + +```python + +# Sweep param 0 over 10 values, param 1 over 8 values, param 2 fixed +p0 = np.linspace(0, np.pi, 10)[:, np.newaxis, np.newaxis] # (10, 1, 1) +p1 = np.linspace(0, np.pi, 8)[np.newaxis, :, np.newaxis] # (1, 8, 1) +p2 = np.array([[[0.5]]]) # (1, 1, 1) + +parameter_values = np.broadcast_arrays(p0, p1, p2) +parameter_values = np.stack(parameter_values, axis=-1).squeeze() # (10, 8, 3) + +# Extrinsic shape: (10, 8), intrinsic shape: (3,) +``` + +### Combining multiple inputs + +When combining inputs with different intrinsic shapes, align extrinsic dimensions using +size-1 axes: + +```python +# 4 parameter configurations, 3 noise scales → 4×3 = 12 total configurations +parameter_values = np.random.rand(4, 1, 2) # extrinsic (4, 1), intrinsic (2,) +noise_scale = np.array([0.8, 1.0, 1.2]) # extrinsic (3,), intrinsic () + +# Broadcasted extrinsic shape: (4, 3) +``` +## Next steps + + + - Review the overview of [broadcasting.](/docs/guides/broadcasting) + diff --git a/docs/guides/executor-input-output.ipynb b/docs/guides/executor-input-output.ipynb deleted file mode 100644 index abf622fd6f1..00000000000 --- a/docs/guides/executor-input-output.ipynb +++ /dev/null @@ -1,248 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "dbb193c8-d927-434c-a199-48de57c99694", - "metadata": {}, - "source": [ - "---\n", - "title: Inputs and outputs\n", - "description: Understand the inputs and outputs to the Executor primitive.\n", - "---\n", - "\n", - "\n", - "# Executor inputs and outputs" - ] - }, - { - "cell_type": "markdown", - "id": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", - "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": "a4800a7e-9db5-47cf-aaf9-e69c2c6e1b5e", - "metadata": {}, - "source": [ - "The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer." - ] - }, - { - "cell_type": "markdown", - "id": "eba624e4-093c-491d-b503-1b91ce54d434", - "metadata": {}, - "source": [ - "## Quantum programs\n", - "\n", - "The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a\n", - "[`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a\n", - "different task for the Executor to perform. Typically, each item owns one of the following options:\n", - "\n", - "* A `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates\n", - "* A parametrized `qiskit.circuit.QuantumCircuit` with an array of parameter values\n", - "* A parametrized `qiskit.circuit.QuantumCircuit` with a `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values\n", - "\n", - "Each of these items, including instructions to add them to a `QuantumProgram` is explained in more detail below.\n", - "\n", - "The following cell initializes a `QuantumProgram` and specifies that it should run 1024 shots for every configuration of each item in the program. Then it appends a version of the target circuit with set parameters, transpiled according to the backend's ISA." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "401d4d84-28f4-4ad0-9f8f-751ebf21f612", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit.transpiler import generate_preset_pass_manager\n", - "from qiskit_ibm_runtime.quantum_program import QuantumProgram\n", - "\n", - "# Initialize an empty program\n", - "program = QuantumProgram(shots=1024)\n", - "\n", - "# Initialize circuit to generate and measure GHZ state\n", - "circuit = QuantumCircuit(3)\n", - "circuit.h(0)\n", - "circuit.h(1)\n", - "circuit.cz(0, 1)\n", - "circuit.h(1)\n", - "circuit.h(2)\n", - "circuit.cz(1, 2)\n", - "circuit.h(2)\n", - "circuit.rz(0.1, 0)\n", - "circuit.rz(0.2, 1)\n", - "circuit.rz(0.3, 2)\n", - "circuit.measure_all()\n", - "\n", - "# Transpile the circuit\n", - "preset_pass_manager = generate_preset_pass_manager(\n", - " backend=backend, optimization_level=0\n", - ")\n", - "isa_circuit = preset_pass_manager.run(circuit)\n", - "\n", - "# Append the circuit to the program\n", - "program.append_circuit_item(isa_circuit)" - ] - }, - { - "cell_type": "markdown", - "id": "f49d211f-36b4-489d-9e0e-d10aab5e195f", - "metadata": {}, - "source": [ - "Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (1024 per set of parameter values)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "882d8ada-4ec2-4d50-b498-c51a9d185d6f", - "metadata": {}, - "outputs": [], - "source": [ - "from qiskit.circuit import Parameter\n", - "import numpy as np\n", - "\n", - "# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", - "# axis, and measure it\n", - "circuit = QuantumCircuit(3)\n", - "circuit.h(0)\n", - "circuit.h(1)\n", - "circuit.cz(0, 1)\n", - "circuit.h(1)\n", - "circuit.h(2)\n", - "circuit.cz(1, 2)\n", - "circuit.h(2)\n", - "circuit.rz(Parameter(\"theta\"), 0)\n", - "circuit.rz(Parameter(\"phi\"), 1)\n", - "circuit.rz(Parameter(\"lam\"), 2)\n", - "circuit.measure_all()\n", - "\n", - "# Transpile the circuit\n", - "isa_circuit = preset_pass_manager.run(circuit)\n", - "\n", - "# Append the circuit and the parameter value to the program\n", - "program.append_circuit_item(\n", - " isa_circuit,\n", - " circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "6d79baa5-046d-427a-91bd-7d2f1a178a97", - "metadata": {}, - "source": [ - "Finally, in the next cell we append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments,\n", - "we provide ``10`` sets of parameters for the parametric gates in the original circuit. Additionally, we use the ``shape`` request argument to request an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape``\n", - "to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape ``(2, 14, 10)``.\n", - "\n", - " We refer the reader to :mod`~samplomatic` and its documentation for more details on the\n", - " `samplomatic.samplex.Samplex` and its arguments." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "3602ecd1-8d23-48af-9612-4891472775bf", - "metadata": {}, - "outputs": [], - "source": [ - "from samplomatic import build\n", - "from samplomatic.transpiler import generate_boxing_pass_manager\n", - "\n", - "# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z\n", - "# axis, and measure it\n", - "circuit = QuantumCircuit(3)\n", - "circuit.h(0)\n", - "circuit.h(1)\n", - "circuit.cz(0, 1)\n", - "circuit.h(1)\n", - "circuit.h(2)\n", - "circuit.cz(1, 2)\n", - "circuit.h(2)\n", - "circuit.rz(Parameter(\"theta\"), 0)\n", - "circuit.rz(Parameter(\"phi\"), 1)\n", - "circuit.rz(Parameter(\"lam\"), 2)\n", - "circuit.measure_all()\n", - "\n", - "# Transpile the circuit, additionally grouping gates and measurements into annotated boxes\n", - "preset_pass_manager = generate_preset_pass_manager(\n", - " backend=backend, optimization_level=0\n", - ")\n", - "preset_pass_manager.post_scheduling = generate_boxing_pass_manager(\n", - " enable_gates=True,\n", - " enable_measures=True,\n", - ")\n", - "boxed_circuit = preset_pass_manager.run(circuit)\n", - "\n", - "# Build the template and the samplex\n", - "template, samplex = build(boxed_circuit)\n", - "\n", - "# Append the template and samplex as a samplex item\n", - "program.append_samplex_item(\n", - " template,\n", - " samplex=samplex,\n", - " samplex_arguments={\n", - " # the arguments required by the samplex.sample method\n", - " \"parameter_values\": np.random.rand(10, 3),\n", - " },\n", - " shape=(2, 14, 10),\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "165509d7-2137-49ac-ba77-4c75ba6508dd", - "metadata": {}, - "source": [ - "Now that we have populated our `QuantumProgram`, we can proceed with execution." - ] - } - ], - "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/executor-input-output.mdx b/docs/guides/executor-input-output.mdx new file mode 100644 index 00000000000..be0e0186516 --- /dev/null +++ b/docs/guides/executor-input-output.mdx @@ -0,0 +1,141 @@ +--- +title: Inputs and outputs +description: Understand the inputs and outputs to the Executor primitive. + +--- + +# Executor inputs and outputs + +The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer. + +## Quantum programs + +The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a +[`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a +different task for the Executor to perform. Typically, each item owns one of the following options: + +* A `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates +* A parametrized `qiskit.circuit.QuantumCircuit` with an array of parameter values +* A parametrized `qiskit.circuit.QuantumCircuit` with a `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values + +Each of these items, including instructions to add them to a `QuantumProgram` is explained in more detail below. + +The following cell initializes a `QuantumProgram` and specifies that it should run 1024 shots for every configuration of each item in the program. Then it appends a version of the target circuit with set parameters, transpiled according to the backend's ISA. + +```python +from qiskit.transpiler import generate_preset_pass_manager +from qiskit_ibm_runtime.quantum_program import QuantumProgram + +# Initialize an empty program +program = QuantumProgram(shots=1024) + +# Initialize circuit to generate and measure GHZ state +circuit = QuantumCircuit(3) +circuit.h(0) +circuit.h(1) +circuit.cz(0, 1) +circuit.h(1) +circuit.h(2) +circuit.cz(1, 2) +circuit.h(2) +circuit.rz(0.1, 0) +circuit.rz(0.2, 1) +circuit.rz(0.3, 2) +circuit.measure_all() + +# Transpile the circuit +preset_pass_manager = generate_preset_pass_manager( + backend=backend, optimization_level=0 +) +isa_circuit = preset_pass_manager.run(circuit) + +# Append the circuit to the program +program.append_circuit_item(isa_circuit) +``` + +Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (1024 per set of parameter values). + +```python +from qiskit.circuit import Parameter +import numpy as np + +# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z +# axis, and measure it +circuit = QuantumCircuit(3) +circuit.h(0) +circuit.h(1) +circuit.cz(0, 1) +circuit.h(1) +circuit.h(2) +circuit.cz(1, 2) +circuit.h(2) +circuit.rz(Parameter("theta"), 0) +circuit.rz(Parameter("phi"), 1) +circuit.rz(Parameter("lam"), 2) +circuit.measure_all() + +# Transpile the circuit +isa_circuit = preset_pass_manager.run(circuit) + +# Append the circuit and the parameter value to the program +program.append_circuit_item( + isa_circuit, + circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values +) +``` + +Finally, append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments, ``10`` sets of parameters for the parametric gates in the original circuit are provided. The ``shape`` request argument requests an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape`` +to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape ``(2, 14, 10)``. + +See the samplomatic [API](https://github.com/Qiskit/samplomatic/) documentation for full details about `samplomatic.samplex.Samplex` and its arguments. + +```python +from samplomatic import build +from samplomatic.transpiler import generate_boxing_pass_manager + +# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z +# axis, and measure it +circuit = QuantumCircuit(3) +circuit.h(0) +circuit.h(1) +circuit.cz(0, 1) +circuit.h(1) +circuit.h(2) +circuit.cz(1, 2) +circuit.h(2) +circuit.rz(Parameter("theta"), 0) +circuit.rz(Parameter("phi"), 1) +circuit.rz(Parameter("lam"), 2) +circuit.measure_all() + +# Transpile the circuit, additionally grouping gates and measurements into annotated boxes +preset_pass_manager = generate_preset_pass_manager( + backend=backend, optimization_level=0 +) +preset_pass_manager.post_scheduling = generate_boxing_pass_manager( + enable_gates=True, + enable_measures=True, +) +boxed_circuit = preset_pass_manager.run(circuit) + +# Build the template and the samplex +template, samplex = build(boxed_circuit) + +# Append the template and samplex as a samplex item +program.append_samplex_item( + template, + samplex=samplex, + samplex_arguments={ + # the arguments required by the samplex.sample method + "parameter_values": np.random.rand(10, 3), + }, + shape=(2, 14, 10), +) +``` + + +## Next steps + + + - Review the overview of [broadcasting.](/docs/guides/broadcasting) + diff --git a/docs/guides/executor-options.ipynb b/docs/guides/executor-options.ipynb deleted file mode 100644 index a74eed5b995..00000000000 --- a/docs/guides/executor-options.ipynb +++ /dev/null @@ -1,496 +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", - "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": "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/executor-options.mdx b/docs/guides/executor-options.mdx new file mode 100644 index 00000000000..30f72b93746 --- /dev/null +++ b/docs/guides/executor-options.mdx @@ -0,0 +1,15 @@ +--- +title: Specify options +description: Specify options when building with the Qiskit Runtime Executor primitive. + +--- + +# Specify Executor options + + + +## Next steps + + + - Review the overview of [broadcasting.](/docs/guides/broadcasting) + diff --git a/docs/guides/get-started-with-executor.ipynb b/docs/guides/get-started-with-executor.ipynb deleted file mode 100644 index 6058687f3f7..00000000000 --- a/docs/guides/get-started-with-executor.ipynb +++ /dev/null @@ -1,467 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", - "metadata": {}, - "source": [ - "---\n", - "title: Get started\n", - "description: How to use the Executor primitive in Qiskit Runtime.\n", - "---\n", - "\n", - "\n", - "# Get started with the Executor primitive" - ] - }, - { - "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", - "The Executor primitive is part of the directed execution model, which provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information." - ] - }, - { - "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": "bafa61f0-c049-4ee6-ac76-a0ed97e67caf", - "metadata": {}, - "source": [ - "## Steps to get started with Executor\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 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_torino\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", - " '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', 3826), ('sx', 1601), ('cz', 968)])\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: d68n7h0qbmes739gpa0g\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: 23.638839041295284\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', 3385), ('rz', 3036), ('cz', 1248), ('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.](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: d68n8m1v6o8c73d6vbb0\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: ['1000100110000000000110011110110000010111010100010000010001101011000101001110001010000001011010100010100011000100000001010101010', '0101101110010011110011011101100100000111011001100000110100100011110110000100111001000100000000011010011000110001001111111110000', '1101010000100001100000111100000001100001011001100100110010000011010001111000100011101100010000101010000010001000001011110011010', '1001100101010000011001000010100011111111100100010100111100000101110010110100011100001111010001010100100000011000000111001100010', '0000001011010111101100001000010111101011011000000100000100000010100101100101110011010110111000010100001000000001001010110101000', '0101111001000010100001011101001000000010000010101000100100010001000011000000011100101110100100111101000101110000001001000000000', '1100001100101101100000001011001101110001011000100000100001001010111000100001001001101010011111110110010000110001100010110101000', '0010000100001011001111110100100001110010111000000010010011101110000001110001001000011000100011001100000100111001000000100001000', '0000000101110000000010100100001001100000111000001010110001001100110100010000000101100000010100111000011111110100100011111011000', '1010111101101011111100110011110001000000010000010101110111010101101101001000010100010100000010000001101000000000001100000010100']\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 [primitives examples.](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-executor.mdx b/docs/guides/get-started-with-executor.mdx new file mode 100644 index 00000000000..5bfb23ca4d2 --- /dev/null +++ b/docs/guides/get-started-with-executor.mdx @@ -0,0 +1,45 @@ +--- +title: Get started +description: How to use the Executor primitive in Qiskit Runtime. + +--- + +# Get started with the Executor primitive +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. + +The Executor primitive is part of the directed execution model, which provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information. + +## Steps to get started with Executor + +There are three basic steps involved in using the Executor primitive: +1. Initialize a `QuantumProgram` with your workload. +2. Run the `QuantumProgram` on IBM backends by using the `Executor` primitive. +3. Interpret the outputs. + +See [Executor examples](/docs/guides/executor-examples) for a full walkthrough. + +## Run an Executor job + +The following code shows how to initialize an Executor with the default options. See [Executor options](/docs/guides/executor-options) to learn more. + +```python +from qiskit_ibm_runtime import Executor + +executor = Executor(backend) +``` +Next, use the `run()` method to submit the job. + +```python +job = executor.run(program) + +# Retrieve the result +result = job.result() +``` + +Here, the result is of type [`QuantumProgramResult`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) See [Executor input and output](/docs/guides/executor-input-output) to learn about the result object. + +## Next steps + + + - + diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index 3605a229621..abdf0bd2aad 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -27,12 +27,12 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/estimator-input-output.ipynb", "docs/guides/estimator-options.ipynb", "docs/guides/estimator-rest-api.ipynb", - "docs/guides/executor-examples.ipynb", - "docs/guides/executor-input-output.ipynb", + "docs/guides/executor-examples.mdx", + "docs/guides/executor-input-output.mdx", "docs/guides/executor-broadcasting.mdx", "docs/guides/estimator-broadcasting.mdx", "docs/guides/broadcasting.mdx", - "docs/guides/executor-rest-api.ipynb", + "docs/guides/executor-rest-api.mdx", "docs/guides/get-started-with-sampler.ipynb", "docs/guides/pubs.ipynb", "docs/guides/sampler-examples.ipynb", From 320843fc112bb76f992598dc69cd81c069840bae Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 17 Feb 2026 14:49:47 -0600 Subject: [PATCH 055/118] Update allowLists.ts --- scripts/config/allowLists.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index abdf0bd2aad..db899f94f9a 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -28,6 +28,7 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/estimator-options.ipynb", "docs/guides/estimator-rest-api.ipynb", "docs/guides/executor-examples.mdx", + "docs/guides/executor-options.mdx", "docs/guides/executor-input-output.mdx", "docs/guides/executor-broadcasting.mdx", "docs/guides/estimator-broadcasting.mdx", @@ -40,7 +41,7 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/sampler-input-output.ipynb", "docs/guides/sampler-options.ipynb", "docs/guides/get-started-with-estimator.ipynb", - "docs/guides/get-started-with-executor.ipynb", + "docs/guides/get-started-with-executor.mdx", "docs/guides/external-providers-primitives-v2.mdx", "docs/guides/create-a-provider.mdx", "docs/guides/local-simulators.mdx", From d825555eeac64d5f7fbe024425cbddd6e08b7df6 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 17 Feb 2026 15:19:01 -0600 Subject: [PATCH 056/118] spelling --- docs/guides/executor-broadcasting.mdx | 1 + docs/guides/executor-examples.mdx | 313 ++------------------------ 2 files changed, 26 insertions(+), 288 deletions(-) diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index d4555a7ace7..dc634235590 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -3,6 +3,7 @@ title: Broadcasting description: How the Executor handles array inputs and outputs using broadcasting semantics --- +{/* cspell:ignore broadcastable */} # Executor broadcasting semantics The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index d4555a7ace7..6311a8165b8 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -1,310 +1,47 @@ --- -title: Broadcasting -description: How the Executor handles array inputs and outputs using broadcasting semantics +title: Examples +description: Practical examples of using the Executor primitive in Qiskit Runtime. --- +{/* cspell:ignore broadcastable */} -# Executor broadcasting semantics -The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine -multiple experimental configurations, and interpret the shape of returned data. +The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up](install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model) -## Quick start example -This example demonstrates the core idea. It creates a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item. +## Generate the circuit -The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs. +The examples in this guide use the following circuit, which generates a three-qubit GHZ state, rotates +the qubits around the Pauli-Z axis, and measures the qubits in the computational basis. We show how +to add this circuit to a `QuantumProgram`, optionally randomizing its content with twirling +gates, and execute the program by using the `Executor` class. ```python -import numpy as np from qiskit.circuit import Parameter, QuantumCircuit -from qiskit_ibm_runtime.quantum_program import QuantumProgram +from qiskit_ibm_runtime import QiskitRuntimeService -# A circuit with 3 parameters +# Generate the circuit circuit = QuantumCircuit(3) -circuit.rx(Parameter("a"), 0) -circuit.rx(Parameter("b"), 1) -circuit.rx(Parameter("c"), 2) +circuit.h(0) +circuit.h(1) +circuit.cz(0, 1) +circuit.h(1) +circuit.h(2) +circuit.cz(1, 2) +circuit.h(2) +circuit.rz(Parameter("theta"), 0) +circuit.rz(Parameter("phi"), 1) +circuit.rz(Parameter("lam"), 2) circuit.measure_all() -# 5 different parameter configurations (shape: 5 configurations × 3 parameters) -parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3) - -program = QuantumProgram(shots=1024) -program.append(circuit, circuit_arguments=parameter_values) - -# Run and get results -result = executor.run(program).result() - -# result is a list with one entry per program item -# result[0] is a dict mapping classical register names to data arrays -# Output bool arrays have shape (5, 1024, 3) -# 5 = number of parameter configurations -# 1024 = number of shots -# 3 = bits in the classical register -result[0]["meas"] -``` - -## Intrinsic and extrinsic axes - -Broadcasting only applies to _extrinsic_ axes. The intrinsic axes are always preserved as specified. - -- **Intrinsic axes** (rightmost): Determined by the data type. For example, if your circuit - has three parameters, then parameter values require three numbers, giving an intrinsic shape - of ``(3,)``. - -- **Extrinsic axes** (leftmost): Your sweep dimensions. These define how many configurations you - want to run. - -| Input type | Intrinsic shape | Example full shape | -|:----------------------------------------:|:---------------:|:---------------------------------------------------:| -| Parameter values (n parameters) | (n,) | (5, 3) for five configurations and three parameters | -| Scalar inputs (for example, noise scale) | () | (4,) for four configurations | -| Observables (if applicable) | varies | Depends on observable type | - -### Example - -Consider a circuit with two parameters that you want to sweep over a 4x3 grid of configurations, varying both parameter values and a noise scale factor: - -```python -import numpy as np - -# Parameter values: 4 configurations along axis 0, intrinsic shape (2,) -# Full shape: (4, 1, 2) - the "1" allows broadcasting with noise_scale -parameter_values = np.array([ - [[0.1, 0.2]], - [[0.3, 0.4]], - [[0.5, 0.6]], - [[0.7, 0.8]], -]) # shape (4, 1, 2) - -# Noise scale: 3 configurations, intrinsic shape () (scalar) -# Full shape: (3,) -noise_scale = np.array([0.8, 1.0, 1.2]) # shape (3,) - -# Extrinsic shapes: (4, 1) and (3,) → broadcast to (4, 3) -# Result: 12 total configurations in a 4×3 grid - -program.append( - template, - samplex=samplex, - samplex_arguments={ - "parameter_values": parameter_values, - "noise_scale.mod_ref1": noise_scale, - }, -) +# Initialize the service and choose a backend +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) ``` -The shapes are as follows: - -| Input | Full shape | Extrinsic shape | Intrinsic shape | -|:------------------:|:----------:|:---------------:|:---------------:| -| `parameter_values` | (4, 1, 2) | (4, 1) | (2,) | -| `noise_scale` | (3,) | (3,) | () | -| Broadcast | None | (4, 3) | None | - -## Output array shapes - -Output arrays follow the same extrinsic/intrinsic pattern: - -- **Extrinsic shape:** Matches the broadcast shape of all inputs -- **Intrinsic shape:** Determined by the output type - -The most common output is bitstring data from measurements, which is -formatted as an array of boolean values: - -| Output type | Intrinsic shape | Description | -|:-----------------------:|:----------------------:|:--------------------------------:| -| Classical register data | (num_shots, creg_size) | Bitstring data from measurements | -| Expectation values | () or (n_obs,) | Scalar or per-observable | - -### Example - -If you provide inputs with extrinsic shapes ``(4, 1)`` and ``(3,)``, the broadcast extrinsic -shape is ``(4, 3)``. For a circuit with 1024 shots and a 3-bit classical register: - -```python -# Input extrinsic shapes: (4, 1) and (3,) → (4, 3) -# Output for classical register "meas": -# extrinsic: (4, 3) -# intrinsic: (1024, 3) - shots × bits -# full shape: (4, 3, 1024, 3) - -result = executor.run(program).result() -meas_data = result[0]["meas"] # result[0] for first program item -print(meas_data.shape) # (4, 3, 1024, 3) - -# Access a specific configuration -config_2_1 = meas_data[2, 1, :, :] # shape (1024, 3) -``` - - -Each configuration receives the full shot count specified in the quantum program. Shots are **not** divided among configurations. For example, if you request 1024 shots and have 10 configurations, each configuration runs 1024 shots (10,240 total shots executed). - - -## Randomization and the ``shape`` parameter - -When using a [samplex,](/docs/guides/directed-execution-model) each element of the extrinsic shape corresponds to an independent circuit -execution. The samplex typically injects randomness (for example, twirling gates) into each -execution, so even without explicitly requesting multiple randomizations, each element naturally -receives its own random realization. - -The ``shape`` parameter lets you augment the extrinsic shape for the item, effectively letting you -add axes that correspond specifically to randomizing the same configuration many times. It must be -broadcastable from the shape implicit in your ``samplex_arguments``. Axes where ``shape`` exceeds -the implicit shape enumerate additional independent randomizations. - -### No explicit randomization axes - -If you omit ``shape`` (or set it to match your input shapes), you get one execution per -input configuration. Each execution is still randomized by the samplex, but with only a -single random realization you don't benefit from averaging over multiple randomizations. - - -If you're used to enabling twirling with a simple flag like ``twirling=True``, -the Executor requires you to explicitly request multiple randomizations with the ``shape`` argument to -allow your post-processing routines to get the benefits of averaging over multiple -randomizations. A single randomization (the default when ``shape`` is omitted) applies -random gates but typically offers no advantage over running the base circuit without -randomization. - - -The following example demonstrates the default behavior: - -```python -program.append( - template, - samplex=samplex, - samplex_arguments={ - "parameter_values": np.random.rand(10, 3), # extrinsic (10,) - }, - # shape defaults to (10,) - one randomized execution per config -) -# Output shape for "meas": (10, num_shots, creg_size) -``` +The input to the `Executor` is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output) -### Single randomization axis -To run multiple randomizations per configuration, extend the shape with additional axes. -For example, the following code runs 20 randomizations for each of 10 parameter configurations: - -```python -program.append( - template, - samplex=samplex, - samplex_arguments={ - "parameter_values": np.random.rand(10, 3), # extrinsic (10,) - }, - shape=(20, 10), # 20 randomizations × 10 configurations -) -# Output shape for "meas": (20, 10, num_shots, creg_size) -``` - -### Multiple randomization axes - -You can organize randomizations into a multi-dimensional grid. This is useful for structured -analysis, for example, separating randomizations by type or grouping them for statistical processing. - -Here, the input extrinsic shape ``(10,)`` broadcasts to the requested shape ``(2, 14, 10)``, -with axes 0 and 1 filled by independent randomizations. - -```python -program.append( - template, - samplex=samplex, - samplex_arguments={ - "parameter_values": np.random.rand(10, 3), # extrinsic (10,) - }, - shape=(2, 14, 10), # 2×14=28 randomizations per configuration, 10 configurations -) -# Output shape for "meas": (2, 14, 10, num_shots, creg_size) -``` - -### How `shape` and input shapes interact - -The ``shape`` parameter must be broadcastable *from* your input extrinsic shapes. This means: - -- Input shapes with size-1 dimensions can expand to match ``shape``. -- Input shapes must align from the right with ``shape``. -- Axes in ``shape`` that exceed the input dimensions enumerate randomizations. - -Note that ``shape`` can contain size-1 dimensions -that expand to match input dimensions, as is illustrated in the last row of the following table. - -Examples: - -| Input extrinsic | shape | Result | -|:---------------:|:----------:|:-----------------------------------------------------------------:| -| (10,) | (10,) | 10 configurations, 1 randomization each | -| (10,) | (5, 10) | 10 configurations, 5 randomizations each | -| (10,) | (2, 3, 10) | 10 configurations, 2×3=6 randomizations each | -| (4, 1) | (4, 5) | 4 configurations, 5 randomizations each | -| (4, 3) | (2, 4, 3) | 4×3=12 configurations, 2 randomizations each | -| (4, 3) | (2, 1, 3) | 4×3=12 configurations, 2 randomizations each (the 1 expands to 4) | - - - -### Indexing into results - -With randomization axes, you can index into specific randomization/parameter combinations: - -```python -# Using shape=(2, 14, 10) with input extrinsic shape (10,) -result = executor.run(program).result() -meas_data = result[0]["meas"] # shape (2, 14, 10, 1024, 3) - -# Get all shots for randomization (0, 7) and parameter config 3 -specific = meas_data[0, 7, 3, :, :] # shape (1024, 3) - -# Average over all randomizations for parameter config 5 on bit 2 -averaged = meas_data[:, :, 5, :, 2].mean(axis=(0, 1)) -``` - -## Common patterns - -### Sweeping a single parameter -To sweep one parameter while holding others fixed: - -```python - - # Circuit has 3 parameters, sweep first one over 20 values - sweep_values = np.linspace(0, 2*np.pi, 20) - fixed_values = [0.5, 0.3] - - parameter_values = np.column_stack([ - sweep_values, - np.full(20, fixed_values[0]), - np.full(20, fixed_values[1]), - ]) # shape (20, 3) -``` - -### Creating a 2D grid sweep -To create a grid over two parameters: - -```python - -# Sweep param 0 over 10 values, param 1 over 8 values, param 2 fixed -p0 = np.linspace(0, np.pi, 10)[:, np.newaxis, np.newaxis] # (10, 1, 1) -p1 = np.linspace(0, np.pi, 8)[np.newaxis, :, np.newaxis] # (1, 8, 1) -p2 = np.array([[[0.5]]]) # (1, 1, 1) - -parameter_values = np.broadcast_arrays(p0, p1, p2) -parameter_values = np.stack(parameter_values, axis=-1).squeeze() # (10, 8, 3) - -# Extrinsic shape: (10, 8), intrinsic shape: (3,) -``` - -### Combining multiple inputs - -When combining inputs with different intrinsic shapes, align extrinsic dimensions using -size-1 axes: - -```python -# 4 parameter configurations, 3 noise scales → 4×3 = 12 total configurations -parameter_values = np.random.rand(4, 1, 2) # extrinsic (4, 1), intrinsic (2,) -noise_scale = np.array([0.8, 1.0, 1.2]) # extrinsic (3,), intrinsic () -# Broadcasted extrinsic shape: (4, 3) -``` ## Next steps From 122db99e4ace53dfd67fb173d2c1c49c72b99312 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 17 Feb 2026 17:10:46 -0600 Subject: [PATCH 057/118] finish input and output --- docs/guides/executor-broadcasting.mdx | 32 +++--- docs/guides/executor-examples.mdx | 69 +++++++++++- docs/guides/executor-input-output.mdx | 128 +++++++++++----------- docs/guides/get-started-with-executor.mdx | 2 +- 4 files changed, 151 insertions(+), 80 deletions(-) diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index dc634235590..ab4349de8c0 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -51,7 +51,7 @@ Broadcasting only applies to _extrinsic_ axes. The intrinsic axes are always pre - **Intrinsic axes** (rightmost): Determined by the data type. For example, if your circuit has three parameters, then parameter values require three numbers, giving an intrinsic shape - of ``(3,)``. + of `(3,)`. - **Extrinsic axes** (leftmost): Your sweep dimensions. These define how many configurations you want to run. @@ -120,8 +120,8 @@ formatted as an array of boolean values: ### Example -If you provide inputs with extrinsic shapes ``(4, 1)`` and ``(3,)``, the broadcast extrinsic -shape is ``(4, 3)``. For a circuit with 1024 shots and a 3-bit classical register: +If you provide inputs with extrinsic shapes `(4, 1)` and `(3,)`, the broadcast extrinsic +shape is `(4, 3)`. For a circuit with 1024 shots and a 3-bit classical register: ```python # Input extrinsic shapes: (4, 1) and (3,) → (4, 3) @@ -142,29 +142,29 @@ config_2_1 = meas_data[2, 1, :, :] # shape (1024, 3) Each configuration receives the full shot count specified in the quantum program. Shots are **not** divided among configurations. For example, if you request 1024 shots and have 10 configurations, each configuration runs 1024 shots (10,240 total shots executed). -## Randomization and the ``shape`` parameter +## Randomization and the `shape` parameter When using a [samplex,](/docs/guides/directed-execution-model) each element of the extrinsic shape corresponds to an independent circuit execution. The samplex typically injects randomness (for example, twirling gates) into each execution, so even without explicitly requesting multiple randomizations, each element naturally receives its own random realization. -The ``shape`` parameter lets you augment the extrinsic shape for the item, effectively letting you +The `shape` parameter lets you augment the extrinsic shape for the item, effectively letting you add axes that correspond specifically to randomizing the same configuration many times. It must be -broadcastable from the shape implicit in your ``samplex_arguments``. Axes where ``shape`` exceeds +broadcastable from the shape implicit in your `samplex_arguments`. Axes where `shape` exceeds the implicit shape enumerate additional independent randomizations. ### No explicit randomization axes -If you omit ``shape`` (or set it to match your input shapes), you get one execution per +If you omit `shape` (or set it to match your input shapes), you get one execution per input configuration. Each execution is still randomized by the samplex, but with only a single random realization you don't benefit from averaging over multiple randomizations. -If you're used to enabling twirling with a simple flag like ``twirling=True``, -the Executor requires you to explicitly request multiple randomizations with the ``shape`` argument to +If you're used to enabling twirling with a simple flag like `twirling=True`, +the Executor requires you to explicitly request multiple randomizations with the `shape` argument to allow your post-processing routines to get the benefits of averaging over multiple -randomizations. A single randomization (the default when ``shape`` is omitted) applies +randomizations. A single randomization (the default when `shape` is omitted) applies random gates but typically offers no advantage over running the base circuit without randomization. @@ -205,7 +205,7 @@ program.append( You can organize randomizations into a multi-dimensional grid. This is useful for structured analysis, for example, separating randomizations by type or grouping them for statistical processing. -Here, the input extrinsic shape ``(10,)`` broadcasts to the requested shape ``(2, 14, 10)``, +Here, the input extrinsic shape `(10,)` broadcasts to the requested shape `(2, 14, 10)`, with axes 0 and 1 filled by independent randomizations. ```python @@ -222,13 +222,13 @@ program.append( ### How `shape` and input shapes interact -The ``shape`` parameter must be broadcastable *from* your input extrinsic shapes. This means: +The `shape` parameter must be broadcastable *from* your input extrinsic shapes. This means: -- Input shapes with size-1 dimensions can expand to match ``shape``. -- Input shapes must align from the right with ``shape``. -- Axes in ``shape`` that exceed the input dimensions enumerate randomizations. +- Input shapes with size-1 dimensions can expand to match `shape`. +- Input shapes must align from the right with `shape`. +- Axes in `shape` that exceed the input dimensions enumerate randomizations. -Note that ``shape`` can contain size-1 dimensions +Note that `shape` can contain size-1 dimensions that expand to match input dimensions, as is illustrated in the last row of the following table. Examples: diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index 6311a8165b8..fd1ec1ed17c 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -17,7 +17,12 @@ gates, and execute the program by using the `Executor` class. ```python from qiskit.circuit import Parameter, QuantumCircuit -from qiskit_ibm_runtime import QiskitRuntimeService +from qiskit_ibm_runtime import QiskitRuntimeService, Executor +from qiskit_ibm_runtime.quantum_program import QuantumProgram +from qiskit.transpiler import generate_preset_pass_manager +import numpy as np +from samplomatic import build +from samplomatic.transpiler import generate_boxing_pass_manager # Generate the circuit circuit = QuantumCircuit(3) @@ -33,12 +38,71 @@ circuit.rz(Parameter("phi"), 1) circuit.rz(Parameter("lam"), 2) circuit.measure_all() +# Transpile the circuit +preset_pass_manager = generate_preset_pass_manager( + backend=backend, optimization_level=0 +) +isa_circuit = preset_pass_manager.run(circuit) + # Initialize the service and choose a backend service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) ``` -The input to the `Executor` is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output) +## Define a `QuantumProgram` + +The input to the Executor is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output#programs) + +```python +# Initialize an empty program +program = QuantumProgram(shots=1024) + +# Append the circuit to the program +program.append_circuit_item(isa_circuit) + +# Append the circuit and the parameter value to the program +program.append_circuit_item( + isa_circuit, + circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values +) +# Transpile the circuit, additionally grouping gates and measurements into annotated boxes +preset_pass_manager = generate_preset_pass_manager( + backend=backend, optimization_level=0 +) +preset_pass_manager.post_scheduling = generate_boxing_pass_manager( + enable_gates=True, + enable_measures=True, +) +boxed_circuit = preset_pass_manager.run(circuit) + +# Build the template and the samplex +template, samplex = build(boxed_circuit) + +# Append the template and samplex as a samplex item +program.append_samplex_item( + template, + samplex=samplex, + samplex_arguments={ + # the arguments required by the samplex.sample method + "parameter_values": np.random.rand(10, 3), + }, + shape=(2, 14, 10), +) +``` + +## Run the Executor job + +```python +# initialize an Executor with the default options +executor = Executor(backend) + +# Submit the job +job = executor.run(program) + +# Retrieve the result +result = job.result() +``` + @@ -46,4 +110,5 @@ The input to the `Executor` is a `QuantumProgram`. For full details, see [Execut - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Learn how to use [Executor options.](/docs/guides/executor-options) diff --git a/docs/guides/executor-input-output.mdx b/docs/guides/executor-input-output.mdx index be0e0186516..999f66259b1 100644 --- a/docs/guides/executor-input-output.mdx +++ b/docs/guides/executor-input-output.mdx @@ -8,7 +8,8 @@ description: Understand the inputs and outputs to the Executor primitive. The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer. -## Quantum programs + +## Inputs: Quantum programs The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a [`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a @@ -25,28 +26,16 @@ The following cell initializes a `QuantumProgram` and specifies that it should r ```python from qiskit.transpiler import generate_preset_pass_manager from qiskit_ibm_runtime.quantum_program import QuantumProgram +import numpy as np +from samplomatic import build +from samplomatic.transpiler import generate_boxing_pass_manager # Initialize an empty program program = QuantumProgram(shots=1024) -# Initialize circuit to generate and measure GHZ state -circuit = QuantumCircuit(3) -circuit.h(0) -circuit.h(1) -circuit.cz(0, 1) -circuit.h(1) -circuit.h(2) -circuit.cz(1, 2) -circuit.h(2) -circuit.rz(0.1, 0) -circuit.rz(0.2, 1) -circuit.rz(0.3, 2) -circuit.measure_all() - -# Transpile the circuit -preset_pass_manager = generate_preset_pass_manager( - backend=backend, optimization_level=0 -) +# Initialize and transpile a circuit +circuit = ... +... isa_circuit = preset_pass_manager.run(circuit) # Append the circuit to the program @@ -56,27 +45,6 @@ program.append_circuit_item(isa_circuit) Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (1024 per set of parameter values). ```python -from qiskit.circuit import Parameter -import numpy as np - -# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z -# axis, and measure it -circuit = QuantumCircuit(3) -circuit.h(0) -circuit.h(1) -circuit.cz(0, 1) -circuit.h(1) -circuit.h(2) -circuit.cz(1, 2) -circuit.h(2) -circuit.rz(Parameter("theta"), 0) -circuit.rz(Parameter("phi"), 1) -circuit.rz(Parameter("lam"), 2) -circuit.measure_all() - -# Transpile the circuit -isa_circuit = preset_pass_manager.run(circuit) - # Append the circuit and the parameter value to the program program.append_circuit_item( isa_circuit, @@ -84,30 +52,12 @@ program.append_circuit_item( ) ``` -Finally, append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments, ``10`` sets of parameters for the parametric gates in the original circuit are provided. The ``shape`` request argument requests an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting ``shape`` -to ``(2, 14, 10)`` we request to randomize each of the ``10`` sets of parameters ``28`` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape ``(2, 14, 10)``. +Finally, append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments, `10` sets of parameters for the parametric gates in the original circuit are provided. The `shape` request argument requests an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting `shape` +to `(2, 14, 10)` we request to randomize each of the `10` sets of parameters `28` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape `(2, 14, 10)`. See the samplomatic [API](https://github.com/Qiskit/samplomatic/) documentation for full details about `samplomatic.samplex.Samplex` and its arguments. ```python -from samplomatic import build -from samplomatic.transpiler import generate_boxing_pass_manager - -# Initialize circuit to generate a GHZ state, rotate it around the Pauli-Z -# axis, and measure it -circuit = QuantumCircuit(3) -circuit.h(0) -circuit.h(1) -circuit.cz(0, 1) -circuit.h(1) -circuit.h(2) -circuit.cz(1, 2) -circuit.h(2) -circuit.rz(Parameter("theta"), 0) -circuit.rz(Parameter("phi"), 1) -circuit.rz(Parameter("lam"), 2) -circuit.measure_all() - # Transpile the circuit, additionally grouping gates and measurements into annotated boxes preset_pass_manager = generate_preset_pass_manager( backend=backend, optimization_level=0 @@ -133,9 +83,65 @@ program.append_samplex_item( ) ``` +## Outputs + +[`qiskit_ibm_runtime.quantum_program.QuantumProgramResult`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) is an iterable. It contains one +item per circuit task, and the items are in the same order as those in the program. Each of +these items is a dictionary where the keys are strings and the values are of type `np.ndarray`, with elements of type `bool`. + +In the previous example, the result contains three items: + +### Result item 1. +The first item in `result` is the result of running the first task in the program, the circuit with static gates. + +It contains a single key, `'meas'`, corresponding to the name of the input circuit's +classical register, mapped to the results collected for this +classical register. The information is stored in an `np.ndarray` of shape `(shots, register bits)`, for the above example, `(1024, 3)`. + +The following code illustrates how to access this information: + +```python +# Access the results of the classical register of task #0 +result_0 = result[0]["meas"] +print(f"Result shape: {result_0.shape}") +``` + +### Result item 2. + +The second item contains the results of running the second task in the program, +the circuit with parametrized gates. + +It contains a single key, `'meas'`, mapped to an `np.ndarray` of shape `(shots, parameter sets, register bits)`, for the above example, `(1024, 10, 3)`. + +The following code illustrates how to access this information: + +```python +# Access the results of the classical register of task #1 +result_1 = result[1]["meas"] +print(f"Result shape: {result_1.shape}") +``` + +### Result item 3. +The third item contains the results of running the third task in the program. This item +contains multiple keys. In addition to the `'meas'` key (mapped to the array of results for +that classical register), it contains `'measurement_flips.meas'`, the bit-flip corrections to undo +the measurement twirling for the `'meas'` register, as follows: + +```python +# Access the results of the classical register of task #2 +result_2 = result[2]["meas"] +print(f"Result shape: {result_2.shape}") + +# Access the bit-flip corrections +flips_2 = result[2]["measurement_flips.meas"] +print(f"Result shape: {result_0.shape}") + +# Undo the bit flips via classical XOR +unflipped_result_2 = result_2 ^ flips_2 +``` ## Next steps - - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Explore [examples](/docs/guides/executor-examples) that use Executor. diff --git a/docs/guides/get-started-with-executor.mdx b/docs/guides/get-started-with-executor.mdx index 5bfb23ca4d2..c293eaf43cd 100644 --- a/docs/guides/get-started-with-executor.mdx +++ b/docs/guides/get-started-with-executor.mdx @@ -41,5 +41,5 @@ Here, the result is of type [`QuantumProgramResult`.](https://qiskit.github.io/q ## Next steps - - + - Understand [Executor input and output](/docs/guides/executor-input-output) From 01a852c98a21cb5c7a5d16f5d08c16d94fe84f76 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 08:42:33 -0600 Subject: [PATCH 058/118] fixes --- docs/guides/executor-rest-api.mdx | 14 ++++++++++++++ qiskit_bot.yaml | 5 ----- 2 files changed, 14 insertions(+), 5 deletions(-) create mode 100644 docs/guides/executor-rest-api.mdx diff --git a/docs/guides/executor-rest-api.mdx b/docs/guides/executor-rest-api.mdx new file mode 100644 index 00000000000..bc1c44c4758 --- /dev/null +++ b/docs/guides/executor-rest-api.mdx @@ -0,0 +1,14 @@ +--- +title: REST API +description: Using the Executor primitive with the REST API. + +--- + + + +## Next steps + + + - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Learn how to use [Executor options.](/docs/guides/executor-options) + diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 6154146617d..1ee1281f657 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -312,11 +312,6 @@ notifications: - "@ElePT" - "`@beckykd`" - "`@abbycross`" - "docs/guides/primitives-examples": - - "@jyu00" - - "`@beckykd`" - - "`@abbycross`" - - "`@blakejohnson`" "docs/guides/processor-types": - "`@lerongil`" - "@abbycross" From f7f9aaff2f67d9163fd6f665a7ed799fd043a5ef Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 08:55:51 -0600 Subject: [PATCH 059/118] REST api isn't ready yet --- docs/guides/_toc.json | 8 +--- docs/guides/broadcasting.mdx | 61 ++++++++++++++----------------- docs/guides/executor-rest-api.mdx | 14 ------- qiskit_bot.yaml | 6 --- 4 files changed, 29 insertions(+), 60 deletions(-) delete mode 100644 docs/guides/executor-rest-api.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 0b4983297a5..ecf8dde4ee8 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -427,12 +427,8 @@ { "title": "Examples", "url": "/docs/guides/executor-examples" - }, - { - "title": "REST API", - "url": "/docs/guides/executor-rest-api" - } - ] + } + ] }, { "title": "Manage noise", diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx index 89befc0a7e9..6db1b3fe5a0 100644 --- a/docs/guides/broadcasting.mdx +++ b/docs/guides/broadcasting.mdx @@ -1,52 +1,45 @@ --- title: Broadcasting -description: How the Executor handles array inputs and outputs using broadcasting semantics +description: Understand how primitives handle array inputs and outputs using broadcasting semantics --- -# Executor broadcasting semantics -This guide explains how the executor handles array inputs and outputs using broadcasting semantics. -Understanding these concepts will help you efficiently sweep over parameter values, combine -multiple experimental configurations, and interpret the shape of returned data. +# Primitive brodcasting -## Quick start example +## Rules -Before explaining the details, here's a simple example that demonstrates the core idea. The following example sets up a parametric circuit and and five different parameter configurations. The executor automatically runs all five configurations and returns data organized by configuration, with one result per classical register in each quantum program item. The rest of this guide explains how this works in detail and how to build more complex sweeps, including samplomatic-based randomization and inputs. +The primitives 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). -```python -import numpy as np -from qiskit.circuit import Parameter, QuantumCircuit -from qiskit_ibm_runtime.quantum_program import QuantumProgram +Rules: -# A circuit with 3 parameters -circuit = QuantumCircuit(3) -circuit.rx(Parameter("a"), 0) -circuit.rx(Parameter("b"), 1) -circuit.rx(Parameter("c"), 2) -circuit.measure_all() +* Input arrays do not need to have the same number of dimensions. + * The resulting array will have the same number of dimensions as the input array with the largest dimension. + * The size of each dimension is the largest size of the corresponding dimension. + * Missing dimensions are assumed to have size one. +* Shape comparisons start with the rightmost dimension and continue to the left. +* Two dimensions are compatible if their sizes are equal or if one of them is 1. -# 5 different parameter configurations (shape: 5 configurations × 3 parameters) -parameter_values = np.linspace(0, np.pi, 15).reshape(5, 3) +Examples of array pairs that broadcast: -program = QuantumProgram(shots=1024) -program.append(circuit, circuit_arguments=parameter_values) +```text +A1 (1d array): 1 +A2 (2d array): 3 x 5 +Result (2d array): 3 x 5 -# Run and get results -result = executor.run(program).result() -# result is a list with one entry per program item -# result[0] is a dict mapping classical register names to data arrays -# Output bool arrays have shape (5, 1024, 3) -# 5 = number of parameter configurations -# 1024 = number of shots -# 3 = bits in the classical register -result[0]["meas"] +A1 (3d array): 11 x 2 x 7 +A2 (3d array): 11 x 1 x 7 +Result (3d array): 11 x 2 x 7 ``` +Examples of array pairs that do not broadcast: +```text +A1 (1d array): 5 +A2 (1d array): 3 -## Next steps +A1 (2d array): 2 x 1 +A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5. +``` - - - - +The primitives return one value for each element of the broadcasted shape. \ No newline at end of file diff --git a/docs/guides/executor-rest-api.mdx b/docs/guides/executor-rest-api.mdx deleted file mode 100644 index bc1c44c4758..00000000000 --- a/docs/guides/executor-rest-api.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API -description: Using the Executor primitive with the REST API. - ---- - - - -## Next steps - - - - Review the overview of [broadcasting.](/docs/guides/broadcasting) - - Learn how to use [Executor options.](/docs/guides/executor-options) - diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 1ee1281f657..1a11e06c608 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -469,12 +469,6 @@ notifications: - "@pacomf" - "@Bagherpoor" - "@kaelynj" - "docs/guides/executor-rest-api": - - "@born-2learn" - - "@HuangJunye" - - "@pacomf" - - "@Bagherpoor" - - "@kaelynj" "docs/guides/estimator-rest-api": - "@born-2learn" - "@HuangJunye" From e52d181ad9bfabbed6c9aa72722c0cc3dcfbc95f Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 09:26:24 -0600 Subject: [PATCH 060/118] Pull in working toc --- docs/guides/_toc.json | 1141 +++++------------------------------------ 1 file changed, 139 insertions(+), 1002 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index ecf8dde4ee8..e2c40c91ef1 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -1,989 +1,19 @@ { - "title": "Documentation", - "collapsed": true, - "children": [ - { - "title": "Get started", - "children": [ - { - "title": "Introduction", - "url": "/docs/guides" - }, - { - "title": "Quickstart", - "url": "/docs/guides/quick-start" - }, - { - "title": "Latest updates", - "url": "/docs/guides/latest-updates" - } - ], - "collapsible": false - }, - { - "title": "Qiskit", - "children": [ - { - "title": "Introduction to Qiskit", - "url": "/docs/guides/tools-intro" - }, - { - "title": "Install", - "children": [ - { - "title": "Install Qiskit", - "url": "/docs/guides/install-qiskit" - }, - { - "title": "Install the Qiskit SDK from source", - "url": "/docs/guides/install-qiskit-source" - }, - { - "title": "Configure the Qiskit SDK locally", - "url": "/docs/guides/configure-qiskit-local" - }, - { - "title": "Install the Qiskit C API", - "url": "/docs/guides/install-c-api" - }, - { - "title": "Extend Qiskit in Python with C", - "url": "/docs/guides/c-extension-for-python" - }, - { - "title": "Online lab environments", - "url": "/docs/guides/online-lab-environments" - } - ] - }, - { - "title": "Circuits and operators", - "children": [ - { - "title": "Overview", - "url": "/docs/guides/construct-circuits" - }, - { - "title": "Circuit library", - "url": "/docs/guides/circuit-library" - }, - { - "title": "Save circuits to disk", - "url": "/docs/guides/save-circuits" - }, - { - "title": "Measure qubits", - "url": "/docs/guides/measure-qubits" - }, - { - "title": "Operators module", - "children": [ - { - "title": "Operators module overview", - "url": "/docs/guides/operators-overview" - }, - { - "title": "The Operator class", - "url": "/docs/guides/operator-class" - }, - { - "title": "Synthesize unitary operators", - "url": "/docs/guides/synthesize-unitary-operators" - }, - { - "title": "Specify observables in the Pauli basis", - "url": "/docs/guides/specify-observables-pauli" - } - ] - }, - { - "title": "Advanced circuit building", - "children": [ - { - "title": "Fractional gates", - "url": "/docs/guides/fractional-gates" - }, - { - "title": "Classical feedforward and control flow", - "url": "/docs/guides/classical-feedforward-and-control-flow" - }, - { - "title": "Deferred timing resolution using stretch", - "url": "/docs/guides/stretch" - }, - { - "title": "Bit-ordering in the Qiskit SDK", - "url": "/docs/guides/bit-ordering" - } - ] - }, - { - "title": "OpenQASM", - "children": [ - { - "title": "Intro to OpenQASM", - "url": "/docs/guides/introduction-to-qasm" - }, - { - "title": "OpenQASM 2 and the Qiskit SDK", - "url": "/docs/guides/interoperate-qiskit-qasm2" - }, - { - "title": "OpenQASM 3 and the Qiskit SDK", - "url": "/docs/guides/interoperate-qiskit-qasm3" - }, - { - "title": "OpenQASM 3 feature table", - "url": "/docs/guides/qasm-feature-table" - }, - { - "title": "OpenQASM 3.x live specification", - "url": "https://openqasm.com/" - } - ] - } - ] - }, - { - "title": "Transpilation", - "children": [ - { - "title": "Introduction to transpilation", - "url": "/docs/guides/transpile" - }, - { - "title": "Transpiler stages", - "url": "/docs/guides/transpiler-stages" - }, - { - "title": "Transpile with pass managers", - "url": "/docs/guides/transpile-with-pass-managers" - }, - { - "title": "Create a pass manager for dynamical decoupling", - "url": "/docs/guides/dynamical-decoupling-pass-manager" - }, - { - "title": "Compare transpiler settings", - "url": "/docs/guides/circuit-transpilation-settings" - }, - { - "title": "Configure preset pass managers", - "children": [ - { - "title": "Default settings and configuration options", - "url": "/docs/guides/defaults-and-configuration-options" - }, - { - "title": "Set optimization level", - "url": "/docs/guides/set-optimization" - }, - { - "title": "Commonly used parameters for transpilation", - "url": "/docs/guides/common-parameters" - }, - { - "title": "Represent quantum computers", - "url": "/docs/guides/represent-quantum-computers" - } - ] - }, - { - "title": "Advanced transpilation resources", - "children": [ - { - "title": "Write a custom transpiler pass", - "url": "/docs/guides/custom-transpiler-pass" - }, - { - "title": "Create and transpile against custom backends", - "url": "/docs/guides/custom-backend" - }, - { - "title": "Install and use transpiler plugins", - "url": "/docs/guides/transpiler-plugins" - }, - { - "title": "Create a transpiler plugin", - "url": "/docs/guides/create-transpiler-plugin" - }, - { - "title": "Work with DAGs in transpiler passes", - "url": "/docs/guides/DAG-representation" - } - ] - } - ] - }, - { - "title": "Exact simulation with Qiskit SDK primitives", - "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" - - }, - { - "title": "Debugging", - "children": [ - { - "title": "Simulate circuits with noise", - "children": [ - { - "title": "Introduction to debugging tools", - "url": "/docs/guides/debugging-tools" - }, - { - "title": "Exact and noisy simulation with Qiskit Aer primitives", - "url": "/docs/guides/simulate-with-qiskit-aer" - }, - { - "title": "Build noise models", - "url": "/docs/guides/build-noise-models" - }, - { - "title": "Efficient simulation of stabilizer circuits with Qiskit Aer primitives", - "url": "/docs/guides/simulate-stabilizer-circuits" - }, - { - "title": "Debug Qiskit Runtime jobs", - "url": "/docs/guides/debug-qiskit-runtime-jobs" - } - ] - }, - { - "title": "Visualization", - "children": [ - { - "title": "Visualize circuits", - "url": "/docs/guides/visualize-circuits" - }, - { - "title": "Visualize circuit timing", - "url": "/docs/guides/visualize-circuit-timing", - "isNew": true, - "isNewDate": "2025-11-20" - }, - { - "title": "Plot quantum states", - "url": "/docs/guides/plot-quantum-states" - }, - { - "title": "Visualize results", - "url": "/docs/guides/visualize-results" - } - ] - } - ] - }, - { - "title": "Advanced techniques", - "url": "/docs/guides/addons" - }, - { - "title": "Create a provider", - "url": "/docs/guides/create-a-provider" - }, - { - "title": "Integrations", - "children": [ - { - "title": "Quantum resource management interface (QRMI)", - "url": "/docs/guides/qrmi", - "isNew": true - }, - { - "title": "SPANK plugin for QRMI", - "url": "/docs/guides/slurm-plugin", - "isNew": true - }, - { - "title": "SPANK plugin user guide", - "url": "/docs/guides/slurm-hpc-ux", - "isNew": true - }, - { - "title": "Qiskit MCP servers", - "url": "/docs/guides/qiskit-mcp-servers" - } - ] - }, - { - "title": "Qiskit code assistant", - "children": [ - { - "title": "Qiskit Code Assistant overview", - "url": "/docs/guides/qiskit-code-assistant" - }, - { - "title": "Use Qiskit Code Assistant in JupyterLab", - "url": "/docs/guides/qiskit-code-assistant-jupyterlab" - }, - { - "title": "Use Qiskit Code Assistant in VS Code", - "url": "/docs/guides/qiskit-code-assistant-vscode" - }, - { - "title": "Use Qiskit Code Assistant in local mode", - "url": "/docs/guides/qiskit-code-assistant-local" - }, - { - "title": "Qiskit Code Assistant - OpenAI API compatibility", - "url": "/docs/guides/qiskit-code-assistant-openai-api" - } - ] - } - ], - "collapsible": false - }, - { - "title": "IBM Quantum Compute platform", - "children": [ - { - "title": "Run your first circuit on hardware", - "url": "/docs/guides/hello-world" - }, - { - "title": "Execute with primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/primitives" - }, - { - "title": "Introduction to PUBs", - "url": "/docs/guides/pubs" - }, - { - "title": "Introduction to broadcasting", - "url": "/docs/guides/broadcasting" - }, - { - "title": "Estimator", - "children": [ - { - "title": "Get started", - "url": "/docs/guides/get-started-with-estimator" - }, - { - "title": "Inputs and outputs", - "url": "/docs/guides/estimator-input-output" - }, - { - "title": "Broadcasting", - "url": "/docs/guides/estimator-broadcasting" - }, - { - "title": "Options", - "url": "/docs/guides/estimator-options" - }, - { - "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": "Examples", - "url": "/docs/guides/sampler-examples" - }, - { - "title": "REST API", - "url": "/docs/guides/sampler-rest-api" - } - ] - }, - { - "title": "Executor", - "children": [ - { - "title": "Get started", - "url": "/docs/guides/get-started-with-executor" - }, - { - "title": "Inputs and outputs", - "url": "/docs/guides/executor-input-output" - }, - { - "title": "Options", - "url": "/docs/guides/executor-options" - }, - { - "title": "Examples", - "url": "/docs/guides/executor-examples" - } - ] - }, - { - "title": "Manage noise", - "children": [ - { - "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": "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": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - } - ] - }, - { - "title": "IBM quantum computers", - "children": [ - { - "title": "Processor types", - "url": "/docs/guides/processor-types" - }, - { - "title": "QPU information", - "url": "/docs/guides/qpu-information" - }, - { - "title": "Get backend information with Qiskit", - "url": "/docs/guides/get-qpu-information" - }, - { - "title": "Calibration jobs", - "url": "/docs/guides/calibration-jobs" - }, - { - "title": "Qubit initialization", - "url": "/docs/guides/repetition-rate-execution" - }, - { - "title": "Retired cloud QPUs", - "url": "/docs/guides/retired-qpus" - }, - { - "title": "Fair-share scheduler", - "url": "/docs/guides/fair-share-scheduler" - }, - { - "title": "View cost", - "url": "/docs/guides/view-cost" - } - ] - }, - { - "title": "Manage workload execution", - "children": [ - { - "title": "Monitor or cancel a job", - "url": "/docs/guides/monitor-job" - }, - { - "title": "Workload usage", - "url": "/docs/guides/estimate-job-run-time" - }, - { - "title": "Minimize job run time", - "url": "/docs/guides/minimize-time" - }, - { - "title": "Maximum execution time", - "url": "/docs/guides/max-execution-time" - }, - { - "title": "Job limits", - "url": "/docs/guides/job-limits" - }, - { - "title": "Organize and search by job tags", - "url": "/docs/guides/add-job-tags" - }, - { - "title": "Retrieve and save job results", - "url": "/docs/guides/save-jobs" - } - ] - }, - { - "title": "Execution modes", - "children": [ - { - "title": "Introduction to execution modes", - "url": "/docs/guides/execution-modes" - }, - { - "title": "Choose the right execution mode", - "url": "/docs/guides/choose-execution-mode" - }, - { - "title": "Run jobs in a batch", - "url": "/docs/guides/run-jobs-batch" - }, - { - "title": "Run jobs in a session", - "url": "/docs/guides/run-jobs-session" - }, - { - "title": "Execution modes using REST API", - "url": "/docs/guides/execution-modes-rest-api" - } - ] - }, - { - "title": "IBM Quantum Platform", - "children": [ - { - "title": "Set up IBM Quantum Platform", - "children": [ - { - "title": "Set up your IBM Cloud account", - "url": "/docs/guides/cloud-setup" - }, - { - "title": "Set up your IBM Cloud account - invited users", - "url": "/docs/guides/cloud-setup-invited", - "platform": "cloud" - }, - { - "title": "Set up your IBM Cloud account in an untrusted environment", - "url": "/docs/guides/cloud-setup-untrusted", - "platform": "cloud" - }, - { - "title": "Set up to use IBM Quantum Platform with REST API", - "url": "/docs/guides/cloud-setup-rest-api", - "platform": "cloud" - }, - { - "title": "Save your login credentials", - "url": "/docs/guides/save-credentials", - "platform": "cloud" - }, - { - "title": "Initialize your Qiskit Runtime service account", - "url": "/docs/guides/initialize-account", - "platform": "cloud" - }, - { - "title": "Set up for an organization", - "children": [ - { - "title": "Setup considerations", - "url": "/docs/guides/considerations-set-up-runtime" - }, - { - "title": "Configure IBM Quantum Platform", - "url": "/docs/guides/quickstart-steps-org" - } - ] - } - ] - }, - { - "title": "IBM Quantum plans", - "children": [ - { - "title": "Overview of plans", - "url": "/docs/guides/plans-overview" - }, - { - "title": "Upgrade from the Open Plan", - "url": "/docs/guides/upgrade-from-open" - }, - { - "title": "Manage cost on the Pay-As-You-Go Plan", - "url": "/docs/guides/manage-cost" - } - ] - }, - { - "title": "Work with instances", - "children": [ - { - "title": "Create and manage instances", - "url": "/docs/guides/instances" - }, - { - "title": "Set allocation limits", - "url": "/docs/guides/allocation-limits" - }, - { - "title": "Use IBM Cloud Platform APIs to access instances", - "url": "/docs/guides/access-instances-platform-apis" - } - ] - }, - { - "title": "Accounts, access groups, and policies", - "children": [ - { - "title": "Cloud account structure", - "url": "/docs/guides/cloud-account-structure" - }, - { - "title": "Create access groups and policies", - "url": "/docs/guides/access-groups" - }, - { - "title": "Set up custom roles", - "url": "/docs/guides/custom-roles" - } - ] - }, - { - "title": "Manage users", - "children": [ - { - "title": "Invite users and manage access", - "url": "/docs/guides/invite-and-manage-users" - }, - { - "title": "Manage ID provider users", - "url": "/docs/guides/manage-appid" - }, - { - "title": "Manage IBM Cloud users", - "url": "/docs/guides/manage-cloud-users" - } - ] - }, - { - "title": "Logging", - "url": "/docs/guides/logging" - } - ] - }, - { - "title": "Qiskit Serverless", - "children": [ - { - "title": "Qiskit Serverless overview", - "url": "/docs/guides/serverless" - }, - { - "title": "Write your first Qiskit Serverless program", - "url": "/docs/guides/serverless-first-program" - }, - { - "title": "Run your first Qiskit Serverless workload remotely", - "url": "/docs/guides/serverless-run-first-workload" - }, - { - "title": "Manage Qiskit Serverless compute and data resources", - "url": "/docs/guides/serverless-manage-resources" - }, - { - "title": "Port code to Qiskit Serverless", - "url": "/docs/guides/serverless-port-code" - } - ] - }, - { - "title": "Qiskit Transpiler Service", - "children": [ - { - "title": "Transpile circuits remotely with the Qiskit Transpiler Service", - "url": "/docs/guides/qiskit-transpiler-service" - }, - { - "title": "AI transpiler passes", - "url": "/docs/guides/ai-transpiler-passes" - } - ] - } - ], - "collapsible": false - }, + "title": "Documentation", + "collapsed": true, + "children": [ + { + "title": "Get started", + "children": [ { - "title": "Applications research tools", - "children": [ - { - "title": "Introduction to Qiskit Functions", - "url": "/docs/guides/functions" - }, - { - "title": "Circuit functions", - "children": [ - { - "title": "IBM Circuit function", - "url": "/docs/guides/ibm-circuit-function" - }, - { - "title": "Algorithmiq Tensor-network error mitigation", - "url": "/docs/guides/algorithmiq-tem" - }, - { - "title": "Q-CTRL Performance Management", - "url": "/docs/guides/q-ctrl-performance-management" - }, - { - "title": "Qedma QESEM", - "url": "/docs/guides/qedma-qesem" - } - ] - }, - { - "title": "Application functions", - "children": [ - { - "title": "Kipu Quantum Iskay Quantum Optimizer", - "url": "/docs/guides/kipu-optimization" - }, - { - "title": "Multiverse Computing Singularity", - "url": "/docs/guides/multiverse-computing-singularity" - }, - { - "title": "Q-CTRL Optimization Solver", - "url": "/docs/guides/q-ctrl-optimization-solver" - }, - { - "title": "Quantum Portfolio Optimizer: A Qiskit Function by Global Data Quantum", - "url": "/docs/guides/global-data-quantum-optimizer" - }, - { - "title": "QUICK-PDE: A Qiskit Function by ColibriTD", - "url": "/docs/guides/colibritd-pde" - }, - { - "title": "Qunova Computing HI-VQE Chemistry", - "url": "/docs/guides/qunova-chemistry" - } - ] - }, - { - "title": "Qiskit Function templates", - "children": [ - { - "title": "Introduction to Qiskit Function templates", - "url": "/docs/guides/qiskit-function-templates" - }, - { - "title": "Template for chemistry simulation", - "url": "/docs/guides/function-template-chemistry-workflow" - }, - { - "title": "Template for Hamiltonian simulation", - "url": "/docs/guides/function-template-hamiltonian-simulation" - } - ] - }, - { - "title": "Sample-based quantum diagonalization (SQD)", - "children": [ - { - "title": "SQD addon overview", - "url": "/docs/guides/qiskit-addons-sqd" - }, - { - "title": "Get started with SQD", - "url": "/docs/guides/qiskit-addons-sqd-get-started" - } - ] - } - ], - "collapsible": false + "title": "Introduction", + "url": "/docs/guides" }, { - "title": "Additional resources", - "collapsible": false, - "children": [ - { - "title": "Support and FAQ", - "children": [ - { - "title": "Support", - "url": "/docs/guides/support" - }, - { - "title": "Frequently-asked questions", - "url": "/docs/guides/faq" - }, - { - "title": "Execution modes FAQ", - "url": "/docs/guides/execution-modes-faq" - } - ] - }, - { - "title": "Development workflow", - "url": "/docs/guides/intro-to-patterns" - }, - { - "title": "Migration guides", - "children": [ - { - "title": "Migrate to Qiskit 2.0", - "children": [ - { - "title": "Qiskit v2.0 migration guide", - "url": "/docs/guides/qiskit-2.0" - }, - { - "title": "Migrate from BackendV1 to BackendV2", - "url": "/docs/guides/qiskit-backendv1-to-v2" - } - ] - }, - { - "title": "Migrate to Qiskit 1.0", - "children": [ - { - "title": "Introduction", - "url": "/docs/guides/qiskit-1.0" - }, - { - "title": "Understand the breaking package changes", - "url": "/docs/guides/metapackage-migration" - }, - { - "title": "Install the new package", - "url": "/docs/guides/qiskit-1.0-installation" - }, - { - "title": "Feature changes", - "url": "/docs/guides/qiskit-1.0-features" - } - ] - }, - { - "title": "Migrate from Qiskit Pulse to fractional gates", - "url": "/docs/guides/pulse-migration" - }, - { - "title": "Migrate to the Qiskit Runtime V2 primitives", - "url": "/docs/guides/v2-primitives" - }, - { - "title": "Migrate to local simulators", - "url": "/docs/guides/local-simulators" - } - ] - }, - { - "title": "Open-source resources", - "children": [ - { - "title": "Introduction", - "url": "/docs/guides/open-source" - }, - { - "title": "Code of conduct", - "url": "/docs/guides/code-of-conduct" - }, - { - "title": "Contributor license agreements", - "children": [ - { - "title": "Individual contributor", - "url": "/docs/open-source/qiskit-cla.pdf" - }, - { - "title": "Corporate contributor", - "url": "/docs/open-source/qiskit-corporate-cla.pdf" - } - ] - }, - { - "title": "Qiskit SDK", - "children": [ - { - "title": "Version strategy", - "url": "/docs/guides/qiskit-sdk-version-strategy" - }, - { - "title": "Create a provider", - "url": "/docs/guides/create-a-provider" - }, - { - "title": "Contributor guide", - "url": "https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md" - }, - { - "title": "Maintainer guide", - "url": "https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md" - } - ] - }, - { - "title": "Qiskit ecosystem", - "url": "https://www.ibm.com/quantum/ecosystem" - } - ] - }, - { - "title": "Security and compliance", - "collapsed": true, - "children": [ - { - "title": "Securing your data", - "url": "/docs/guides/secure-data" - }, - { - "title": "Understanding your responsibilities when using Qiskit Runtime", - "url": "/docs/guides/responsibilities" - }, - { - "title": "Use virtual private endpoints for VPC", - "url": "/docs/guides/virtual-private-endpoints" - }, - { - "title": "High availability and disaster recovery", - "url": "/docs/guides/ha-dr" - }, - { - "title": "Activity tracking events for Qiskit Runtime", - "url": "/docs/guides/observability" - }, - { - "title": "Protecting Qiskit Runtime Service resources with context-based restrictions", - "url": "/docs/guides/context-based-restrictions" - } - ] - } - ] + "title": "Quickstart", + "url": "/docs/guides/quick-start" }, { - "title": "IBM Quantum Composer", - "url": "/docs/guides/composer" - } - ] -} "title": "Latest updates", "url": "/docs/guides/latest-updates" } @@ -1185,27 +215,134 @@ } ] }, - { - "title": "Primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/primitives" - }, - { - "title": "Get started with primitives", - "url": "/docs/guides/get-started-with-primitives" - }, - { - "title": "Primitive inputs and outputs", - "url": "/docs/guides/primitive-input-output" - }, - { - "title": "Exact simulation with Qiskit SDK primitives", - "url": "/docs/guides/simulate-with-qiskit-sdk-primitives" - } - ] - }, + { + "title": "Execute with primitives", + "children": [ + { + "title": "Introduction to primitives", + "url": "/docs/guides/primitives" + }, + { + "title": "Introduction to PUBs", + "url": "/docs/guides/pubs" + }, + { + "title": "Introduction to broadcasting", + "url": "/docs/guides/broadcasting" + }, + { + "title": "Estimator", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-estimator" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/estimator-input-output" + }, + { + "title": "Broadcasting", + "url": "/docs/guides/estimator-broadcasting" + }, + { + "title": "Options", + "url": "/docs/guides/estimator-options" + }, + { + "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": "Examples", + "url": "/docs/guides/sampler-examples" + }, + { + "title": "REST API", + "url": "/docs/guides/sampler-rest-api" + } + ] + }, + { + "title": "Executor", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-executor" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/executor-input-output" + }, + { + "title": "Options", + "url": "/docs/guides/executor-options" + }, + { + "title": "Examples", + "url": "/docs/guides/executor-examples" + } ] + }, + { + "title": "Manage noise", + "children": [ + { + "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": "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": "Qiskit Runtime local testing mode", + "url": "/docs/guides/local-testing-mode" + } + ] + }, { "title": "Debugging", "children": [ @@ -1886,4 +1023,4 @@ "url": "/docs/guides/composer" } ] -} +} \ No newline at end of file From 7210da599053644ab8aaf3d52d9b38d11692e301 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 09:35:10 -0600 Subject: [PATCH 061/118] spelling --- docs/guides/broadcasting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx index 6db1b3fe5a0..103c53390b2 100644 --- a/docs/guides/broadcasting.mdx +++ b/docs/guides/broadcasting.mdx @@ -4,7 +4,7 @@ description: Understand how primitives handle array inputs and outputs using bro --- -# Primitive brodcasting +# Primitive broadcasting ## Rules From ceb14aad8939db90f3db202fe75be0aa995277b0 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 10:14:53 -0600 Subject: [PATCH 062/118] fix links --- docs/api/qiskit-ibm-runtime/release-notes.mdx | 4 ++-- docs/guides/directed-execution-model.mdx | 2 +- docs/guides/execution-modes-rest-api.ipynb | 5 +++-- docs/guides/execution-modes.mdx | 2 +- docs/guides/get-started-with-estimator.ipynb | 2 +- docs/guides/get-started-with-sampler.ipynb | 4 ++-- docs/guides/primitives.ipynb | 2 +- docs/guides/q-ctrl-performance-management.ipynb | 2 +- docs/guides/simulate-with-qiskit-sdk-primitives.ipynb | 4 ++-- 9 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index 450afaf2487..962b0508a86 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -1057,7 +1057,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/executor-examples)) to see this coupled with operator transformations. @@ -1101,7 +1101,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/executor-examples)) to see this coupled with operator transformations. diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index 66ae63463af..1984f086ce6 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -52,7 +52,7 @@ To learn more about Samplomatic, visit the [guides](https://qiskit.github.io/sam 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. -The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to [Get started with Executor](/docs/guides/get-started-executor) for more information. +The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to [Get started with Executor](/docs/guides/get-started-with-executor) for more information. ### NoiseLearnerV3 diff --git a/docs/guides/execution-modes-rest-api.ipynb b/docs/guides/execution-modes-rest-api.ipynb index 24c1452af2f..1573b11b008 100644 --- a/docs/guides/execution-modes-rest-api.ipynb +++ b/docs/guides/execution-modes-rest-api.ipynb @@ -37,7 +37,7 @@ "\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 the Estimator or the Sampler is made without a context manager. See how to run a quantum circuit using [Estimator](estimator-rest-api) and [Sampler](sampler-rest-api) for some examples.\n", "\n", "## Session mode with REST API\n", "\n", @@ -278,7 +278,8 @@ "## Next steps\n", "\n", "\n", - " - Review detailed [Sampler and Estimator](primitives-rest-api) primitives examples using REST API.\n", + " - Review detailed [Sampler](sampler-rest-api) primitives examples using REST API.\n", + " - Review detailed [Estimator](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", diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index f799f4cdcd1..05aca0e6cd9 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 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 [Estimator examples](/docs/guides/estimator-examples) or [Sampler examples](/docs/guides/sampler-examples) for usage. ## Batch mode diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 5577474aa4e..7f9406705f7 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -332,7 +332,7 @@ "\n", "\n", " - Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", - " - Review detailed [primitives examples.](primitives-examples)\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](transpile/) section.\n", " - Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings#compare-transpiler-settings) guide.\n", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index 1147904ae30..85f4f29b392 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -284,11 +284,11 @@ "\n", "\n", " - Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", - " - Review detailed [primitives examples.](primitives-examples)\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.](runtime-options-overview)\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", "" diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 7c746244ac3..a826c980be5 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -142,7 +142,7 @@ "\n", "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) that contains the computed expectation values per pair, and their standard errors, in `PubResult` form. Each `PubResult` contains both data and metadata.\n", "\n", - "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive inputs and outputs](pubs#broadcasting-rules) topic.\n", + "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/guides/docs/broadcasting) topic.\n", "\n", "Example:" ] diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index db2a72525ca..10aa4c7e5a8 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -382,7 +382,7 @@ "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/estimator-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", - "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./pubs#broadcasting-rules) as the `QiskitRuntime` primitives.\n", + "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./broadcasting) as the `QiskitRuntime` primitives.\n", "- (Optional) A target precision for expectation values to estimate.\n", "- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": }`.\n", "\n", diff --git a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb index 32b99a1d3fd..bbd27c89d74 100644 --- a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb +++ b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb @@ -251,7 +251,7 @@ "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", @@ -518,7 +518,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](./sampler-examples) page.\n", "## Next steps\n", "\n", "\n", From db61b1ff192b1eafb2ecb7067ca9f4bd42040aad Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 10:35:14 -0600 Subject: [PATCH 063/118] fix links --- docs/guides/local-testing-mode.ipynb | 3 ++- docs/guides/primitives.ipynb | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/local-testing-mode.ipynb b/docs/guides/local-testing-mode.ipynb index f7312fd9e0b..6fa5bbc5ae8 100644 --- a/docs/guides/local-testing-mode.ipynb +++ b/docs/guides/local-testing-mode.ipynb @@ -267,7 +267,8 @@ "## Next steps\n", "\n", "\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/primitives.ipynb b/docs/guides/primitives.ipynb index a826c980be5..c2fc770faef 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -142,7 +142,7 @@ "\n", "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) that contains the computed expectation values per pair, and their standard errors, in `PubResult` form. Each `PubResult` contains both data and metadata.\n", "\n", - "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/guides/docs/broadcasting) topic.\n", + "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/docs/guides/broadcasting) topic.\n", "\n", "Example:" ] @@ -227,7 +227,7 @@ "\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](pubs#broadcasting-rules) for full details.\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 broadcasting](/docs/guides/broadcasting) for full details.\n", "\n", "Example:" ] From 4b5df2c11c14906d7e10c9bc4c2b33c27875d3ff Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 13:02:41 -0600 Subject: [PATCH 064/118] fix toc --- docs/guides/_toc.json | 4 + .../runtime-options-overview-estimator.mdx | 997 ------------------ .../runtime-options-overview-sampler.mdx | 420 -------- 3 files changed, 4 insertions(+), 1417 deletions(-) delete mode 100644 docs/guides/runtime-options-overview-estimator.mdx delete mode 100644 docs/guides/runtime-options-overview-sampler.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index e2c40c91ef1..bfdaeb4e60d 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -296,6 +296,10 @@ "url": "/docs/guides/executor-input-output" }, { + "title": "Broadcasting", + "url": "/docs/guides/executor-broadcasting" + }, + { "title": "Options", "url": "/docs/guides/executor-options" }, diff --git a/docs/guides/runtime-options-overview-estimator.mdx b/docs/guides/runtime-options-overview-estimator.mdx deleted file mode 100644 index 4e5f7a068ef..00000000000 --- a/docs/guides/runtime-options-overview-estimator.mdx +++ /dev/null @@ -1,997 +0,0 @@ ---- -title: Introduction to options -description: Available options for building with Qiskit Runtime primitives -in_page_toc_min_heading_level: 2 -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 - - -### 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. - - -### 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. - - -## 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. - - - -
- -### `default_shots` - - -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) -
- -
- -### `default_precision` - - -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) -
- -
- -### `dynamical_decoupling` - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling) -
- -#### `dynamical_decoupling.enable` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- -#### `dynamical_decoupling.extra_slack_distribution` - - -**Choices**: `middle`, `edges` - -**Default**: `middle` -
- -
- -#### `dynamical_decoupling.scheduling_method` - - -Choices: `asap`, `alap` -Default: `alap` -
- -
- -#### `dynamical_decoupling.sequence_type` - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` -
- -
- -#### `dynamical_decoupling.skip_reset_qubits` - - -Choices: `True`, `False` -Default: `False` -
- -
- - -
- -### `environment` - - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment) -
- -#### `environment.callback` - - -Callable function that receives the `Job ID` and `Job result`. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.job_tags` - - -List of tags. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.log_level` - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING -
- -
- -#### `environment.private` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- - -
- -### `execution` - - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution) -
- -#### `execution.init_qubits` - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` -
- -
- -#### `execution.rep_delay` - -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` -
- -
- - -
- -### `max_execution_time` - -**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) -
- -
- -### `resilience` - -Advanced resilience options to fine tune the resilience strategy. - -[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience) -
- -#### `resilience.layer_noise_learning` - - -Options for learning layer noise. - -[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options) -
- -
- -##### `resilience.layer_noise_learning.layer_pair_depths` - - -**Choices**: list[int] of 2-10 values in the range [0, 200] - -**Default**: `(0, 1, 2, 4, 16, 32)` - -
- -
- -##### `resilience.layer_noise_learning.max_layers_to_learn` - - -**Choices**: None, Integer >= 1 - -**Default**: `4` - -
- -
- -##### `resilience.layer_noise_learning.num_randomizations` - - -**Choices**: Integer >= 1 - -**Default**: `32` - -
- -
- -##### `resilience.layer_noise_learning.shots_per_randomization` - - -**Choices**: Integer >= 1 - -**Default**: `128` - -
- -
- -#### `resilience.layer_noise_model` - - -**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]` - -**Default**: None - -
- -
- -#### `resilience.measure_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `True` - -
- -
- -#### `resilience.measure_noise_learning` - - -Options for measurement noise learning. - -[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options) -
- -
- -##### `resilience.measure_noise_learning.num_randomizations` - - -**Choices**: Integer >= 1 - -**Default**: `32` - -
- -
- -##### `resilience.measure_noise_learning.shots_per_randomization` - - -**Choices**: Integer, `auto` - -**Default**: `auto` - -
- -
- -#### `resilience.pec_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `False` - -
- -
- -#### `resilience.pec` - - -Probabilistic error cancellation mitigation options. - -[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options) -
- -
- -##### `resilience.pec.max_overhead` - - -**Choices**: `None`, Integer >= 1 - - -**Default**: `100` - -
- -
- -##### `resilience.pec.noise_gain` - - -**Choices**: `auto`, float in the range [0, 1] - -**Default**: `auto` - -
- -
- -#### `resilience.zne_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `False` - -
- -
- -#### `resilience.zne` - - -[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options) -
- -
- -##### `resilience.zne.amplifier` - - -**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea` - -**Default**: `gate_folding` - -
-
- -##### `resilience.zne.extrapolated_noise_factors` - - -**Choices**: List of floats - -**Default**: `[0, *noise_factors]` - -
- -
- -##### `resilience.zne.extrapolator` - - -**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback` - -**Default**: `(exponential, linear)` - -
- -
- -##### `resilience.zne.noise_factors` - - -**Choices**: List of floats; each float >= 1 - -**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise - -
- -
- - -
- -### `resilience_level` - - -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) -
- -
- -### `seed_estimator` - - -**Choices**: Integer - -**Default**: None - -[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator) -
-
- -### `simulator` - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) -
- -#### `simulator.basis_gates` - - -**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) - -
- -
- -#### `simulator.coupling_map` - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - -
- -
- -#### `simulator.noise_model` - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - -
- -
- -#### `simulator.seed_simulator` - - -**Choices**: Integer - -**Default**: None - -
- -
- - -
- -### `twirling` - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) -
- -#### `twirling.enable_gates` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.enable_measure` - - -**Choices**: True, False - -**Default**: True - -
- -
- -#### `twirling.num_randomizations` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.shots_per_randomization` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.strategy` - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - -
- -
- - -
- -### `experimental` - - -Experimental options, when available. - -
- - - - - -
- -### `default_shots` - - -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) -
- -
- -### `dynamical_decoupling` - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) -
- -#### `dynamical_decoupling.enable` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- -#### `dynamical_decoupling.extra_slack_distribution` - - -**Choices**: `middle`, `edges` - -**Default**: `middle` -
- -
- -#### `dynamical_decoupling.scheduling_method` - - -Choices: `asap`, `alap` -Default: `alap` -
- -
- -#### `dynamical_decoupling.sequence_type` - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` -
- -
- -#### `dynamical_decoupling.skip_reset_qubits` - - -Choices: `True`, `False` -Default: `False` -
- -
- - -
- -### `environment` - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) -
- -#### `environment.job_tags` - - -List of tags. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.log_level` - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING -
- -
- -#### `environment.private` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- - -
- -### `execution` - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) -
- -#### `execution.init_qubits` - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` -
- -
- -#### `execution.rep_delay` - -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` -
-
- -#### `execution.meas_type` - - -**Choices**: `classified`, `kerneled`, `avg_kerneled` - -**Default**: `classified` -
- -
- - -
- -### `max_execution_time` - -**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) -
- -
- -### `simulator` - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) -
- -#### `simulator.basis_gates` - - -**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) - -
- -
- -#### `simulator.coupling_map` - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - -
- -
- -#### `simulator.noise_model` - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - -
- -
- -#### `simulator.seed_simulator` - - -**Choices**: Integer - -**Default**: None - -
- -
- - -
- -### `twirling` - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) -
- -#### `twirling.enable_gates` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.enable_measure` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.num_randomizations` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.shots_per_randomization` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.strategy` - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - -
- -
- - -
- -### `experimental` - - -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: - - Can be used with gate twirling for non-conditional gates. - - 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: - - Can be used with dynamic circuits with non-conditional gates. - - 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 - - - - -## 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). - diff --git a/docs/guides/runtime-options-overview-sampler.mdx b/docs/guides/runtime-options-overview-sampler.mdx deleted file mode 100644 index 5c569ab7741..00000000000 --- a/docs/guides/runtime-options-overview-sampler.mdx +++ /dev/null @@ -1,420 +0,0 @@ ---- -title: Introduction to options -description: Available options for building with Qiskit Runtime primitives -in_page_toc_min_heading_level: 2 -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 - - -### 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. - - -### 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. - - -## 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. - - [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. - - - -
- -### `default_shots` - - -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) -
- -
- -### `dynamical_decoupling` - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) -
- -#### `dynamical_decoupling.enable` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- -#### `dynamical_decoupling.extra_slack_distribution` - - -**Choices**: `middle`, `edges` - -**Default**: `middle` -
- -
- -#### `dynamical_decoupling.scheduling_method` - - -Choices: `asap`, `alap` -Default: `alap` -
- -
- -#### `dynamical_decoupling.sequence_type` - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` -
- -
- -#### `dynamical_decoupling.skip_reset_qubits` - - -Choices: `True`, `False` -Default: `False` -
- -
- - -
- -### `environment` - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) -
- -#### `environment.job_tags` - - -List of tags. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.log_level` - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING -
- -
- -#### `environment.private` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- - -
- -### `execution` - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) -
- -#### `execution.init_qubits` - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` -
- -
- -#### `execution.rep_delay` - -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` -
-
- -#### `execution.meas_type` - - -**Choices**: `classified`, `kerneled`, `avg_kerneled` - -**Default**: `classified` -
- -
- - -
- -### `max_execution_time` - -**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) -
- -
- -### `simulator` - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) -
- -#### `simulator.basis_gates` - - -**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) - -
- -
- -#### `simulator.coupling_map` - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - -
- -
- -#### `simulator.noise_model` - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - -
- -
- -#### `simulator.seed_simulator` - - -**Choices**: Integer - -**Default**: None - -
- -
- - -
- -### `twirling` - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) -
- -#### `twirling.enable_gates` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.enable_measure` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.num_randomizations` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.shots_per_randomization` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.strategy` - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - -
- -
- - -
- -### `experimental` - - -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: - - Can be used with gate twirling for non-conditional gates. - - 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: - - Can be used with dynamic circuits with non-conditional gates. - - 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 - - - - - - -## Next steps - - - - 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). - From a5e16136140eaaf0c89e4a0a8fff8d0ab7e0e51a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 14:00:54 -0600 Subject: [PATCH 065/118] Update qiskit_bot.yaml --- qiskit_bot.yaml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 1a11e06c608..f2b125e51e6 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -139,15 +139,6 @@ notifications: - "abbycross" - "@jyu00" - "@beckykd" - "docs/guides/runtime-options-overview-estimator": - - "abbycross" - - "@jyu00" - - "@beckykd" - "docs/guides/runtime-options-overview-sampler": - - "abbycross" - - "@jyu00" - - "@beckykd" - "docs/guides/fair-share-scheduler": - "`@lerongil`" - "@jyu00" From 2d95bb3896ef6fbd33a00cd9b0fe086e30523bb9 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 14:09:21 -0600 Subject: [PATCH 066/118] Update _toc.json --- docs/guides/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index bfdaeb4e60d..4d63bcd671d 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -361,6 +361,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" From 1f0092c84720e04acb3093a40f82d755dad3bdfb Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 14:25:20 -0600 Subject: [PATCH 067/118] delete unused images --- .../images/guides/hello-world/extracted-outputs/87143fcc-0.svg | 1 - .../images/guides/hello-world/extracted-outputs/930ca3b6-0.svg | 1 - .../images/guides/hello-world/extracted-outputs/9a901271-0.svg | 1 - .../images/guides/hello-world/extracted-outputs/de91ebd0-0.svg | 1 - 4 files changed, 4 deletions(-) delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.svg delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.svg delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/9a901271-0.svg delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg 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 8b11d42af1d..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.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.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.svg b/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg deleted file mode 100644 index 9871a29b582..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file From e454b399a32d638fb74acdb9e3fc48709ab4ba09 Mon Sep 17 00:00:00 2001 From: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com> Date: Wed, 18 Feb 2026 17:33:25 -0500 Subject: [PATCH 068/118] Run linter --- qiskit_bot.yaml | 54 ++++++++++++++++++------------------ scripts/config/allowLists.ts | 2 +- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index f2b125e51e6..594263f1602 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -164,37 +164,37 @@ notifications: - "@beckykd" - "@jyu00" "docs/guides/executor-examples": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/executor-input-output": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/get-started-with-sampler": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/pubs": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/sampler-examples": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/sampler-input-output": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/sampler-options": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/get-started-with-estimator": - - "@abbycross" - - "@beckykd" - - "@jyu00" + - "@abbycross" + - "@beckykd" + - "@jyu00" "docs/guides/ha-dr": - "@abbycross" - "@beckykd" @@ -441,19 +441,19 @@ notifications: - "@HuangJunye" - "@pacomf" - "@Bagherpoor" - - "@kaelynj" + - "@kaelynj" "docs/guides/estimator-broadcasting": - "@born-2learn" - "@HuangJunye" - "@pacomf" - "@Bagherpoor" - - "@kaelynj" + - "@kaelynj" "docs/guides/broadcasting": - "@born-2learn" - "@HuangJunye" - "@pacomf" - "@Bagherpoor" - - "@kaelynj" + - "@kaelynj" "docs/guides/sampler-rest-api": - "@born-2learn" - "@HuangJunye" diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index db899f94f9a..5d51bfe8a8f 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -37,7 +37,7 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/get-started-with-sampler.ipynb", "docs/guides/pubs.ipynb", "docs/guides/sampler-examples.ipynb", - "docs/guides/sampler-rest-api.ipynb", + "docs/guides/sampler-rest-api.ipynb", "docs/guides/sampler-input-output.ipynb", "docs/guides/sampler-options.ipynb", "docs/guides/get-started-with-estimator.ipynb", From d01ad8d467aa229cdc6e42a0e94cbc4e783b5738 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 16:54:36 -0600 Subject: [PATCH 069/118] Update notebook-testing.toml --- scripts/config/notebook-testing.toml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 5c1495cf9c9..a02759040d4 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -36,6 +36,17 @@ notebooks = [ "docs/guides/operators-overview.ipynb", "docs/guides/plot-quantum-states.ipynb", "docs/guides/primitives-rest-api.ipynb", + "docs/guides/estimator-rest-api.ipynb", + "docs/guides/sampler-rest-api.ipynb", + "docs/guides/get-started-with-sampler.ipynb", + "docs/guides/sampler-input-output.ipynb", + "docs/guides/sampler-options.ipynb", + "docs/guides/estimator-examples.ipynb", + "docs/guides/sampler-examples.ipynb", + "docs/guides/estimator-input-output.ipynb", + "docs/guides/pubs.ipynb", + "docs/guides/estimator-options.ipynb", + "docs/guides/get-started-with-estimator.ipynb", "docs/guides/quick-start.ipynb", "docs/guides/repetition-rate-execution.ipynb", "docs/guides/represent-quantum-computers.ipynb", From 65bbf2a7ae59a3dd2e0e820f0a4c43aa20fa4871 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 17:00:47 -0600 Subject: [PATCH 070/118] squeaky --- docs/guides/hello-world.ipynb | 4 ++-- docs/guides/sampler-rest-api.ipynb | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index 286ba99093f..fbf5db25790 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -741,7 +741,7 @@ "metadata": { "celltoolbar": "Raw Cell Format", "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -755,7 +755,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.2" + "version": "3" }, "widgets": { "application/vnd.jupyter.widget-state+json": { diff --git a/docs/guides/sampler-rest-api.ipynb b/docs/guides/sampler-rest-api.ipynb index c1fb013d061..3175ffa66c8 100644 --- a/docs/guides/sampler-rest-api.ipynb +++ b/docs/guides/sampler-rest-api.ipynb @@ -24,6 +24,7 @@ }, { "cell_type": "markdown", + "id": "8fb95343-9735-45ae-aa83-7dad8d23e92d", "metadata": {}, "source": [ "## 1. Initialize the account\n", @@ -137,7 +138,7 @@ "\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](./error-mitigation-and-suppression-techniques) topic.\n", "\n", - "### Dynamical decoupling \n", + "### Dynamical decoupling\n", "```python\n", "import requests\n", "\n", From 6e5b920991719fa71d81be352cf7bd2a386447bb Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 17:09:33 -0600 Subject: [PATCH 071/118] version info --- docs/guides/estimator-rest-api.ipynb | 20 +++++++++++++- docs/guides/execution-modes-rest-api.ipynb | 20 +++++++++++++- docs/guides/sampler-rest-api.ipynb | 31 +++++++++++++++++++++- 3 files changed, 68 insertions(+), 3 deletions(-) diff --git a/docs/guides/estimator-rest-api.ipynb b/docs/guides/estimator-rest-api.ipynb index 6bc8c934600..5d5457e7377 100644 --- a/docs/guides/estimator-rest-api.ipynb +++ b/docs/guides/estimator-rest-api.ipynb @@ -24,7 +24,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", diff --git a/docs/guides/execution-modes-rest-api.ipynb b/docs/guides/execution-modes-rest-api.ipynb index 1573b11b008..8cd2272cbea 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", diff --git a/docs/guides/sampler-rest-api.ipynb b/docs/guides/sampler-rest-api.ipynb index 3175ffa66c8..30c56617d79 100644 --- a/docs/guides/sampler-rest-api.ipynb +++ b/docs/guides/sampler-rest-api.ipynb @@ -11,7 +11,36 @@ "---\n", "\n", "\n", - "{/* cspell:ignore IIZII, XIZZZ, accum */}\n", + "{/* cspell:ignore IIZII, XIZZZ, accum */}\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "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", + "metadata": {}, + "source": [ "\n", "# Sampler with the REST API\n", "\n", From b7b931a0433fa3001250571736a95067c9be8af2 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 17:27:55 -0600 Subject: [PATCH 072/118] change to markdown --- docs/guides/sampler-rest-api.mdx | 347 +++++++++++++++++++++++++++++++ scripts/config/allowLists.ts | 2 +- 2 files changed, 348 insertions(+), 1 deletion(-) create mode 100644 docs/guides/sampler-rest-api.mdx diff --git a/docs/guides/sampler-rest-api.mdx b/docs/guides/sampler-rest-api.mdx new file mode 100644 index 00000000000..3e76886d171 --- /dev/null +++ b/docs/guides/sampler-rest-api.mdx @@ -0,0 +1,347 @@ +--- +title: 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](./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](./transpile) section. + diff --git a/scripts/config/allowLists.ts b/scripts/config/allowLists.ts index 5d51bfe8a8f..af049d351d4 100644 --- a/scripts/config/allowLists.ts +++ b/scripts/config/allowLists.ts @@ -37,7 +37,7 @@ const IGNORE_TITLE_MISMATCHES: string[] = [ "docs/guides/get-started-with-sampler.ipynb", "docs/guides/pubs.ipynb", "docs/guides/sampler-examples.ipynb", - "docs/guides/sampler-rest-api.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", From a7cafb9ec13f7a7832f7a18602dcfafc9023c2eb Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 18 Feb 2026 17:28:35 -0600 Subject: [PATCH 073/118] Delete sampler-rest-api.ipynb --- docs/guides/sampler-rest-api.ipynb | 416 ----------------------------- 1 file changed, 416 deletions(-) delete mode 100644 docs/guides/sampler-rest-api.ipynb diff --git a/docs/guides/sampler-rest-api.ipynb b/docs/guides/sampler-rest-api.ipynb deleted file mode 100644 index 30c56617d79..00000000000 --- a/docs/guides/sampler-rest-api.ipynb +++ /dev/null @@ -1,416 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "0998165a-381f-4561-a79a-bf584aed9687", - "metadata": {}, - "source": [ - "---\n", - "title: REST API\n", - "description: How to use the Sampler primitive with the Qiskit Runtime REST API.\n", - "---\n", - "\n", - "\n", - "{/* cspell:ignore IIZII, XIZZZ, accum */}\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "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", - "metadata": {}, - "source": [ - "\n", - "# Sampler with the REST API\n", - "\n", - "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", - "" - ] - }, - { - "cell_type": "markdown", - "id": "8fb95343-9735-45ae-aa83-7dad8d23e92d", - "metadata": {}, - "source": [ - "## 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", - "\n", - "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)\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:\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", - "\n", - "The code snippets given below assume that the `qasm_string` has been transpiled to a new string `resulting_qasm`.\n", - "\n", - "\n", - "## 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). `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.\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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm],[resulting_qasm,None,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(\"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-942fb30edced\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", - "# Get results for the first PUB\n", - "counts=res_dict['results'][0]['data']['c']['samples']\n", - "\n", - "print(counts[:20])\n", - "```\n", - "Output\n", - "```text\n", - "['0x3', '0x0', '0x2', '0x1', '0x0', '0x3', '0x0', '0x3', '0x1', '0x2', '0x2', '0x0', '0x2', '0x0', '0x3', '0x3', '0x2', '0x0', '0x1', '0x0']\n", - "```\n", - "\n", - "## 5. Work with Qiskit 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](./error-mitigation-and-suppression-techniques) topic.\n", - "\n", - "### Dynamical decoupling\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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", - "```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", - "job_input = {\n", - " 'program_id': 'sampler',\n", - " \"backend\": backend,\n", - " \"params\": {\n", - " \"pubs\": [[resulting_qasm]], # primitive unified blocs (PUBs) containing one circuit each.\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", - "\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 Sampler V2 API\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': 'sampler',\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](./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 -} From 8a59c9a8ac96c17754093481869889faca03a592 Mon Sep 17 00:00:00 2001 From: Frank Harkins Date: Thu, 19 Feb 2026 09:21:05 +0000 Subject: [PATCH 074/118] Extract images --- docs/guides/hello-world.ipynb | 12 ++++-------- .../extracted-outputs/87143fcc-0.avif | Bin 0 -> 2870 bytes .../extracted-outputs/930ca3b6-0.avif | Bin 0 -> 1291 bytes .../extracted-outputs/9a901271-1.avif | Bin 0 -> 2451 bytes .../extracted-outputs/de91ebd0-0.avif | Bin 0 -> 5921 bytes 5 files changed, 4 insertions(+), 8 deletions(-) create mode 100644 public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.avif create mode 100644 public/docs/images/guides/hello-world/extracted-outputs/930ca3b6-0.avif create mode 100644 public/docs/images/guides/hello-world/extracted-outputs/9a901271-1.avif create mode 100644 public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.avif diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb index fbf5db25790..ac4eacc4439 100644 --- a/docs/guides/hello-world.ipynb +++ b/docs/guides/hello-world.ipynb @@ -158,9 +158,8 @@ "outputs": [ { "data": { - "image/png": "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", "text/plain": [ - "
" + "\"Output" ] }, "execution_count": 1, @@ -277,9 +276,8 @@ }, { "data": { - "image/png": "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", "text/plain": [ - "
" + "\"Output" ] }, "execution_count": 3, @@ -447,9 +445,8 @@ "outputs": [ { "data": { - "image/png": "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FJgebtTQ7iNHjsjcuXN1p2A1pHvVqlXeTsN5eXl6BJXHsGHD5I033pCHHnpIHnzwQT2Jnxop1adPHxO/CwAAECpMn+cm2Pw9zw0AAAitz2/TZygGAADwJ8INAACwFcINAACwFcINAACwFdNHSwWbp/+0v9eYAgAAgeP53G7OOKiwCzelpaX6ayCWYAAAAIH/HFejpk4n7IaCqxmQDxw4IAkJCeJwOPz63J51q/bt28cw8wDiOgcH15nrbDe8p619nVVcUcGmU6dOPvPfNSbsam7UBenSpUtAX0P9MJlDJ/C4zsHBdeY62w3vaete5zPV2HjQoRgAANgK4QYAANgK4caPYmJiZN68eforAofrHBxcZ66z3fCeDp/rHHYdigEAgL1RcwMAAGyFcAMAAGyFcAMAAGyFcAMAAGyFcHOOfv7zn8u4ceNkzZo1eqbjpm5XXnmlf39iYXytXS6XDBs2TH7yk5/43F9cXKxnw5wzZ45pZbS65ryPc3Nz9faWLVvMLq5lNec9zHUO7Pv4iiuuOO05a9eubfHP2e5czXgfv/feexIdHS2bN2/2Oeepp56S1NRUyc/PD2wh1WgpnL1JkyYZN910k1FZWWkcPHiwwe3FF180HA6H8eabb3J5/XStlW3bthmtWrUy/vSnP3nvv/POO42+ffvqnwXOTXPex3v27FEjK40vv/ySy9wCZ3oPc50D+z4uLCxscP/evXuNPn36GAMHDjROnDjB+7sZmvO7eMqUKcZFF11kVFRU6P1vv/3WiI2NNZYvX24EGuHGDx+4p/ruu++MhIQEY86cOS352aCJa/3MM88YycnJxoEDB4x33nnHiIqKMrZs2cL18rNT38d86PrP6d7DXGf/as7v46lTpxppaWnGvn37/Pzq9vbMGX4Xl5SUGN26dTNmzpxpVFdX6/B46623BqVshBs/h5tjx44ZmZmZxtixYw23293Snw8audbqul5xxRXGVVddZbRv39545JFHuE5+1tj7mA9d/znde5jr7D/N+X28ZMkSIzo62vjkk0/8+Mrhwd2M38WrV682IiMjjZ/+9KdGhw4djIKCgqCULewWzgz0iuO33367REZGyuuvv+73VcdRS13XF154QS688EK5+OKLZdasWVwaP+J9HHi8h0Pjfbxu3Tq5//775fnnn9d9SOD/9/GoUaPklltukeXLl8uKFSsk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GSPr1q3Tc96sWrVKhx41AunRRx/1CRJPPPGEDg9qpNRf/vIX3alYUbUpr7zyiu7Uq4aX/+lPf9JhR82ZowKACigqKL311lu6eUd17F2wYIGu+TgT9djNmzfrstxyyy16JJWHCiiqpmjDhg26puk//uM/5NChQw2eQzVTqaYkVbukRlM9++yz3rKfSjU1qWarcePG6VFkubm5+vnVyDE1Iko1v6kO0qpmZ+/evfq6qI7F9YMeAD/zcx8eADaXm5trTJo0yejQoYMRFRVlpKenG/fdd59RUFDg0+F2/vz5xq233mrExcUZaWlpxjPPPOO9X3VKHjJkiO6IGx8fb1x22WXGhx9+6L1fdTSeO3eukZGRoV+jY8eOxs0332x8/fXX3g7FSUlJTZZx8ODBusPxRx995HO8sLDQuOmmm4zWrVsb7du3Nx566CFj4sSJ+lj9DsW//OUvjXvuuUeXLzk52XjwwQd9OhjX71CslJSU6GvQqVMn7zW54447jLy8PKOystK47bbb9LHo6Gh9zr333mucOHGiRT8HAE1zqH/8HZgAAADMQrMUAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAACwFcINAAAQO/l/a+m/xMkLkVAAAAAASUVORK5CYII=", "text/plain": [ - "
" + "\"Output" ] }, "metadata": {}, @@ -685,9 +682,8 @@ "outputs": [ { "data": { - "image/png": "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", "text/plain": [ - "
" + "\"Output" ] }, "metadata": {}, 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 0000000000000000000000000000000000000000..fd83d254a4fbcbe4c29a8e809bf0f54dc3ea1b53 GIT binary patch literal 2870 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 literal 0 HcmV?d00001 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 0000000000000000000000000000000000000000..c8a3c02eabaaf05fb1d0aa6da79592bb4c7ab160 GIT binary patch literal 5921 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 literal 0 HcmV?d00001 From 172d28a4087985e11fa5191074cb9ff34ef3ec14 Mon Sep 17 00:00:00 2001 From: Frank Harkins Date: Thu, 19 Feb 2026 12:30:41 +0000 Subject: [PATCH 075/118] Fix notebook testing config --- scripts/config/notebook-testing.toml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index a02759040d4..59e83212c81 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -35,7 +35,6 @@ notebooks = [ "docs/guides/operator-class.ipynb", "docs/guides/operators-overview.ipynb", "docs/guides/plot-quantum-states.ipynb", - "docs/guides/primitives-rest-api.ipynb", "docs/guides/estimator-rest-api.ipynb", "docs/guides/sampler-rest-api.ipynb", "docs/guides/get-started-with-sampler.ipynb", @@ -72,7 +71,6 @@ test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ "docs/guides/specify-runtime-options.ipynb", "docs/guides/visualize-results.ipynb", - "docs/guides/hello-world.ipynb", ] # Mock the following notebooks in our extended checks using IBM Quantum's @@ -106,13 +104,7 @@ notebooks = [ [groups.cron-job-only] test-strategies.hardware = { patch = "qiskit-ibm-runtime-open" } notebooks = [ - "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 - "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 From bb80ce2756a3fdaecc9f64d4f8839db574f1ca76 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 20 Feb 2026 11:27:59 -0600 Subject: [PATCH 076/118] Add options info --- docs/guides/broadcasting.mdx | 4 +- docs/guides/estimator-broadcasting.mdx | 26 +++-- docs/guides/estimator-input-output.ipynb | 4 +- docs/guides/estimator-options.ipynb | 119 +++++++++------------- docs/guides/executor-broadcasting.mdx | 1 + docs/guides/executor-input-output.mdx | 4 +- docs/guides/executor-options.mdx | 90 +++++++++++++++- docs/guides/get-started-with-executor.mdx | 14 +-- docs/guides/primitives.ipynb | 12 ++- docs/guides/pubs.ipynb | 4 +- docs/guides/sampler-input-output.ipynb | 4 +- docs/guides/sampler-options.ipynb | 14 +-- 12 files changed, 185 insertions(+), 111 deletions(-) diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx index 103c53390b2..389817f643f 100644 --- a/docs/guides/broadcasting.mdx +++ b/docs/guides/broadcasting.mdx @@ -6,11 +6,9 @@ description: Understand how primitives handle array inputs and outputs using bro # Primitive broadcasting -## Rules - The primitives 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). -Rules: +## Rules * Input arrays do not need to have the same number of dimensions. * The resulting array will have the same number of dimensions as the input array with the largest dimension. diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index af76dffb53a..31f46a6143a 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -4,7 +4,7 @@ description: How the Estimator handles array inputs and outputs using broadcasti --- -# Executor broadcasting semantics +# Estimator broadcasting semantics When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics. Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: @@ -62,17 +62,25 @@ observables = [ Each `SparsePauliOp` counts as a single element in this context, regardless of the number of Paulis contained in the `SparsePauliOp`. Thus, for the purpose of these broadcasting rules, all of the following elements have the same shape: -```text -a = SparsePauliOp("Z") # shape () -b = SparsePauliOp("IIIIZXYIZ") # shape () -c = SparsePauliOp.from_list(["XX", "XY", "IZ"]) # shape () +```python +# shape () +a = SparsePauliOp("Z") + +# shape () +b = SparsePauliOp("IIIIZXYIZ") + +# shape () +c = SparsePauliOp.from_list(["XX", "XY", "IZ"]) ``` The following lists of operators, while equivalent in terms of information contained, have different shapes: -```text -list1 = SparsePauliOp.from_list(["XX", "XY", "IZ"]) # shape () -list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] # shape (3, ) +```python +# shape () +list1 = SparsePauliOp.from_list(["XX", "XY", "IZ"]) + +# shape (3, ) +list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] ``` @@ -80,4 +88,6 @@ list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] # shape - See the [broadcasting guide](/docs/guides/broadcasting) for an overview of broadcasting. + - Learn about [PUBs.](/docs/guides/pubs) + - Understand [Estimator inputs and outputs.](/docs/guides/estimator-input-output) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 16dcc3eee43..c9ba8b0e45a 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." ] }, { @@ -58,7 +58,7 @@ "source": [ "## Inputs\n", "\n", - "The inputs to the Estimator primitive are [PUBs.](/docs/guides/pubs) For the Estimator primitive, the format of the PUB should contain at most four values:\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", diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index fbc6e813388..e9d0f77d00d 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -48,31 +48,29 @@ "id": "8fdcbe4a", "metadata": {}, "source": [ - "You can use options to customize the Estimator 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`](/docs/api/qiskit/primitives#primitives) and [`qiskit_aer.primitives`](https://qiskit.github.io/qiskit-aer/apidocs/aer_primitives.html) options.\n", + "You can use options to customize the Estimator 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 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 about specifying options in the primitives:\n", + "Notes about specifying options in the Estimator primitives:\n", "\n", - "- You can see the available options and update option values during or after primitive initialization.\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", - "## Set primitive options\n", + "## Set Estimator 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", + "You can set options when initializing Estimator, after initializing Estimator, 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", + "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` 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", + "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:\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))." + "Example:" ] }, { @@ -110,12 +108,12 @@ "source": [ "#### Dictionary\n", "\n", - "You can specify options as a dictionary when initializing the primitive." + "You can specify options as a dictionary when initializing Estimator." ] }, { "cell_type": "code", - "execution_count": 2, + "execution_count": null, "id": "0ee1eaf6-c221-437f-8ff8-40ec2aa937c0", "metadata": {}, "outputs": [], @@ -126,7 +124,7 @@ "service = QiskitRuntimeService()\n", "backend = service.least_busy(operational=True, simulator=False)\n", "\n", - "# Setting options during primitive initialization\n", + "# Setting options during initialization\n", "estimator = Estimator(\n", " backend,\n", " options={\n", @@ -146,14 +144,14 @@ "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", + "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 `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." + "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, + "execution_count": null, "id": "71de6acf-77a5-460f-ac54-f88f7a4d2fa6", "metadata": {}, "outputs": [], @@ -166,12 +164,12 @@ "\n", "estimator = Estimator(mode=backend)\n", "\n", - "# Setting options after primitive initialization\n", + "# Setting options after initialization\n", "# This uses auto-complete.\n", - "estimator.options.default_shots = 4000\n", + "estimator.options.default_precision = .01\n", "# This does bulk update.\n", "estimator.options.update(\n", - " default_shots=4000, resilience={\"zne_mitigation\": True}\n", + " default_precision=.02, resilience={\"zne_mitigation\": True}\n", ")" ] }, @@ -183,19 +181,19 @@ "\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." + "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": 4, + "execution_count": null, "id": "f2c12ead-4785-4d4f-bf4a-f015295d7083", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": 4, @@ -224,15 +222,14 @@ "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", + "estimator = Estimator(mode=backend)\n", + "# Default precision to use if not specified in run()\n", + "estimator.options.default_precision = .01\n", + "# Run two circuits, requiring a precision of .02 for both.\n", + "estimator.run([transpiled1, transpiled2], precision=.02)\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)])" + "# Run two circuits with different precision requirements.\n", + "estimator.run([(transpiled1, None, .01), (transpiled2, None, .02)])" ] }, { @@ -242,7 +239,7 @@ "source": [ "### Special cases\n", "\n", - "#### Resilience level (Estimator only)\n", + "#### Resilience level\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", @@ -275,32 +272,21 @@ "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", + "#### Precision \n", "\n", - "Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used.\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 Executor execution interface, and are independent of the Runtime Executor's options. They take precedence over any values specified as options in order to comply with the Estimator abstraction.\n", "\n", - "#### Precision (Estimator only)\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", - "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", + "Note that the 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 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", + "3. 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", + "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", @@ -316,12 +302,6 @@ "### 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", @@ -334,14 +314,14 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": null, "id": "43ed5d23-8d2e-43a7-82a9-b563de861ab1", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": 6, @@ -351,7 +331,7 @@ ], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\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", "\n", @@ -371,20 +351,20 @@ "transpiled2 = pass_manager.run(circuit2)\n", "\n", "\n", - "# Setting shots during primitive initialization\n", - "sampler = Sampler(mode=backend, options={\"default_shots\": 4096})\n", + "# Setting precision during primitive initialization\n", + "estimator = Estimator(mode=backend, options={\"default_precision\": .01})\n", "\n", "# Setting options after primitive initialization\n", "# This uses auto-complete.\n", - "sampler.options.default_shots = 2000\n", + "estimator.options.default_precision = .01\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", + "# This does bulk update. The value for default_precision is overridden if you specify precision with run() or in the PUB.\n", + "estimator.options.update(\n", + " default_precision=.01, dynamical_decoupling={\"sequence_type\": \"XpXm\"}\n", ")\n", "\n", - "# Sample two circuits at 128 shots each.\n", - "sampler.run([transpiled1, transpiled2], shots=128)" + "# Run two circuits to a precision of .02 each.\n", + "estimator.run([transpiled1, transpiled2], precision=.02)" ] }, { @@ -425,11 +405,9 @@ "\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", + "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:\n", - "\n", - "Turn off all error mitigation and suppression in Estimator." + "Example:" ] }, { @@ -465,7 +443,6 @@ "\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", "" diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index ab4349de8c0..88d218ef56c 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -310,4 +310,5 @@ noise_scale = np.array([0.8, 1.0, 1.2]) # extrinsic (3,), intrinsic () - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Understand [Executor inputs and outputs.](/docs/guides/executor-input-output) diff --git a/docs/guides/executor-input-output.mdx b/docs/guides/executor-input-output.mdx index 999f66259b1..28f2095bd02 100644 --- a/docs/guides/executor-input-output.mdx +++ b/docs/guides/executor-input-output.mdx @@ -6,7 +6,7 @@ description: Understand the inputs and outputs to the Executor primitive. # Executor inputs and outputs -The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM quantum computer. +The inputs and output of the Executor primitive are very different from those of the Sampler and Estimator primitives. As part of the [directed execution model,](/docs/guides/directed-execution-model) the Executor primitive helps provide more flexibility when customizing your error mitigation workflow. This primitive takes a `QuantumProgram` as input, and outputs a Qiskit Runtime job, which is then run on an IBM® quantum computer. ## Inputs: Quantum programs @@ -85,7 +85,7 @@ program.append_samplex_item( ## Outputs -[`qiskit_ibm_runtime.quantum_program.QuantumProgramResult`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) is an iterable. It contains one +Executor's output is a [`qiskit_ibm_runtime.quantum_program.QuantumProgramResult`,](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) which is an iterable. It contains one item per circuit task, and the items are in the same order as those in the program. Each of these items is a dictionary where the keys are strings and the values are of type `np.ndarray`, with elements of type `bool`. diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index 30f72b93746..ca15fb8d696 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -6,10 +6,96 @@ description: Specify options when building with the Qiskit Runtime Executor prim # Specify Executor options +You can use options to customize the Executor primitive. This section focuses on how to specify Qiskit Runtime primitive options. Consult the API reference for information about the [`ExecutorOptions`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.options.ExecutorOptions.html) class. - +Notes about specifying options in the primitives: + +- You can see the available options and update option values during or after primitive initialization. +- Use the `update()` method to apply changes to the `options` attribute. +- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. +- The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. + + +## Set Executor options + +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. + +### Primitive initialization + +You can pass in an instance of the options class or a dictionary when initializing Executor, 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. + +#### Options class + +When creating an instance of the `Executor` 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` + +See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options) for full details about the options class. + +Example: + +```python +from qiskit_ibm_runtime import QiskitRuntimeService, Executor +from qiskit_ibm_runtime.options import ExecutorOptions + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +options = ExecutorOptions( + environment={"log_level" = INFO}, + execution={"init_qubits": True}, +) + +# or... +options = ExecutorOptions() +options.log_level = INFO +options.init_qubits = True + +executor = Executor(mode=backend, options=options) +``` + +#### Dictionary + +You can specify options as a dictionary when initializing Executor. + +```python +from qiskit_ibm_runtime import QiskitRuntimeService, executor + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +# Setting options during primitive initialization +executor = Executor( + backend, + options={ + "environment"={"log_level" = INFO}, + "execution"={"init_qubits": True}, + }, +) +``` + +### Update options after initialization + +You can specify the options in this format: `executor.options.option.sub-option.sub-sub-option = choice` to take advantage of auto-complete, or use the `update()` method to make bulk updates. + +Executor's options class ([`ExecutorOptions`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.options.ExecutorOptions.html)) does not need to be instantiated if you are setting options after initializing the primitive. + +```python +from qiskit_ibm_runtime import QiskitRuntimeService, Executor + +service = QiskitRuntimeService() +backend = service.least_busy(operational=True, simulator=False) + +executor = Executor(mode=backend) + +# Setting options after primitive initialization +# This uses auto-complete. +executor.options.log_level = INFO +# This does bulk update. +sampler.options.update(environment={"log_level" = INFO} +) +``` ## Next steps - - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Review the [ExecutionOptionsV2](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) API documentation. + - Review the [EnvironmentOptions](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) API documentation. diff --git a/docs/guides/get-started-with-executor.mdx b/docs/guides/get-started-with-executor.mdx index c293eaf43cd..823ed81eeff 100644 --- a/docs/guides/get-started-with-executor.mdx +++ b/docs/guides/get-started-with-executor.mdx @@ -5,22 +5,20 @@ description: How to use the Executor primitive in Qiskit Runtime. --- # Get started with the Executor primitive -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. - The Executor primitive is part of the directed execution model, which provides more flexibility when customizing your error mitigation workflow. See the [Directed execution model](/docs/guides/directed-execution-model) guide for more information. ## Steps to get started with Executor There are three basic steps involved in using the Executor primitive: 1. Initialize a `QuantumProgram` with your workload. -2. Run the `QuantumProgram` on IBM backends by using the `Executor` primitive. +2. Run the `QuantumProgram` on IBM® backends by using the `Executor` primitive. 3. Interpret the outputs. See [Executor examples](/docs/guides/executor-examples) for a full walkthrough. ## Run an Executor job -The following code shows how to initialize an Executor with the default options. See [Executor options](/docs/guides/executor-options) to learn more. +The following code shows how to initialize an Executor with the default options. See [Executor options](/docs/guides/executor-options) to learn about the available options. ```python from qiskit_ibm_runtime import Executor @@ -36,10 +34,12 @@ job = executor.run(program) result = job.result() ``` -Here, the result is of type [`QuantumProgramResult`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) See [Executor input and output](/docs/guides/executor-input-output) to learn about the result object. +The result is of type [`QuantumProgramResult`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramResult.html#qiskit_ibm_runtime.quantum_program.QuantumProgramResult) See [Executor input and output](/docs/guides/executor-input-output) to learn about the result object. ## Next steps - - - Understand [Executor input and output](/docs/guides/executor-input-output) + + - Try some [Executor examples](/docs/guides/executor-examples) + - Understand [Executor input and output.](/docs/guides/executor-input-output) + - Learn about [Executor broadcasting semantics.](/docs/guides/executor-broadcasting) diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index c2fc770faef..b40081429bb 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -94,7 +94,11 @@ "\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", + "\n", + "There is not yet a base class for the Executor primitive.\n", + "\n", "\n", "### Base classes\n", "\n", @@ -123,7 +127,7 @@ "\n", "## Primitive details\n", "\n", - "As described previously, all primitives are created from the base classes; therefore, they have the same general structure and usage. For example, the format of the input for all Estimator primitives is the same. However, there are differences in implementations that make them unique.\n", + "As described previously, the Estimator and Sampler primitives are created from the base classes; therefore, they have the same general structure and usage. For example, the format of the input for all Estimator primitives is the same. However, there are differences in implementations that make them unique.\n", "\n", "\n", "Because most users access the Qiskit Runtime primitives, the examples in the rest of this section are based on Qiskit Runtime primitives.\n", @@ -272,9 +276,7 @@ "\n", "### Executor (beta)\n", "\n", - "The Executor Qiskit Runtime primitive 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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model)\n", - "\n", - "The inputs and output of the Executor primitive are very different from those of Sampler and Estimator. Refer to the [Executor input and output topic](/docs/guides/executor-input-output) for more information." + "The Executor Qiskit Runtime primitive takes a program (a template circuit and 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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model)" ] }, { diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb index 841270eb2a6..9a4e2d85c9b 100644 --- a/docs/guides/pubs.ipynb +++ b/docs/guides/pubs.ipynb @@ -11,7 +11,7 @@ "---\n", "\n", "\n", - "# Introduction to Primitive Unified Blocs" + "# Introduction to PUBs" ] }, { @@ -50,7 +50,7 @@ "source": [ "The Estimator and Sampler primitives help you efficiently define vectorized workloads by using a data structure known as a _Primitive Unified Bloc (PUB)_. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the `run()` method for the primitives, which execute 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 Sampler or Estimator primitives.\n", "\n", - "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through broadcasting." + "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting)" ] }, { diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 78184e084ca..16349113771 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a **Primitive Unified Bloc (PUB)**. These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." ] }, { @@ -58,7 +58,7 @@ "source": [ "## Input\n", "\n", - "The input to the Sampler primitive is a [PUB](/docs/guides/pubs) tuple that contains at most three values:\n", + "For the Estimator 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", diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index afada4a9089..3a0132fefd2 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -48,7 +48,7 @@ "id": "8fdcbe4a", "metadata": {}, "source": [ - "You can use options to customize the 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", + "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", "Notes about specifying options in the primitives:\n", "\n", @@ -58,19 +58,19 @@ "- 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", + "## Set Sampler 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", + "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", - "`SamplerV2` and `EstimatorV2` have separate options classes. See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options)." + "See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options) for full details about the options class." ] }, { @@ -108,7 +108,7 @@ "source": [ "#### Dictionary\n", "\n", - "You can specify options as a dictionary when initializing the primitive." + "You can specify options as a dictionary when initializing Sampler." ] }, { @@ -144,7 +144,7 @@ "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", + "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." ] @@ -181,7 +181,7 @@ "\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` or `default_precision` for the current run." + "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." ] }, { From 1f20e9bbc4231185e5ce19b800973fcffe7194d4 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 20 Feb 2026 12:02:24 -0600 Subject: [PATCH 077/118] links --- docs/guides/executor-options.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index ca15fb8d696..a51d527d9aa 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -96,6 +96,6 @@ sampler.options.update(environment={"log_level" = INFO} ## Next steps - - Review the [ExecutionOptionsV2](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) API documentation. - - Review the [EnvironmentOptions](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) API documentation. + - Review the [ExecutionOptionsV2](/docs/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) API documentation. + - Review the [EnvironmentOptions](/docs/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) API documentation. From 32b6a0f8a0835cb66ea9af5cc839826a2a1607c7 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Fri, 20 Feb 2026 12:21:13 -0600 Subject: [PATCH 078/118] Apply suggestion from @beckykd --- docs/api/qiskit-ibm-runtime/release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index 962b0508a86..7accce66b1e 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -918,7 +918,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-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)) +* 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)) * `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)) From 535a914b6c853d72ad2a3343faa9be589236310b Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Fri, 20 Feb 2026 12:21:56 -0600 Subject: [PATCH 079/118] Apply suggestion from @beckykd --- docs/api/qiskit-ibm-runtime/release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index 7accce66b1e..fb1d23d3964 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -1057,7 +1057,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/executor-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/primitives-examples)) to see this coupled with operator transformations. From 3180dd9d7c4c1ec333c1def94047dbd1e1691687 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Fri, 20 Feb 2026 12:22:40 -0600 Subject: [PATCH 080/118] Apply suggestion from @beckykd --- docs/api/qiskit-ibm-runtime/release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/qiskit-ibm-runtime/release-notes.mdx b/docs/api/qiskit-ibm-runtime/release-notes.mdx index fb1d23d3964..75ca95e4204 100644 --- a/docs/api/qiskit-ibm-runtime/release-notes.mdx +++ b/docs/api/qiskit-ibm-runtime/release-notes.mdx @@ -1101,7 +1101,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/executor-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/primitives-examples)) to see this coupled with operator transformations. From 65fe542d301ed1d27ec93f088282db9855369dc0 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 20 Feb 2026 12:36:47 -0600 Subject: [PATCH 081/118] links --- docs/guides/executor-options.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index a51d527d9aa..dbd08d7f17a 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -26,9 +26,9 @@ You can pass in an instance of the options class or a dictionary when initializi #### Options class -When creating an instance of the `Executor` 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` +When creating an instance of the `Executor` 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.log_level = INFO` -See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-sampler-options) for full details about the options class. +See [`ExecutorOptions`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.options.ExecutorOptions.html) for full details about the options class. Example: @@ -96,6 +96,6 @@ sampler.options.update(environment={"log_level" = INFO} ## Next steps - - Review the [ExecutionOptionsV2](/docs/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.EnvironmentOptions) API documentation. - - Review the [EnvironmentOptions](/docs/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.ExecutionOptionsV2) API documentation. + - Review the [ExecutionOptionsV2](/docs/api/qiskit-ibm-runtime/options-execution-options-v2) API documentation. + - Review the [EnvironmentOptions](/docs/api/qiskit-ibm-runtime/options-environment-options) API documentation. From 6a75ead77ce119ecb3477c56b7e1c9471b27e544 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 20 Feb 2026 12:48:23 -0600 Subject: [PATCH 082/118] code fix --- docs/guides/estimator-options.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index e9d0f77d00d..ed216751061 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -203,7 +203,7 @@ ], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService\n", - "from qiskit_ibm_runtime import SamplerV2 as Sampler\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", "\n", From aa950c73ea0a3987adfb2d04be30e82e64237d13 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 20 Feb 2026 13:42:48 -0600 Subject: [PATCH 083/118] squeaky clean --- docs/guides/estimator-options.ipynb | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index ed216751061..ceffbbbcb59 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -166,10 +166,10 @@ "\n", "# Setting options after initialization\n", "# This uses auto-complete.\n", - "estimator.options.default_precision = .01\n", + "estimator.options.default_precision = 0.01\n", "# This does bulk update.\n", "estimator.options.update(\n", - " default_precision=.02, resilience={\"zne_mitigation\": True}\n", + " default_precision=0.02, resilience={\"zne_mitigation\": True}\n", ")" ] }, @@ -224,12 +224,12 @@ "\n", "estimator = Estimator(mode=backend)\n", "# Default precision to use if not specified in run()\n", - "estimator.options.default_precision = .01\n", + "estimator.options.default_precision = 0.01\n", "# Run two circuits, requiring a precision of .02 for both.\n", - "estimator.run([transpiled1, transpiled2], precision=.02)\n", + "estimator.run([transpiled1, transpiled2], precision=0.02)\n", "\n", "# Run two circuits with different precision requirements.\n", - "estimator.run([(transpiled1, None, .01), (transpiled2, None, .02)])" + "estimator.run([(transpiled1, None, 0.01), (transpiled2, None, 0.02)])" ] }, { @@ -272,11 +272,11 @@ "id": "52024f25-74ef-445a-9df8-d76da4ec7a32", "metadata": {}, "source": [ - "#### Precision \n", + "#### 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 Executor execution interface, and are independent of the Runtime Executor'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", + "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 the 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", @@ -352,19 +352,19 @@ "\n", "\n", "# Setting precision during primitive initialization\n", - "estimator = Estimator(mode=backend, options={\"default_precision\": .01})\n", + "estimator = Estimator(mode=backend, options={\"default_precision\": 0.01})\n", "\n", "# Setting options after primitive initialization\n", "# This uses auto-complete.\n", - "estimator.options.default_precision = .01\n", + "estimator.options.default_precision = 0.01\n", "\n", "# This does bulk update. The value for default_precision is overridden if you specify precision with run() or in the PUB.\n", "estimator.options.update(\n", - " default_precision=.01, dynamical_decoupling={\"sequence_type\": \"XpXm\"}\n", + " default_precision=0.01, dynamical_decoupling={\"sequence_type\": \"XpXm\"}\n", ")\n", "\n", "# Run two circuits to a precision of .02 each.\n", - "estimator.run([transpiled1, transpiled2], precision=.02)" + "estimator.run([transpiled1, transpiled2], precision=0.02)" ] }, { From 7d2381d50b8dff7ce6077a9dfd9e91d2b2fd4bdf Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 13:48:27 -0600 Subject: [PATCH 084/118] Apply suggestions from code review Co-authored-by: abbycross --- docs/guides/broadcasting.mdx | 2 +- docs/guides/estimator-broadcasting.mdx | 4 +-- docs/guides/executor-broadcasting.mdx | 39 ++++---------------------- docs/guides/executor-examples.mdx | 6 ++-- docs/guides/executor-input-output.mdx | 14 ++++----- 5 files changed, 18 insertions(+), 47 deletions(-) diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx index 389817f643f..6ba9cab57ff 100644 --- a/docs/guides/broadcasting.mdx +++ b/docs/guides/broadcasting.mdx @@ -15,7 +15,7 @@ The primitives aggregate elements from multiple arrays (observables and paramete * The size of each dimension is the largest size of the corresponding dimension. * Missing dimensions are assumed to have size one. * Shape comparisons start with the rightmost dimension and continue to the left. -* Two dimensions are compatible if their sizes are equal or if one of them is 1. +* Two dimensions are compatible if their sizes are equal or if one of them is one. Examples of array pairs that broadcast: diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index 31f46a6143a..c5c4cf1aaa1 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -10,11 +10,11 @@ When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/es Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: -Parameter value sets are represented by n x m arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates. +Parameter value sets are represented by `n x m` arrays, and observable arrays are represented by one or more single-column arrays. For each example in the previous code, the parameter value sets are combined with their observable array to create the resulting expectation value estimates. - *Example 1*: (broadcast single observable) has a parameter value set that is a 5x1 array and a 1x1 observables array. The one item in the observables array is combined with each item in the parameter value set to create a single 5x1 array where each item is a combination of the original item in the parameter value set with the item in the observables array. -- *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the nth item in the parameter value set with the nth item in the observables array. +- *Example 2*: (zip) has a 5x1 parameter value set and a 5x1 observables array. The output is a 5x1 array where each item is a combination of the $n^{th}$ item in the parameter value set with the $n^{th}$ item in the observables array. - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output. diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index 88d218ef56c..555b195a8cf 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -149,8 +149,8 @@ execution. The samplex typically injects randomness (for example, twirling gates execution, so even without explicitly requesting multiple randomizations, each element naturally receives its own random realization. -The `shape` parameter lets you augment the extrinsic shape for the item, effectively letting you -add axes that correspond specifically to randomizing the same configuration many times. It must be +You can use the `shape` parameter to augment the extrinsic shape for the item, effectively +adding axes that correspond specifically to randomizing the same configuration many times. It must be broadcastable from the shape implicit in your `samplex_arguments`. Axes where `shape` exceeds the implicit shape enumerate additional independent randomizations. @@ -161,7 +161,7 @@ input configuration. Each execution is still randomized by the samplex, but with single random realization you don't benefit from averaging over multiple randomizations. -If you're used to enabling twirling with a simple flag like `twirling=True`, +If you're accustomed to enabling twirling with a simple flag like `twirling=True`, the Executor requires you to explicitly request multiple randomizations with the `shape` argument to allow your post-processing routines to get the benefits of averaging over multiple randomizations. A single randomization (the default when `shape` is omitted) applies @@ -262,7 +262,7 @@ averaged = meas_data[:, :, 5, :, 2].mean(axis=(0, 1)) ## Common patterns -### Sweeping a single parameter +### Sweep a single parameter To sweep one parameter while holding others fixed: ```python @@ -276,39 +276,10 @@ To sweep one parameter while holding others fixed: np.full(20, fixed_values[0]), np.full(20, fixed_values[1]), ]) # shape (20, 3) -``` - -### Creating a 2D grid sweep -To create a grid over two parameters: - -```python - -# Sweep param 0 over 10 values, param 1 over 8 values, param 2 fixed -p0 = np.linspace(0, np.pi, 10)[:, np.newaxis, np.newaxis] # (10, 1, 1) -p1 = np.linspace(0, np.pi, 8)[np.newaxis, :, np.newaxis] # (1, 8, 1) -p2 = np.array([[[0.5]]]) # (1, 1, 1) - -parameter_values = np.broadcast_arrays(p0, p1, p2) -parameter_values = np.stack(parameter_values, axis=-1).squeeze() # (10, 8, 3) - -# Extrinsic shape: (10, 8), intrinsic shape: (3,) -``` - -### Combining multiple inputs - -When combining inputs with different intrinsic shapes, align extrinsic dimensions using -size-1 axes: - -```python -# 4 parameter configurations, 3 noise scales → 4×3 = 12 total configurations -parameter_values = np.random.rand(4, 1, 2) # extrinsic (4, 1), intrinsic (2,) -noise_scale = np.array([0.8, 1.0, 1.2]) # extrinsic (3,), intrinsic () - -# Broadcasted extrinsic shape: (4, 3) ``` ## Next steps - - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Review the [broadcasting](/docs/guides/broadcasting) overview. - Understand [Executor inputs and outputs.](/docs/guides/executor-input-output) diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index fd1ec1ed17c..53b14b46f48 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -5,7 +5,7 @@ description: Practical examples of using the Executor primitive in Qiskit Runtim --- {/* cspell:ignore broadcastable */} -The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install and set up](install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model) +The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install Qiskit](/docs/guides/install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model) ## Generate the circuit @@ -51,7 +51,7 @@ backend = service.least_busy(operational=True, simulator=False) ## Define a `QuantumProgram` -The input to the Executor is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output#programs) +The input to Executor is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output#programs) ```python # Initialize an empty program @@ -109,6 +109,6 @@ result = job.result() ## Next steps - - Review the overview of [broadcasting.](/docs/guides/broadcasting) + - Review the [broadcasting](/docs/guides/broadcasting) overview. - Learn how to use [Executor options.](/docs/guides/executor-options) diff --git a/docs/guides/executor-input-output.mdx b/docs/guides/executor-input-output.mdx index 28f2095bd02..dbe2c354a33 100644 --- a/docs/guides/executor-input-output.mdx +++ b/docs/guides/executor-input-output.mdx @@ -13,13 +13,13 @@ The inputs and output of the Executor primitive are very different from those of The input to an Executor primitive is a [`QuantumProgram`](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgram.html#qiskit_ibm_runtime.quantum_program.QuantumProgram), which is an iterable of a [`qiskit_ibm_runtime.quantum_program.QuantumProgramItem`.](https://qiskit.github.io/qiskit-ibm-runtime/stubs/qiskit_ibm_runtime.quantum_program.QuantumProgramItem.html) Each of these items represents a -different task for the Executor to perform. Typically, each item owns one of the following options: +different task for Executor to perform. Typically, each item owns one of the following options: * A `qiskit.circuit.QuantumCircuit` with static, non-parametrized gates * A parametrized `qiskit.circuit.QuantumCircuit` with an array of parameter values -* A parametrized `qiskit.circuit.QuantumCircuit` with a `samplomatic.samplex.Samplex` to generate randomize arrays of parameter values +* A parametrized `qiskit.circuit.QuantumCircuit` with a `samplomatic.samplex.Samplex` to generate randomized arrays of parameter values -Each of these items, including instructions to add them to a `QuantumProgram` is explained in more detail below. +Each of these items, including instructions to add them to a `QuantumProgram`, is explained in more detail below. The following cell initializes a `QuantumProgram` and specifies that it should run 1024 shots for every configuration of each item in the program. Then it appends a version of the target circuit with set parameters, transpiled according to the backend's ISA. @@ -53,7 +53,7 @@ program.append_circuit_item( ``` Finally, append a parametrized `qiskit.circuit.QuantumCircuit` and a `samplomatic.samplex.Samplex`, which is responsible for generating randomized sets of parameters for the given circuit. As part of the `samplomatic.samplex.Samplex` arguments, `10` sets of parameters for the parametric gates in the original circuit are provided. The `shape` request argument requests an extension of the implicit shape defined by the `samplomatic.samplex.Samplex` arguments. In particular, by setting `shape` -to `(2, 14, 10)` we request to randomize each of the `10` sets of parameters `28` times, and to arrange the randomized parameter sets in an array of be arranged in an array of shape `(2, 14, 10)`. +to `(2, 14, 10)` we request to randomize each of the `10` sets of parameters `28` times, and to arrange the randomized parameter sets in an array of shape `(2, 14, 10)`. See the samplomatic [API](https://github.com/Qiskit/samplomatic/) documentation for full details about `samplomatic.samplex.Samplex` and its arguments. @@ -91,7 +91,7 @@ these items is a dictionary where the keys are strings and the values are of typ In the previous example, the result contains three items: -### Result item 1. +### Result item 1 The first item in `result` is the result of running the first task in the program, the circuit with static gates. It contains a single key, `'meas'`, corresponding to the name of the input circuit's @@ -106,7 +106,7 @@ result_0 = result[0]["meas"] print(f"Result shape: {result_0.shape}") ``` -### Result item 2. +### Result item 2 The second item contains the results of running the second task in the program, the circuit with parametrized gates. @@ -121,7 +121,7 @@ result_1 = result[1]["meas"] print(f"Result shape: {result_1.shape}") ``` -### Result item 3. +### Result item 3 The third item contains the results of running the third task in the program. This item contains multiple keys. In addition to the `'meas'` key (mapped to the array of results for that classical register), it contains `'measurement_flips.meas'`, the bit-flip corrections to undo From 519577edf2820bc9a4660c98294d945b1ed40971 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:24:46 -0600 Subject: [PATCH 085/118] Update docs/guides/estimator-examples.ipynb Co-authored-by: abbycross --- docs/guides/estimator-examples.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb index 0592a2d6bdd..10eefb7bade 100644 --- a/docs/guides/estimator-examples.ipynb +++ b/docs/guides/estimator-examples.ipynb @@ -48,7 +48,7 @@ "id": "bae32e60", "metadata": {}, "source": [ - "The examples in this section illustrate some common ways to use Estimator. Before running these examples, follow the instructions in [Install and set up.](install-qiskit)\n", + "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", From 98e92fab3dbeaae86d635288be7d5a017693884c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:25:11 -0600 Subject: [PATCH 086/118] Update docs/guides/get-started-with-estimator.ipynb Co-authored-by: abbycross --- docs/guides/get-started-with-estimator.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 7f9406705f7..6715084a366 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -284,7 +284,7 @@ "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 Estimator primitive can be run with any provider by using [`qiskit.primitives.BackendEstimatorV2`](../api/qiskit/qiskit.primitives.BackendEstimatorV2).\n", + "The Estimator primitive can be run with any provider by using [`qiskit.primitives.BackendEstimatorV2`](/docs/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." ] From 2465e681dee9ce84d31b4abefd2b6f9aa6d268f7 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:25:30 -0600 Subject: [PATCH 087/118] Update docs/guides/get-started-with-estimator.ipynb Co-authored-by: abbycross --- docs/guides/get-started-with-estimator.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 6715084a366..51f5c8c64ec 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -313,7 +313,7 @@ "source": [ "### Similarities and differences between backend and Runtime primitives\n", "\n", - "- The inputs to and outputs from [`qiskit.primitives.BackendEstimatorV2`](../api/qiskit/qiskit.primitives.BackendEstimatorV2)\n", + "- The inputs to and outputs from [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2)\n", "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) for details.\n", "However, there can be differences in the fields of the returned metadata.\n", "\n", From 37bac5f2066c628f3f5a016d42b4cd2f6ea9752a Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:26:41 -0600 Subject: [PATCH 088/118] Update docs/guides/executor-options.mdx Co-authored-by: abbycross --- docs/guides/executor-options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index dbd08d7f17a..037932ec202 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -18,7 +18,7 @@ Notes about specifying options in the primitives: ## Set Executor options -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. +You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](/docs/guides/runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. ### Primitive initialization From 13c0d4c94ff8aaaab265016dd1731ff272ad55ff Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:27:01 -0600 Subject: [PATCH 089/118] Update docs/guides/estimator-options.ipynb Co-authored-by: abbycross --- docs/guides/estimator-options.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index ceffbbbcb59..1268507ce2b 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -48,7 +48,7 @@ "id": "8fdcbe4a", "metadata": {}, "source": [ - "You can use options to customize the Estimator 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 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", + "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 about specifying options in the Estimator primitives:\n", "\n", From c7bb82ef415f61dfb40d1bc07d4660ae45705128 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:27:16 -0600 Subject: [PATCH 090/118] Update docs/guides/estimator-options.ipynb Co-authored-by: abbycross --- docs/guides/estimator-options.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 1268507ce2b..9ac8299d1fc 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -60,7 +60,7 @@ "\n", "## Set Estimator options\n", "\n", - "You can set options when initializing Estimator, after initializing Estimator, 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", + "You can set options when initializing Estimator, after initializing Estimator, or in the `run()` method. See the [precedence rules](/docs/guides/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", From 6adaef6f451179050876d477b75c8291a782af15 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:37:00 -0600 Subject: [PATCH 091/118] Update docs/guides/estimator-options.ipynb Co-authored-by: abbycross --- docs/guides/estimator-options.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 9ac8299d1fc..de929a28d11 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -241,7 +241,7 @@ "\n", "#### Resilience level\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", + "The resilience level is not actually an option that directly impacts the primitive query, but specifies a base set of curated options as a starting point. 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", From c05b09b8a3d60dcdbab9a46c15a751480e6374be Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 14:37:15 -0600 Subject: [PATCH 092/118] Update docs/guides/estimator-options.ipynb Co-authored-by: abbycross --- docs/guides/estimator-options.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index de929a28d11..710889b29d7 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -296,7 +296,7 @@ "\n", "## Commonly used options\n", "\n", - "There are many available options, but the following are the most commonly used:\n", + "Among the many available options, the following are the most commonly used:\n", "\n", "\n", "### Shots\n", From 922e593239e1dff8f87b8899dacefe419e82447a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 23 Feb 2026 15:05:38 -0600 Subject: [PATCH 093/118] review comments --- docs/guides/estimator-broadcasting.mdx | 4 ++-- docs/guides/estimator-options.ipynb | 1 - docs/guides/executor-broadcasting.mdx | 8 ++++---- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index c5c4cf1aaa1..fa54b322cbe 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -18,7 +18,7 @@ Parameter value sets are represented by `n x m` arrays, and observable arrays ar - *Example 3*: (outer/product) has a 1x6 parameter value set and a 4x1 observables array. Their combination results in a 4x6 array that is created by combining each item in the parameter value set with *every* item in the observables array, and thus each parameter value becomes an entire column in the output. -- *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. +- *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. ![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs/broadcasting.avif "Visual representation of broadcasting") @@ -42,7 +42,7 @@ observables = [ ] # shape (4, 1) # >> pub result has shape (4, 6) -# Standard nd generalization +# Standard `nd` generalization parameter_values = np.random.uniform(size=(3, 6)) # shape (3, 6) observables = [ [ diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 710889b29d7..0783029e420 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -2,7 +2,6 @@ "cells": [ { "cell_type": "markdown", - "id": "8bbb8d7d-bcd5-4092-9df1-9930c67b17bc", "metadata": {}, "source": [ "---\n", diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index 555b195a8cf..7146e7b5808 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -56,7 +56,7 @@ Broadcasting only applies to _extrinsic_ axes. The intrinsic axes are always pre - **Extrinsic axes** (leftmost): Your sweep dimensions. These define how many configurations you want to run. -| Input type | Intrinsic shape | Example full shape | +| Input type | Intrinsic shape | Example full shape | |:----------------------------------------:|:---------------:|:---------------------------------------------------:| | Parameter values (n parameters) | (n,) | (5, 3) for five configurations and three parameters | | Scalar inputs (for example, noise scale) | () | (4,) for four configurations | @@ -97,7 +97,7 @@ program.append( The shapes are as follows: -| Input | Full shape | Extrinsic shape | Intrinsic shape | +| Input | Full shape | Extrinsic shape | Intrinsic shape | |:------------------:|:----------:|:---------------:|:---------------:| | `parameter_values` | (4, 1, 2) | (4, 1) | (2,) | | `noise_scale` | (3,) | (3,) | () | @@ -113,7 +113,7 @@ Output arrays follow the same extrinsic/intrinsic pattern: The most common output is bitstring data from measurements, which is formatted as an array of boolean values: -| Output type | Intrinsic shape | Description | +| Output type | Intrinsic shape | Description | |:-----------------------:|:----------------------:|:--------------------------------:| | Classical register data | (num_shots, creg_size) | Bitstring data from measurements | | Expectation values | () or (n_obs,) | Scalar or per-observable | @@ -233,7 +233,7 @@ that expand to match input dimensions, as is illustrated in the last row of the Examples: -| Input extrinsic | shape | Result | +| Input extrinsic | Shape | Result | |:---------------:|:----------:|:-----------------------------------------------------------------:| | (10,) | (10,) | 10 configurations, 1 randomization each | | (10,) | (5, 10) | 10 configurations, 5 randomizations each | From 58bff653a68fc3eb619e13c1f7345e3b99dabf48 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Mon, 23 Feb 2026 15:12:10 -0600 Subject: [PATCH 094/118] Apply suggestions from code review Co-authored-by: Yael Ben-Haim Co-authored-by: abbycross --- docs/guides/executor-examples.mdx | 5 ++--- docs/guides/executor-input-output.mdx | 2 +- docs/guides/executor-options.mdx | 12 ++++++------ docs/guides/get-started-with-executor.mdx | 2 +- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index 53b14b46f48..0d4082e654d 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -57,14 +57,13 @@ The input to Executor is a `QuantumProgram`. For full details, see [Executor inp # Initialize an empty program program = QuantumProgram(shots=1024) -# Append the circuit to the program -program.append_circuit_item(isa_circuit) -# Append the circuit and the parameter value to the program +# Append the circuit and the parameter values to the program program.append_circuit_item( isa_circuit, circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values ) + # Transpile the circuit, additionally grouping gates and measurements into annotated boxes preset_pass_manager = generate_preset_pass_manager( backend=backend, optimization_level=0 diff --git a/docs/guides/executor-input-output.mdx b/docs/guides/executor-input-output.mdx index dbe2c354a33..1438fc70b38 100644 --- a/docs/guides/executor-input-output.mdx +++ b/docs/guides/executor-input-output.mdx @@ -45,7 +45,7 @@ program.append_circuit_item(isa_circuit) Next, append a second item that contains a parametrized `qiskit.circuit.QuantumCircuit` and an array containing 10 sets of parameter values. This amounts to a circuit task requiring a total of 10240 shots (1024 per set of parameter values). ```python -# Append the circuit and the parameter value to the program +# Append the circuit and the parameter values to the program program.append_circuit_item( isa_circuit, circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index 037932ec202..754c898fb63 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -40,14 +40,14 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) options = ExecutorOptions( - environment={"log_level" = INFO}, + environment={"log_level": INFO}, execution={"init_qubits": True}, ) # or... options = ExecutorOptions() -options.log_level = INFO -options.init_qubits = True +options.environment.log_level = INFO +options.execution.init_qubits = True executor = Executor(mode=backend, options=options) ``` @@ -66,7 +66,7 @@ backend = service.least_busy(operational=True, simulator=False) executor = Executor( backend, options={ - "environment"={"log_level" = INFO}, + "environment"={"log_level": INFO}, "execution"={"init_qubits": True}, }, ) @@ -88,9 +88,9 @@ executor = Executor(mode=backend) # Setting options after primitive initialization # This uses auto-complete. -executor.options.log_level = INFO +executor.options.environment.log_level = INFO # This does bulk update. -sampler.options.update(environment={"log_level" = INFO} +executor.options.update(environment={"log_level": INFO} ) ``` ## Next steps diff --git a/docs/guides/get-started-with-executor.mdx b/docs/guides/get-started-with-executor.mdx index 823ed81eeff..20c06cc4bdf 100644 --- a/docs/guides/get-started-with-executor.mdx +++ b/docs/guides/get-started-with-executor.mdx @@ -39,7 +39,7 @@ The result is of type [`QuantumProgramResult`.](https://qiskit.github.io/qiskit- ## Next steps - - Try some [Executor examples](/docs/guides/executor-examples) + - Try some [Executor examples.](/docs/guides/executor-examples) - Understand [Executor input and output.](/docs/guides/executor-input-output) - Learn about [Executor broadcasting semantics.](/docs/guides/executor-broadcasting) From 838aad531680294d59bce8845164dc1bdd39b0b0 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 23 Feb 2026 16:58:51 -0600 Subject: [PATCH 095/118] changes from review --- docs/guides/directed-execution-model.mdx | 1 + docs/guides/executor-input-output.mdx | 10 +++++----- docs/guides/executor-options.mdx | 1 - docs/guides/primitives.ipynb | 8 +++++++- 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/guides/directed-execution-model.mdx b/docs/guides/directed-execution-model.mdx index 1984f086ce6..3204d47654a 100644 --- a/docs/guides/directed-execution-model.mdx +++ b/docs/guides/directed-execution-model.mdx @@ -35,6 +35,7 @@ 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: diff --git a/docs/guides/executor-input-output.mdx b/docs/guides/executor-input-output.mdx index 1438fc70b38..cc6c1396924 100644 --- a/docs/guides/executor-input-output.mdx +++ b/docs/guides/executor-input-output.mdx @@ -47,7 +47,7 @@ Next, append a second item that contains a parametrized `qiskit.circuit.QuantumC ```python # Append the circuit and the parameter values to the program program.append_circuit_item( - isa_circuit, + parametrized_isa_circuit, circuit_arguments=np.random.rand(10, 3), # 10 sets of parameter values ) ``` @@ -91,7 +91,7 @@ these items is a dictionary where the keys are strings and the values are of typ In the previous example, the result contains three items: -### Result item 1 +### Result item 0 The first item in `result` is the result of running the first task in the program, the circuit with static gates. It contains a single key, `'meas'`, corresponding to the name of the input circuit's @@ -106,7 +106,7 @@ result_0 = result[0]["meas"] print(f"Result shape: {result_0.shape}") ``` -### Result item 2 +### Result item 1 The second item contains the results of running the second task in the program, the circuit with parametrized gates. @@ -121,7 +121,7 @@ result_1 = result[1]["meas"] print(f"Result shape: {result_1.shape}") ``` -### Result item 3 +### Result item 2 The third item contains the results of running the third task in the program. This item contains multiple keys. In addition to the `'meas'` key (mapped to the array of results for that classical register), it contains `'measurement_flips.meas'`, the bit-flip corrections to undo @@ -134,7 +134,7 @@ print(f"Result shape: {result_2.shape}") # Access the bit-flip corrections flips_2 = result[2]["measurement_flips.meas"] -print(f"Result shape: {result_0.shape}") +print(f"Bit-flip corrections: {result_2.flips_2}") # Undo the bit flips via classical XOR unflipped_result_2 = result_2 ^ flips_2 diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index 754c898fb63..513ad8c9d64 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -12,7 +12,6 @@ Notes about specifying options in the primitives: - You can see the available options and update option values during or after primitive initialization. - Use the `update()` method to apply changes to the `options` attribute. -- If you do not specify a value for an option, it is given a special value of `Unset` and the server defaults are used. - The `options` attribute is the `dataclass` Python type. You can use the built-in `asdict` method to convert it to a dictionary. diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index b40081429bb..0b0947538bb 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -276,7 +276,13 @@ "\n", "### Executor (beta)\n", "\n", - "The Executor Qiskit Runtime primitive takes a program (a template circuit and 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. The Executor primitive is part of the [directed execution model.](/docs/guides/directed-execution-model)" + "The Executor Qiskit Runtime primitive takes a _program_ 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. \n", + "\n", + "The Executor primitive is part of the [directed execution model,](/docs/guides/directed-execution-model) which introduces some new terminology:\n", + "\n", + "- A **program** is a list of program items, where each item is either a circuit item or a samplex item.\n", + "- A **samplex item** is a pair that consists of a template circuit and a samplex pair.\n", + "- **Samplex** is the core type of the [Samplomatic library.](/docs/guides/directed-execution-model#samplex)" ] }, { From 05794d2e60962f026ea8788da6b26c7d6766340a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 24 Feb 2026 11:23:21 -0600 Subject: [PATCH 096/118] There is no precedence section! --- docs/guides/_toc.json | 15 +- docs/guides/configure-error-mitigation.ipynb | 5 +- docs/guides/configure-error-suppression.ipynb | 2 +- docs/guides/estimator-options.ipynb | 2 +- docs/guides/executor-options.mdx | 2 +- docs/guides/max-execution-time.ipynb | 2 +- docs/guides/noise-learning.ipynb | 1 - docs/guides/runtime-options-overview.mdx | 8 +- docs/guides/sampler-options.ipynb | 2 +- docs/guides/specify-runtime-options.ipynb | 496 ------------------ docs/guides/v2-primitives.mdx | 4 +- qiskit_bot.yaml | 2 - scripts/config/notebook-testing.toml | 1 - 13 files changed, 18 insertions(+), 524 deletions(-) delete mode 100644 docs/guides/specify-runtime-options.ipynb diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 4d63bcd671d..1964cd2dbc0 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -221,6 +221,9 @@ { "title": "Introduction to primitives", "url": "/docs/guides/primitives" + }, { + "title": "Introduction to options", + "url": "/docs/guides/runtime-options-overview" }, { "title": "Introduction to PUBs", @@ -333,14 +336,6 @@ "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": "Qiskit Runtime local testing mode", "url": "/docs/guides/local-testing-mode" @@ -490,10 +485,6 @@ "title": "Introduction to options", "url": "/docs/guides/runtime-options-overview" }, - { - "title": "Specify options", - "url": "/docs/guides/specify-runtime-options" - }, { "title": "Qiskit Runtime local testing mode", "url": "/docs/guides/local-testing-mode" diff --git a/docs/guides/configure-error-mitigation.ipynb b/docs/guides/configure-error-mitigation.ipynb index fe2cceecd0f..20924df507c 100644 --- a/docs/guides/configure-error-mitigation.ipynb +++ b/docs/guides/configure-error-mitigation.ipynb @@ -250,7 +250,7 @@ "\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", + "For instructions to turn off all error mitigation when using Estimator, 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", @@ -258,7 +258,8 @@ " - 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", + " - Explore Sampler [options.](/docs/guides/sampler-options)\n", + " - Explore Estimator [options.](/docs/guides/estimator-options)\n", " - Decide what [execution mode](execution-modes) to run your job in.\n", "" ] diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index efce0a8fb9a..04cb8b134bf 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -120,7 +120,7 @@ "\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", + "For instructions to turn off all error suppression, see the [Turn off all error suppression and mitigation](estimator-options#no-error-mitigation) section.\n", "\n", "## Next steps\n", "\n", diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 0783029e420..ad0f55c59c4 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -59,7 +59,7 @@ "\n", "## Set Estimator options\n", "\n", - "You can set options when initializing Estimator, after initializing Estimator, or in the `run()` method. See the [precedence rules](/docs/guides/runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places.\n", + "You can set options when initializing Estimator, after initializing Estimator, or (for `precision`) in the `run()` method.\n", "\n", "### Primitive initialization\n", "\n", diff --git a/docs/guides/executor-options.mdx b/docs/guides/executor-options.mdx index 513ad8c9d64..6450d5551b7 100644 --- a/docs/guides/executor-options.mdx +++ b/docs/guides/executor-options.mdx @@ -17,7 +17,7 @@ Notes about specifying options in the primitives: ## Set Executor options -You can set options when initializing the primitive, after initializing the primitive, or in the `run()` method. See the [precedence rules](/docs/guides/runtime-options-overview#options-precedence) section to understand what happens when the same option is specified in multiple places. +You can set options when initializing the primitive or after initializing the primitive. If an option is specified in both locations, the value set after initializing the primitive is used. ### Primitive initialization diff --git a/docs/guides/max-execution-time.ipynb b/docs/guides/max-execution-time.ipynb index eb90a943ce7..2b722288547 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), [Sampler options](/docs/guides/sampler-options), or [Executor options](/docs/guides/executor-options) guides for information about setting options.\n", "\n", "```python\n", "from qiskit_ibm_runtime import QiskitRuntimeService\n", diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index 35b1649fd6b..037258903eb 100644 --- a/docs/guides/noise-learning.ipynb +++ b/docs/guides/noise-learning.ipynb @@ -354,7 +354,6 @@ " - 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", " - Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", "" ] diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index ad9379a9b80..c44b9aa5efc 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -14,7 +14,7 @@ in_page_toc_max_heading_level: 2 ### 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 different categories, such as `execution`. See [Estimator options,](/docs/guides/estimator-options) [Sampler options,](/docs/guides/sampler-options) and [Executor options](/docs/guides/executor-options) for full details. ### Defaults @@ -26,7 +26,7 @@ The tables in the [Options classes summary](#options-classes) section lists the ## 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 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 [Estimator options,](/docs/guides/estimator-options) [Sampler options,](/docs/guides/sampler-options) and [Executor options](/docs/guides/executor-options) for full details. ## Options classes summary @@ -993,5 +993,7 @@ Due to differences in the device compilation process, certain runtime features c - 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). + - Learn how to work with [Estimator options.](/docs/guides/estimator-options) + - Learn how to work with [Sampler options.](/docs/guides/sampler-options) + - Learn how to work with [Executor options.](/docs/guides/executor-options) diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 3a0132fefd2..5738179fd61 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -60,7 +60,7 @@ "\n", "## Set Sampler 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", + "You can set options when initializing the primitive, after initializing the primitive, or (for `shots`) in the `run()` method.\n", "\n", "### Primitive initialization\n", "\n", diff --git a/docs/guides/specify-runtime-options.ipynb b/docs/guides/specify-runtime-options.ipynb deleted file mode 100644 index 658d44cb98c..00000000000 --- a/docs/guides/specify-runtime-options.ipynb +++ /dev/null @@ -1,496 +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", - "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": "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/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index a6f05414661..f2d2a804c47 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() @@ -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 about setting options in the [Sampler options,](/docs/guides/sampler-options) [Estimator options,](/docs/guides/estimator-options) and [Executor options](/docs/guides/executor-options) guides. - Learn more details about [Primitive inputs and outputs.](/docs/guides/pubs) - Experiment with the [CHSH Inequality](/docs/tutorials/chsh-inequality) tutorial. diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 594263f1602..6e6bbd40227 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -373,8 +373,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": diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 59e83212c81..d9044c001a1 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -69,7 +69,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", ] From e8f53a7326af0f2f04d0c507a955a383e4cf95af Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 24 Feb 2026 11:35:46 -0600 Subject: [PATCH 097/118] links should have the full path --- docs/guides/DAG-representation.ipynb | 4 ++-- docs/guides/ai-transpiler-passes.ipynb | 4 ++-- docs/guides/build-noise-models.ipynb | 4 ++-- docs/guides/circuit-library.ipynb | 2 +- docs/guides/cloud-setup-invited.mdx | 2 +- docs/guides/cloud-setup.mdx | 2 +- docs/guides/considerations-set-up-runtime.mdx | 2 +- docs/guides/construct-circuits.ipynb | 6 +++--- docs/guides/custom-transpiler-pass.ipynb | 2 +- docs/guides/debugging-tools.mdx | 10 +++++----- docs/guides/defaults-and-configuration-options.ipynb | 4 ++-- docs/guides/estimate-job-run-time.ipynb | 2 +- docs/guides/estimator-examples.ipynb | 2 +- docs/guides/estimator-input-output.ipynb | 2 +- docs/guides/estimator-rest-api.ipynb | 4 ++-- docs/guides/execution-modes-rest-api.ipynb | 6 +++--- docs/guides/fractional-gates.ipynb | 2 +- .../function-template-chemistry-workflow.ipynb | 2 +- docs/guides/functions.ipynb | 4 ++-- docs/guides/get-started-with-estimator.ipynb | 2 +- docs/guides/get-started-with-sampler.ipynb | 2 +- docs/guides/ibm-circuit-function.ipynb | 8 ++++---- docs/guides/interoperate-qiskit-qasm2.ipynb | 2 +- docs/guides/interoperate-qiskit-qasm3.ipynb | 2 +- docs/guides/metapackage-migration.mdx | 2 +- docs/guides/minimize-time.mdx | 4 ++-- docs/guides/online-lab-environments.mdx | 2 +- docs/guides/operator-class.ipynb | 2 +- docs/guides/operators-overview.ipynb | 4 ++-- docs/guides/q-ctrl-performance-management.ipynb | 6 +++--- docs/guides/qasm-feature-table.mdx | 2 +- docs/guides/qiskit-1.0-installation.mdx | 2 +- docs/guides/qiskit-function-templates.mdx | 12 ++++++------ docs/guides/repetition-rate-execution.ipynb | 4 ++-- docs/guides/run-jobs-session.ipynb | 2 +- docs/guides/sampler-examples.ipynb | 2 +- docs/guides/sampler-input-output.ipynb | 2 +- docs/guides/sampler-rest-api.mdx | 4 ++-- docs/guides/serverless-first-program.ipynb | 2 +- docs/guides/serverless-manage-resources.ipynb | 4 ++-- docs/guides/serverless-run-first-workload.ipynb | 6 +++--- docs/guides/serverless.mdx | 4 ++-- docs/guides/set-optimization.ipynb | 2 +- docs/guides/simulate-stabilizer-circuits.ipynb | 2 +- docs/guides/simulate-with-qiskit-aer.ipynb | 2 +- .../guides/simulate-with-qiskit-sdk-primitives.ipynb | 4 ++-- docs/guides/synthesize-unitary-operators.ipynb | 2 +- docs/guides/tools-intro.mdx | 12 ++++++------ docs/guides/transpiler-plugins.ipynb | 2 +- docs/guides/transpiler-stages.ipynb | 4 ++-- docs/guides/upgrade-from-open.mdx | 4 ++-- docs/guides/view-cost.mdx | 2 +- 52 files changed, 92 insertions(+), 92 deletions(-) diff --git a/docs/guides/DAG-representation.ipynb b/docs/guides/DAG-representation.ipynb index c5910fec4d7..92edefe2da0 100644 --- a/docs/guides/DAG-representation.ipynb +++ b/docs/guides/DAG-representation.ipynb @@ -464,8 +464,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/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 c6176ad9de8..3130a39eff0 100644 --- a/docs/guides/build-noise-models.ipynb +++ b/docs/guides/build-noise-models.ipynb @@ -592,7 +592,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." ] }, { @@ -974,7 +974,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 8d5ef9cc924..4ecfc5b21fa 100644 --- a/docs/guides/circuit-library.ipynb +++ b/docs/guides/circuit-library.ipynb @@ -491,7 +491,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 a8df3277857..dbc272bbd09 100644 --- a/docs/guides/cloud-setup-invited.mdx +++ b/docs/guides/cloud-setup-invited.mdx @@ -13,7 +13,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/cloud-setup.mdx b/docs/guides/cloud-setup.mdx index 664d8dc9305..2bf30ae11bb 100644 --- a/docs/guides/cloud-setup.mdx +++ b/docs/guides/cloud-setup.mdx @@ -11,7 +11,7 @@ If you were emailed an invitation to join an account, follow the steps in [Set u 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). diff --git a/docs/guides/considerations-set-up-runtime.mdx b/docs/guides/considerations-set-up-runtime.mdx index 125d2128ce4..518b6ed80bf 100644 --- a/docs/guides/considerations-set-up-runtime.mdx +++ b/docs/guides/considerations-set-up-runtime.mdx @@ -100,7 +100,7 @@ The steps of this guide can be automated for consistent and repeatable managemen ## Next steps - * See [Configure IBM Quantum Platform for an organization](./quickstart-steps-org) for the steps to set up IBM Quantum Platform. + * See [Configure IBM Quantum Platform for an organization](/docs/guides/quickstart-steps-org) for the steps to set up IBM Quantum Platform. * [Understand available plans.](/docs/guides/plans-overview) * [Create instances.](/docs/guides/instances) * [Understand the IBM Cloud structure.](/docs/guides/cloud-account-structure) diff --git a/docs/guides/construct-circuits.ipynb b/docs/guides/construct-circuits.ipynb index 7a001ab5e9d..2432ba4e598 100644 --- a/docs/guides/construct-circuits.ipynb +++ b/docs/guides/construct-circuits.ipynb @@ -189,7 +189,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." ] }, { @@ -450,10 +450,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](./primitives#sampler) primitive, measurements are required. However, circuits submitted to an [Estimator](./primitives#estimator) primitive must not contain measurements.\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/primitives#sampler) primitive, measurements are required. However, circuits submitted to an [Estimator](/docs/guides/primitives#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 fe208385568..3655d4277b4 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 384cb371a8e..732124e53ee 100644 --- a/docs/guides/debugging-tools.mdx +++ b/docs/guides/debugging-tools.mdx @@ -13,22 +13,22 @@ Because the cost of classically simulating quantum circuits scales exponentially - Test smaller versions of the circuits that can be simulated classically. - Modify the circuits so that they become classically simulable, although less accurate. -Stabilizer circuits, also known as Clifford circuits, are a useful tool for accomplishing this latter goal. These are a restricted class of quantum circuits that can be efficiently simulated classically. Specialized simulators can easily simulate stabilizer circuits with thousands of qubits. See [Efficient simulation of stabilizer circuits with Qiskit Aer primitives](./simulate-stabilizer-circuits) for more information. +Stabilizer circuits, also known as Clifford circuits, are a useful tool for accomplishing this latter goal. These are a restricted class of quantum circuits that can be efficiently simulated classically. Specialized simulators can easily simulate stabilizer circuits with thousands of qubits. See [Efficient simulation of stabilizer circuits with Qiskit Aer primitives](/docs/guides/simulate-stabilizer-circuits) for more information. For general quantum circuits, the following tools are available to test and debug your quantum programs: - For simulating circuits when using Qiskit Runtime, use its [local testing mode](local-testing-mode). -- 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). - For Qiskit Runtime Estimator jobs, use the Qiskit Runtime [`Neat`](/docs/api/qiskit-ibm-runtime/debug-tools) class to debug and analyze your jobs. See [Debug Qiskit Runtime jobs](/docs/guides/debug-qiskit-runtime-jobs) for details. ## 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). \ No newline at end of file diff --git a/docs/guides/defaults-and-configuration-options.ipynb b/docs/guides/defaults-and-configuration-options.ipynb index 9e69f153a98..54eb166b1a4 100644 --- a/docs/guides/defaults-and-configuration-options.ipynb +++ b/docs/guides/defaults-and-configuration-options.ipynb @@ -303,9 +303,9 @@ "\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", + " - Learn how to [Set the optimization level when using Qiskit Runtime.](/docs/guides/runtime-options-overview)\n", " - Visit the [Transpile with pass managers](transpile-with-pass-managers) topic.\n", - " - For examples, see [Representing quantum computers.](./represent-quantum-computers)\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/estimate-job-run-time.ipynb b/docs/guides/estimate-job-run-time.ipynb index 3975aadfca6..fcc7020db6c 100644 --- a/docs/guides/estimate-job-run-time.ipynb +++ b/docs/guides/estimate-job-run-time.ipynb @@ -87,7 +87,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 index 10eefb7bade..9b6564804c1 100644 --- a/docs/guides/estimator-examples.ipynb +++ b/docs/guides/estimator-examples.ipynb @@ -383,7 +383,7 @@ "\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", + " - 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", diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index c9ba8b0e45a..b63e49df562 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -166,7 +166,7 @@ "\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 `PubResults`, one corresponding to each PUB).\n", "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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)). Meanwhile, 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", diff --git a/docs/guides/estimator-rest-api.ipynb b/docs/guides/estimator-rest-api.ipynb index 5d5457e7377..8c11be71250 100644 --- a/docs/guides/estimator-rest-api.ipynb +++ b/docs/guides/estimator-rest-api.ipynb @@ -163,7 +163,7 @@ "\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](./error-mitigation-and-suppression-techniques) topic.\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", @@ -440,7 +440,7 @@ " - 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](./transpile) section.\n", + " - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.\n", "" ] } diff --git a/docs/guides/execution-modes-rest-api.ipynb b/docs/guides/execution-modes-rest-api.ipynb index 8cd2272cbea..10a39c2fa9a 100644 --- a/docs/guides/execution-modes-rest-api.ipynb +++ b/docs/guides/execution-modes-rest-api.ipynb @@ -59,7 +59,7 @@ "\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", @@ -134,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", @@ -300,7 +300,7 @@ " - Review detailed [Estimator](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/fractional-gates.ipynb b/docs/guides/fractional-gates.ipynb index 4518d244b56..2e225900d43 100644 --- a/docs/guides/fractional-gates.ipynb +++ b/docs/guides/fractional-gates.ipynb @@ -65,7 +65,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 1042d006726..95e69ba5a53 100644 --- a/docs/guides/function-template-chemistry-workflow.ipynb +++ b/docs/guides/function-template-chemistry-workflow.ipynb @@ -697,7 +697,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/functions.ipynb b/docs/guides/functions.ipynb index 968a76af623..8d85a322aa5 100644 --- a/docs/guides/functions.ipynb +++ b/docs/guides/functions.ipynb @@ -518,8 +518,8 @@ "\n", "\n", "\n", - "- [Explore circuit functions](./ibm-circuit-function) to build new algorithms and applications, without needing to manage transpilation or error handling.\n", - "- [Explore application functions](./q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n", + "- [Explore circuit functions](/docs/guides/ibm-circuit-function) to build new algorithms and applications, without needing to manage transpilation or error handling.\n", + "- [Explore application functions](/docs/guides/q-ctrl-optimization-solver) to solve domain-specific tasks, with classical inputs and outputs.\n", "\n", "" ] diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 51f5c8c64ec..a750cf00e09 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -26,7 +26,7 @@ "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", + " 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", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index 85f4f29b392..bb6439b4c7c 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -26,7 +26,7 @@ "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", + " 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", diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index d9bf66df04d..32d32cdc1cb 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -35,7 +35,7 @@ "\n", "## Overview\n", "\n", - "The IBM® Circuit function takes [abstract PUBs](./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." + "The IBM® Circuit function takes [abstract PUBs](/docs/guides/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." ] }, { @@ -47,9 +47,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-estimator), 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)" ] diff --git a/docs/guides/interoperate-qiskit-qasm2.ipynb b/docs/guides/interoperate-qiskit-qasm2.ipynb index 03f7ace51b5..670791be1ad 100644 --- a/docs/guides/interoperate-qiskit-qasm2.ipynb +++ b/docs/guides/interoperate-qiskit-qasm2.ipynb @@ -439,7 +439,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 debd3fb2d0f..8b22d6b5ceb 100644 --- a/docs/guides/interoperate-qiskit-qasm3.ipynb +++ b/docs/guides/interoperate-qiskit-qasm3.ipynb @@ -224,7 +224,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/metapackage-migration.mdx b/docs/guides/metapackage-migration.mdx index 790077a9228..f6fdce69ce8 100644 --- a/docs/guides/metapackage-migration.mdx +++ b/docs/guides/metapackage-migration.mdx @@ -110,4 +110,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..f144988eca9 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/configure-error-suppression), and [Configure error mitigation](configure-error-mitigation) 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/online-lab-environments.mdx b/docs/guides/online-lab-environments.mdx index 3550d62e414..33241588c56 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 caf1a502d25..6bab898bf6a 100644 --- a/docs/guides/operator-class.ipynb +++ b/docs/guides/operator-class.ipynb @@ -47,7 +47,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 a5a7d7bba80..06cb3d9085c 100644 --- a/docs/guides/operators-overview.ipynb +++ b/docs/guides/operators-overview.ipynb @@ -522,9 +522,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/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 10aa4c7e5a8..209f0561144 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -64,7 +64,7 @@ "\n", "![Visualization of the improved runtime](/docs/images/guides/qctrl-performance-management/achieve_more.svg)\n", "\n", - "The Performance Management function can be used with any algorithm, and you can easily use it in place of the standard [Qiskit Runtime primitives](./primitives). Behind the scenes, multiple error suppression techniques work together to prevent errors from happening at runtime. All Fire Opal pipeline methods are pre-configured and algorithm-agnostic, meaning you always get the best performance out of the box.\n", + "The Performance Management function can be used with any algorithm, and you can easily use it in place of the standard [Qiskit Runtime primitives](/docs/guides/primitives). Behind the scenes, multiple error suppression techniques work together to prevent errors from happening at runtime. All Fire Opal pipeline methods are pre-configured and algorithm-agnostic, meaning you always get the best performance out of the box.\n", "\n", "To get access to Performance Management, [contact Q-CTRL](https://form.typeform.com/to/uOAVDnGg?typeform-source=q-ctrl.com)." ] @@ -279,7 +279,7 @@ "id": "c07af9d0", "metadata": {}, "source": [ - "You can use the familiar [Qiskit Serverless APIs](./serverless) to check your Qiskit Function workload's status:" + "You can use the familiar [Qiskit Serverless APIs](/docs/guides/serverless) to check your Qiskit Function workload's status:" ] }, { @@ -382,7 +382,7 @@ "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/estimator-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", - "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](./broadcasting) as the `QiskitRuntime` primitives.\n", + "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](/docs/guides/broadcasting) as the `QiskitRuntime` primitives.\n", "- (Optional) A target precision for expectation values to estimate.\n", "- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": }`.\n", "\n", diff --git a/docs/guides/qasm-feature-table.mdx b/docs/guides/qasm-feature-table.mdx index 67d13c19e7c..ec36bdfd041 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-installation.mdx b/docs/guides/qiskit-1.0-installation.mdx index 6e59a988383..73e7e9c7e79 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-function-templates.mdx b/docs/guides/qiskit-function-templates.mdx index a2dd9ffcf45..1281a38ccc5 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/repetition-rate-execution.ipynb b/docs/guides/repetition-rate-execution.ipynb index 88f57ca699d..877f4e26575 100644 --- a/docs/guides/repetition-rate-execution.ipynb +++ b/docs/guides/repetition-rate-execution.ipynb @@ -107,8 +107,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 Estimator.](./get-started-with-estimator)\n", - " - Review how to [get started with Sampler.](./get-started-with-sampler)\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-session.ipynb b/docs/guides/run-jobs-session.ipynb index 80c41be49eb..1a6419676a5 100644 --- a/docs/guides/run-jobs-session.ipynb +++ b/docs/guides/run-jobs-session.ipynb @@ -57,7 +57,7 @@ "\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:" ] }, { diff --git a/docs/guides/sampler-examples.ipynb b/docs/guides/sampler-examples.ipynb index c352509c215..3e477b9d4e6 100644 --- a/docs/guides/sampler-examples.ipynb +++ b/docs/guides/sampler-examples.ipynb @@ -329,7 +329,7 @@ "\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", + " - 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", diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 16349113771..3edc4348e15 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -148,7 +148,7 @@ "\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 `PubResults`, one corresponding to each PUB).\n", "\n", - "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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](./error-mitigation-and-suppression-techniques#zero-noise-extrapolation-zne) or [PEC](./error-mitigation-and-suppression-techniques#probabilistic-error-cancellation-pec)). Meanwhile, 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", + "Each of these `PubResult` objects possess both a `data` and a `metadata` attribute. The `data` attribute is a customized [`DataBin`](/docs/api/qiskit/qiskit.primitives.DataBin) that contains the actual measurement values, standard deviations, and so forth. This `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)). Meanwhile, 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:\n", "\n", diff --git a/docs/guides/sampler-rest-api.mdx b/docs/guides/sampler-rest-api.mdx index 3e76886d171..1861cd0a341 100644 --- a/docs/guides/sampler-rest-api.mdx +++ b/docs/guides/sampler-rest-api.mdx @@ -122,7 +122,7 @@ Error mitigation techniques allow users to mitigate circuit errors by modeling t 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](./error-mitigation-and-suppression-techniques) topic. +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 @@ -343,5 +343,5 @@ Output - 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](./transpile) section. + - 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 4a95a9f7781..76438d9e8b8 100644 --- a/docs/guides/serverless-first-program.ipynb +++ b/docs/guides/serverless-first-program.ipynb @@ -401,7 +401,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 ba584ae33e4..1b7307a7dac 100644 --- a/docs/guides/serverless-manage-resources.ipynb +++ b/docs/guides/serverless-manage-resources.ipynb @@ -130,7 +130,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)." ] @@ -644,7 +644,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 f4b6142bb6d..dd29625d58b 100644 --- a/docs/guides/serverless-run-first-workload.ipynb +++ b/docs/guides/serverless-run-first-workload.ipynb @@ -44,7 +44,7 @@ "source": [ "This section explores how to use `qiskit-ibm-catalog` to list programs available in Qiskit Serverless, pass inputs into these programs, run them remotely, check their status, and retrieve results and logs.\n", "\n", - "Be sure you have authenticated to Qiskit Serverless using your [API key](https://quantum.cloud.ibm.com/) (see [Deploy to IBM Quantum Platform](./serverless-first-program#deploy-to-ibm-quantum-platform) for instructions)." + "Be sure you have authenticated to Qiskit Serverless using your [API key](https://quantum.cloud.ibm.com/) (see [Deploy to IBM Quantum Platform](/docs/guides/serverless-first-program#deploy-to-ibm-quantum-platform) for instructions)." ] }, { @@ -54,7 +54,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)." ] }, { @@ -435,7 +435,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/serverless.mdx b/docs/guides/serverless.mdx index cf59cbbdbf4..5b737696f76 100644 --- a/docs/guides/serverless.mdx +++ b/docs/guides/serverless.mdx @@ -15,7 +15,7 @@ Premium users can build, deploy, and run their workloads remotely on classical c ## When should I use Qiskit Serverless? -Qiskit Serverless helps manage classical and quantum resources across the entire [Qiskit patterns](./intro-to-patterns) workflow. This includes some of the following examples: +Qiskit Serverless helps manage classical and quantum resources across the entire [Qiskit patterns](/docs/guides/intro-to-patterns) workflow. This includes some of the following examples: - Parallelizing classical tasks, such as pre-processing and post-processing - Persisting long-running workloads in the cloud, even if your laptop is turned off @@ -47,7 +47,7 @@ Currently, the IBM Quantum workloads table only reflects Qiskit Runtime workload -- Explore how to [write your first Qiskit Serverless program](./serverless-first-program). +- Explore how to [write your first Qiskit Serverless program](/docs/guides/serverless-first-program). - Try out some [tutorials](/docs/tutorials). \ No newline at end of file diff --git a/docs/guides/set-optimization.ipynb b/docs/guides/set-optimization.ipynb index 3ccc46ca450..29eb606e1b9 100644 --- a/docs/guides/set-optimization.ipynb +++ b/docs/guides/set-optimization.ipynb @@ -385,7 +385,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 70b500ad607..ca478144fb4 100644 --- a/docs/guides/simulate-stabilizer-circuits.ipynb +++ b/docs/guides/simulate-stabilizer-circuits.ipynb @@ -253,7 +253,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 4cb1d74fa9d..f2d614492eb 100644 --- a/docs/guides/simulate-with-qiskit-aer.ipynb +++ b/docs/guides/simulate-with-qiskit-aer.ipynb @@ -135,7 +135,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 bbd27c89d74..a8e2fd7c203 100644 --- a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb +++ b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb @@ -49,7 +49,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", @@ -518,7 +518,7 @@ "id": "1c0e76fe-4b5d-4fd4-9eec-da5332d76cfb", "metadata": {}, "source": [ - "For a full example, see the [Sampler 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/synthesize-unitary-operators.ipynb b/docs/guides/synthesize-unitary-operators.ipynb index ac00125ba15..b2f8bd6c5fa 100644 --- a/docs/guides/synthesize-unitary-operators.ipynb +++ b/docs/guides/synthesize-unitary-operators.ipynb @@ -186,7 +186,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 84c467dd30f..e36ac53a3c4 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 @@ -43,9 +43,9 @@ Benchmarking is important for comparing the relative performance of quantum soft ## Qiskit Runtime -Qiskit Runtime is a 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 the Qiskit primitives for IBM Quantum hardware. To get started with Qiskit Runtime primitives, visit the [documentation](./primitives). +Qiskit Runtime is a 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 the Qiskit primitives for IBM Quantum hardware. To get started with Qiskit Runtime 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](./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/configure-error-mitigation) 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. @@ -55,7 +55,7 @@ To quickly install Qiskit Runtime, run the following command: pip install qiskit-ibm-runtime ``` -More details on setting up a development environment for building quantum programs can be found in the [installation page](./install-qiskit). +More details on setting up a development environment for building quantum programs can be found in the [installation page](/docs/guides/install-qiskit). ### Is Qiskit Runtime open-source? The short answer is, _not all of it_. The Qiskit Runtime service software that handles the technicalities of running your quantum program on an IBM Quantum device (including any error mitigation and suppression) is **not** open-source. However, the Qiskit Runtime client (the interface for users to access the Qiskit Runtime service), the Qiskit SDK running on the server side, and some of the software used for error mitigation, **are** open-source. To get involved with the Qiskit open-source efforts, visit our GitHub organization at [github.com/Qiskit](https://github.com/Qiskit) and [github.com/Qiskit-Extensions](https://github.com/Qiskit-Extensions/). @@ -89,7 +89,7 @@ pip install qiskit-ibm-catalog ``` ## Qiskit Transpiler Service -The Qiskit Transpiler Service ([package name `qiskit-ibm-transpiler`](https://pypi.org/project/qiskit-ibm-transpiler/)) is a new experimental service that provides remote transpilation capabilities on the cloud to IBM Quantum Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. In addition to the local Qiskit SDK transpiler capabilities, your transpilation tasks can benefit from both IBM Quantum cloud resources and AI-powered transpiler passes using this service. To learn more about how to integrate cloud-based transpilation into your Qiskit workflow you can [check out the documentation](./qiskit-transpiler-service). +The Qiskit Transpiler Service ([package name `qiskit-ibm-transpiler`](https://pypi.org/project/qiskit-ibm-transpiler/)) is a new experimental service that provides remote transpilation capabilities on the cloud to IBM Quantum Premium Plan, Flex Plan, and On-Prem (via IBM Quantum Platform API) Plan users. In addition to the local Qiskit SDK transpiler capabilities, your transpilation tasks can benefit from both IBM Quantum cloud resources and AI-powered transpiler passes using this service. To learn more about how to integrate cloud-based transpilation into your Qiskit workflow you can [check out the documentation](/docs/guides/qiskit-transpiler-service). The transpiler service can be installed with pip: ```bash diff --git a/docs/guides/transpiler-plugins.ipynb b/docs/guides/transpiler-plugins.ipynb index b52601b8f89..259c96632cd 100644 --- a/docs/guides/transpiler-plugins.ipynb +++ b/docs/guides/transpiler-plugins.ipynb @@ -422,7 +422,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 62a8e0f4c70..d9afbeb9872 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.avif \"Qubit mapping\")\n", @@ -239,7 +239,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 0ada4486afb..c10e525f3f7 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/view-cost.mdx b/docs/guides/view-cost.mdx index 038ba1a39bd..e379f15fb39 100644 --- a/docs/guides/view-cost.mdx +++ b/docs/guides/view-cost.mdx @@ -26,5 +26,5 @@ To determine how much usage a specific workload incurred, open the [Workloads pa ## Next steps - - To learn how to limit costs, see [Manage costs.](./manage-cost) + - To learn how to limit costs, see [Manage costs.](/docs/guides/manage-cost) \ No newline at end of file From 5a9020ee5a34699ab9508cffb8ccf3d5b9dcb51a Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 24 Feb 2026 14:32:11 -0600 Subject: [PATCH 098/118] Move stuff around --- docs/guides/_toc.json | 279 +++++++++++++++++++----------------------- 1 file changed, 127 insertions(+), 152 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 196ca7846ab..c1c69ce87ff 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -215,133 +215,6 @@ } ] }, - { - "title": "Execute with primitives", - "children": [ - { - "title": "Introduction to primitives", - "url": "/docs/guides/primitives" - }, { - "title": "Introduction to options", - "url": "/docs/guides/runtime-options-overview" - }, - { - "title": "Introduction to PUBs", - "url": "/docs/guides/pubs" - }, - { - "title": "Introduction to broadcasting", - "url": "/docs/guides/broadcasting" - }, - { - "title": "Estimator", - "children": [ - { - "title": "Get started", - "url": "/docs/guides/get-started-with-estimator" - }, - { - "title": "Inputs and outputs", - "url": "/docs/guides/estimator-input-output" - }, - { - "title": "Broadcasting", - "url": "/docs/guides/estimator-broadcasting" - }, - { - "title": "Options", - "url": "/docs/guides/estimator-options" - }, - { - "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": "Examples", - "url": "/docs/guides/sampler-examples" - }, - { - "title": "REST API", - "url": "/docs/guides/sampler-rest-api" - } - ] - }, - { - "title": "Executor", - "children": [ - { - "title": "Get started", - "url": "/docs/guides/get-started-with-executor" - }, - { - "title": "Inputs and outputs", - "url": "/docs/guides/executor-input-output" - }, - { - "title": "Broadcasting", - "url": "/docs/guides/executor-broadcasting" - }, - { - "title": "Options", - "url": "/docs/guides/executor-options" - }, - { - "title": "Examples", - "url": "/docs/guides/executor-examples" - } ] - }, - { - "title": "Manage noise", - "children": [ - { - "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": "Directed execution model (beta)", - "url": "/docs/guides/directed-execution-model" - }, - { - "title": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - } - ] - }, { "title": "Debugging", "children": [ @@ -470,31 +343,133 @@ "title": "Run your first circuit on hardware", "url": "/docs/guides/hello-world" }, - { - "title": "Execute with primitives", - "children": [ - { - "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": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - } - ] - }, + { + "title": "Execute with primitives", + "children": [ + { + "title": "Introduction to primitives", + "url": "/docs/guides/primitives" + }, { + "title": "Introduction to options", + "url": "/docs/guides/runtime-options-overview" + }, + { + "title": "Introduction to PUBs", + "url": "/docs/guides/pubs" + }, + { + "title": "Introduction to broadcasting", + "url": "/docs/guides/broadcasting" + }, + { + "title": "Estimator", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-estimator" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/estimator-input-output" + }, + { + "title": "Broadcasting", + "url": "/docs/guides/estimator-broadcasting" + }, + { + "title": "Options", + "url": "/docs/guides/estimator-options" + }, + { + "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": "Examples", + "url": "/docs/guides/sampler-examples" + }, + { + "title": "REST API", + "url": "/docs/guides/sampler-rest-api" + } + ] + }, + { + "title": "Executor", + "children": [ + { + "title": "Get started", + "url": "/docs/guides/get-started-with-executor" + }, + { + "title": "Inputs and outputs", + "url": "/docs/guides/executor-input-output" + }, + { + "title": "Broadcasting", + "url": "/docs/guides/executor-broadcasting" + }, + { + "title": "Options", + "url": "/docs/guides/executor-options" + }, + { + "title": "Examples", + "url": "/docs/guides/executor-examples" + } ] + }, + { + "title": "Manage noise", + "children": [ + { + "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": "Directed execution model (beta)", + "url": "/docs/guides/directed-execution-model" + }, + { + "title": "Qiskit Runtime local testing mode", + "url": "/docs/guides/local-testing-mode" + } + ] + }, { "title": "IBM quantum computers", "children": [ From 72957ee845eb4d264254b1df1dba148fe9108500 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 24 Feb 2026 14:49:16 -0600 Subject: [PATCH 099/118] Apply suggestions from code review Co-authored-by: abbycross --- docs/guides/estimator-examples.ipynb | 2 +- docs/guides/estimator-input-output.ipynb | 8 ++++---- docs/guides/estimator-options.ipynb | 6 +++--- docs/guides/estimator-rest-api.ipynb | 4 ++-- docs/guides/execution-modes-rest-api.ipynb | 6 +++--- docs/guides/get-started-with-sampler.ipynb | 4 ++-- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/guides/estimator-examples.ipynb b/docs/guides/estimator-examples.ipynb index 9b6564804c1..73e2a19967b 100644 --- a/docs/guides/estimator-examples.ipynb +++ b/docs/guides/estimator-examples.ipynb @@ -382,7 +382,7 @@ "\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", + " - 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", diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index b63e49df562..0f59f632e29 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -7,7 +7,7 @@ "source": [ "---\n", "title: Inputs and outputs\n", - "description: Understand the Estimator input and output format of Estimator primitives\n", + "description: Understand the input and output format of the Estimator primitive\n", "---\n", "\n", "\n", @@ -162,7 +162,7 @@ "source": [ "## Output\n", "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator.\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of Estimator.\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 `PubResults`, one corresponding to each PUB).\n", "\n", @@ -300,9 +300,9 @@ "id": "389bd235-c6c7-4dc0-87c5-272b85cfaae0", "metadata": {}, "source": [ - "#### How the Estimator calculates error\n", + "#### 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`), 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", + "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", diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index ad0f55c59c4..90131ea2ed8 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -441,9 +441,9 @@ "## 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 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", + " - Find more details about the `EstimatorV2` methods in the [Estimator API reference](/docs/api/qiskit-ibm-runtime/estimator-v2).\n", + " - Find details about how to configure [error suppression](configure-error-suppression) and [error mitigation](/docs/guides/configure-error-mitigation).\n", + " - Decide what [execution mode](/docs/guides/execution-modes) to run your job in.\n", "" ] } diff --git a/docs/guides/estimator-rest-api.ipynb b/docs/guides/estimator-rest-api.ipynb index 8c11be71250..58e60e8be16 100644 --- a/docs/guides/estimator-rest-api.ipynb +++ b/docs/guides/estimator-rest-api.ipynb @@ -49,7 +49,7 @@ "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", + "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", @@ -439,7 +439,7 @@ "\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", + " - 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/execution-modes-rest-api.ipynb b/docs/guides/execution-modes-rest-api.ipynb index 10a39c2fa9a..25298e64869 100644 --- a/docs/guides/execution-modes-rest-api.ipynb +++ b/docs/guides/execution-modes-rest-api.ipynb @@ -55,7 +55,7 @@ "\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](estimator-rest-api) and [Sampler](sampler-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", @@ -296,8 +296,8 @@ "## Next steps\n", "\n", "\n", - " - Review detailed [Sampler](sampler-rest-api) primitives examples using REST API.\n", - " - Review detailed [Estimator](estimator-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](/docs/guides/transpile) section.\n", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index bb6439b4c7c..6176cd7358a 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -25,7 +25,7 @@ "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", + "\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", @@ -75,7 +75,7 @@ "\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." + "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." ] }, { From 1a0fce30a84c09213f404bcb4d19f1d55ddca1d3 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 24 Feb 2026 14:52:31 -0600 Subject: [PATCH 100/118] merge conflicts --- docs/guides/get-started-with-estimator.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index a750cf00e09..57e869e729a 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -78,7 +78,7 @@ "\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." + "Follow the steps in the [Set up your IBM Cloud account](cloud-setup) if you don't already have an account." ] }, { From 745a26c27190d16883bfa7a67c8b54bac7d15efa Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 26 Feb 2026 09:56:55 -0600 Subject: [PATCH 101/118] links --- docs/guides/compute-services.mdx | 2 +- docs/guides/configure-error-suppression.ipynb | 2 +- docs/guides/primitives.ipynb | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/compute-services.mdx b/docs/guides/compute-services.mdx index 612eeb06bc0..38b565f8e34 100644 --- a/docs/guides/compute-services.mdx +++ b/docs/guides/compute-services.mdx @@ -8,7 +8,7 @@ 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. diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index 04cb8b134bf..ae91b951a0a 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -61,7 +61,7 @@ "\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", + "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](estimator-options#no-error-mitigation) section.\n", "\n", "\n", "## Advanced error suppression options\n", diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 0b0947538bb..2f07a5305b5 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -282,7 +282,7 @@ "\n", "- A **program** is a list of program items, where each item is either a circuit item or a samplex item.\n", "- A **samplex item** is a pair that consists of a template circuit and a samplex pair.\n", - "- **Samplex** is the core type of the [Samplomatic library.](/docs/guides/directed-execution-model#samplex)" + "- **Samplex** is the core type of the [Samplomatic library.](/docs/guides/directed-execution-model#samplomatic)" ] }, { From d07207ecd42d63b7a102dd1cbb3393f8fdbddbe3 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 26 Feb 2026 10:22:16 -0600 Subject: [PATCH 102/118] squeaky clean --- docs/guides/estimator-options.ipynb | 1 + docs/guides/primitives.ipynb | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 90131ea2ed8..9bb939f9fce 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "id": "7acdb263-fde4-4ff3-a13d-c499a2ba77e4", "metadata": {}, "source": [ "---\n", diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 2f07a5305b5..02248bb6d1f 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -276,7 +276,7 @@ "\n", "### Executor (beta)\n", "\n", - "The Executor Qiskit Runtime primitive takes a _program_ 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. \n", + "The Executor Qiskit Runtime primitive takes a _program_ 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.\n", "\n", "The Executor primitive is part of the [directed execution model,](/docs/guides/directed-execution-model) which introduces some new terminology:\n", "\n", From 51dcbfcb43066d45c850d034653bff2bcd7481ba Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 26 Feb 2026 11:32:37 -0600 Subject: [PATCH 103/118] Marry pubs and broadcasting topics --- docs/guides/_toc.json | 8 +- docs/guides/algorithmiq-tem.ipynb | 2 +- docs/guides/broadcasting.mdx | 43 --------- docs/guides/estimator-broadcasting.mdx | 8 +- docs/guides/estimator-input-output.ipynb | 2 +- docs/guides/executor-broadcasting.mdx | 4 +- docs/guides/executor-examples.mdx | 2 +- docs/guides/get-started-with-estimator.ipynb | 2 +- docs/guides/get-started-with-sampler.ipynb | 2 +- docs/guides/ibm-circuit-function.ipynb | 4 +- docs/guides/monitor-job.ipynb | 2 +- docs/guides/primitives.ipynb | 8 +- docs/guides/pubs.ipynb | 93 ------------------- docs/guides/pubs_broadcasting.mdx | 62 +++++++++++++ .../q-ctrl-performance-management.ipynb | 4 +- docs/guides/qedma-qesem.ipynb | 2 +- docs/guides/sampler-input-output.ipynb | 2 +- docs/guides/v2-primitives.mdx | 2 +- .../vqe.ipynb | 2 +- .../exploring-uncertainty-with-qiskit.ipynb | 2 +- qiskit_bot.yaml | 8 +- scripts/config/notebook-testing.toml | 1 - 22 files changed, 90 insertions(+), 175 deletions(-) delete mode 100644 docs/guides/broadcasting.mdx delete mode 100644 docs/guides/pubs.ipynb create mode 100644 docs/guides/pubs_broadcasting.mdx diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index da3ca234a19..59abb4e4df7 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -507,12 +507,8 @@ "url": "/docs/guides/runtime-options-overview" }, { - "title": "Introduction to PUBs", - "url": "/docs/guides/pubs" - }, - { - "title": "Introduction to broadcasting", - "url": "/docs/guides/broadcasting" + "title": "Introduction to PUBs and broadcasting", + "url": "/docs/guides/pubs_broadcasting" }, { "title": "Estimator", diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index 7114396eda2..4f62cd804d6 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -298,7 +298,7 @@ "\n", "Name | Type | Description | Required | Default | Example\n", "-- | -- | -- | -- | -- | --\n", - "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", + "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs_broadcasting#pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", "\n", diff --git a/docs/guides/broadcasting.mdx b/docs/guides/broadcasting.mdx deleted file mode 100644 index 6ba9cab57ff..00000000000 --- a/docs/guides/broadcasting.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Broadcasting -description: Understand how primitives handle array inputs and outputs using broadcasting semantics - ---- - -# Primitive broadcasting - -The primitives 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). - -## Rules - -* Input arrays do not need to have the same number of dimensions. - * The resulting array will have the same number of dimensions as the input array with the largest dimension. - * The size of each dimension is the largest size of the corresponding dimension. - * Missing dimensions are assumed to have size one. -* Shape comparisons start with the rightmost dimension and continue to the left. -* Two dimensions are compatible if their sizes are equal or if one of them is one. - -Examples of array pairs that broadcast: - -```text -A1 (1d array): 1 -A2 (2d array): 3 x 5 -Result (2d array): 3 x 5 - - -A1 (3d array): 11 x 2 x 7 -A2 (3d array): 11 x 1 x 7 -Result (3d array): 11 x 2 x 7 -``` - -Examples of array pairs that do not broadcast: - -```text -A1 (1d array): 5 -A2 (1d array): 3 - -A1 (2d array): 2 x 1 -A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5. -``` - -The primitives return one value for each element of the broadcasted shape. \ No newline at end of file diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index fa54b322cbe..5888987f5fd 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -5,7 +5,7 @@ description: How the Estimator handles array inputs and outputs using broadcasti --- # Estimator broadcasting semantics -When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics. +When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs_broadcasting#pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics. Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: @@ -20,7 +20,7 @@ Parameter value sets are represented by `n x m` arrays, and observable arrays ar - *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. -![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs/broadcasting.avif "Visual representation of broadcasting") +![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs_broadcasting#pubs/broadcasting.avif "Visual representation of broadcasting") ```python # Broadcast single observable @@ -87,7 +87,7 @@ list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] ## Next steps - - See the [broadcasting guide](/docs/guides/broadcasting) for an overview of broadcasting. - - Learn about [PUBs.](/docs/guides/pubs) + - See the [broadcasting guide](/docs/guides/pubs_broadcasting#broadcasting) for an overview of broadcasting. + - Learn about [PUBs.](/docs/guides/pubs_broadcasting#pubs) - Understand [Estimator inputs and outputs.](/docs/guides/estimator-input-output) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 0f59f632e29..24a12d564ae 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." ] }, { diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index 7146e7b5808..bad6272df0d 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -6,7 +6,7 @@ description: How the Executor handles array inputs and outputs using broadcastin {/* cspell:ignore broadcastable */} # Executor broadcasting semantics -The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine +The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine multiple experimental configurations, and interpret the shape of returned data. ## Quick start example @@ -280,6 +280,6 @@ To sweep one parameter while holding others fixed: ## Next steps - - Review the [broadcasting](/docs/guides/broadcasting) overview. + - Review the [broadcasting](/docs/guides/pubs_broadcasting#broadcasting) overview. - Understand [Executor inputs and outputs.](/docs/guides/executor-input-output) diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index 0d4082e654d..27abfa8f39a 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -108,6 +108,6 @@ result = job.result() ## Next steps - - Review the [broadcasting](/docs/guides/broadcasting) overview. + - Review the [broadcasting](/docs/guides/pubs_broadcasting#broadcasting) overview. - Learn how to use [Executor options.](/docs/guides/executor-options) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 57e869e729a..d71c25f1364 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -314,7 +314,7 @@ "### Similarities and differences between backend and Runtime primitives\n", "\n", "- The inputs to and outputs from [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2)\n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) for details.\n", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs_broadcasting#pubs) 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", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index 6176cd7358a..431aaefb82f 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -267,7 +267,7 @@ "### 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)\n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs) for details.\n", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs_broadcasting#pubs) for details.\n", "However, there can be differences in the fields of the returned metadata.\n", "\n", "- The [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) class requires a backend that supports the `memory` option.\n", diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index 32d32cdc1cb..c01c50acea4 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -35,7 +35,7 @@ "\n", "## Overview\n", "\n", - "The IBM® Circuit function takes [abstract PUBs](/docs/guides/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." + "The IBM® Circuit function takes [abstract PUBs](/docs/guides/pubs_broadcasting#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." ] }, { @@ -206,7 +206,7 @@ "| Name | Type | Description | Required | Default | Example |\n", "|-----------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------|------------------------------------------|\n", "| backend_name | str | Name of the backend to make the query. | Yes | N/A | `ibm_fez` |\n", - "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", + "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/pubs_broadcasting#pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", "| options | dict | Input options. See the **Options** section for more details. | No | See the **Options** section for details. | `{\"optimization_level\": 3}` |\n", "| instance | str | The cloud resource name of the instance to use in that format. | No | One is randomly picked if your account has access to multiple instances. | `CRN` |" ] diff --git a/docs/guides/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index b3a45d4686b..8ca0df19e39 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -226,7 +226,7 @@ "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/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", + "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/pubs_broadcasting#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", "Example:" ] diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 02248bb6d1f..7c8f9d1fd5f 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -138,7 +138,7 @@ "\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/pubs) Each PUB is in the format:\n", + "The input is an array of [PUBs.](/docs/guides/pubs_broadcasting#pubs) Each PUB is in the format:\n", "\n", "(``, ``, ``, ``),\n", "\n", @@ -146,7 +146,7 @@ "\n", "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) that contains the computed expectation values per pair, and their standard errors, in `PubResult` form. Each `PubResult` contains both data and metadata.\n", "\n", - "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/docs/guides/broadcasting) topic.\n", + "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/docs/guides/pubs_broadcasting#broadcasting) topic.\n", "\n", "Example:" ] @@ -225,13 +225,13 @@ "\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/pubs) in the format:\n", + "The input is one or more [PUBs,](/docs/guides/pubs_broadcasting#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 broadcasting](/docs/guides/broadcasting) for full details.\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 broadcasting](/docs/guides/pubs_broadcasting#broadcasting) for full details.\n", "\n", "Example:" ] diff --git a/docs/guides/pubs.ipynb b/docs/guides/pubs.ipynb deleted file mode 100644 index 9a4e2d85c9b..00000000000 --- a/docs/guides/pubs.ipynb +++ /dev/null @@ -1,93 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "dbb193c8-d927-434c-a199-48de57c99694", - "metadata": {}, - "source": [ - "---\n", - "title: Introduction to PUBs\n", - "description: Understand what Primitive Unified Blocs are, and how to use them as input to Sampler and Estimator primitives.\n", - "---\n", - "\n", - "\n", - "# Introduction to PUBs" - ] - }, - { - "cell_type": "markdown", - "id": "13bdfd0b-b5df-4dc8-9de5-f4ee382bc1d4", - "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": "61903cfe-d221-4137-8324-9f0d3c1b517d", - "metadata": {}, - "source": [ - "The Estimator and Sampler primitives help you efficiently define vectorized workloads by using a data structure known as a _Primitive Unified Bloc (PUB)_. These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the `run()` method for the primitives, which execute 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 Sampler or Estimator primitives.\n", - "\n", - "When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/broadcasting)" - ] - }, - { - "cell_type": "markdown", - "id": "9d2e7be3-082c-4a8a-b29b-54349fa5fba9", - "metadata": {}, - "source": [ - "## Next Steps\n", - "\n", - "\n", - "- Learn about [Estimator input and output](/docs/guides/estimator-input-output) in depth.\n", - "- Learn about [Sampler input and output](/docs/guides/sampler-input-output) in depth.\n", - "- Learn about [broadcasting.](/docs/guides/broadcasting)\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/pubs_broadcasting.mdx b/docs/guides/pubs_broadcasting.mdx new file mode 100644 index 00000000000..570ac0561ff --- /dev/null +++ b/docs/guides/pubs_broadcasting.mdx @@ -0,0 +1,62 @@ +--- +title: PUBs and broadcasting +description: Understand what PUBs are and how primitives handle array inputs and outputs using broadcasting semantics + +--- + +# Introduction to PUBs and broadcasting + + +## Introduction to PUBs + +The Estimator and Sampler primitives help you efficiently define vectorized workloads by using a data structure known as a _Primitive Unified Bloc (PUB)_. (Executor does not use PUBs.) These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the `run()` method for the primitives, which execute 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 Sampler or Estimator primitives. + +When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) + + +## Primitive broadcasting + +The Estimator and Executor primitives aggregate elements from multiple arrays (observables and parameter values) by following the same broadcasting rules as NumPy. (Sampler does not use broadcasting.) 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). + + +### Rules + +* Input arrays do not need to have the same number of dimensions. + * The resulting array will have the same number of dimensions as the input array with the largest dimension. + * The size of each dimension is the largest size of the corresponding dimension. + * Missing dimensions are assumed to have size one. +* Shape comparisons start with the rightmost dimension and continue to the left. +* Two dimensions are compatible if their sizes are equal or if one of them is one. + +Examples of array pairs that broadcast: + +```text +A1 (1d array): 1 +A2 (2d array): 3 x 5 +Result (2d array): 3 x 5 + + +A1 (3d array): 11 x 2 x 7 +A2 (3d array): 11 x 1 x 7 +Result (3d array): 11 x 2 x 7 +``` + +Examples of array pairs that do not broadcast: + +```text +A1 (1d array): 5 +A2 (1d array): 3 + +A1 (2d array): 2 x 1 +A2 (3d array): 6 x 5 x 4 # This would work if the middle dimension were 2, but it is 5. +``` + +The primitives return one value for each element of the broadcasted shape. + +## Next Steps + + +- Learn about [Estimator input and output](/docs/guides/estimator-input-output) in depth. +- Learn about [Sampler input and output](/docs/guides/sampler-input-output) in depth. +- Learn about [Executor input and output](/docs/guides/executor-input-output) in depth. + \ No newline at end of file diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 60cf04c7cdd..062e558161e 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -89,7 +89,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/pubs)." + "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/pubs_broadcasting#pubs)." ] }, { @@ -384,7 +384,7 @@ "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/estimator-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", - "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](/docs/guides/broadcasting) as the `QiskitRuntime` primitives.\n", + "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](/docs/guides/pubs_broadcasting#broadcasting) as the `QiskitRuntime` primitives.\n", "- (Optional) A target precision for expectation values to estimate.\n", "- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": }`.\n", "\n", diff --git a/docs/guides/qedma-qesem.ipynb b/docs/guides/qedma-qesem.ipynb index 2c383d2aed4..b1ef513921f 100644 --- a/docs/guides/qedma-qesem.ipynb +++ b/docs/guides/qedma-qesem.ipynb @@ -244,7 +244,7 @@ "\n", "| Name | Type | Description | Required | Default | Example |\n", "| -----| ------| ------------| -------- | ------- | -------- |\n", - "| `pubs` | [EstimatorPubLike](/docs/guides/pubs) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", + "| `pubs` | [EstimatorPubLike](/docs/guides/pubs_broadcasting#pubs) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", "| `backend_name`| string|Name of the backend to use |No | QESEM will get least busy device reported by IBM| `\"ibm_fez\"`|\n", "| `instance` | string| The cloud resource name of the instance to use in that format | No | N/A | `“CRN”` |\n", "| `options` | dictionary |Input options. See **Options** section for more details. | No | See the **Options** section for details. | `{ default_precision = 0.03, \"max_execution_time\" = 3600, \"transpilation_level\" = 0}` |\n", diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 3edc4348e15..39529e38fd8 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." + "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." ] }, { diff --git a/docs/guides/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index f2d2a804c47..4831c9b420e 100644 --- a/docs/guides/v2-primitives.mdx +++ b/docs/guides/v2-primitives.mdx @@ -1207,6 +1207,6 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}") - Learn more about setting options in the [Sampler options,](/docs/guides/sampler-options) [Estimator options,](/docs/guides/estimator-options) and [Executor options](/docs/guides/executor-options) guides. - - Learn more details about [Primitive inputs and outputs.](/docs/guides/pubs) + - Learn more details about [Primitive inputs and outputs.](/docs/guides/pubs_broadcasting#pubs) - Experiment with the [CHSH Inequality](/docs/tutorials/chsh-inequality) tutorial. diff --git a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb index bd6140e7a42..97a20e738c9 100644 --- a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb +++ b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb @@ -354,7 +354,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/pubs) 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/pubs_broadcasting#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", diff --git a/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb b/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb index a2c2f9f0844..2b448cbd917 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/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/pubs_broadcasting#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/qiskit_bot.yaml b/qiskit_bot.yaml index 01f805ca294..4e4831325dc 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -175,7 +175,7 @@ notifications: - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/pubs": + "docs/guides/pubs_broadcasting": - "@abbycross" - "@beckykd" - "@jyu00" @@ -446,12 +446,6 @@ notifications: - "@pacomf" - "@Bagherpoor" - "@kaelynj" - "docs/guides/broadcasting": - - "@born-2learn" - - "@HuangJunye" - - "@pacomf" - - "@Bagherpoor" - - "@kaelynj" "docs/guides/sampler-rest-api": - "@born-2learn" - "@HuangJunye" diff --git a/scripts/config/notebook-testing.toml b/scripts/config/notebook-testing.toml index 08664ad6f7f..0b9e8b6a591 100644 --- a/scripts/config/notebook-testing.toml +++ b/scripts/config/notebook-testing.toml @@ -43,7 +43,6 @@ notebooks = [ "docs/guides/estimator-examples.ipynb", "docs/guides/sampler-examples.ipynb", "docs/guides/estimator-input-output.ipynb", - "docs/guides/pubs.ipynb", "docs/guides/estimator-options.ipynb", "docs/guides/get-started-with-estimator.ipynb", "docs/guides/quick-start.ipynb", From 23d6da9e2ff5c4bc7c9d343062cf5905980a4ce9 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 26 Feb 2026 13:23:50 -0600 Subject: [PATCH 104/118] Update _toc.json --- docs/guides/_toc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 59abb4e4df7..12e2b71d0b1 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -507,7 +507,7 @@ "url": "/docs/guides/runtime-options-overview" }, { - "title": "Introduction to PUBs and broadcasting", + "title": "PUBs and broadcasting", "url": "/docs/guides/pubs_broadcasting" }, { From daae80df60d574bb1ad18aa0049805eedc8c9fab Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 26 Feb 2026 17:00:16 -0600 Subject: [PATCH 105/118] Clean up the options overview --- docs/guides/estimator-options.ipynb | 657 +++++++++++++++ docs/guides/runtime-options-overview.mdx | 969 +---------------------- docs/guides/sampler-options.ipynb | 358 ++++++++- 3 files changed, 1015 insertions(+), 969 deletions(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 9bb939f9fce..b22aad18afd 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -101,6 +101,20 @@ "estimator = Estimator(mode=backend, options=options)" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Options classes summary\n", + "\n", + " - [Dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options): Options for dynamical decoupling.\n", + " - [Environment](/docs/api/qiskit-ibm-runtime/options-environment-options): Execution environment options, such as the logging level to set and job tags to add.\n", + " - [Execution](/docs/api/qiskit-ibm-runtime/options-execution-options-v2): Primitive execution options, including whether to initialize qubits and the repetition delay.\n", + " - [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.\n", + " - [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.\n", + " - [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.\n" + ] + }, { "cell_type": "markdown", "id": "ba2f5146-2781-49da-9fa2-8a22647225d0", @@ -434,6 +448,649 @@ "options.resilience_level = 0" ] }, + { + "cell_type": "markdown", + "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", + "### `default_shots`\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", + "### `default_precision`\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", + "### `dynamical_decoupling`\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", + "#### `dynamical_decoupling.enable`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.extra_slack_distribution`\n", + "\n", + "\n", + "**Choices**: `middle`, `edges`\n", + "\n", + "**Default**: `middle`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.scheduling_method`\n", + "\n", + "\n", + "Choices: `asap`, `alap`\n", + "Default: `alap`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.sequence_type`\n", + "\n", + "\n", + "Choices: `XX`, `XpXm`, `XY4`\n", + "Default: `XX`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.skip_reset_qubits`\n", + "\n", + "\n", + "Choices: `True`, `False`\n", + "Default: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `environment`\n", + "\n", + "\n", + "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment)\n", + "
\n", + "\n", + "#### `environment.callback`\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", + "#### `environment.job_tags`\n", + "\n", + "\n", + "List of tags.\n", + "\n", + "**Choices**: None\n", + "\n", + "**Default**: None\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `environment.log_level`\n", + "\n", + "\n", + "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", + "\n", + "**Default**: WARNING\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `environment.private`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `execution`\n", + "\n", + "\n", + "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution)\n", + "
\n", + "\n", + "#### `execution.init_qubits`\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", + "#### `execution.rep_delay`\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", + "### `max_execution_time`\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-estimator-options#max_execution_time)\n", + "
\n", + "\n", + "
\n", + "\n", + "### `resilience`\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", + "#### `resilience.layer_noise_learning`\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", + "##### `resilience.layer_noise_learning.layer_pair_depths`\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", + "##### `resilience.layer_noise_learning.max_layers_to_learn`\n", + "\n", + "\n", + "**Choices**: None, Integer >= 1\n", + "\n", + "**Default**: `4`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.layer_noise_learning.num_randomizations`\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `32`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.layer_noise_learning.shots_per_randomization`\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `128`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.layer_noise_model`\n", + "\n", + "\n", + "**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]`\n", + "\n", + "**Default**: None\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.measure_mitigation`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `True`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.measure_noise_learning`\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", + "##### `resilience.measure_noise_learning.num_randomizations`\n", + "\n", + "\n", + "**Choices**: Integer >= 1\n", + "\n", + "**Default**: `32`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.measure_noise_learning.shots_per_randomization`\n", + "\n", + "\n", + "**Choices**: Integer, `auto`\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.pec_mitigation`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.pec`\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", + "##### `resilience.pec.max_overhead`\n", + "\n", + "\n", + "**Choices**: `None`, Integer >= 1\n", + "\n", + "\n", + "**Default**: `100`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.pec.noise_gain`\n", + "\n", + "\n", + "**Choices**: `auto`, float in the range [0, 1]\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.zne_mitigation`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `resilience.zne`\n", + "\n", + "\n", + "[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options)\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.zne.amplifier`\n", + "\n", + "\n", + "**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea`\n", + "\n", + "**Default**: `gate_folding`\n", + "\n", + "
\n", + "
\n", + "\n", + "##### `resilience.zne.extrapolated_noise_factors`\n", + "\n", + "\n", + "**Choices**: List of floats\n", + "\n", + "**Default**: `[0, *noise_factors]`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "##### `resilience.zne.extrapolator`\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", + "##### `resilience.zne.noise_factors`\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", + "### `resilience_level`\n", + "\n", + "\n", + "How much resilience to build against errors. Higher levels generate more accurate results at the expense of longer processing times.\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", + "### `seed_estimator`\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", + "### `simulator`\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", + "#### `simulator.basis_gates`\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", + "#### `simulator.coupling_map`\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", + "#### `simulator.noise_model`\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", + "#### `simulator.seed_simulator`\n", + "\n", + "\n", + "**Choices**: Integer\n", + "\n", + "**Default**: None\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `twirling`\n", + "\n", + "\n", + "Twirling options\n", + "\n", + "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", + "
\n", + "\n", + "#### `twirling.enable_gates`\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: False\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.enable_measure`\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: True\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.num_randomizations`\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.shots_per_randomization`\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.strategy`\n", + "\n", + "\n", + "**Choices**: `active`, `active-circuit`, `active-accum`, `all`\n", + "\n", + "**Default**: `active-accum`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `experimental`\n", + "\n", + "\n", + "Experimental options, when available.\n", + "\n", + "
\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "## Feature compatibility\n", + "\n", + "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:\n", + "\n", + "\n", + " \n", + " Incompatible with:\n", + " - Gate-folding ZNE\n", + " - PEA\n", + " - PEC\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", + " - PEA\n", + " - PEC\n", + "\n", + " Compatible with dynamic circuits when using `qiskit-ibm-runtime` v0.42.0 or later.\n", + "\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - Dynamic circuits\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", + " - 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", + " Incompatible with:\n", + " - Dynamic circuits\n", + " - Fractional gates\n", + " - Gate-folding ZNE\n", + " - PEC\n", + " \n", + "\n", + " \n", + " Incompatible with:\n", + " - Dynamic circuits\n", + " - Fractional gates\n", + " - Gate-folding ZNE\n", + " - PEA\n", + " \n", + "\n", + "\n" + ] + }, { "cell_type": "markdown", "id": "9b86001b-718a-4d72-b3b5-4a67eabf0a45", diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 851a800c2ff..791ef058e74 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -26,974 +26,13 @@ The tables in the [Options classes summary](#options-classes) section lists the ## 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 [Estimator options,](/docs/guides/estimator-options) [Sampler options,](/docs/guides/sampler-options) and [Executor options](/docs/guides/executor-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. - - - -
- -### `default_shots` - - -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) -
- -
- -### `default_precision` - - -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) -
- -
- -### `dynamical_decoupling` - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#dynamical_decoupling) -
- -#### `dynamical_decoupling.enable` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- -#### `dynamical_decoupling.extra_slack_distribution` - - -**Choices**: `middle`, `edges` - -**Default**: `middle` -
- -
- -#### `dynamical_decoupling.scheduling_method` - - -Choices: `asap`, `alap` -Default: `alap` -
- -
- -#### `dynamical_decoupling.sequence_type` - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` -
- -
- -#### `dynamical_decoupling.skip_reset_qubits` - - -Choices: `True`, `False` -Default: `False` -
- -
- - -
- -### `environment` - - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment) -
- -#### `environment.callback` - - -Callable function that receives the `Job ID` and `Job result`. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.job_tags` - - -List of tags. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.log_level` - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING -
- -
- -#### `environment.private` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- - -
- -### `execution` - - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution) -
- -#### `execution.init_qubits` - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` -
- -
- -#### `execution.rep_delay` - -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` -
- -
- - -
- -### `max_execution_time` - -**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) -
- -
- -### `resilience` - -Advanced resilience options to fine tune the resilience strategy. - -[`resilience` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience) -
- -#### `resilience.layer_noise_learning` - - -Options for learning layer noise. - -[`resilience.layer_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-layer-noise-learning-options) -
- -
- -##### `resilience.layer_noise_learning.layer_pair_depths` - - -**Choices**: list[int] of 2-10 values in the range [0, 200] - -**Default**: `(0, 1, 2, 4, 16, 32)` - -
- -
- -##### `resilience.layer_noise_learning.max_layers_to_learn` - - -**Choices**: None, Integer >= 1 - -**Default**: `4` - -
- -
- -##### `resilience.layer_noise_learning.num_randomizations` - - -**Choices**: Integer >= 1 - -**Default**: `32` - -
- -
- -##### `resilience.layer_noise_learning.shots_per_randomization` - - -**Choices**: Integer >= 1 - -**Default**: `128` - -
- -
- -#### `resilience.layer_noise_model` - - -**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]` - -**Default**: None - -
- -
- -#### `resilience.measure_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `True` - -
- -
- -#### `resilience.measure_noise_learning` - - -Options for measurement noise learning. - -[`resilience.measure_noise_learning` API documentation](/docs/api/qiskit-ibm-runtime/options-measure-noise-learning-options) -
- -
- -##### `resilience.measure_noise_learning.num_randomizations` - - -**Choices**: Integer >= 1 - -**Default**: `32` - -
- -
- -##### `resilience.measure_noise_learning.shots_per_randomization` - - -**Choices**: Integer, `auto` - -**Default**: `auto` - -
- -
- -#### `resilience.pec_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `False` - -
- -
- -#### `resilience.pec` - - -Probabilistic error cancellation mitigation options. - -[`resilience.pec` API documentation](/docs/api/qiskit-ibm-runtime/options-pec-options) -
- -
- -##### `resilience.pec.max_overhead` - - -**Choices**: `None`, Integer >= 1 - - -**Default**: `100` - -
- -
- -##### `resilience.pec.noise_gain` - - -**Choices**: `auto`, float in the range [0, 1] - -**Default**: `auto` - -
- -
- -#### `resilience.zne_mitigation` - - -**Choices**: `True`, `False` - -**Default**: `False` - -
- -
- -#### `resilience.zne` - - -[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options) -
- -
- -##### `resilience.zne.amplifier` - - -**Choices**: `gate_folding`, `gate_folding_front`, `gate_folding_back`, `pea` - -**Default**: `gate_folding` - -
-
- -##### `resilience.zne.extrapolated_noise_factors` - - -**Choices**: List of floats - -**Default**: `[0, *noise_factors]` - -
- -
- -##### `resilience.zne.extrapolator` - - -**Choices**: One or more of: `exponential`, `linear`, `double_exponential`, `polynomial_degree_(1 <= k <= 7)`, `fallback` - -**Default**: `(exponential, linear)` - -
- -
- -##### `resilience.zne.noise_factors` - - -**Choices**: List of floats; each float >= 1 - -**Default**: `(1, 1.5, 2)` for `PEA`, and `(1, 3, 5)` otherwise - -
- -
- - -
- -### `resilience_level` - - -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) -
- -
- -### `seed_estimator` - - -**Choices**: Integer - -**Default**: None - -[`seed_estimator`](/docs/api/qiskit-ibm-runtime/options-estimator-options#seed_estimator) -
-
- -### `simulator` - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) -
- -#### `simulator.basis_gates` - - -**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) - -
- -
- -#### `simulator.coupling_map` - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - -
- -
- -#### `simulator.noise_model` - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - -
- -
- -#### `simulator.seed_simulator` - - -**Choices**: Integer - -**Default**: None - -
- -
- - -
- -### `twirling` - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) -
- -#### `twirling.enable_gates` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.enable_measure` - - -**Choices**: True, False - -**Default**: True - -
- -
- -#### `twirling.num_randomizations` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.shots_per_randomization` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.strategy` - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - -
- -
- - -
- -### `experimental` - - -Experimental options, when available. - -
- - - - - -
- -### `default_shots` - - -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) -
- -
- -### `dynamical_decoupling` - - -Control dynamical decoupling error mitigation settings. - -[`dynamical_decoupling` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#dynamical_decoupling) -
- -#### `dynamical_decoupling.enable` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- -#### `dynamical_decoupling.extra_slack_distribution` - - -**Choices**: `middle`, `edges` - -**Default**: `middle` -
- -
- -#### `dynamical_decoupling.scheduling_method` - - -Choices: `asap`, `alap` -Default: `alap` -
- -
- -#### `dynamical_decoupling.sequence_type` - - -Choices: `XX`, `XpXm`, `XY4` -Default: `XX` -
- -
- -#### `dynamical_decoupling.skip_reset_qubits` - - -Choices: `True`, `False` -Default: `False` -
- -
- - -
- -### `environment` - -[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment) -
- -#### `environment.job_tags` - - -List of tags. - -**Choices**: None - -**Default**: None -
- -
- -#### `environment.log_level` - - -**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL - -**Default**: WARNING -
- -
- -#### `environment.private` - - -**Choices**: `True`, `False` - -**Default**: `False` -
- -
- - -
- -### `execution` - -[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution) -
- -#### `execution.init_qubits` - -Whether to reset the qubits to the ground state for each shot. - -**Choices**: `True`, `False` - -**Default**: `True` -
- -
- -#### `execution.rep_delay` - -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` -
-
- -#### `execution.meas_type` - - -**Choices**: `classified`, `kerneled`, `avg_kerneled` - -**Default**: `classified` -
- -
- - -
- -### `max_execution_time` - -**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) -
- -
- -### `simulator` - - -Options to pass when simulating a backend - -[`simulator` API documentation](/docs/api/qiskit-ibm-runtime/options-simulator-options) -
- -#### `simulator.basis_gates` - - -**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) - -
- -
- -#### `simulator.coupling_map` - - -**Choices**: List of directed two-qubit interactions - -**Default**: None, which implies no connectivity constraints (full connectivity). - -
- -
- -#### `simulator.noise_model` - - -**Choices**: [Qiskit Aer NoiseModel](/docs/guides/build-noise-models), or its representation - -**Default**: None - -
- -
- -#### `simulator.seed_simulator` - - -**Choices**: Integer - -**Default**: None - -
- -
- - -
- -### `twirling` - - -Twirling options - -[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options) -
- -#### `twirling.enable_gates` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.enable_measure` - - -**Choices**: True, False - -**Default**: False - -
- -
- -#### `twirling.num_randomizations` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.shots_per_randomization` - - -**Choices**: `auto`, Integer >= 1 - -**Default**: `auto` - -
- -
- -#### `twirling.strategy` - - -**Choices**: `active`, `active-circuit`, `active-accum`, `all` - -**Default**: `active-accum` - -
- -
- - -
- -### `experimental` - - -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. 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. ## 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 work with [Estimator options.](/docs/guides/estimator-options) - - Learn how to work with [Sampler options.](/docs/guides/sampler-options) - - Learn how to work with [Executor options.](/docs/guides/executor-options) + - Learn more about [Estimator options.](/docs/guides/estimator-options) + - Learn more about [Sampler options.](/docs/guides/sampler-options) + - Learn more about [Executor options.](/docs/guides/executor-options) diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 5738179fd61..4a7ca081ae6 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -101,6 +101,20 @@ "sampler = Sampler(mode=backend, options=options)" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Options classes summary\n", + "\n", + " - [Dynamical decoupling](/docs/api/qiskit-ibm-runtime/options-dynamical-decoupling-options): Options for dynamical decoupling.\n", + " - [Environment](/docs/api/qiskit-ibm-runtime/options-environment-options): Execution environment options, such as the logging level to set and job tags to add.\n", + " - [Execution](/docs/api/qiskit-ibm-runtime/options-execution-options-v2): Primitive execution options, including whether to initialize qubits and the repetition delay.\n", + " - [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.\n", + " - [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.\n", + "\n" + ] + }, { "cell_type": "markdown", "id": "ba2f5146-2781-49da-9fa2-8a22647225d0", @@ -365,13 +379,349 @@ }, { "cell_type": "markdown", - "id": "eabb08cf-e67c-452a-8aa5-d028baee77e0", "metadata": {}, "source": [ - "\n", - "## Turn off all error mitigation and error suppression\n", + "\n", + "## Available options\n", + "\n", + "The following table documents options from the latest version of `qiskit-ibm-runtime`. To see older option versions, visit the [`qiskit-ibm-runtime` API reference](/docs/api/qiskit-ibm-runtime) and select a previous version.\n", + "\n", + "
\n", + "\n", + "### `default_shots`\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", + "### `dynamical_decoupling`\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", + "#### `dynamical_decoupling.enable`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.extra_slack_distribution`\n", + "\n", + "\n", + "**Choices**: `middle`, `edges`\n", + "\n", + "**Default**: `middle`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.scheduling_method`\n", + "\n", + "\n", + "Choices: `asap`, `alap`\n", + "Default: `alap`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.sequence_type`\n", + "\n", + "\n", + "Choices: `XX`, `XpXm`, `XY4`\n", + "Default: `XX`\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `dynamical_decoupling.skip_reset_qubits`\n", + "\n", + "\n", + "Choices: `True`, `False`\n", + "Default: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `environment`\n", + "\n", + "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment)\n", + "
\n", + "\n", + "#### `environment.job_tags`\n", + "\n", + "\n", + "List of tags.\n", + "\n", + "**Choices**: None\n", + "\n", + "**Default**: None\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `environment.log_level`\n", + "\n", + "\n", + "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", + "\n", + "**Default**: WARNING\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `environment.private`\n", + "\n", + "\n", + "**Choices**: `True`, `False`\n", + "\n", + "**Default**: `False`\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `execution`\n", + "\n", + "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution)\n", + "
\n", + "\n", + "#### `execution.init_qubits`\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", + "#### `execution.rep_delay`\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", + "#### `execution.meas_type`\n", + "\n", + "\n", + "**Choices**: `classified`, `kerneled`, `avg_kerneled`\n", + "\n", + "**Default**: `classified`\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `max_execution_time`\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", + "### `simulator`\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", + "#### `simulator.basis_gates`\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", + "#### `simulator.coupling_map`\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", + "#### `simulator.noise_model`\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", + "#### `simulator.seed_simulator`\n", + "\n", + "\n", + "**Choices**: Integer\n", + "\n", + "**Default**: None\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `twirling`\n", + "\n", + "\n", + "Twirling options\n", + "\n", + "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", + "
\n", + "\n", + "#### `twirling.enable_gates`\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: False\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.enable_measure`\n", + "\n", + "\n", + "**Choices**: True, False\n", + "\n", + "**Default**: False\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.num_randomizations`\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.shots_per_randomization`\n", + "\n", + "\n", + "**Choices**: `auto`, Integer >= 1\n", + "\n", + "**Default**: `auto`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "#### `twirling.strategy`\n", + "\n", + "\n", + "**Choices**: `active`, `active-circuit`, `active-accum`, `all`\n", + "\n", + "**Default**: `active-accum`\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "\n", + "
\n", + "\n", + "### `experimental`\n", + "\n", + "\n", + "Experimental options, when available.\n", + "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "## Feature compatibility\n", + "\n", + "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:\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", - "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 SamplerV2, no changes are necessary because no error mitigation or suppression options are enabled by default." + "\n" ] }, { From dfe2005a9e1a48a97ecead3c4a5259390220da27 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 27 Feb 2026 10:28:15 -0600 Subject: [PATCH 106/118] fix twisties --- docs/guides/estimator-options.ipynb | 458 ++++++++++++---------------- docs/guides/sampler-options.ipynb | 248 +++++++-------- 2 files changed, 306 insertions(+), 400 deletions(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index b22aad18afd..79e9e90d265 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -457,10 +457,8 @@ "\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", - "### `default_shots`\n", - "\n", + "\n", + "\n", "\n", "The total number of shots to use per circuit per configuration.\n", "\n", @@ -469,12 +467,10 @@ "**Default**: None\n", "\n", "[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#default_shots)\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "### `default_precision`\n", - "\n", + "\n", + "\n", "\n", "The default precision to use for any PUB or `run()` call that does not specify one.\n", "\n", @@ -483,389 +479,340 @@ "**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", - "### `dynamical_decoupling`\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", - "#### `dynamical_decoupling.enable`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.extra_slack_distribution`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `middle`, `edges`\n", "\n", "**Default**: `middle`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.scheduling_method`\n", - "\n", + "\n", + "\n", "\n", "Choices: `asap`, `alap`\n", "Default: `alap`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.sequence_type`\n", - "\n", + "\n", + "\n", "\n", "Choices: `XX`, `XpXm`, `XY4`\n", "Default: `XX`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.skip_reset_qubits`\n", - "\n", + "\n", + "\n", "\n", "Choices: `True`, `False`\n", "Default: `False`\n", - "
\n", + " \n", "\n", - "
\n", + "\n", "\n", + " \n", "\n", - "
\n", - "\n", - "### `environment`\n", - "\n", + "\n", + "\n", + "\n", "\n", "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#environment)\n", - "
\n", - "\n", - "#### `environment.callback`\n", - "\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", - "#### `environment.job_tags`\n", - "\n", + "\n", + "\n", "\n", "List of tags.\n", "\n", "**Choices**: None\n", "\n", "**Default**: None\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `environment.log_level`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", "\n", "**Default**: WARNING\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `environment.private`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", - "
\n", + " \n", "\n", - "
\n", + "\n", "\n", + " \n", "\n", - "
\n", - "\n", - "### `execution`\n", - "\n", + "\n", + "\n", + "\n", "\n", "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#execution)\n", - "
\n", - "\n", - "#### `execution.init_qubits`\n", - "\n", + "\n", + "\n", "Whether to reset the qubits to the ground state for each shot.\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `True`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `execution.rep_delay`\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", - "\n", - "### `max_execution_time`\n", - "\n", + "\n", + "\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-estimator-options#max_execution_time)\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "### `resilience`\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", - "#### `resilience.layer_noise_learning`\n", - "\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", - "##### `resilience.layer_noise_learning.layer_pair_depths`\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", - "##### `resilience.layer_noise_learning.max_layers_to_learn`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: None, Integer >= 1\n", "\n", "**Default**: `4`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "##### `resilience.layer_noise_learning.num_randomizations`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: Integer >= 1\n", "\n", "**Default**: `32`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "##### `resilience.layer_noise_learning.shots_per_randomization`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: Integer >= 1\n", "\n", "**Default**: `128`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `resilience.layer_noise_model`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: `NoiseLearnerResult`, `Sequence[LayerError]`\n", "\n", "**Default**: None\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `resilience.measure_mitigation`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `True`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `resilience.measure_noise_learning`\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", - "##### `resilience.measure_noise_learning.num_randomizations`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: Integer >= 1\n", "\n", "**Default**: `32`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "##### `resilience.measure_noise_learning.shots_per_randomization`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: Integer, `auto`\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `resilience.pec_mitigation`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `resilience.pec`\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", - "##### `resilience.pec.max_overhead`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `None`, Integer >= 1\n", "\n", "\n", "**Default**: `100`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "##### `resilience.pec.noise_gain`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `auto`, float in the range [0, 1]\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `resilience.zne_mitigation`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `resilience.zne`\n", - "\n", + "\n", + "\n", "\n", "[`resilience.zne` API documentation](/docs/api/qiskit-ibm-runtime/options-zne-options)\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "##### `resilience.zne.amplifier`\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", - "##### `resilience.zne.extrapolated_noise_factors`\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", - "##### `resilience.zne.extrapolator`\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", - "##### `resilience.zne.noise_factors`\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", - "### `resilience_level`\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.\n", "\n", @@ -874,148 +821,139 @@ "**Default**: `1`\n", "\n", "[`resilience_level` API documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options#resilience_level)\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "### `seed_estimator`\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", - "### `simulator`\n", - "\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", - "#### `simulator.basis_gates`\n", - "\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", - "#### `simulator.coupling_map`\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", - "#### `simulator.noise_model`\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", - "#### `simulator.seed_simulator`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: Integer\n", "\n", "**Default**: None\n", "\n", - "
\n", + " \n", "\n", - "
\n", + "\n", + "\n", + "\n", + " \n", "\n", "\n", - "
\n", - "\n", - "### `twirling`\n", - "\n", + "\n", + "\n", "\n", "Twirling options\n", "\n", "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", - "
\n", - "\n", - "#### `twirling.enable_gates`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: True, False\n", "\n", "**Default**: False\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `twirling.enable_measure`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: True, False\n", "\n", "**Default**: True\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `twirling.num_randomizations`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: `auto`, Integer >= 1\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `twirling.shots_per_randomization`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `auto`, Integer >= 1\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `twirling.strategy`\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`\n", - "\n", + "\n", + "\n", + "\n", "\n", "Experimental options, when available.\n", "\n", - "
\n" + " \n", + "\n", + "\n", + "" ] }, { diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 4a7ca081ae6..8ff9f059e68 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -386,10 +386,9 @@ "\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", - "### `default_shots`\n", - "\n", + "\n", + "\n", + "\n", "\n", "The total number of shots to use per circuit per configuration.\n", "\n", @@ -398,285 +397,254 @@ "**Default**: None\n", "\n", "[`default_shots` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#default_shots)\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "### `dynamical_decoupling`\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", - "#### `dynamical_decoupling.enable`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.extra_slack_distribution`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `middle`, `edges`\n", "\n", "**Default**: `middle`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.scheduling_method`\n", - "\n", + "\n", + "\n", "\n", "Choices: `asap`, `alap`\n", "Default: `alap`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.sequence_type`\n", - "\n", + "\n", + "\n", "\n", "Choices: `XX`, `XpXm`, `XY4`\n", "Default: `XX`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `dynamical_decoupling.skip_reset_qubits`\n", - "\n", + "\n", + "\n", "\n", "Choices: `True`, `False`\n", "Default: `False`\n", - "
\n", + " \n", "\n", - "
\n", + "\n", "\n", + " \n", "\n", - "
\n", - "\n", - "### `environment`\n", - "\n", + "\n", + "\n", + "\n", "[`environment` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#environment)\n", - "
\n", - "\n", - "#### `environment.job_tags`\n", - "\n", + "\n", + "\n", "\n", "List of tags.\n", "\n", "**Choices**: None\n", "\n", "**Default**: None\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `environment.log_level`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: DEBUG, INFO, WARNING, ERROR, CRITICAL\n", "\n", "**Default**: WARNING\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `environment.private`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `False`\n", - "
\n", + " \n", "\n", - "
\n", + "\n", "\n", + " \n", "\n", - "
\n", - "\n", - "### `execution`\n", - "\n", + "\n", + "\n", + "\n", "[`execution` API documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options#execution)\n", - "
\n", - "\n", - "#### `execution.init_qubits`\n", - "\n", + "\n", + "\n", "Whether to reset the qubits to the ground state for each shot.\n", "\n", "**Choices**: `True`, `False`\n", "\n", "**Default**: `True`\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `execution.rep_delay`\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", - "#### `execution.meas_type`\n", - "\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", - "\n", - "### `max_execution_time`\n", - "\n", + "\n", + "\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", - "### `simulator`\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", - "#### `simulator.basis_gates`\n", - "\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", - "#### `simulator.coupling_map`\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", - "#### `simulator.noise_model`\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", - "#### `simulator.seed_simulator`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: Integer\n", "\n", "**Default**: None\n", "\n", - "
\n", + " \n", "\n", - "
\n", + "\n", + "\n", + "\n", + " \n", "\n", "\n", - "
\n", - "\n", - "### `twirling`\n", - "\n", + "\n", + "\n", "\n", "Twirling options\n", "\n", "[`twirling` API documentation](/docs/api/qiskit-ibm-runtime/options-twirling-options)\n", - "
\n", - "\n", - "#### `twirling.enable_gates`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: True, False\n", "\n", "**Default**: False\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `twirling.enable_measure`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: True, False\n", "\n", "**Default**: False\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `twirling.num_randomizations`\n", - "\n", + "\n", + "\n", "\n", "**Choices**: `auto`, Integer >= 1\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", "\n", - "
\n", - "\n", - "#### `twirling.shots_per_randomization`\n", - "\n", + "\n", + "\n", + "\n", "\n", "**Choices**: `auto`, Integer >= 1\n", "\n", "**Default**: `auto`\n", "\n", - "
\n", + " \n", + "\n", "\n", - "
\n", - "\n", - "#### `twirling.strategy`\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", - "\n", - "### `experimental`\n", - "\n", + "\n", + "\n", "\n", "Experimental options, when available.\n", "\n", - "
" + " \n", + "\n", + "\n", + "" ] }, { From ff86adb550518b9cd1b85f89e756e8e411ec531b Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 27 Feb 2026 16:03:59 -0600 Subject: [PATCH 107/118] Merge branch 'main' of https://github.com/Qiskit/documentation into bd-new-toc --- docs/guides/circuit-transpilation-settings.ipynb | 2 +- docs/guides/configure-error-suppression.ipynb | 2 +- ...ror-mitigation-and-suppression-techniques.ipynb | 10 +++++----- docs/guides/estimator-broadcasting.mdx | 4 ++-- docs/guides/estimator-input-output.ipynb | 2 +- docs/guides/estimator-options.ipynb | 2 +- docs/guides/execution-modes.mdx | 2 +- docs/guides/functions.ipynb | 2 +- docs/guides/get-started-with-estimator.ipynb | 4 ++-- docs/guides/get-started-with-sampler.ipynb | 4 ++-- docs/guides/global-data-quantum-optimizer.ipynb | 4 ++-- docs/guides/intro-to-patterns.mdx | 4 ++-- docs/guides/local-simulators.mdx | 6 +++--- docs/guides/local-testing-mode.ipynb | 6 +++--- docs/guides/q-ctrl-performance-management.ipynb | 8 ++++---- docs/guides/qiskit-1.0-features.mdx | 8 ++++---- docs/guides/run-jobs-batch.ipynb | 4 ++-- docs/guides/sampler-input-output.ipynb | 4 ++-- .../simulate-with-qiskit-sdk-primitives.ipynb | 6 +++--- docs/guides/v2-primitives.mdx | 4 ++-- .../depth-reduction-with-circuit-cutting.ipynb | 2 +- docs/tutorials/ghz-spacetime-codes.ipynb | 4 ++-- docs/tutorials/global-data-quantum-optimizer.ipynb | 2 +- docs/tutorials/grovers-algorithm.ipynb | 2 +- .../tutorials/krylov-quantum-diagonalization.ipynb | 2 +- ...uantum-approximate-optimization-algorithm.ipynb | 4 ++-- .../tutorials/quantum-phase-estimation-qctrl.ipynb | 2 +- docs/tutorials/sml-classification.ipynb | 2 +- .../courses/quantum-chem-with-vqe/geometry.ipynb | 2 +- .../quantum-chem-with-vqe/ground-state.ipynb | 4 ++-- .../running-quantum-circuits.ipynb | 6 +++--- .../simulating-nature.ipynb | 4 ++-- .../utility-scale-qaoa.ipynb | 2 +- .../quantum-diagonalization-algorithms/vqe.ipynb | 14 +++++++------- .../variational-quantum-algorithms.ipynb | 2 +- 35 files changed, 71 insertions(+), 71 deletions(-) diff --git a/docs/guides/circuit-transpilation-settings.ipynb b/docs/guides/circuit-transpilation-settings.ipynb index 6e03c20779c..159e8dec19f 100644 --- a/docs/guides/circuit-transpilation-settings.ipynb +++ b/docs/guides/circuit-transpilation-settings.ipynb @@ -289,7 +289,7 @@ "source": [ "## Step 3: Execute using Qiskit primitives\n", "\n", - "At this point, you have a list of circuits transpiled for the specified QPU. Next, create an instance of the sampler primitive and start a batched job using the context manager (`with ...:`), which automatically opens and closes the batch.\n", + "At this point, you have a list of circuits transpiled for the specified QPU. Next, create an instance of the Sampler primitive and start a batched job using the context manager (`with ...:`), which automatically opens and closes the batch.\n", "\n", "Within the context manager, sample the circuits and store the results to `result`." ] diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index d07e4359326..ecdbd14118e 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -115,7 +115,7 @@ "\n", "\n", diff --git a/docs/guides/error-mitigation-and-suppression-techniques.ipynb b/docs/guides/error-mitigation-and-suppression-techniques.ipynb index 9da4f510e6b..69a7b0206cb 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." ] }, { @@ -188,7 +188,7 @@ "\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 are required to be set explicitly." ] }, { @@ -237,7 +237,7 @@ "- `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 are required to be set explicitly." ] }, { @@ -317,7 +317,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." ] }, { diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index 5888987f5fd..3b9fae2d49e 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -1,11 +1,11 @@ --- title: Broadcasting -description: How the Estimator handles array inputs and outputs using broadcasting semantics +description: How Estimator handles array inputs and outputs using broadcasting semantics --- # Estimator broadcasting semantics -When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs_broadcasting#pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how the Estimator handles array inputs and outputs using broadcasting semantics. +When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs_broadcasting#pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how Estimator handles array inputs and outputs using broadcasting semantics. Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 24a12d564ae..80311312f98 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -148,7 +148,7 @@ "# (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", + "# 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", diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 79e9e90d265..251ed7b19f3 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -292,7 +292,7 @@ "\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 the 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", + "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 particular Estimator PUB:\n", "\n", diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index 05aca0e6cd9..d05f352a158 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 [Estimator examples](/docs/guides/estimator-examples) or [Sampler examples](/docs/guides/sampler-examples) for usage. +A single primitive request of an Estimator or Sampler primitive 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) or [Sampler examples](/docs/guides/sampler-examples) for usage. ## Batch mode diff --git a/docs/guides/functions.ipynb b/docs/guides/functions.ipynb index 393cb98a875..769ad87759d 100644 --- a/docs/guides/functions.ipynb +++ b/docs/guides/functions.ipynb @@ -81,7 +81,7 @@ "|----------------------------------------------------------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n", "| [Tensor-Network Error Mitigation](/docs/guides/algorithmiq-tem) | Algorithmiq | Workloads that have low-weight observables and loop-free circuits. | Reduces measurement overhead and variance, outperforming standard error mitigation baselines such as Zero Noise Extrapolation (ZNE) and Probabilistic Error Cancellation (PEC) for relevant circuit classes. |\n", "| [QESEM: Error Suppression and Error Mitigation](/docs/guides/qedma-qesem) | Qedma | Workloads that include circuits with fractional or parameterized gates, high-weight observables, and workflows that require unbiased expectation values and accurate runtime estimates. | Produces unbiased expectation values with lower variance and resource overhead, outperforming ZNE and PEC for relevant circuit classes. |\n", - "| [Performance Management](/docs/guides/q-ctrl-performance-management) | Q-CTRL | Workloads that contain parametric circuits, deep circuits, or require many circuit executions. | Automatically applies AI-driven error suppression to quantum algorithms, maximizing the performance of IBM devices to deliver accurate results while reducing the number of shots, compute time, and cost required.

Zero-overhead method that improves execution accuracy for the Sampler and the Estimator primitives, compatible with any weight of observables. |\n", + "| [Performance Management](/docs/guides/q-ctrl-performance-management) | Q-CTRL | Workloads that contain parametric circuits, deep circuits, or require many circuit executions. | Automatically applies AI-driven error suppression to quantum algorithms, maximizing the performance of IBM devices to deliver accurate results while reducing the number of shots, compute time, and cost required.

Zero-overhead method that improves execution accuracy for the Sampler and Estimator primitives, compatible with any weight of observables. |\n", "\n", "\n", "### Application functions\n", diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index 2c03346cad2..d10e9c0eeb1 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -199,7 +199,7 @@ "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)" + "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)" ] }, { @@ -219,7 +219,7 @@ "id": "59b13a43-0c9f-4fdb-a379-af5115c153e1", "metadata": {}, "source": [ - "### 4. Invoke the Estimator and get results\n", + "### 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." ] diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index 431aaefb82f..b6547a6e690 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -156,7 +156,7 @@ "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.](execution-modes) Note that Open Plan users cannot submit session jobs." + "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." ] }, { @@ -176,7 +176,7 @@ "id": "f35972bf-17d3-40be-852b-9e56615c7c3c", "metadata": {}, "source": [ - "### 4. Invoke the Sampler and get results\n", + "### 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." ] diff --git a/docs/guides/global-data-quantum-optimizer.ipynb b/docs/guides/global-data-quantum-optimizer.ipynb index aafc0dd07de..9651daaad3b 100644 --- a/docs/guides/global-data-quantum-optimizer.ipynb +++ b/docs/guides/global-data-quantum-optimizer.ipynb @@ -327,8 +327,8 @@ "source": [ "| Name | Type | Description | Required | Default | Example |\n", "|-------------------|--------|--------------------------------------------|----------|----------------------------|----------------------------|\n", - "| sampler_shots | int | Number of shots of the Sampler. | No | 100000 | - |\n", - "| estimator_shots | int | Number of shots of the Estimator. | No | 25000 | - |\n", + "| sampler_shots | int | Number of shots for Sampler. | No | 100000 | - |\n", + "| estimator_shots | int | Number of shots for Estimator. | No | 25000 | - |\n", "| estimator_precision | float | Desired precision of the expected value. If specified, the precision will be used instead of the `estimator_shots`. | No | `None` | 0.015625 · (1 / sqrt(4096)) |\n", "| max_time | int or str | Maximum amount of time a runtime session can remain open before being forcibly closed. Can be given in seconds (int) or as a string, like `\"2h 30m 40s\"`. Must be less than the system-imposed maximum. | No | `None` | `\"1h 15m\"` |" ] 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 05911d51dba..2cf3bd67b6e 100644 --- a/docs/guides/local-simulators.mdx +++ b/docs/guides/local-simulators.mdx @@ -98,7 +98,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) @@ -138,7 +138,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) @@ -172,7 +172,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 65bef567562..b97780342f1 100644 --- a/docs/guides/local-testing-mode.ipynb +++ b/docs/guides/local-testing-mode.ipynb @@ -120,7 +120,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", @@ -160,7 +160,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", @@ -210,7 +210,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", diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 1f300a5559d..0e29b2468ea 100644 --- a/docs/guides/q-ctrl-performance-management.ipynb +++ b/docs/guides/q-ctrl-performance-management.ipynb @@ -262,12 +262,12 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": null, "id": "26952e1f", "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", @@ -517,12 +517,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/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/run-jobs-batch.ipynb b/docs/guides/run-jobs-batch.ipynb index 337dacab66d..2474c3e4d8c 100644 --- a/docs/guides/run-jobs-batch.ipynb +++ b/docs/guides/run-jobs-batch.ipynb @@ -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/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 39529e38fd8..1c623feb429 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -130,7 +130,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 = Sampler(mode=backend)\n", "job = sampler.run([sampler_pub])\n", @@ -144,7 +144,7 @@ "source": [ "## Output\n", "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of the Estimator, or samples of the circuit output in the case of the Sampler.\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of Estimator, or samples of the circuit output in the case of Sampler.\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 `PubResults`, one corresponding to each PUB).\n", "\n", diff --git a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb index fa958b1a9f7..25cb49ddcb5 100644 --- a/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb +++ b/docs/guides/simulate-with-qiskit-sdk-primitives.ipynb @@ -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", @@ -259,7 +259,7 @@ "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", diff --git a/docs/guides/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index 4831c9b420e..f820329ef30 100644 --- a/docs/guides/v2-primitives.mdx +++ b/docs/guides/v2-primitives.mdx @@ -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 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/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 1ecd9661378..9791d449187 100644 --- a/docs/tutorials/global-data-quantum-optimizer.ipynb +++ b/docs/tutorials/global-data-quantum-optimizer.ipynb @@ -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." ] }, { 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/quantum-approximate-optimization-algorithm.ipynb b/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb index 47efec9586b..0f6f0521160 100644 --- a/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb +++ b/docs/tutorials/quantum-approximate-optimization-algorithm.ipynb @@ -500,7 +500,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$." ] }, { @@ -514,7 +514,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/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..626d46a771c 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", 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 97a20e738c9..ccdd6848840 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", @@ -639,18 +639,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", @@ -951,7 +951,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/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$." ] }, { From 2963cf5b9fb224fa01c3b8399e7de2ff39023068 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 27 Feb 2026 16:04:48 -0600 Subject: [PATCH 108/118] untangle toc --- docs/guides/_toc.json | 31 +------------------------------ 1 file changed, 1 insertion(+), 30 deletions(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index ba74936dcc0..6ceaf35fb9d 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -466,35 +466,6 @@ "url": "/docs/guides/logging" } ] - }, - { - "title": "Execute with primitives", - "children": [ - { - "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": "Qiskit Runtime local testing mode", - "url": "/docs/guides/local-testing-mode" - } - ] }, { "title": "Execute with primitives", @@ -635,7 +606,7 @@ "url": "/docs/guides/get-qpu-information" }, { - "title": "Monitoring, calibrations, and benchmarking", + "title": "Calibration jobs", "url": "/docs/guides/calibration-jobs" }, { From 085d209c1046d50a509592c4261cb1207aadd19e Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Fri, 27 Feb 2026 16:26:31 -0600 Subject: [PATCH 109/118] AC comments --- docs/guides/estimator-input-output.ipynb | 4 ++-- docs/guides/estimator-options.ipynb | 6 +++--- docs/guides/sampler-input-output.ipynb | 9 ++++----- docs/guides/sampler-options.ipynb | 2 +- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index 80311312f98..f2418476081 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime primitives that execute workloads on IBM Quantum® compute resources. These primitives provide you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method for the Estimator primitive, which execute 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 Estimator primitives." + "This page gives an overview of the inputs and outputs of the Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#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." ] }, { @@ -162,7 +162,7 @@ "source": [ "## Output\n", "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of Estimator.\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be expectation values and their error bars.\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 `PubResults`, one corresponding to each PUB).\n", "\n", diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 251ed7b19f3..faf2b0a8104 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -390,7 +390,7 @@ "\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." + "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](/docs/guides/local-testing-mode) because that mode does not use quantum time." ] }, { @@ -426,14 +426,14 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": null, "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", + "# Define the service. This allows you to access an IBM QPU.\n", "service = QiskitRuntimeService()\n", "\n", "# Get a backend\n", diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 1c623feb429..59f08c8f0ee 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -45,10 +45,9 @@ }, { "cell_type": "markdown", - "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Qiskit Runtime Sampler primitives, which execute workloads on IBM Quantum® compute resources. The Sampler primitive provides you with the ability to efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#pubs) These PUBs are the fundamental unit of work that a QPU needs in order to execute these workloads. They are used as inputs to the [`run()`](/docs/api/qiskit-ibm-runtime/sampler-v2#run) method for the 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 Sampler primitives." + "This page gives an overview of the inputs and outputs of the 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/pubs_broadcasting#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." ] }, { @@ -58,7 +57,7 @@ "source": [ "## Input\n", "\n", - "For the Estimator primitive, a PUB can contain at most three values:\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", @@ -130,7 +129,7 @@ "\n", "sampler_pub = (transpiled_circuit, params)\n", "\n", - "# Instantiate the new Estimator object, then run the transpiled circuit\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", @@ -144,7 +143,7 @@ "source": [ "## Output\n", "\n", - "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB. Depending on the primitive used, these data will be either expectation values and their error bars in the case of Estimator, or samples of the circuit output in the case of Sampler.\n", + "Once 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 [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult) objects that contain the execution results for each PUB.These data will be samples of the circuit output\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 `PubResults`, one corresponding to each PUB).\n", "\n", diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 8ff9f059e68..db80ff0ccd8 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -356,7 +356,7 @@ "\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." + "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](/docs/guides/local-testing-mode) because that mode does not use quantum time." ] }, { From b28291833a4dcb45dbd1788a2f48c7f9f5139245 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 2 Mar 2026 10:06:19 -0600 Subject: [PATCH 110/118] title mismatch --- docs/guides/pubs_broadcasting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/pubs_broadcasting.mdx b/docs/guides/pubs_broadcasting.mdx index 570ac0561ff..d3a27200dcd 100644 --- a/docs/guides/pubs_broadcasting.mdx +++ b/docs/guides/pubs_broadcasting.mdx @@ -1,5 +1,5 @@ --- -title: PUBs and broadcasting +title: Introduction to PUBs and broadcasting description: Understand what PUBs are and how primitives handle array inputs and outputs using broadcasting semantics --- From 460a27c46bb886e267decb64eb9203e95c56bac4 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 2 Mar 2026 10:40:32 -0600 Subject: [PATCH 111/118] Capitalization --- docs/guides/monitor-job.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index 8ca0df19e39..3efb7764a08 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -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", From 4b68a9ce1c9b5387dc42490cf2f8b9cc616b8419 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 2 Mar 2026 11:46:13 -0600 Subject: [PATCH 112/118] links --- docs/guides/configure-error-mitigation.ipynb | 5 +++-- docs/guides/configure-error-suppression.ipynb | 2 +- docs/guides/estimator-broadcasting.mdx | 2 +- docs/guides/noise-learning.ipynb | 4 ++-- ...{pubs_broadcasting.mdx => pubs-broadcasting.mdx} | 0 docs/guides/runtime-options-overview.mdx | 2 +- docs/guides/sampler-input-output.ipynb | 2 +- docs/tutorials/dc-hex-ising.ipynb | 2 +- .../error-mitigation-with-qiskit-functions.ipynb | 2 +- docs/tutorials/operator-back-propagation.ipynb | 2 +- .../{pubs => pubs-broadcasting}/broadcasting.avif | Bin 11 files changed, 12 insertions(+), 11 deletions(-) rename docs/guides/{pubs_broadcasting.mdx => pubs-broadcasting.mdx} (100%) rename public/docs/images/guides/{pubs => pubs-broadcasting}/broadcasting.avif (100%) diff --git a/docs/guides/configure-error-mitigation.ipynb b/docs/guides/configure-error-mitigation.ipynb index faf5e43bafa..11f4bb966a0 100644 --- a/docs/guides/configure-error-mitigation.ipynb +++ b/docs/guides/configure-error-mitigation.ipynb @@ -205,8 +205,8 @@ "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", + "- Not all options are available for all primitives. See each primitive's \"options\" page for its list of available options.\n", + "- Not all methods work together on all types of circuits. See the feature compatibility table for [Estimator](estimator-options#options-compatibility-table) or [Sampler](sampler-options#options-compatibility-table) for details.\n", "\n", "\n", "\n", @@ -261,6 +261,7 @@ " - [Configure error suppression.](configure-error-suppression)\n", " - Explore Sampler [options.](/docs/guides/sampler-options)\n", " - Explore Estimator [options.](/docs/guides/estimator-options)\n", + " - Explore Executor [options.](/docs/guides/executor-options)\n", " - Decide what [execution mode](execution-modes) to run your job in.\n", "" ] diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index ecdbd14118e..56438e48e45 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -70,7 +70,7 @@ "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 options are available for both primitives. See each primitive's "options" page for its 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", "" ] diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index 3b9fae2d49e..4e035543e7b 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -20,7 +20,7 @@ Parameter value sets are represented by `n x m` arrays, and observable arrays ar - *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. -![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs_broadcasting#pubs/broadcasting.avif "Visual representation of broadcasting") +![This image illustrates several visual representations of array broadcasting](/docs/images/guides/pubs-broadcasting/broadcasting.avif "Visual representation of broadcasting") ```python # Broadcast single observable diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index 886841901f5..b2c6ae0dcab 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#probabilistic-error-amplification-pea) and [PEC](docs/guides/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", "\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](./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/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." ] }, { diff --git a/docs/guides/pubs_broadcasting.mdx b/docs/guides/pubs-broadcasting.mdx similarity index 100% rename from docs/guides/pubs_broadcasting.mdx rename to docs/guides/pubs-broadcasting.mdx diff --git a/docs/guides/runtime-options-overview.mdx b/docs/guides/runtime-options-overview.mdx index 791ef058e74..fc0cd09dcdb 100644 --- a/docs/guides/runtime-options-overview.mdx +++ b/docs/guides/runtime-options-overview.mdx @@ -21,7 +21,7 @@ When calling the primitives, you can pass in options by using an options class o 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 sections on each primitive's options guide lists the default values. ## Set options diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 59f08c8f0ee..946464ab0cb 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -47,7 +47,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the 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/pubs_broadcasting#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." + "This page gives an overview of the inputs and outputs of the 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/pubs_broadcasting#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." ] }, { diff --git a/docs/tutorials/dc-hex-ising.ipynb b/docs/tutorials/dc-hex-ising.ipynb index d2b047381b1..ebed134fefc 100644 --- a/docs/tutorials/dc-hex-ising.ipynb +++ b/docs/tutorials/dc-hex-ising.ipynb @@ -877,7 +877,7 @@ "metadata": {}, "source": [ "### Transpilation for dynamic circuits\n", - "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/pubs) (PUBs) as the Sampler primitive input." + "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/pubs-broadcasting-broadcasting) (PUBs) as the Sampler primitive input." ] }, { diff --git a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb index f6e8e4cf825..4ee051077cc 100644 --- a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb +++ b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb @@ -24,7 +24,7 @@ "id": "34260848-be4c-45f7-914f-9d9bcc2be504", "metadata": {}, "source": [ - "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/pubs) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", + "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/pubs-broadcasting-broadcasting) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", "\n", "Visit the documentation for an [introduction to Qiskit Functions](/docs/guides/functions) and learn how to get started with the [IBM Circuit function](/docs/guides/ibm-circuit-function)." ] diff --git a/docs/tutorials/operator-back-propagation.ipynb b/docs/tutorials/operator-back-propagation.ipynb index 9e466e8fbdb..edb991d0896 100644 --- a/docs/tutorials/operator-back-propagation.ipynb +++ b/docs/tutorials/operator-back-propagation.ipynb @@ -546,7 +546,7 @@ "id": "8b4487c1-b1e6-4ae8-b02d-c8bf980ad19b", "metadata": {}, "source": [ - "We create the Primitive Unified Bloc (PUB) for each of the three cases." + "We create the Primitive Unified Bloc (PUB) for each of the three cases." ] }, { diff --git a/public/docs/images/guides/pubs/broadcasting.avif b/public/docs/images/guides/pubs-broadcasting/broadcasting.avif similarity index 100% rename from public/docs/images/guides/pubs/broadcasting.avif rename to public/docs/images/guides/pubs-broadcasting/broadcasting.avif From feb7505ead21efe3cd6a808f8a4374a452be5e4c Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 2 Mar 2026 11:51:24 -0600 Subject: [PATCH 113/118] Something fun --- docs/guides/configure-error-suppression.ipynb | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index 56438e48e45..858613fb672 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -70,7 +70,7 @@ "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 each primitive's "options" page for its list of available options.\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", "" ] @@ -129,6 +129,9 @@ " - 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", + " - Explore Sampler [options.](/docs/guides/sampler-options)\n", + " - Explore Estimator [options.](/docs/guides/estimator-options)\n", + " - Explore Executor [options.](/docs/guides/executor-options)\n", " - Decide what [execution mode](execution-modes) to run your job in.\n", "" ] From e565670270a26cc08c1c60f464bd070275a83808 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Mon, 2 Mar 2026 12:12:35 -0600 Subject: [PATCH 114/118] typo --- qiskit_bot.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index 4e4831325dc..b4467818699 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -175,7 +175,7 @@ notifications: - "@abbycross" - "@beckykd" - "@jyu00" - "docs/guides/pubs_broadcasting": + "docs/guides/pubs-broadcasting": - "@abbycross" - "@beckykd" - "@jyu00" From b915ddbebd20d2458e5311aa5271335e6efe0230 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 3 Mar 2026 10:51:22 -0600 Subject: [PATCH 115/118] Add PEA example --- docs/guides/algorithmiq-tem.ipynb | 2 +- docs/guides/configure-error-suppression.ipynb | 2 +- docs/guides/estimator-broadcasting.mdx | 6 +- docs/guides/estimator-input-output.ipynb | 2 +- docs/guides/executor-broadcasting.mdx | 4 +- docs/guides/executor-examples.mdx | 257 +++++++++++++++++- docs/guides/get-started-with-estimator.ipynb | 2 +- docs/guides/get-started-with-sampler.ipynb | 2 +- docs/guides/ibm-circuit-function.ipynb | 4 +- docs/guides/monitor-job.ipynb | 2 +- docs/guides/noise-learning.ipynb | 4 +- docs/guides/primitives.ipynb | 8 +- docs/guides/pubs-broadcasting.mdx | 2 +- .../q-ctrl-performance-management.ipynb | 4 +- docs/guides/qedma-qesem.ipynb | 2 +- docs/guides/sampler-input-output.ipynb | 2 +- docs/guides/v2-primitives.mdx | 2 +- docs/tutorials/dc-hex-ising.ipynb | 2 +- ...ror-mitigation-with-qiskit-functions.ipynb | 2 +- .../tutorials/operator-back-propagation.ipynb | 2 +- .../vqe.ipynb | 2 +- .../exploring-uncertainty-with-qiskit.ipynb | 2 +- 22 files changed, 282 insertions(+), 35 deletions(-) diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb index c090bb20837..a7bfc2b2185 100644 --- a/docs/guides/algorithmiq-tem.ipynb +++ b/docs/guides/algorithmiq-tem.ipynb @@ -319,7 +319,7 @@ "\n", "Name | Type | Description | Required | Default | Example\n", "-- | -- | -- | -- | -- | --\n", - "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs_broadcasting#pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", + "`pubs` | Iterable[EstimatorPubLike] | An iterable of PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameters, precision)`. See [Overview of PUBs](/docs/guides/pubs-broadcasting#pubs) for more information. If a non-ISA circuit is passed, it will be transpiled with optimal settings. If an ISA circuit is passed, it will not be transpiled; in this case, the observable must be defined on the whole QPU. | Yes | N/A | (circuit, observables)\n", "`backend_name` | str | Name of the backend to make the query.| No | If not provided, the least-busy backend will be used. | \"ibm_fez\"\n", "`options` | dict | Input options. See `Options` section for more details. | No | See `Options` section for more details.| \\{\"max_bond_dimension\": 100\\}\n", "\n", diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index 858613fb672..7f511192441 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -71,7 +71,7 @@ "\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", + "- Not all methods work together on all types of circuits. See the feature compatibility table for details in the [Estimator options](/docs/guides/estimator-options) or [Sampler options](/docs/guides/sampler-options guide.\n", "" ] }, diff --git a/docs/guides/estimator-broadcasting.mdx b/docs/guides/estimator-broadcasting.mdx index 4e035543e7b..afee7b8028d 100644 --- a/docs/guides/estimator-broadcasting.mdx +++ b/docs/guides/estimator-broadcasting.mdx @@ -5,7 +5,7 @@ description: How Estimator handles array inputs and outputs using broadcasting s --- # Estimator broadcasting semantics -When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs_broadcasting#pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how Estimator handles array inputs and outputs using broadcasting semantics. +When invoking an Estimator primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a tuple called a [PUB.](/docs/guides/pubs-broadcasting#pubs) The data provided to these tuples can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs-broadcasting#broadcasting) This guide explains how Estimator handles array inputs and outputs using broadcasting semantics. Following are some examples of common patterns expressed in terms of array broadcasting. Their accompanying visual representation is shown in the figure that follows: @@ -87,7 +87,7 @@ list2 = [SparsePauliOp("XX"), SparsePauliOp("XY"), SparsePauliOp("IZ")] ## Next steps - - See the [broadcasting guide](/docs/guides/pubs_broadcasting#broadcasting) for an overview of broadcasting. - - Learn about [PUBs.](/docs/guides/pubs_broadcasting#pubs) + - See the [broadcasting guide](/docs/guides/pubs-broadcasting#broadcasting) for an overview of broadcasting. + - Learn about [PUBs.](/docs/guides/pubs-broadcasting#pubs) - Understand [Estimator inputs and outputs.](/docs/guides/estimator-input-output) diff --git a/docs/guides/estimator-input-output.ipynb b/docs/guides/estimator-input-output.ipynb index f2418476081..01796ddbbc3 100644 --- a/docs/guides/estimator-input-output.ipynb +++ b/docs/guides/estimator-input-output.ipynb @@ -48,7 +48,7 @@ "id": "6962c44c-da86-45ac-a70f-bd4ceb2c262b", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs_broadcasting#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." + "This page gives an overview of the inputs and outputs of the Estimator primitive, which executes workloads on IBM Quantum® compute resources. Estimator lets you efficiently define vectorized workloads by using a data structure known as a [**Primitive Unified Bloc (PUB)**.](/docs/guides/pubs-broadcasting#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." ] }, { diff --git a/docs/guides/executor-broadcasting.mdx b/docs/guides/executor-broadcasting.mdx index bad6272df0d..01c506d4407 100644 --- a/docs/guides/executor-broadcasting.mdx +++ b/docs/guides/executor-broadcasting.mdx @@ -6,7 +6,7 @@ description: How the Executor handles array inputs and outputs using broadcastin {/* cspell:ignore broadcastable */} # Executor broadcasting semantics -The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine +The data provided to the Executor primitive can be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs-broadcasting#broadcasting) This guide explains how the Executor handles array inputs and outputs using broadcasting semantics. Understanding these concepts will help you efficiently sweep over parameter values, combine multiple experimental configurations, and interpret the shape of returned data. ## Quick start example @@ -280,6 +280,6 @@ To sweep one parameter while holding others fixed: ## Next steps - - Review the [broadcasting](/docs/guides/pubs_broadcasting#broadcasting) overview. + - Review the [broadcasting](/docs/guides/pubs-broadcasting#broadcasting) overview. - Understand [Executor inputs and outputs.](/docs/guides/executor-input-output) diff --git a/docs/guides/executor-examples.mdx b/docs/guides/executor-examples.mdx index 27abfa8f39a..0a975291f82 100644 --- a/docs/guides/executor-examples.mdx +++ b/docs/guides/executor-examples.mdx @@ -7,8 +7,9 @@ description: Practical examples of using the Executor primitive in Qiskit Runtim The examples in this section illustrate some common ways to use the Executor primitive. Before running these examples, follow the instructions in [Install Qiskit](/docs/guides/install-qiskit) and [Get started with Executor.](/docs/guides/directed-execution-model) +## Example: Parameterized circuit -## Generate the circuit +This example illustrates how to add circuit items with parameters, as well as how to add samplex items. The examples in this guide use the following circuit, which generates a three-qubit GHZ state, rotates the qubits around the Pauli-Z axis, and measures the qubits in the computational basis. We show how @@ -49,9 +50,9 @@ service = QiskitRuntimeService() backend = service.least_busy(operational=True, simulator=False) ``` -## Define a `QuantumProgram` +### Define a `QuantumProgram` -The input to Executor is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output#programs) +The input to Executor is a `QuantumProgram`. For full details, see [Executor input and output.](/docs/guides/executor-input-output#programs) Note that Samplomatic uses [`generate_boxing_pass_manager`](https://qiskit.github.io/samplomatic/guides/transpiler.html) for transpilation. ```python # Initialize an empty program @@ -89,7 +90,7 @@ program.append_samplex_item( ) ``` -## Run the Executor job +### Run the Executor job ```python # initialize an Executor with the default options @@ -102,12 +103,258 @@ job = executor.run(program) result = job.result() ``` +## Example: Perform PEC +This example shows how to use a samplex item to perform probabilistic error cancellation ([PEC](/docs/guides/error-mitigation-and-suppression-techniques#pec)) for error mitigation. +Consider a mirrored-version of a circuit with ten qubits and two unique layers of CX gates. These are the main tasks: +- Execute the circuit with twirling. +- Execute the circuit with PEC mitigation, as in [Probabilistic error cancellation with sparse Pauli-Lindblad models on noisy quantum processors](https://arxiv.org/abs/2201.09866). + +The pipeline consists of the following steps: +1. Setup: Generate the target circuit and group its operations into boxes. +2. Learning: Learn the noise of the instructions that we want to mitigate with PEC. +3. Execution: Run the circuit on a backend and analyze the results. + +### Set up the circuit + +Choose a backend and prepare a 10 qubit circuit. + +```python +from qiskit_ibm_runtime import QiskitRuntimeService + +token = "" +service = QiskitRuntimeService() + +backend = service.least_busy( + simulator=False, operational=True, min_num_qubits=100) + +# Prepare a circuit + +num_qubits = 10 +num_layers = 10 + +qubits = list(range(num_qubits)) +circuit = QuantumCircuit(num_qubits) + +for layer_idx in range(num_layers): + circuit.rx(Parameter(f"theta_{layer_idx}"), qubits) + for i in range(num_qubits // 2): + circuit.cz(qubits[2 * i], qubits[2 * i + 1]) + + circuit.rx(Parameter(f"phi_{layer_idx}"), qubits) + for i in range(num_qubits // 2 - 1): + circuit.cz(qubits[2 * i] + 1, qubits[2 * i + 1] + 1) + +circuit.draw("mpl", scale=0.35, fold=100) +``` + +Combine the circuit with its inverse to create a mirror circuit. + +```python +mirror_circuit = circuit.compose(circuit.inverse()) +mirror_circuit.measure_all() + +mirror_circuit.draw("mpl", scale=0.35, fold=100) +``` + +Set some parameter values: + +```python +import numpy as np + +parameter_values=np.random.rand(mirror_circuit.num_parameters) +``` + +Use the pass manager to transpile the circuit against our backend, and group gates and measurements into annotated boxes. Begin by creating a circuit with twirled-annotated boxes. + +```python +preset_pass_manager = generate_preset_pass_manager( + backend=backend, + initial_layout=list(range(40, 50)), # qubits 40 to 50 + optimization_level=0, +) + +# Run the boxing pass manager after the scheduling stage +preset_pass_manager.post_scheduling = generate_boxing_pass_manager( + enable_gates=True, + enable_measures=True, +) + +mirror_circuit_twirl = preset_pass_manager.run(mirror_circuit) +``` + +Next, generate a new boxed circuit with `Twirl` and `InjectNoise` annotations. + +```python +preset_pass_manager = generate_preset_pass_manager( + backend=backend, + initial_layout=list(range(40, 50)), + optimization_level=0, +) + +# Run the boxing pass manager after the scheduling stage +preset_pass_manager.post_scheduling = generate_boxing_pass_manager( + enable_gates=True, + enable_measures=True, + inject_noise_targets="gates", # no measurement mitigation + inject_noise_strategy="uniform_modification", +) + +mirror_circuit_pec = preset_pass_manager.run(mirror_circuit) +``` + +### Learn the noise + +To minimize the number of noise learning experiments, identify the unique instructions in the second circuit (the one with boxes annotated with `InjectNoise`). In defining uniqueness, two box instructions are equal if: +- Their content is equal, up to single-qubit gates. +- Their `Twirl` annotation is equal (every other annotation is disregarded). + +This leads to three unique instructions, namely the odd and even gate boxes, and the final measurement box. + +```python +from samplomatic.utils import find_unique_box_instructions + +unique_box_instructions = find_unique_box_instructions(mirror_circuit_pec.data) +assert len(unique_box_instructions) == 3 +``` + +Initialize a `NoiseLearnerV3`, choose the learning parameters by setting its options, and run a noise learning job. + +```python +from qiskit_ibm_runtime.noise_learner_v3 import NoiseLearnerV3 + +use_cached_results = True + +if use_cached_results: + learner_job = shared_service.job("d607atruf71s73cje640") +else: + learner = NoiseLearnerV3(backend) + + learner.options.shots_per_randomization = 128 + learner.options.num_randomizations = 32 + learner.options.layer_pair_depths = [0, 1, 2, 4, 16, 32] + + learner_job = learner.run(unique_box_instructions) + +learner_job.job_id() +learner_result = learner_job.result() +``` + +To convert `result` to the object required by the samplex, use the `result.to_dict` method. + +```python +noise_maps = learner_result.to_dict(instructions=unique_box_instructions, require_refs=False) +``` + +### Execute the circuits + +The `Executor` runs `QuantumProgram` objects. Each `QuantumProgram` is able to contain several *items*, which can be thought of as a template, samplex pair. + +Initialize an empty program, requesting `1000` shots for each of its items. + +```python +from qiskit_ibm_runtime.quantum_program import QuantumProgram + +# Generate a quantum program +program = QuantumProgram(shots=1000) +``` + +Next, append the template and samplex built for `mirror_circuit_twirl`, requesting `900` randomizations. This means that the samplex will produce `900` sets of parameters, and each set will be executed `1000` times in the QPU. + +```python +template_twirl, samplex_twirl = build(mirror_circuit_twirl) + +program.append_samplex_item( + template_twirl, + samplex=samplex_twirl, + samplex_arguments={"parameter_values": parameter_values}, + shape=(900,) +) +``` + +Similarly, append the template and samplex built for `mirror_circuit_pec`, requesting `900` randomizations. + +```python +template_pec, samplex_pec = build(mirror_circuit_pec) + +program.append_samplex_item( + template_pec, + samplex=samplex_pec, + samplex_arguments={ + "parameter_values": parameter_values, + "pauli_lindblad_maps": noise_maps, + "noise_scales": {ref: -1.0 for ref in noise_maps} # Set the scales to -1 for PEC + }, + shape=(900,) +) +``` + +Import `Executor` and submit a job. + +```python +from qiskit_ibm_runtime.executor import Executor + +use_cached_results = True + +if use_cached_results: + executor_job = shared_service.job("d607e2l7fc0s73aupsqg") +else: + executor = Executor(backend) + executor_job = executor.run(program) + +executor_job.job_id() + +executor_results = executor_job.result() +executor_results + +twirl_result = executor_results[0] + +print(f"Twirl result keys:\n {list(twirl_result.keys())}\n") +print(f"Shape of results: {twirl_result['meas'].shape}") + +pec_result = executor_results[1] + +print(f"PEC result keys:\n {list(pec_result.keys())}\n") +print(f"Shape of results: {pec_result['meas'].shape}") +``` + +### Analyze results + +Finally, post-process the results to estimate the expectation values of single-qubit Pauli-Z operators acting on each of the ten active qubits (expected value: `1.0`). + +```python +# Undo measurement twirling +twirl_result_unflipped = twirl_result["meas"] ^ twirl_result["measurement_flips.meas"] + +# Calculate the expectation values of single-qubit Z operators +exp_vals = 1 - 2 * twirl_result_unflipped.mean(axis=1).mean(axis=0) + +for qubit, val in enumerate(exp_vals): + print(f"Qubit {qubit} -> {np.round(val, 2)}") +``` + +```python +# Undo measurement twirling +pec_result_unflipped = pec_result["meas"] ^ pec_result["measurement_flips.meas"] + +# Calculate the signs for PEC mitigation +signs = np.prod((-1)**pec_result["pauli_signs"], axis=-1) +signs = signs.reshape((signs.shape[0], 1)) + +# Calculate the expectation values of single-qubit Z operators as required by +# PEC mitigation +exp_vals = 1 - (2 * pec_result_unflipped.mean(axis=1) * signs).mean(axis=0) + +for qubit, val in enumerate(exp_vals): + print(f"Qubit {qubit} -> {np.round(val, 2)}") +``` ## Next steps - - Review the [broadcasting](/docs/guides/pubs_broadcasting#broadcasting) overview. + - Review the [broadcasting](/docs/guides/pubs-broadcasting#broadcasting) overview. - Learn how to use [Executor options.](/docs/guides/executor-options) + - Understand the [directed execution model.](/docs/guides/directed-execution-model) + - Review the [Samplomatic documentation.](https://qiskit.github.io/samplomatic/) diff --git a/docs/guides/get-started-with-estimator.ipynb b/docs/guides/get-started-with-estimator.ipynb index be06991b446..d77a15fd986 100644 --- a/docs/guides/get-started-with-estimator.ipynb +++ b/docs/guides/get-started-with-estimator.ipynb @@ -478,7 +478,7 @@ "### Similarities and differences between backend and Runtime primitives\n", "\n", "- The inputs to and outputs from [`qiskit.primitives.BackendEstimatorV2`](/docs/api/qiskit/qiskit.primitives.BackendEstimatorV2)\n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs_broadcasting#pubs) for details.\n", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs-broadcasting#pubs) 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", diff --git a/docs/guides/get-started-with-sampler.ipynb b/docs/guides/get-started-with-sampler.ipynb index b6547a6e690..301f58be89a 100644 --- a/docs/guides/get-started-with-sampler.ipynb +++ b/docs/guides/get-started-with-sampler.ipynb @@ -267,7 +267,7 @@ "### 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)\n", - "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs_broadcasting#pubs) for details.\n", + "follow the same PUB format as the primitives in Qiskit Runtime. See [PUBs](/docs/guides/pubs-broadcasting#pubs) for details.\n", "However, there can be differences in the fields of the returned metadata.\n", "\n", "- The [`qiskit.primitives.BackendSamplerV2`](/docs/api/qiskit/qiskit.primitives.BackendSamplerV2) class requires a backend that supports the `memory` option.\n", diff --git a/docs/guides/ibm-circuit-function.ipynb b/docs/guides/ibm-circuit-function.ipynb index c01c50acea4..12cf8f0b4fd 100644 --- a/docs/guides/ibm-circuit-function.ipynb +++ b/docs/guides/ibm-circuit-function.ipynb @@ -35,7 +35,7 @@ "\n", "## Overview\n", "\n", - "The IBM® Circuit function takes [abstract PUBs](/docs/guides/pubs_broadcasting#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." + "The IBM® Circuit function takes [abstract PUBs](/docs/guides/pubs-broadcasting#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." ] }, { @@ -206,7 +206,7 @@ "| Name | Type | Description | Required | Default | Example |\n", "|-----------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------|------------------------------------------|\n", "| backend_name | str | Name of the backend to make the query. | Yes | N/A | `ibm_fez` |\n", - "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/pubs_broadcasting#pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", + "| pubs | Iterable[EstimatorPubLike] | An iterable of abstract PUB-like (primitive unified bloc) objects, such as tuples `(circuit, observables)` or `(circuit, observables, parameter_values)`. See [Overview of PUBs](/docs/guides/pubs-broadcasting#pubs) for more information. The circuits can be abstract (non-ISA). | Yes | N/A | (circuit, observables, parameter_values) |\n", "| options | dict | Input options. See the **Options** section for more details. | No | See the **Options** section for details. | `{\"optimization_level\": 3}` |\n", "| instance | str | The cloud resource name of the instance to use in that format. | No | One is randomly picked if your account has access to multiple instances. | `CRN` |" ] diff --git a/docs/guides/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index 3efb7764a08..ecae45b26a2 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -226,7 +226,7 @@ "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/pubs_broadcasting#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", + "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/pubs-broadcasting#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", "Example:" ] diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index b2c6ae0dcab..1447d9703ee 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](docs/guides/error-mitigation-and-suppression-techniques#probabilistic-error-amplification-pea) and [PEC](docs/guides/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`](../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", "\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](docs/guides/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/pubs-broadcasting), 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." ] }, { diff --git a/docs/guides/primitives.ipynb b/docs/guides/primitives.ipynb index 178e62b9f1d..620b0bc19f2 100644 --- a/docs/guides/primitives.ipynb +++ b/docs/guides/primitives.ipynb @@ -139,7 +139,7 @@ "\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/pubs_broadcasting#pubs) Each PUB is in the format:\n", + "The input is an array of [PUBs.](/docs/guides/pubs-broadcasting#pubs) Each PUB is in the format:\n", "\n", "(``, ``, ``, ``),\n", "\n", @@ -147,7 +147,7 @@ "\n", "The output is a [`PubResult`](/docs/api/qiskit/qiskit.primitives.PubResult#pubresult) that contains the computed expectation values per pair, and their standard errors, in `PubResult` form. Each `PubResult` contains both data and metadata.\n", "\n", - "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/docs/guides/pubs_broadcasting#broadcasting) topic.\n", + "The Estimator combines elements from observables and parameter values by following NumPy broadcasting rules as described in the [Primitive broadcasting](/docs/guides/pubs-broadcasting#broadcasting) topic.\n", "\n", "Example:" ] @@ -226,13 +226,13 @@ "\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/pubs_broadcasting#pubs) in the format:\n", + "The input is one or more [PUBs,](/docs/guides/pubs-broadcasting#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 broadcasting](/docs/guides/pubs_broadcasting#broadcasting) for full details.\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 broadcasting](/docs/guides/pubs-broadcasting#broadcasting) for full details.\n", "\n", "Example:" ] diff --git a/docs/guides/pubs-broadcasting.mdx b/docs/guides/pubs-broadcasting.mdx index d3a27200dcd..d2e5fd54ceb 100644 --- a/docs/guides/pubs-broadcasting.mdx +++ b/docs/guides/pubs-broadcasting.mdx @@ -11,7 +11,7 @@ description: Understand what PUBs are and how primitives handle array inputs and The Estimator and Sampler primitives help you efficiently define vectorized workloads by using a data structure known as a _Primitive Unified Bloc (PUB)_. (Executor does not use PUBs.) These PUBs are the fundamental unit of work a QPU needs to execute these workloads. They are used as inputs to the `run()` method for the primitives, which execute 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 Sampler or Estimator primitives. -When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs_broadcasting#broadcasting) +When invoking an Estimator or Sampler primitive's [`run()`](/docs/api/qiskit-ibm-runtime/estimator-v2#run) method, the main argument that is required is a `list` of one or more tuples -- one for each circuit being executed by the primitive. Each of these tuples is considered a PUB, and the required elements of each tuple in the list depends on the primitive used. The data provided to these tuples can also be arranged in a variety of shapes to provide flexibility in a workload through [broadcasting.](/docs/guides/pubs-broadcasting#broadcasting) ## Primitive broadcasting diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb index 0e29b2468ea..75e3d27e965 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/pubs_broadcasting#pubs)." + "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/pubs-broadcasting#pubs)." ] }, { @@ -385,7 +385,7 @@ "**`QctrlEstimatorPubLike` components (derived from the [Qiskit Runtime PUB definition](/docs/guides/estimator-input-output)):**\n", "- A single circuit defined as a `QuantumCircuit` or in OpenQASM 2.0 or 3.0 string format.\n", "- One or more observables that specify the expectation values to estimate, in any of the formats denoted in the list \"Supported observables formats\".\n", - "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](/docs/guides/pubs_broadcasting#broadcasting) as the `QiskitRuntime` primitives.\n", + "- (Optional) A collection of parameter values to bind the circuit against, which follow the same [array broadcasting rules](/docs/guides/pubs-broadcasting#broadcasting) as the `QiskitRuntime` primitives.\n", "- (Optional) A target precision for expectation values to estimate.\n", "- (Optional) A real number representing the precision, or a dictionary of run options containing the shot count. For example: `{\"shots\": }`.\n", "\n", diff --git a/docs/guides/qedma-qesem.ipynb b/docs/guides/qedma-qesem.ipynb index 00cd22b0e8e..1dbbc82f0f4 100644 --- a/docs/guides/qedma-qesem.ipynb +++ b/docs/guides/qedma-qesem.ipynb @@ -244,7 +244,7 @@ "\n", "| Name | Type | Description | Required | Default | Example |\n", "| -----| ------| ------------| -------- | ------- | -------- |\n", - "| `pubs` | [EstimatorPubLike](/docs/guides/pubs_broadcasting#pubs) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", + "| `pubs` | [EstimatorPubLike](/docs/guides/pubs-broadcasting#pubs) |This is the main input. The `Pub` contains 2-4 elements: a circuit, one or more observables, 0 or a single set of parameter values, and an optional precision. If a precision was not specified, then the `default_precision` from `options` will be used| Yes| N/A | `[(circuit, [obs1,obs2,obs3], parameter_values, 0.03)]` |\n", "| `backend_name`| string|Name of the backend to use |No | QESEM will get least busy device reported by IBM| `\"ibm_fez\"`|\n", "| `instance` | string| The cloud resource name of the instance to use in that format | No | N/A | `“CRN”` |\n", "| `options` | dictionary |Input options. See **Options** section for more details. | No | See the **Options** section for details. | `{ default_precision = 0.03, \"max_execution_time\" = 3600, \"transpilation_level\" = 0}` |\n", diff --git a/docs/guides/sampler-input-output.ipynb b/docs/guides/sampler-input-output.ipynb index 946464ab0cb..f611753a51a 100644 --- a/docs/guides/sampler-input-output.ipynb +++ b/docs/guides/sampler-input-output.ipynb @@ -47,7 +47,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "This page gives an overview of the inputs and outputs of the 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/pubs_broadcasting#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." + "This page gives an overview of the inputs and outputs of the 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/pubs-broadcasting#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." ] }, { diff --git a/docs/guides/v2-primitives.mdx b/docs/guides/v2-primitives.mdx index f820329ef30..eff26ce9855 100644 --- a/docs/guides/v2-primitives.mdx +++ b/docs/guides/v2-primitives.mdx @@ -1207,6 +1207,6 @@ print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}") - Learn more about setting options in the [Sampler options,](/docs/guides/sampler-options) [Estimator options,](/docs/guides/estimator-options) and [Executor options](/docs/guides/executor-options) guides. - - Learn more details about [Primitive inputs and outputs.](/docs/guides/pubs_broadcasting#pubs) + - Learn more details about [Primitive inputs and outputs.](/docs/guides/pubs-broadcasting#pubs) - Experiment with the [CHSH Inequality](/docs/tutorials/chsh-inequality) tutorial. diff --git a/docs/tutorials/dc-hex-ising.ipynb b/docs/tutorials/dc-hex-ising.ipynb index ebed134fefc..2315430bea0 100644 --- a/docs/tutorials/dc-hex-ising.ipynb +++ b/docs/tutorials/dc-hex-ising.ipynb @@ -877,7 +877,7 @@ "metadata": {}, "source": [ "### Transpilation for dynamic circuits\n", - "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/pubs-broadcasting-broadcasting) (PUBs) as the Sampler primitive input." + "First, we transpile the dynamic circuits, with and without adding the DD sequence. To ensure we use the same set of physical qubits in all circuits for more consistent results, we first transpile the circuit once, and then use its layout for all subsequent circuits, specified by [`initial_layout`](/docs/api/qiskit/qiskit.transpiler.TranspileLayout#initial_layout) in the pass manager. We then construct the [primitive unified blocs](/docs/guides/pubs-broadcasting) (PUBs) as the Sampler primitive input." ] }, { diff --git a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb index 4ee051077cc..cbe8ab07fa5 100644 --- a/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb +++ b/docs/tutorials/error-mitigation-with-qiskit-functions.ipynb @@ -24,7 +24,7 @@ "id": "34260848-be4c-45f7-914f-9d9bcc2be504", "metadata": {}, "source": [ - "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/pubs-broadcasting-broadcasting) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", + "This tutorial walks through an example of building and running a workflow using the IBM Circuit function. This function takes [Primitive Unified Blocs](/docs/guides/pubs-broadcasting) (PUBs) as inputs and returns error-mitigated expectation values as outputs. It provides an automated and customized pipeline to optimize circuits and execute on quantum hardware so that researchers can focus on algorithm and application discovery.\n", "\n", "Visit the documentation for an [introduction to Qiskit Functions](/docs/guides/functions) and learn how to get started with the [IBM Circuit function](/docs/guides/ibm-circuit-function)." ] diff --git a/docs/tutorials/operator-back-propagation.ipynb b/docs/tutorials/operator-back-propagation.ipynb index edb991d0896..6f88b2add19 100644 --- a/docs/tutorials/operator-back-propagation.ipynb +++ b/docs/tutorials/operator-back-propagation.ipynb @@ -546,7 +546,7 @@ "id": "8b4487c1-b1e6-4ae8-b02d-c8bf980ad19b", "metadata": {}, "source": [ - "We create the Primitive Unified Bloc (PUB) for each of the three cases." + "We create the Primitive Unified Bloc (PUB) for each of the three cases." ] }, { diff --git a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb index ccdd6848840..f84e286a304 100644 --- a/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb +++ b/learning/courses/quantum-diagonalization-algorithms/vqe.ipynb @@ -354,7 +354,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/pubs_broadcasting#pubs) 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/pubs-broadcasting#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", diff --git a/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb b/learning/modules/quantum-mechanics/exploring-uncertainty-with-qiskit.ipynb index 2b448cbd917..8327b0bd1d8 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/pubs_broadcasting#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/pubs-broadcasting#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." ] From dd5f006018a7ea1f931581088debf686aeabbb55 Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Tue, 3 Mar 2026 11:34:53 -0600 Subject: [PATCH 116/118] links --- docs/guides/configure-error-suppression.ipynb | 6 ++++-- docs/guides/noise-learning.ipynb | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/guides/configure-error-suppression.ipynb b/docs/guides/configure-error-suppression.ipynb index 7f511192441..2ee930311d7 100644 --- a/docs/guides/configure-error-suppression.ipynb +++ b/docs/guides/configure-error-suppression.ipynb @@ -70,8 +70,10 @@ "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 table for details in the [Estimator options](/docs/guides/estimator-options) or [Sampler options](/docs/guides/sampler-options guide.\n", + "- Not all options are available for both primitives. \n", + "- Not all methods work together on all types of circuits. \n", + "\n", + "See the [Estimator options](/docs/guides/estimator-options) or [Sampler options](/docs/guides/sampler-options) guide for full details.\n", "" ] }, diff --git a/docs/guides/noise-learning.ipynb b/docs/guides/noise-learning.ipynb index 1447d9703ee..ad0a206f4cc 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](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`](../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](docs/guides/pubs-broadcasting), 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/pubs-broadcasting), 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." ] }, { From 5a0d8c39f30cb20dc3b001ee6bb6986430fbea3d Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Wed, 4 Mar 2026 16:19:54 -0600 Subject: [PATCH 117/118] yarghhh --- docs/guides/_toc.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 6c7ebe9f452..a6f7fa4839c 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -483,7 +483,7 @@ }, { "title": "PUBs and broadcasting", - "url": "/docs/guides/pubs_broadcasting" + "url": "/docs/guides/pubs-broadcasting" }, { "title": "Estimator", From 41e909f7d19fbda25d79ccc9e806f784b491aa9b Mon Sep 17 00:00:00 2001 From: Becky Dimock Date: Thu, 5 Mar 2026 08:50:49 -0600 Subject: [PATCH 118/118] remove unused images --- .../images/guides/hello-world/extracted-outputs/87143fcc-0.svg | 1 - .../images/guides/hello-world/extracted-outputs/de91ebd0-0.svg | 1 - 2 files changed, 2 deletions(-) delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/87143fcc-0.svg delete mode 100644 public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg 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 04e5c60ae38..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/de91ebd0-0.svg b/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg deleted file mode 100644 index 397c11e36cd..00000000000 --- a/public/docs/images/guides/hello-world/extracted-outputs/de91ebd0-0.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file

Gq^HO(i*8bq}+{?&*5IS8uub>$F#&|e( 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%0D$9)G(*z(K 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 %*hLHClct1D<~fIkT}FBtBCoBz z3^L^-%WvM)--RgpX7_=v$z1iF3*y@n^>G-=kxTB7yB}d>4otyrjnd>%8^8aivi5^J&Qk4alS7NpxEAH$v9^Qm$f# zq3Le1j9cC=)&{1Dawb%pY7PrqZa`n~Am0C6m{Q2E#mpq(FdY?;@_eN`Jogh8oNGnH zwb#fig_;eE|6rh6DHZyqkaD`ey*ca`2*RHr81y|oTXFo+!EdyteoE8MWFOtlcb?Q~OYAy4NkZ zy03a=cAUZ∋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�!&$eDGM-V0j4a#lm(cw08Ii%y#F-$2YUED@E5d1$%xV(EE-MtDSjkZeOWA!yDe5z32{>F4rne zZ^A&d2r}Y!Xm8>5Qh}PfB%}5uQ=}`hK)KTr3v4G8$B$c(@_9mgXKsH;II8pX&qRE) z+Ojyn;sA>SEDo?Zz~TUl11t`(IKbinivuhUusHC&Z~(wP`q0c8Q8k$6IOIJm4(mm= zOQDi*bEUXh!Vm;AXvREjOi0XAliv}TqDOgVL^%UHJ#s8a*~J-?mO>U`cp%6_&<$us zc08kWTW^~AzSBSMOhx=rEIYAXGQEE#P3##CH8Pa?9_S;-D>CPcdK2Jq_;R{Kse6Cu zWWTx4$qx;^H+On2!CyC*_{EftWc2F3CY%J^P`XAvZ$9JIBz9PB#>#TxkZqx@gm`7` z>08>+WMv-8{qRXE5dX~{vtG^4D;QNsUER!#K!tFxd|bOewBR^23O*uKGu z*R_)*SM=%aa2-c6R_?mtA-y?&e!c#YX7`k9gRAas4_k8GGJ@2$`V?0Oo(FZ#uuF8+ zzL*H!y44Ga+|=A8D=4X~s25PH0LwX}nV!LFZ^Y&opRSa6u*dDOO|swJy*kD_?$`fy z?h`$$Zg`KaIVQ-vV`u$-Rt0WG<8x z3GCioV;@)Ns8fuJK3N-6w7t-^^LS(0a&1L5l2}|~Jxi<=$C67dQOVj+ zSlcd3IbrEbEUl8Id$TMQmeIsAEm;OQ3#MQpCoFu4g~GA0N)~*|0-0G*Jj-Fh@}aOi zO)P)h|7owKBOR2=4_2yoAT3NkeNZz8ZXvXsm+bHV3{03ZS|5Q}U5-pHcRNMBfaftA z6u+wcqT?pU0AZaiVLVuv(!6wutT1Lbva%FhSQdD}DLkrh;Rz5(7JCj&(zugGw*pDK zC<+HL(s*IJuj@cUMr99W+IRCJZdH^9O)&Fb<)9C9{+MnM6m? z0TC&n=;^3O*>C*ZUPtd=E7&)fB&Cvn7;(AS*nD0k{22<@6PO!i5d%}5v=uHu=8p^7 zHH@mb_r~K9EvCl$y5>gjY^3DZkCqzVBjJ?gW}$CZ-gka%_5m7kp{`zzzrBbJFT{HC zwbZzDsyz5DG=ayxL&l8)KRE}!iqBsDoH0y@KKB*6cto?$&b+o5Dgrw4UcW8*k^nom z^GiO%N9@I#Mvz`@;RKk}x}3zVs--i(oW+jqu>ob^gu5ELH*WUN%Ad@yRxqvTzdQk2 zHYoJc_ezo{I`hR1AuDIlTpm}b0Yx)ki%asSYXz5*3jD5B1ZQ5M()}!8-D`Q;BonL2& z*d-|xP82>Ll|p@-S5Yk4=+B2eR7N1$(sb?ABnLB{J-c=Ts1&x{An)nK+1d z^=qoVqfveao3qLe(42O);w809!yMH5-2GcyeOVQjo-0pTzhZHM^-Qo<2TM+{WFc!; zVC|1AO@XB|vGhWghRm`RSXL9ueq`CmEVO`yo3Ich7D~oK$yg{E3ngQrWGs}7g_5yQ zG8Rh4LdpJhQL-~@uHe31fxh_Cfj)B(3Or=|!^}xl#f?k|QgWVzw6ASZRZT4TN*hrW zfQVD}*u2brv){Rl3O%pl49oG>$ceF*trxCdN|zM|cC`azdaLwv-NJN^CUvTtO|%`r z`W8`ktwz_fYa;YZbt-Y%5$b^A%H*``5}SENVfAyV+fn>>t9-$awcO_lUl+J#dt!e~ zD-R!7*3WDjli~LFJ{=8~42cVt$gtGirkDoRj+-AKU-f$4n^Rp2y;L(G8aV#SdTAtj zG8a*;OTFrRUg>5}@8@J_hnTsPyzl1tGlkhy2V`D;j<=niDhT4mAPn8`*0Gmp1bHCi zkD6mTc*!Bv#@6o$8PfNL@?|`*aUY=1l`mni1n>7a9Nf|2&c&qGiqTAdpuPaly!MYG zs={fi2SoG2`_qcVABGj#Aw;u%!LV?1SS7A~zHX2-RKmZi9d1;S*+xH^$C6G+_*R9G^OWyO)QqDpKI|PIospN*ZBbp>a`oMjA^6L)g=EP z!*H4yGvd1yWiSLUKl93Y!C1p9^A0az8c_p!X#vd$B)jcXPuW?jna$q>!V~k&@JjsW8l$7m4Y5lD9NBH~Q zwGmiYw?I~z!!V!c>BxNVP+~K&PBEM4!Bo z#RO18L!(VX!c9Yi9G>3o`}PvZt_4Gx?!t@I%MY534@UU5)if)pi}TMwj(1nSj07Ja zz)8hpniq0TqpaCgTgH)C;k%#SSt~kgmP->Jr{HL4Jv_x=HNW=joQayNMb{0ZMjyfk zG^5?>T4gWV`|SBgnQau2;()?p+FDzY(TcW9>2vdBi&lZFxD&j6rjF^aP(@}IbDq5N z!d;_6NhJYANtQK4#-l_+J+#DF-YNxw7`(lcptSVw6ZAtaJ^#vuJpApdEpk1A{w(zEFpBj|UuQkgf}RZ1oq$b`z7ny9f1;5WKG_u>D)JP}_)n+ympd@^$;= zZfc%9+!UcLy2r-feis6bJiQU(;IaO5hwMWm?3tsa^~HO|3qCp8mpA($s(^j9vgB(1 zKC|{U5vyDCT)=Czw9?KNd~cuXwRm)roU}rZEja49D-4Kwr(hTUE<+byiI%_H@$Sis z?8oxW@Zu`NryExx3HndWR=U0Vm7{X#hag; z{uUXH>=>@~Pjjyl(X}4_c5|*QsPx1|qQj<&ETRCB7xAGxV^MH~cfP=mD@xONjmx^2 zl%;-$`$x>ku|_V1()St%6l6G&hP_2xS2-#__i_?Y@Ljr>Q?V64w8IUrL-VyU_ePkZ z<8mLP0zT6l%8VYHyQGK<$B*X}^E!gs5GdS$B)>Eo<#04Q|IX~=b3_BoQ6-O3pKf`v zmxh{uWCDI`Q)XisP`sf>VYubjAw5Sjy&<$dA`w2d$qj zqU)3Q-`>^P$VoYp*n>0TaL02%YA;Q41RSo`D{wgS#rx#R`fMjR^h`a-L-_qlYr)gs zy7?Es-a2Hy$JRtjGtv#_(7ihRqPGs7X5*H>PqO~(Y!Gko2@I(&yk}_$68xj1p&_=W z5xizl<3x3?T&r=3+uRd-s9(jM2E+z9ka6Yz*nV>1@+zvJRMdE-3o`>oNxi zQva&wZOwd+!W2zG(KD$W%J2OEwY><8nqD#9Y~c=~bQn<^FbzzKiXr{uBq&Wyk40K)iWj74(Lxb5GUW;+Gv<{Yp^Q0r!i$nw=U6d z{hXebnL8tu7Gwc${1Xh_XI)y&%;7}Nsvp9?+y3y5oe;Dn@TC9>SPanK?HD^n*|`vW zt9Osh*=QFrq3t;N;_jd5?7M3EYO!LEEkRnEQS%Al+oRS+K2MkIv+*QR2MrV%`xtU# z>yqm+Jd^+!!-Wb8cy049ip(C2CaAquXDGar=Ot8Fh0)-3|OA$GpQ|KU42De z0JCr4EzGa&pw(Xg35NWDw{qWO6UPIBs{(FqytpZl%lHa-XFv-cUQb}8H(cu3yuKS! zv`fli06)d|v>$x?C;IxHn(jL`;;_diY60H%jSZsa2V~V=rGZN8rjetS8E*9bbi2ld z$MqI@*@mqzVt*T#g!7mB6%%~@oqMB;gCX-Ftv}L#`ntVnPuVuR+Q2_mmH|!Jwocei z2qOU0x^$oZ*6d&WssZ{rtF6VDop7O$F)^V%FB^ZA#!I%^P9*_Q)pAM&{`NYqEqO=O(B^pt2iW6}(H?x*81CpHI(9c`X~DOo|+zz_0HN!b#z-G-`K88T?|_4>bAyh!>fV_?)5Y5loWP!Hp3}7 z3?O>)=ii1^RCaTZt<_+iamhBg#z_DrAk00}_=1W}FIc$Ob=Wtp&VAN!0cyBtAa-YG zLrvzlX8+>XeOy*Q1WWSY0o;M+Y$U{qF?H*%FK+(6iw^g8+rEDKmN^-dl_4AK)E|tW zCA1by7R~?kCpf}2I~TL1PuXVF3<}ipoMMPk_c4z8=Il;aX3dj1PG)_Wrl}dOqXlM5 zZzsd=$^X{Vp#w|}rDdEGAuGb0pNFPd$9o&KC7ad7e1Junn9aG;g42d5I(ux3kx6RV zlcv3aoblKQe3{Q@eGe}*0UJ6&F$LbH$S8>Og(960UXy2rOqKT7%Bn+l77U3i^=mgl zE3Rv_lwHAuu{P{=ve51-Y>B=d8r<2-u#wzjGZkp9=_A-|h8u?P!QD9a*!=4@VX%*Y zX{VsFq&+qS`^3l`MRrF+tTEb9F?5fub~I4E?wi0W8USizo;f`9_nWtfrGE@2yVVKU zxU+8!W))8c&%W4Fgwl2Q*f_M8#uGZe0jP?j?EgX7jh%EnOk|HOGU}pIjHe$M(@UP-$Y-FJ`-Aqj7HW(jJ?t$y#6;<8H7h)kZt`o47ik zhkvaWV`_VBZR6A)TV@fx4zybcNboJotzYKMI;s2@A9D1K*T5KUaVNb=ur-oMyBCi( zLWNsd1RXQcCx#B^5s`o&F~)Ovz;qt$LcFvFd|HPXNb^8P>0##wl8^=|D%^LX4CULx zrV?@DJmIBI*G$dZa4C#>9`_-(jH(`d3giBvbjS;cM4yX{LWH-aLS)VEV{LBz}xw{kJykfdM319!MnSfBsd`>L3eM5iXo!eI|=-9m^c-AVR&5Yhds;l2n08?vC!BUi4jap*xVA)DOc5 zKhbyY!Y$5>5`|FDxdeke7mToP^z1m~z0&L+x zyV-#FK5B08vT5+QL&0WU`7ryOuOa{4AWrTgv-Id4S|8YPn%sMA*Z0__C^q!aU0s_x zW=85JBc|}+XMojH*V1C13wTA!?)vYsbr9;;IChfjVM2Rs;W>M3r&RwsjL@3xhm>-V7A9u(+5@3AgZ!s*l};$$81h%e6@V!S3(fb_ggt?C9# zp$3PBMj&ML#)t>k8l+rDywGYy=j0I{}If zAE;c)KdmL|ImQ961v#v?|$$mAL*5i4kxTY8!$i zx8-d>ona|popo*-U!+|xng>cEXP)U^<4+cC5owMK<0&_CdiYTAN{7dIw5^G!Rgy+r z;TsQ$Pt~R#b^Nz4hc(Op6gC#8T)W41HPy2R3k7=a%ZdHv_XK>$pZ^bSPD+-~9WemT zS)&d$r%Miq@M|?hY-19D>wt7wHoBm+Ag2$PJTj1{!G%QUCB2Koe9`qNc^xl&+Z-et zB-fwqx+P*doayWlrD2WJaON;^JnZeQms1e$OYLvCf+&m*Ao^H*THlEMmfNTCV_^-~(SptQj>uRL)IEl7R?>SjFGi<>L%FNDxAGrWen zJXeaM3dYWATV+y{Hrt1>(^egN@`a>qK~H*G5n|HZ9*PGAfNSicT3#`q6(eOVs#Je= z5+wfdjPCv4Jpz0mrRF2|_mW$bu#yW%RnsC1;vw-N3%b#hBuQPML0uYM4e&~}Shok) zB#oJS02-pW{-gp&TnhklKiD*o6OQ}ULp*6$R!>&wA9#{-bLpUkN-?Kp>n|plc z)#@%SER`B6dqk6o8cyQq{+*t{=OQIJP-vpN-D8A&4GCNGat?e}bCxbnS(D9kwj*N5 z-75VB#X2@Rd>)fGq%jyLZEnYhreTqW{Bk4n2lWMyFK*@TS_V zPv@j+F}fT91GR$ufEQge(5wX~0MRl``ucmPf4?tJ3xtvtuonrFN4lBo zCf1?LcBiVWOwb>j8##>>4}Z$GJr~yR%oBC{_RMW3AJ{FKu$Rnt2HmSEhHrmQC3_xf z1MM}^2E-A0OX4Y{6sV+An2l31iK#77h71`^x~DY(jc*QQSzRLg5BHaPI-3ZWt&MiVmwzZr0*xmy2 zE!9a8YX}SBoj3pBb;L9ESP|7B+N-GDg~Fgufw49@C)w+!T(i)&*DsNswpxk+XbJ$U zlqs}2OsoDIcaBR}4~skBJDXTT7fA{FMh_lDM433HdDBdGN2Gm_;x^mX=->s@QLpRz z=B`&=hoV*d;)01ut7_!uB~q)){qm4IYj-F@Hb&Q-t z_eI8~*%-3HZFs|$5a0%Waul0syDj-bDBL$$J?IIZQT$+cqgYooE4kqPFMndJpyE=% zq+$Veo%%Rv>G3UER_!60I5}n;P6)2>yR8y@DC^4_V6ZnBfjw>Ef4}$Nd%Cu>c<}yz z(W~pe#($~Eufx`JfGs(~=uqv84cOIT##mN1-g`sMm61Ch{6(NgM!;EvPLw_!q{sL4 z-?_2R#F}ZU#b++iZ!*`aPcPt+`W@NskVB)MiiU&b@KaRz!13O!L0Z;uhC$rcBGmG4 z?GCaJk8V`$u|)&c%)Cx87cvqs57>Etm<@80-3HAx++Tgm^LM}K-}$~T<60MECHPw~ z!-8**%_?}dew&%b>Y&S@ZCcfCJN@eUU#6#io3Xz)`i|dxA6sOQ@BV*7LHFzW`l`^H z-{B{&+YVvWAClHi)$Kp)6=j>MVt~fb>`~4o?tIO2oERGD#&eU?`es!Xo_r}g628)h z$U%KP-S7V|>fSS|$*o%(=Gn!DWuqceRho39gpNEaH8dfFKp?Q`LI_9+RbX!wlrAMf zx&}fZA)zJ^kgzS(P^2V~gd)wlqpZw?ARs=T$r^;s5j@@NfhP4eP%#C(j&?#aWZE_eIss2zPELu297r? z!Mxaolhv%(Gyb-ZqOMV$Yl^~Fu;`N;Ms&w)^-yL-T=92#FHlv<_dyy_|Hc)o$EV|d z@RSS=Joa)}Q2peUhcGzb2X3F!8B$jRj7{)$&h%|hP=jHbU}mlEgH7t?(;yZ4yn+(E zZeA%a%;>#N`q~l9GlTA%x@>&S9&;&KPAf3hsEJXo%MQH~XGH5!;q1H$tcy+ioHB>Q_#7UQGtWU65z zxD*j0UMYfdWE0_iZ5goxnnMyVYSDxJDccN!55w3@2Ctu%j^DF@2%9> z1*<-K{)3ssFn>{5qbdwy;1%%JW|gIWZcKQm;ub5v32`AiXxwPr z-be88(Xi`I)xh)j^Zx|=JEK6Tjed~}L}s2e#rM<7jw5zyaM2fsxFrEbl~3h!F%!Vr zjlf;8d+Z%o$Z-x!KUHan{jH&%H5z8VU36MYd68VPR6ieA_&r$u0(cD_&YG+e?jl`l zx@g&T_?@zh*qv=(AB*0JC`^+b^B#+`Z(ziAa=`liw3DNV!{>G)CUP^;A_xG?M6e^+ zk4P*suc>P*3)`U#2`dE|aIwYNd!(|uwTf1oKW5^d0JMPe%eijNI#@8pK{3Po*6- zPUxn`_Ft)K(@o)|1DOX^`@()W>h9!Z`i;j)&tA?tr+cK95z42vRxQEgx~?#di2A+> zCfmcS@AihlQ8{3k8MCdqXwanQC}J>f;6STAH1hbe-c=QG7}vOdLMI=*U#4{}`|ZSb zfm_N>CTs6~yz%R?8B+fuSE|+%CpYZhQZ0U^T7FpgTPgv?mbAkNu2kM5qBU)r$(#%f zz;&aWVH2{}N?R45QasJqP4%ASw=}b9R~XC7@qwfK{nz2CsYG%gJuGyleev(p@Uxb0 z@!<>?8UMj^P_KQ`#0_4>?W~=gXVrHA0*`aHyw(2f?=AnY2j_qB=l@NP_zjWl>?i8c z3%)+R9^%tNq=WnSHWtX{A=lOBm?)R+1woD3i?%4 zAV zd16a&bH)|+&1RJIRJX>vtmE+VvCjK&&KT@^WkF0@z9)6I8@9a5g5r>*(SN?9t@f7Q zKU;cWCcF?zo*?8Isqg;a`NjDsXlRV$-7=;P2(oCHD3@z)TVoC%>KvZ7=_0?zEB!|1 z8?rZ@9~#teEU{?oo?EcD)V#ne3~@=#KQs^(yl`7#y>xhsh3sKGI&rDkDc3<ONeQM}?|tgC9lg zf;dh&@_89fvJrXGgmA!(PYOxQvZ3)h)WG5@a=V)V1}hN3{Q~5g%P}bytW>?@f+{aN zdP31Xp6kgTkM#8^zrpm@T&L@lMl8)`0dRSV4at}&j;kZ>p71gkcHyj0e(>0)%cX8N ze8vMEohqAyhxEkZFi{0KZd>Pv2Bll|2Qzc-SzH{#LFws&t6!pA;fP~Qj_nfM)$EH99-4P9 z_uJARH*FU#-y>+AF@oCPs^-a&zPOubipq_4JsIF3BKyjLyPG zXY4|pljHp`YZgkgMmy=%^|oB~eBm#x$QS>rrcbxYEAsy;vg#6GbyrC0DHyg@TE`q% z?|Fsw4fJ1GBJ=q(F7eWuY8_`VZ2@Nb1K^ zN^9wnblM%Y*gQ&U$!*<3yEiL`zZ3si_B_fYy@R0W<`9s_l&Yz{;Vtzs+5H$ z+0eEMZeo*gF-#b6*92hG%T1u1amHZEY-~Wmn6fRq`TITwc`>-p|F%dZG5+aXnA+!?jbnmjFv8}US0vv$ps#wDL#cD z?8V|CUec*Q77OdbG^&RVavm>r!F-?A_j}ERS-u8mtWA&4oL8A)nScbkZ;yj#Nv_bA zlfmRrnWxBYJ1TH+FxmJ`**kNEI}h}%lGHQk$^!95!J22QcLTe39*dXzcb7A%cXB7w z3c~o!aB6Med3cs0DL%#YU zXoa+`)QnM9Iy2-0x?X1(Y}G`c*fEAY8o%-9=q^j{Yid>H4hEwDQ5ARxxiWxwn} zsFw^j=uj%4QorfN26Mc_KiH2X4;KlO=u=B2DF^E67a$NG2h_0#vjg)VT19nRDo-|s z8t=lBmMi5ijgCrA>lL5rU-yp&d<-^StO$+0mo#gmcsppJT|glZ$SA0MFc-*X*k#$4 zYu7Ff)zb2P8#*MUQZw6Uo&>AZ8gI>ohz*B07kT8BSIo((@bmM5qU6LeTbMQL@Bv*} z$E|w3qP6(sKpJE!ev9$41Id~h<@c?L@Rb9YV6O$Vyl6dZB~C z0O$O%`gCg}=lXVf#Qd@JWbBku+~K{li`pOKK4V)~6S8&?qoKt=cuf5Jw}vuer{NhB zT*%UlqTFcibMo0Q=&u)_u^(3xs&){iS#@0<9)GXv|251Jd49z0cby5jtmZ3PpYB{Y zM`5n@%;hR5De{AttS$LUpHDLtmF(+})UA@EwsBL~bCQ`dAU{Vz;Ydnpw8PkOCjK^I zF7R%9M|Y!#$o4l6=h-bAKCnLM{Krk*7u2g+4*qedBY0s>Eb*mE(u;{Enw8n&BFy}X zQOPxJ;A(+<%!m^r5rf(tM-Efi_GB#Y`KmV=y>R*RvDrDepIb=bJV1cb445#=%<$bg8i!;UXwqikP-pbfbZ1T+}UPq(Lj{G2E7e1+C9I;U0 z_5Yb{Cpa*3BW)=^wZMyC8>L@4-M5l45cYUPiF@lyPjDaJ{Qo~NLcGIq<#+2BupRBr zN$gR3WRZJ+n6xHw=-CMRFIRofGE2b>pn6P-C!Tg=9E{%$;vR>vxph8?u_LMSye6`4Eh3h}`HSw=#U1Sz~Xm~~DP@s$f5)T-T^HyZHskM`T80ULU`UYbMq>^y+2>{c<^J7o z&}ljd-Tq=6u2P|P)U3hgB#RLFx&frL_L7Y*3!_Ei^5Y2u`Oe_;&wl$L?z!ZL2G0mZ zs*R<|bq_Ac*fYQ_gfB|ayb*uYXW+hcxzCG)+?Tt?@4lr+Pjs@Em3CGL13_qU4{aS? z00Ms5f!+Bv3R!D0>!+^+Z728J_07Pt{nkFdQxSs1C{OT3jo9|7ZImr3Hqo#n8pC1Z zNLq0laR=l%ZXQ6?=O@Fzg*&f$MAmzx2L%9uO9Bj|8%)2KG@g4EV4cI!wlTQRXD7WMQ_hxqWfl22~Nw; z@LVrOQGf^Q3wdN;n3c$pXFDO?on*tCn|t5!*A4`vySmDTkw#1l@?y_IlPHJI6)zym z+B)6M$)H(PFIUl@n?}U#fuFuL+4sFN%#llY(&Sww4bPf;T&4HgZfrje|8C(%{P$H2 z`R7lxe5)idVRJpHD?1`taIxu#!=01l$6;2LM4PaM+WM_yzp#lVT8s5?4yqW+xSIUx0CFeih`F*X+anwQkvQ^DCFC0H25%EVMm~ z!>X7|y8R?U?Wd%AzdW05Y~YS|;)}bVGXn!~fkFeBi)6B9T5gN4@VmA5fK~^l{UXfT zl&qnvSAFk6KrRUZU`|WeLufdeiMvTjO0s=_3MAw6B3N=w*KxSKRAuj^CNsH3R)h7= zd81#0l|BvPy}&1OT0`fEbI}Dam&qhJ=4n%1h5=}8=7L*Dlt+$zx^n;OYg(2-Nk~4Z zw8hs^$4j7n;wxp`tkttgr}fXMciXaTvG*sC$3ByTkAqQ6v7-U4=R=8xZ5WeMtKiS8 zrE6HZOg&u8QLr7ZXD>c@Iln`(9(y0!*d3tz0jn(Va=?Z^;@xu4nWH!cfpU0eY*i}# z59i#@og?+RrvAwam7FP?70D9S(-7vq$TPu~Xa_|{q&#$N(N^$l$}6bV!OjMvRH%HD z9Q&-H>Ph58(iaj7vs4byD8K>b6%X)!&}M(r)H2GrlhCknwuKc%4){%2FQqK7d%>#= zRlN-Ay87Fr15E#gUoyahWC>h($m=~PYKBE(eE~EMoCy#q|Fq;l4A#70Pi~$p@VQQE zY?rLlW5Q$JOwDr;Ch^6p~Ic3Ej@9Tg;M{c}# zYhHwt0cmZQB*Q%x1^3vLcc< z2-IHNE6x1K2W5nP6qRV8LWe&J%?H}`ae;e7X9Gcc8i3Bs_NCsbCm<)1qI)+!XCK`q z8eH(^w&P*P0`&Qt>aqF)QE|UEL}@~4r}k_xMvnDH+lMl_Kwy}&Kw)HN0x;eMv1in` z9Hw^HoPWaLLSVV;4#F(Xu1a-6zxuI41EWkf|Er*W;1;vngQcK8LIi?_oGN$W^LNRz zz(F!mUmYvYCC}!Sap`SQN&Tqi(Lnpc)b0j(81f=NERZk!V{YxDeDZf=K+BFf&--&xxy{#@QS^8I<8rq3-B69% zSw+14_>)E1Xho*1#PSI78|@zvh+<2I&7&3&xZStA!pYjdao7x1Jq%nnIbYin8`>+8 zL7>baTGpm*ddtk9y*Mks)3!97a~*T2RpXCpIWcOeZ~!=N(Yd+ds0#uQQAQPVY?EFAQty5XeZY!U71#I{RBMsTaVp(91_X2`#V3jS+M9%4;waIw%W`v?!c zoAI(^C;g79mZ#UXm-#l`qgGiRvn)o0fBxNjPl<(=Ga<6h$vv+BfZq~o8VKiP&e*C9 z@cy%!j*LFRqzxD36%zBPy+-!UdN5t*T=+~oe_xo5qmW#{Qc-!n%pRFv_OgEiulSDc z1uImC&s%-|%_rZrwR?*kLgZzT=nbEkqAk=e z`T${02%nVqMh!=rlTqR27`$uG;?felsESa5_UfLh3SRf0JT@KTtI=x*ocEY{lAJ?@ z&68#}vvT!+c~GhH^@Xft&0+B9DqwBlyzLCpWh@t6Fq&3#_^Oq;eU0LKKFE}f4JU-- zu_8=*i&G1K6$X3O$brZK0#QE6rc(9?h?FQ??~7^OiycRG?TP@sR{8M zj;^Wqx^jibh?c!MAeq#hAV0|XTKmXT0C*Rfdd-+P^Si3n{+SVb$7r)tyi#C3d=Va> zX4&LBhsz+ectq!-jOL=lC9a7 zb=%PbGlsJiW54l^%j0RfFIQQuj%_>c+86Kk);ahqd$t7n*>zN08g<{NvlV&y1=Bns z??23pUw&V)AHp(nt?kAIB!n8m*3fS8azq?h+sx!gruYsrvTp63GwxPvof? z6Yg8OCDp44dJ5;CV_jvhkn&tADn0GgMphbhoi5E<9b|xh8}*X9VXLY#@$mge**%$D zLHUdzk5g)@HWx6kcQ$gRtmd|B_A^6PvsXICeLaZ{_O_qOGc9@Z#UN*@EVPN>WeHR{ z!{viqMSwS9IvP|6ZQKNFP7kzSQn4_>RDsX8J~HtOjnHph-^UFp-WusvT|Va{!dQ11 zoFg(&ne23q(;rO1REo?3=iC1737Tn3yc}AWP~JGxQ$2A*^}%F}xiiU_Fe#kN8{Eit zL}?MT=fUutaLwO8VfDIKiWECr%a*)6pMe|2HI zI(b1psGND?YbGCUIB1Ke*{aUlZ4Yua)BV;N+S1YSZ_f{u;v0LJBfmFE*rw z^4j2A#19^9zd~GdisoKUdd8N?7JHKHbTF6w`DlQPaB)+GUc7lbn8GDF!hO{0D<>r* zlDkd}rd4ge?<*~R)(y0u&aB;rW~l6+3VGV+@rpDX7?8P&NV#uy4_~zwkhH4cz+u`l_R}Et*`fV)|w7@o%WZ9O6 z&#V{^zqOXI-oCEC3q~OPSAyVeK3e@ZHbslKDeI~GDk6rgj%!EzoEFXaZEL%W*B2aV znn71mL}I&2OXgHzvTu;m#Lii9Kk~Y&;He8w?@ea~U`UTMFUntkR~n6#SbLnLr0f$V zpp@yyFqa)E=XyLwW)|BfcZ>3_yAb=jo3z*?@*%B)e#`T*+Pk?C?8?+smoPHllP$}W zidxUwx<1T}1te19RZi0Hl*}*3<+M!qUZ+eZXO4j|qnBpTDwrq03IyJkv*ZLv=5Wkg z_=ydmA>ihzB_~2bV%N$c#Z!utEe z{F9v@JnJ1N_`W~i#%<${U;N-n0l=(#jehX>9bdN)3;o%Vdu^w&@tN#*vtE(_cUbhowzDUdf2 z#R~aN&WL~lTFib|Ead~;q&b>$(BZH9+m#MT!%3*t=Vo)EaZL1 zFWKlQ-W4xt)Z0c15gi2-R&4k46-FS0{RUpK6v;M2>xz}7);Std8Ipn5YJ-CPBUMLm z+s1WyO=Xk6j6@}Q#WU*cAVaG5MBBb)C9aPF5YwK5-LJti(wVqac@ap7q>xHj^p6)U3Z0 z65beaPjV{WDf+8MPPA?6qqz|={8g7kt>v9@ZIYJeR9Mn>KrMJ+u{q}FN36)VRkhCI zSa^U)RYvJ6SH=1oyP$VT1QC#z16rZ8hA_?kFs>j}Vl@2FZsenWQQ2D`zl>QVo8@STXGPu3Y@eT9 z4-W?4y9931G^^r`J{$^kH)TcV6U~0Pf-Pt5M}8E`els8>I2boDeU@ky^K1kDGt+Jkvm^ z^g8|E@j4bv`4Y1EAAD`@zs2r8Ngs5s4DXEDm@}~1;G>_`Eq+wl_EGP&r@}xO+~*2j z!x3L@IF>|2880c{GYp{04>obKh}=?@E&>osC>aUN-UcSy=wM1ga&ii3A21j<(DnC& zU(oq42-g-6HI+2ffr3**R~nJY|JF4zB13H6Gy6iA^Z6PwsoKn{|O z!z|io6XmUq;x3#I;2eQkR1ZsA5+cwCcDv_W`O70s^aXEdo+j)r_o&xN52~oHJJ^5B zNXbfzKoRO=Zrtos@vd@gx@UeZV4)U&vkAh+gpYd-6FoJG$SWq4b2va}8a)3henfoD z$jErg2Bc*-*79_)%YtF&c+(Gqmy@41GO`M_19!`XfeJ6V6!8NxJw66VspfJCogb}K zzj@d8N?m?DVOE(HW!Z*zAX6$3!?=(J4EEP^+WaJ- zj$N=eKfgetH#bfqQ^D%9n?prF@hA&b>EiHE4uJiJE92ER8$Gh>>G->{}oJ$~!q6%&`Yw%)tKO zG1$;hyz`Po>=xgy-kgdfYVLPIcuIlZ7Kvr-qo$EP-COsihf8HP6*;0tTz}Dp|3i#9j!#Q{KFi?1Zqb zfGtoMzUD1gX+`MaN;_DEP)j^LkM?wR`%<$?vp!sOh)Uo{75`Zn7J2->r|H^~#)%WH zo{?#>)~#N&(1lggdhxky5|PH9inPDySWpb@93VodPe;oqT6_Ph2v|Ez$#*89w!qfC$V%=_|`%H zlJd~yNSwu64{iP%(8+K0Tt1GqpwDZw-2vvJ`R$LffghI?QQ5TS2f^fs3y{}`6GlcJ zLHbWiQQ!Ou{|v6WO00b70g&6hTpR>Z^cd&}IlXC{9Tcl8yu4p18wTY~cFSGrBA}|f zP~EEjUyEQT{Cs^56I8>|4Cm!#&EJ%>&w_!q#=~Y6l+u7J(X4c|+Sxw*%d~)5SlN`G zYEc2sMg8VK{?s<=Y>E7orjM8~LqKxs->dHk$maA&PHg$d-I*d&08iVdj?1?4Wesv> ztiIOxM+)$YKTGU-xpmF)>Trvb2NT@(z+B&Xk(g8@6s7mN95k3| z_UVIW1h)LX`*&ZNxmlY(KD}`=_W12gC5BLP;c}Z4(-D5v{zSmhNgrXi4bmU;+|V%* z*A8UeiK*^#7%#B)SnHBDD|jD|t-br=NquEn z$2>Cga`2^P>$9K3aULCMFlgbf)d~=XM3b;vl*OU%_LM;s(cpAhy(Z$+tRpEB?1~!P z^9r6O6_<{Bx;jvWrd1H(9i^hia?_1R}CA);s(+e*AYvr1p+w=V8W zWCG=F$?u>9DWV-5<(x!}_GQo5;{m}8lno1pO|3}iZU&S7>Zn2Sch0g6LqqrNS6!&0 zN_S=;A?uGSp0`gNk!5r8mPN-qxi)?2)Q28Q>?Ujf@`z@wlYC*fhB4v}HqddTRx?Cq z&c%0}0*hLb?&YnrlyfF_VZCTIZ_E@eottgD02ck@^}Ba{Mf)0!f~j zET)%Bh?cstPHQxhF9JQ-0E5~V<$P=MYR-gNAylr<R# zlt3$1+&@l^!9%qg{&AJmz6yM*;HAO=&$O) z_skp^W>fIO(Ts{3`6mm)FFbm{_Elb2w;~q)!Bnuk^6g5HdX=LucO1TJEcM2A{xPjjcen0ZrVtry<+2 zK%1BwqV?|qKJFg-*Vj*pV@n6tdb`t?RH>RBDW`4L&$*r(JjCgbXuT_Q{WBnZ|G}OG zG;+*2x?;DQbMTYYFus?=if)^JE1p|U4xpY=Tqa(@X;Is_0QluF8=_SLPK7eCaG;aqa61!P`lJT1YJ6AHPd>*+<(z!`UK=Q*;-y#I=P&h-h} zbp{^e&ky*m2JCcx(~uF%-{)_uomgM~G7W4PV8eGsuk$s_GDQ;o*T3GXe;@zKAN%@A zX+c2um*T%oeRa$xCz`k8LNpYoPiVe7Qf+g0sBT4hTR+g6ur#@Npzn7O+5Qe9N$HWp zbuZS$+nv;(8ZWcCrqhE_cDmH;ut^7$&K6j zDG{0F<4YKfRqow;p~Juf+pV?Q1DMzFHjya52h3Nfbgp$2s$jv#7%Lb|@ii^Rol1Ay zeKNifdq4OfB1T*(^!t#~9|;_%({i&ef7omqvy6YGY@DVVBQITuZgSo}X=G)kiF&Sw zoX?xU)>KEHFJKB`%tk+C@R6x!HH4)I;IVQ^4SIrygJuRJdOcT`LbvZQ zhCYIRB-Dp?c@^Rfd$0FsN!w#DY(_qx+}TtSSu;(Smef1(NxvR zL+;~OQgr9QR`I~Er;iDTD6`thyGTadUniSq7yk(JDEi~yH;)~iWZ-fUw$(Rx>UPHp zA1PuA?N--x$8?}biY?LU!TwJdpZ8k24&k=q3+-tk<(E6)n37Xf=Oqr zK*dyTxdQZ?h2PJ-+3pL*jtM@6bbByFP2!y@;!PJ8&Ippsq(YQoq-LLd;y9{fy!`DOyy>mbq_)KLo+L(?Gl}arrC1;< zQd!?@f47)Q0|*pH(|l43Bxhsy+QG}Jy^e1*(wtr>+bIO+KN&Q*j4BhE`f$!E*suP9 zw5_a9*d$^nS~1yvNeL^Da2s2MnFNr^z2`rgt7qWLg5-=>QdyQ`-WuaZ$Q`RC`3ABZh12j_bRQntu&mpG16#pVsR{pXd|!d+56my&C41z?Oax9d2W~n zT)(Xhl~>)@R9ymUSw>##Hf_Z2;J1a*)aVF11*D~gjrL+%d6Cw*_%@xa@RAWV3-S$K z!FHEH3PA-6!P>Xt*We&N!+D7-!EUKw2aBE61NIX`%QZMw&vb{_S=$dcg53b1(U+D`lYDyzzz0%)lFtN1ZzmhjvhQr43OZeIXJ&~$r zSA-S#T3{A?-k!E~)s{bd|G9N&otW-(jc~3+WOU>V(S6D$*N>n&Y~-iJ4K_+-x!d<`v{bCx0#SbSZZP?yoymrhRjLjU0BKk58FIV1*Bla&@i>j0WS)Z3)OPv7b1|jNLK^Jh;q=_X)^-$e!Lsq2 z?^t4X=wjDxR{%kdhIHu@WWQ&GDf2hb@Si|^A@6QQyq3Bl-8I|iw~?Os?Exc%Ob054)6Ijmfe8GIrr7_M!{c#3Hb(_{rIDfyqHX^%|_M%H)U`dnPx)svJTT8sWxuHq>JUxY-@h z-~T+y#jSB#@7hRfo5;=_o;{WbOkq!lQ5tD#Rij@wk1Z<&xxjy4b95;4BS+pPwWiYu z;$R4b}AYzFQmsWKHU zHycVdoMTyRzLhHYgJB*p{vZc_ZPV9-;5qzkdG4B9Xr84~e3x784Ws4Cu=edoix~jl zCFopt31{a7-;(2wL+@!bmOn=g(($uzkbSz4*mH~0c2WviQbKwp5`I0vIk&1RDE^(J+^(_nPHz7CctI)DY^#3M*LE!g zA);~|b0gVItD-Z>o?Dzk772CIbn@kd!bd{ z3=&9$jn0`B-YfD61Lf-SW{*1(Wd-K4!RLSQc<;>|OQn2d-LRsW|K)%g7`RSy8XaL` zRVpj+a+Br(&Fceo(k8;R#X(NAxj$BhJWQmN71EHJps<0Lm?=8Hx*vMcZWHC^SY4R187178Srp!5 zrKtrR*@%Ylx@Tq^UCT8O-@KkQ619!>_k4bE`E@q~Qb$C&Xdb|qDU&vVMv6qWzM-RY zkKYP2i?U27Z%2bSEPc^=NgJP77CMoNwYD&a6t;;Z66WDdp!6;>Ue!~0o0LAv;6*BO zbbj>@DO(M%1a@T!&c)7v=Kw=e^iov|nl+%rbo6YbnP1;Tn)=g$pk-{J{fJz13Id{} zoQ|)mh+dQ&hd=b6aw2+W*)wmBi{--WK+xrSikJ?5%EZhVz0(z%sneAEjop^`iUG_p zWKzi!;}IN!lxP+pk zoRoqZ{A1YleF8;V%PX%V+Dv;;R~HcV<`VJHJr-D|usA8nmRFPFh!G?EWyzjm!d#&_ zH_!z#kJe_C8fgpPDCi`i1O{{_mA~DGJ;9Y2Vti5A!g4_`mH50?v%f{+59hYi4m8tMY8pi` z{NI+86JmGXUnxqR67A-rqQ% zyz~4jW{SX}S=JIovle*jTDTf0YC4thU`&d3_EV&C&&V zl`W2aw^9g#mxu5UTibx9>vKiY<}NcPG!u;eP4Gmp7zPF1JW zZyliMC&6AhloiK#o1((CNqu}^2V&Sp&u3LTXN*MiMMDcrl{GLF2R|1H@z=ZL6I6xt z7MfSQZ~iNXt?NPmx@q6hN)=S_(EUr5|21h*-0dm)V5Fm`?a))N$8X#0Ll_`4J&4O} zCXdBB%$63e8>sYK%fDV$;?Fc(_97WAYpae(uX-6xxH0(C>|lL<(|vXz=IN3KP1rWi z!eL3ngw;Y_YEjCQgoZID1vsoo8WVQm z$42Eic?G9OOL)vgl{gBE>{281+Qq5ejg!v}!Af|HIDS)HuBxD5#`*1tPw6x4XMawC zPz`uYF7u3pe?ZKVOl`w}`cT8ri@_pp^(;jFksoLX^jls+H~wYL889S2wCHXt3VL$-86!?!4X!avmKU12wANHl;V4py^0_S$4rIM3wkRSTI>>Fo0v-Cn6a0&Q zumN|~R`2u!r&z5r>qi}cc$jgf7A5~_m&V}o#M^N1IsLf@2}Ye$=OuIH%|Azr-a@HA z>FxHTgpNxM+32{*k@<@NBv zn1E?!7}_6{HB7q#FO@oPl|-;a>*^mf>E(qvmYz)y?m`t?ePa}es|sx%8<9}yLir_G zyJ>!+0u~O0xf+!kFLLBjd_K9k%S}bjw~MROTn1%<;J;d#cAH?rVJ+>gT0!LO4KZ!6 zXRMmNaq1mW`U@K;VLjA)92=;3Zr?nR*4cxWU;+dAU$;oEx{RizX((9{mpt;+m#d@)eb<{oLp3kSYlz9l+m@5T%RNC z!qN|(dmC}barX*#VG+?jqm0AQcAe%T1MLZp#f>e!xWRd}!Fapyk$Fewfy4nKkWD-e z0X~X-^n-_+_d4<5^TP#Wi{TTS&4!l+a^{yn+0E1EhQR$*sJe@RSrszP3kUyXx9`V0 zntU+sZrw3mi>$7pGx8+|+ln+FG~m0Tg>K-nN97vYUKWpo@}15c&2qHZ9{~K1^UYB0 zn%Q@aO;Q^qLVB~#`WBInwIVOo)*y6CBdrtsTk`Ytz-ej;U-wR8cU)}3Rv=GS4-w6L zmd*D5*ENC)5@uNHD6#$v_oqrBMu;=fP3ns?Lelg6^NMw$4QCoASQ zHQ+$YQ{{N_mKB|A^zG4(T<#l0dR_uLul<;bp+esBsS>`43z)uLn_3Wjiq=mu;J=Ax-0Oez6Q-W@eM6!BcLptpu5R(siY;Jd|06G>7kx0bT2 zF(rrO#}w9ibNeJIQYtO{)1phgLCIEiKEBTR+7Jm)p>yK9>c!Vi1+8+q7UFUwP)#q} zB~X1Mt7F8da!VrT95gFzW1Ub*{K4~dc))B?P6j(Uf8?YhNL@ z05wp57XChAD{gj9(Oo|5Qb|EWXez%MKqiwCwc{9G#`eCx)7fs?W}>pfO<9`@aeg_6 zkK}fCi=VNx;~r;2yUm=}bHMaB|7pbkA07P<)uI0R^lIQC_c^xX#sNX+6u0^evv}vm z$sGpL03dKo*mAoQ`T2q;506TkQFCbftvj2dbdA;Owv97CczkxBUwcsO{;KZ$qZRz6 zyhBgV>^dJ}3pNW~CA`z=$N@Zl_WalrWpzlQdp{k4;IAu%Ap{6YOm>l4ma}4B@Ve^* zn@_z`dSgZ~MUiUrHtVa^W^J9TN{?nz_o79H-!uFa4FbzE(M^ZmB^Aj&X=N4E0nl)J z72MND@I2!@DnFj=z_SiRkVOt5)n8e_Wq0LS0Xhxn$4JhC%LF-;EJiT8`h)) zyzE+bgY1SIbmWo}HI#-g8zd(PPD<>Ed(4E!m`NX;%>K~f!8LWRjiNx|4OH9C*>2nKbE9u6@sW-Ig3GXe`ZYxe{E+R=kcqEah zLwW)?>df}Nhg#DRtzS*{&4M_a`&gRnm&pzj+lec&IOy7j$-{8HIC=GAG(vZ8j&mXz zmz^WpYLMsjwdlf8DDqz?>-d+sEaDUA_FSTc-nC!I@enLE_rV)CW`COhTB|j;A@hbc zIIyJuB5b|Z+SY$PKVGPuNEm%qMt3e$fXS1XRT{jjh4{4OhmHYEIhHR6%r7;^afIVD zQ5)vGavnHh!dX|V{ojkEdzcCVnSu^!5aTTi)UWN6A&HwDc=_sY9pZoOm;1e`OspkW zMq@%>=@@GmtC~(!f=&Ee((FEF*xziT{oq-7#|3s-KX|@)M?1X(am^%`V^hIp$M6>@ zzeqpn=7PB)KX}IGK0LM#TS$43)KvGMM~Zav{b^_2vh6jubc(-!%ciS;N+#NWzoEW1 zm^B^C;??yg{r0%HGP7bb9I$r(n<6r5Dh}ej%vQFC5y|@BgW>UYRxa}2{Im*Hym0w1 z3D^?!*@%j-=(Ac>(Y9WZjMhsYdHI^B*vZzP9}yG*$cYyQZlGcIU3q>F2~0AFy1hM@7i5&+qfgI2Yx&0(pT+pnw%#7RArRhoBP(jfT zo`;`b=#S7YkL-Yp7_#*X0a2~hxSd%Epg1TUCv zHlOIly}h+?2bpE86B}MtZCR3R{`;Z)g|^KjRb*|dbdYoRDK*KC84kX1!6j=nH>_{8 zkwTHd*5hBokVRy;7ouuP7A;fefyvVVwvEl1GF#Ft*4XgciL?)!k)sD4Eomn0yDFn& zbK20k{qEN;?A0ysrP~2@@61LDBp3BNQ-3b!X#XGT-a9DGym9x=KG`IjzQ(ArCu%HU ziM_{7BK8tgBr0m`QLNZC>a!`v2F8NDY_Nl1L;=yD8w)D7*sx$(dqZ7&)aV|b-<w8_F3pHAM=N`)C_tvJ@U(&}Hc{{%DOwF(z)d?HXV_e^- zsuwdQlv2kcABKqETkqCOi`%>n3(|e^jHh`MYWgq0(@~UB9svpzl=aPU^A4xpBiK>^ zIAS6i!l*H*AL)iZ`FV)oVG}G7#-&y$IMr7z$)<7%HMDv_e@T2N7rg)Y&}MO#@7Swq zrUCLwH>TKXPrfhP%Z zFRo~E-jR}Qp;wRpHRfEDtw7n(`(hNbF1l(H=QDg>7JqvpFWAMqC$y=TDfXS5?_lT3 zN_H|4D?6&|3iPeAyPUSm=A)_v988$E_PY%kpJd{UyEJ*%DjQ|Q)*|+-do0_lkrT#q z9{LvMtKVlc4aJU8@I2ZrpYr`y{OXeX7gt3@txVHT}{p-_~RR482;^?qM+T_W{4 z;l|u>qe#lA*V()H|O6=!<~?3&(u6V#By;# zZ>82Xs>^e04>rj=AzqoSA*BoVKQ|`YeOzpSTKK`$^3oa{8q90DNN!V1iX6Hrg=0h~ z%t8cM7Of)JoT&S~Q3rN>x61=R#N^$+zve*gCpVVN3S;^Fkq){}e1+@Nm992s{&3+= zfIPcVwcnx1Z#YC-E+!-aTLVJf*xmpKi4PChjDz+>=QAsL!R2*76rk&cU(?$h`QB|& z@-K1RO|&ul1#z$HvIl=D<&rBQdRCt+7t;xf^crc>QH^ryqItj*LAPNDGvOrC?aj3h z6i+R5b|PdY>gjUrmVW1Z7NV9*1VPnSxxtY$eHk6;G_-uEPn|$gTO+(QAp*>bycK}d(_q4)_2}E*b=4wp!#HT$ zUs|`Fo;}Ds&Bfi=M)Y=cYEQD1Oc;{5wHqaX!?*wo)wa`saM45q*&$^Kb-@P>u1+!He)5z*8oY~FNi?9D3elrR%LpXjGr%9mAe^DK2;!7960D~hyS!c zdxzug`4#kj97YQrvlX_)&}thy-zuK_-&C%RM7QHZuMi@yRzE0Hp3Z;w*G}L4TF0@s zPwRtZvb$JGbc%^$(a8H$(2PFAp1;m8w@;Aqte=wK<^0via7`=Ue0ac8t~H+b8RWXN z>>xdXX+v+HL~}+ss}K;hWHNyW&?Fe@zNo6TtGUwwl<{#7`Dj$xHFMB|NrQl^>YJFV zP9!iQWvUYI1JL@Yb8m?r`Lzh*-EY2eFyr_DPo&H5N?)$I>lyF&d$U!Fa)F2md0Icy zD`Ua5%U~ipnaBLyd$z}rCCe=jTdYMMGxft)R3}0eb$K>Ho&0wQ63FO#(L7+~0(qhQ zK}9mtT8WrvA3mo+$Eq@N$D;z=hWp^3n|(Yq(UvZ>=t4Jb!=Jt$`tyio(gkaSZoswL z%f5jh{+dZgtlHZBd?N{PAKN9JF;2aVvZnE%O*VMSy0K;GveB&_lWq*^)ig<{mS~{) zsB&3X;1J*z#)C~RAVgnLj20G3MXr6IFTpcD^+Dhn-)x*F5+YT5iq!vRU3)+NC7*Tg z@Q+ra>?bnc)sOB8y&B%)nN5k=1%5Y>A8U!I%B2@M{NeR9ec7jpiniH6ki1EU?C6-) zbAt)Elsgx7joaz03=~D$nlR4{Kd@i%5>8biT=QNps;)o|(eSKbhm;a7urke>pMxOW z1LUZu(yX;&5fvVt-dno6(HAELmF%@#owT`r_dx%xo%-UPonrRMb8tDHeVG-)Ml_lg} znAsj&WV4{@i&faD|?skFihhS zhz4nkUxil5*87Jbn690fJqi#SboF7OWDMt*N!x6@Q4Y z9mm%T9~Hqnah{sHn7-j_di$vSbmNqwvB?*2A@bzxUUz%Fmzu}`Q$iVu=3Xn!#yD+Q zm&HU^zOx#Os>jQcPtSNAujbL)S6qgB+jlI>(HuW@5K&Y2a?Kw`vBgx3KT16&rFW8( z%c-_J?O`qF_-pKLr@U_BtkZN}&DgI5e^op*_1J19N~Yf#U#|g|#3K;}e)g1ZMZZHlK)^bp0sG^OkBB_JM)64KTtZS=x(|Y?o2B@)-6; zksLx!;M0UDWAV?)nUnf%;nXb~kc}Hxzw3eqO?t zEd)j~yy}K!Y~~fC!@BJDPo%KYjO&i4x>RjB(PF8~7~L}8!&AYo&o1eM6*vn{&Pk;9 z$jjb(yvf-P0N<$gHQLN9@{)Y5Wo=rwa?mx#{^vqd!9N!uW|ZC7qlI*X)3QKt|QiW&eUrPHl5=+{cn%pkmcuZ5LkS&V*r+NjX#h{TF1*6JRl2%B1aRcuJvF0(k#tq3R$VT>+M-}S zu&K4tSyF;1cVS-v(5YpeMzGaBn>u_w{Hhy-Q4i+?Es6?sVB>b=vYDxh*3Y{6gkiT> z=eHW~`pXgba7*{a5edx0x=uyo)PS(_Yfg%%wzUjxM^h)U>?+V%2)<)v)=$N%=Mu;_ zu#Z=5!3I6x{~}#onywAN2SX~S2gN*Edoa_$ZG741Ac==uq3vHSf7FHB7vk zwh+tQN4$2~&r8H*HT2KedSQjofJ+Sy)nQi@LkWsS@FK~efuH+oD|U`a+qLYbUx&xT z^wOVvp_K#X@LThqZZn^Qg1xR&sGdioJZKB@Y`8Vqna$~O{=3Kdx+OF!hyfvp~te-qbWVAW!Ne|xdUm5-J zp829^Y3Mk`^G_x}OWo>Tmdj1I_65(0+KiYRn_*-lRrf>I^GxLHZc~`5!HMjINfe2k zHSLHh!U$B_>FOY}_`#5Lbq$0#8e5eKTJfPoNqOARA2hx=eHU+Q)G4NkODREfS;P4) zyu`}4S_Nob=M_RX=jB^XZFUXQBP`0t;R}OQdyQuO9)R6R4!bS!avG5=b33(L8RzBi zTFPblZH0tM87(`sTdgR6=s3fAroaWUyQ_rbI=yYU;=-sL^M_|dk*pDW6`HZvV?0bX zx@1bz@=d18aY5vq0qwjdVxb^9Ja|Dm=xv^m)AH+E;EbKPAUB7kE7!BVE@pPSnJ=?G z-Bh^WPrNZsEuFHlq5ztJKJ$z}@~VayQS!~Kmb)~=KuisM7WAAEZ?H_-a@EEo%7?_3 z@a*7);sOfT7;J|3)0a;i@WFw{XA&A9Q@9rG#w&*PbdfAA)V?(4MZpbL@k9SQqotx3!BkwvjPr z8dAMN$LE9vONmE?lw!K;E`P}nH(~D#O6)9OQu>F4k2%f9IrqpEHTXllTcf73L5Ks| zF4P{`J&9kNC~0EB7eiD+gDinB)_773F>F=)G3^?7xT@2LMgMvF;=XD~wK3rSYcr@g zSN}MD2!j=KfwqZrW_v;8n$pj%>grdZ&G}l_J(eb;19u0UUPdebE1f7V-|jK)Y0~|q zTe`3QJ<`!xG)2cN^hh~kv;#0b#I)_G{t;(cp4nmJ?00wA*ittHY<_3nKvMz)M{@-> z_)uD#!uaY|GQ`Nx0YQ(X+->A3$J0FrR`*cChb>w9Sw|8li?elnW(0J%AF863T6g8H z3wj#WmyZXY!Gdol1tb87n%doVu(B^=K`Ads{7Dj`k4a4`ekP~uG~Y6R$tRA6*5*AA ziqwbI{T$UI8Ya_L{9r5M5UvKtG8=t=zNp~RNExh4?)`KrGSqio)x3i68VD9hMu+_n z^LRbVZZH3OVpb>-sFQZ6HW0cZc&)aFFgmi_JYv_Ir5>EcfIQ4_lhYPPO~`-n_8WO> z@<4s(Ha8h{uS?Sx1C)824IRfs)dD24uT>IIS0TCPtOC5N_5g=|UC0AQxG#K$&5R)E zbgx)pAlKA%CMZn#TN9u#^I2>|_$c2S*e*C?MrrptUms%GuRuGFur$&C@>ICQ)*DmO zndPEc?S6w@?WPTTxXB$T=kW)-ky2p{%ml%$8PA>MD6(b3)(@jRY#+i)a=8@I^QHR1 zc~jp#H`Rf(c0g08hsa3+j9z1(E>^MtaqKfE%X2}(=em-YAJ8(mx$f=TWbXec4G|Jj z=CcasR=%BYzzHbT8XPIOOO!fc->S*lQOrTp+95=9R*Ag6a&IbqY91WdVp=j^`a$i`C zo%`<_qCh*2$;*2_-DvN8P+)xa&@6bkPigQ4L5U>XF5w4ZNYucESL*=FhtOLF*oX|b zh~JrB6?z&MJ++E# zvoG1uG?vKn!R)Ro9O5#*H~N(C^z_|8hTPFc5bmX`R*5ZW8jbceMM*Bnj@skA1t}`m zYAX)LtHin4Xe@S?h!B&E*4~q*!#ErH3)jSB6bBg27dfYzti7`q+^v9`SUATm?FBh` zE*P70T`YP3A)Q_dL-eW^jWj8ZqOl_Jc zolT-f$fx)+Z&REJ{aa;nP&I?&#Qv6zC=Usfb$*ygx zu2ypN>Af{Wl{BhIx4T138Vp=<4un>gAAE~S?=%m!ws)E6 zZ%&LoYtNrTTzu*J=vZsKv8M23Yg)Ba%BlC+Q^HQq8qdyQ5YR*~Qlg||d%p3_8=&7L zHtR;|FSXs=5D0^ALZ{iGXDT~^d7}s%x^lV<>S2NO!Nz#pQ0_q~hUFaS>lWFnhjQJg^#U@ zsqCM--P=|jHdZwVbxLJk*c6(vEx=nf^c*rog;?c<(Q?mm00A7a$cvwQdSF1T#u)GO z3XHbd6AQ?D2&aA~B!ZQT3bQE#24eifYc6q+Wxca?RlTj)VTu1XW?#Z&7r>+~X?N&%&$x1Lpkve59#MIQ5J`y9GcRwx~46HI})(ZCpgw~`v z2mnGbw5}DgL!Qd2)JG#4dSzFKOze%D_)fKb7jD`%W?Fd$8?D?Dx3{7=_yq)Jsjwbo zH%?lu&#uDnE^piRRGGqKe95afnQH0)@ruIY4Xr$oPvq$@D`9yw3H0!oiuqvsR;F>^ z_Xj}#9!UFTO{SLbrk{RyX}ijHzPEJwyj_KT=>6+%G;d0`{h~i#ZbE9L z(NSu?2^FL1%K4IcNf^?jc+t zza5fh4uaT>X%+FAFafHJ>7r1Ojn9&G?Q&StV??phv-~L0BB67N*G`*6aNdS2pUKNc zWYMcq+1`snSl5dW`VrJz=@&l|Q(&`=0*!q%MsoKrG#&=f0vjD25-R^qtTW7a5C6^fF+pMtf z!Iv(1nEM!C(q8o95)7Nf>rWc$$6-39{I$*h1L~%*JNZj`<{N4&*e}ob(BO1K9_k zY7e(xGA{-7IE=4!>S+>etZb}-oUJP+coI7jrjC*42?uQVpZo4bE=nBOtRD?~`2}9g z&9ihw3^*-mTPqCP(FKt%zArqD7^WWAq}b$V52D#FIH2&<+(WJk|1}9(G~A@h^6T1| z0+eOO?0K&P8GP(5vxrP1iDv5|e79XCgNJBu<^0LeP6t!qTG4pEY(Pj7zE!WA!cH1}`nQSrFH3h`#tZ(U4G zFcv42P?SWtZT0x9Iqh5{)OmgC^q&ha_K0yZvav?iC)+g5?bk<^W$ycf>EoU$kxXSB z*3B`E`kA25M7Gz(*4iw9iF*I=m`2YZg4JlI!})TL?T5q;sgJhVw);*C z%GSRAc$u%`ye z1wll`8qNkA3Rv7Le81Q4U~(o_l-`65ZC060C$Ar8XFD2XZB+y1$9^>#VlcB|E9x1^ z4i}RsgX_})&ASP#%(8uq?Q9Iz!D})G;$DeR1V&^ls7s@a999|2JLa5<<;^?eTZ&>W z89Rv+^FeKxjKzF7N8Y*JF<+{bnx1j_+K zz&Nq@B_1BlH1Jfx;nV5=;}g-l+_=gnEBa~@V3(cck#~(XA-|>ckQKs%PXv@@ zS9wsJs%kKwI)T`V3djtz2WWpJ7L2niq^OtKkM1$s)C(7eO9pl%+* z%Ycf)!IK3(rHIbnsQ`&yjjxoQzBZ&Qcfx|5M6=qAU(>7H&Kq2r2AUm`^B6QWdRzn4 z2Y3UQ(jTEPtysAAV(G2BX!h&O&>Mv*VQr(8iw0DCRHqYjo6Z-WQ?SBFvRf-)jz^>hmcp5T?p~ z?M|)4xS=F{CQP}W8R7SS)BPB1Xl-1}cn|{fWYU@3-VVrW7f85Yh3_}{r)LiyqhAO0 zEs^>`U7*8TE~$@$1k)6Ub8IbZT^~5BTGs~ly=EvTY3RHqZ%pFC{a)_cK^3>2+f~0Y z7n;x~&>=p_auTTb2Qc_JHq|6z7NE)jArMu+Sk<_IYobV9m5ZP$vp3yAg^A)X$Ke@r zcBKXYOgRDxVd<|zd;sP9-D%$o$F7v8DiOOjBde%9{5OfqLX$&+PMcXbW0mcZ;wWtD0!nH+W?3I?~r#@o!pBi{Q1x z5|IP8YHD!H=yFG6zHSVVXV;qQW`=E4S2NhFh&RAe@ylk^%A$bB9tFK0e|fva=SaxW zG3k*wIBZ{h=Lz}zNkmRmGk*O>Y@E;I-(#5@=`q6Enn{Y`@y~iXHHpjVkCg1R?Uv)c1>Pm2ZutKd#u zJa`UDQfPdzd)&qlpbL&11UJ~MIJs2@ZLIwgQnl#sBKmKRN9VL~sZM^#<8oVwE5As6 zQg+B(h=aQCtWu6w?6px=wmjF95`I{o=ILkv9xqU{?z}!(Hp**H732nduM%qTu`&1# z=J<0H(ls^eVOSTA0rpE*6Jv!4bMc|QWcf(JYBh-fsmE$y$oDlHSB%tSHn&B3m3%r} z32U_g{ddF0HS*W59Ski2W{)`Gc?VE> z3%!pMkO*{;x1!d9O~y7KLs;c`HuEeVUpe128{e@mPEn({AEFc?hGmS{xDP2`jqd=W z@2G+pHSaiOARTXxjg8E$|-V0 zS(Z9RJnu*m+$n=C$5o_tLvIWk;b@-lG#GWoP&;@Kn%f8QIpndJIoEwx#}|~Il4oqt z;$LStxXlvVNnS?DVogb5gB?ltmm1fmqfEt!;pJu7wmqATlgxPDqVn=2i~!ao(Hl^; z=st3AcenZK+A@*_?zu6jNd!q)7*JE)@|LM;IhAGc)ZSpHPHL)8N!~J+)QboP!g4r@ zF#{lPU6C_nPW`iwKWpADV8l#B`S!r9p)5i3Q7iPmAMcRkCBKO2OZV5LOD}pV@s+(8 z3opCvFsT%R!ON0txDKNGk=suNnN5XEec1rg{=3I-c>f+UbN_69JI z%5r#mId3EBj@>7?B!XzT;`+zPk+jtBK0eNze@)C(F!v6v*TxoG+H@5_&1Lz!w-t=Q zDS))X*22l7CtL4#glG`4AhV9M9MsFfGeDu@4`g!LxBxRJBStB~dnQLZkIT056mu1SpOxfrFhN zn(J`sbHv`t%}%gGehB3uNJ}DPxGuFKIDF?bjcZ6z$J%Mcu$DWDR_zlIwcJ{=4sg6z1;@Z91{?QeiFIc}?h3Nu&4&_5MsZk%*3*Sy z1S!ZNEe5p^E|Ir$(=T9+)WMJvb?XQqR<$Wo8wsWVTrl~5zdkV0YuMDZRc;9Q-iOiY z;1bf~82qVZ{_m6MvOba34G+6VwIz;Ls{*J=LZvbPO$BJ}*N`_Eu4_uBl0!k}(4h2A z5l;AtSS3!(&sLbwpA}C7SI^$cvO}-8`^CgIjzy(7fA!c&ux-wdQSzH=GY9$s?N6F( z8vpRC!OYUJE%9XLWYo;-ZHMv6$!XEb1y?^yb7xO%#yyyoDUaWE2v~h3Yf30LY_mX2 z9xBjJs?bl5ui}o*mD3(0HeE|M$k|g{+PpIqu{!wMg^Pi=L|p#-@6r5{b8J>TEAA~P ztr*(tKziO1jf z+iKruX;pfHDIPp8-OBZC9LFI@<$>>{k-bI`I<|z27cei2Qga6Jy6k zXslVvy=!VC;M}N!`ZS4HBjfAM?cUj2_>9SK8MJ5AUYhiVD9e9?ueB4qi-gvonh-vXSE6dyg>|>Y0s}ift%y9F0qX%knL64lDr3UCkzTFFd zsuNMsw8O3eZ?X}ODYG^-ic&()qu#-##8Ia{RY3gJ-^I$-N=%vLM0;X3_^vEP{nH8r zHD`vSrpAX!<%>HDB~PMM6uvcuAXjavx(|C5J4$@xaPE5l8ur;Yl z$osOEjrCAU?j7Az_lOD)yEYZlw>sS8UwO0?Jn67*a2p#aLvEOHCLj7%XU3|<8_m7B zGv+$Z_Pt@oJ~U6KB!n=`H`J;HK_F6kVzZCGJaH#89A{q*p~NbV{D1}07u{CSj1)tF zI2vg{>W?18CRHXN&B})}yp``ri>ieMCKPPJ7IX#E5T!W(+Zeh2DRrJWy($V+lwvj# z?EyP8I-J767P-|W^CYyqedZdYfqpCm_;QxAy;uLfUQj|mrSc8bYu@1qrW4pK))g7 zwei?zK~wovRZPS|Q%=MBpLWq#jYGm%5NMrX#;}5zjhCFdjLH%nu*?7IxH9+pw9GFj z4e;0MJ{-}y6!i)>z7NOP*qEbRsgjnzdEYKu8~@NCn;+c>-W>jj|~S7s8|dOBZ!_^3@c2XTQ+|N8sJH97Zc#v$tU zTt-FEJx`VNtjauqW-YdVS#qi(#9#B;^kUuCPy%L@d4Ql=Pp&yyKW|y@5QvB@vw`^f zZhG`P_W1y_KY8_tyZTUP5K>CmeW|8#o$BKUUCq!?+ogkvW~a=cf4QMNPITk7(oc&AUy4ZtN+~CC$)PrGeGhilLvfxpfvY`9q-`#*hid||u)m(}S>(TzzTD6-^8ZLAE?W?P~>q*QT zdXM?zsmif2vxGXM{2{e1n>VUEGAXp~J;QAnsal_5{pUvt@O@h3Sn<_)>)y4sy|k;b zGqY(oyH5b)agEBC{Yy?bfgQHT*%iL&-e$z9VbX)IWI8 zh}PwU7SVnGrtV?iEaTt3H@)63$|wi9k-hup$898ph<=U}roJJQootx>+hjlTXnGme zVYO`J(}+w-h|S23o?y_|y8*3BYPo{;Yz59p)5}()@q* z#s6E8qz5dtuEXbD1rLNPHND00ky&k0? z3}^c-es0Jz2@CMZ2P}|32CS>rMh|U5NGf-?P6TN(pF+>8NNa+s6}H1L!W1RLGWd_W zXHWZ|_~WR3o!zD}_`)WeeJkQ)`8>y}LP5vR9U;h-vGePpmka74GdP^=(9qy+teTd6 z(%6W0rcIkkzg&jHU&tVd9V*L;!c~G+D~u;hg>W_xtawiJh@+BzeKdcz8F0R-cZT@q z!uRJh->-1O6dZmlhZ=kKw`Wnc=;~&CY+lgplwZoL!iD1f{Fu{sRL(~(=ctMNAH75E z4m;cLq8-vBU`4@i-L(z@VnC_r#D;(@Q}-12fHXIr>yL=5CASm%$y9V-g}r26c9VH@ zws{{#tycREBmfqOZktK{i+E~Wad3%Z#k6JGzx>i6mxmeyn@rj#F-~|5#W!krkF7$o zW|a$=t*b-o`c=S!mD&Oa)4=fPQReYh*d)&V?%%e?&%}WhxFkrHhRjNE-ng{Si`7xI zA_mZfnl!}Jaw)Mlr}esue<%;l*4qtaOX>dY7U;3a+w{Y(;#@gj4}2547+>^5erYP> z=Ur~j4?^a^JcA1swGM5?pi&-*lz_w@_ta9~v=|=MM@bvviiuyws7yuv-=pg0;*s_1llkb1G(_%ZCa-s; zbI;~TwnjuEpr+os$+L(oX-u~U)hWBf!^V+mlMmm%nSN5ac{dv?(4%5QDkw=pVKF51 z&BX&{tCkdZwc`b|?w?Wqy@Xz$QO9hLs>avQ|GL|bzpDMOyX|Cflf5%hjh||rIcZZ8 z3azQ7q_@t$sG6W<`QlKMPg*LO9ov>9+mUb9?*eHvncu$L4-BsiLFNtPWC&3IlSq{# zEkPX>*+o8g!)q zkfEPB9?+Mm6$S-g9XVXN$y%j%`UPYm*`bC54_98KDj`rnsQ~93@uZzEP2yC_= z^v0Y|YR);6)Yp8qoMk+xNBBI29;kUt`afocD+x1}ocJ9=^aSB>7V~u_`+Imy292au z_dh4xFK03>IE9LTE*$ABw0yTq5gzK>!;GC38=lQ5=S{^`FwaPO8?b=2^aq*wC+@|& z@QThe&F<}ko4*84N6*Q{dDv}QheQ}# zo4IoONgGk(V2CY7w<`%Z=gyYg8ywy$#J6a?(A#vsy>k(_^EqNqS6TPCBna`H)nsv0 zVKxvc)mdnl((M^79=R^dcQ?VeiOT;2=Q{s9%@6F4-l*Epj+0ID0ZvSWdrk{f&PAVH z{Ua&K(GQKW$G&*6CRzDLQk4gG#Gq5I4%Sz-gsVjxGOhcM#Kq&Gxa?n;^d*~>9hoMb zv&Wv60Fhdu=2mLoh~dW{@k|KB(L-GUId8uO>fx&;RP5-6COmn`Rzi;(mCrmuQ|-T5 z5Dk1w`D@c$gr&RRB})$EYgiQ6o;eFMHXzVzugm(~#9#nm?p;5mNM+NopM8zK4afj1 zh5^V7`q|W!e0p>B@vDTDu3SUkW<%=wR5{00#J~bLuwl-FFYQE0M`EBM`%kLxk)PYp zy{z^n-e~ipECpqeFR&k%>pr~qMr~x(^*Y+Yvxc~BS!v6CU}zmpT8PXebu+K)#j$wF ztJ9E7wN6tVpKiFs0$F4fo_`%Io+y<39u)2@7NTab1p=uGKe3(6Yj?LWR4OcR8iq=* z@j!OnYTs?xE#n}Fs&}%1eg=1U+SVVOy%btG|6Y*y&jo=xx3`Y5QLyIO>hqlk!qK89IHw4Ks`V zG*gG}ZFK!M30#4pT62sojM$i zS;{79bn))p@rGWWxa|kg|7NTkhn7uFjJ)0ins~X#kFWk1xH)80_3vSIi<7OOYE*}+ zh0MAV4G!+vrDoUeRuEuYA;=-OC`_(H-)*@Pgrc&FW|rIp)J5z2@L7p9N5>n?oz56~ zn>STI_F8OyW@hPDS77@1VO{%_38-y+O+|P)5`LP2Yz?e@4>w)2yU`>W&3EI?;W)`ZhZi zj^b#ZAZBe9ZQEH9336nO(47;Q~o7IHhIPPxx2C?;Z-@6)~ zd)XyZet>e2J0GFXBdK&nRuJ#={CoAkko;Ed{Fp+G0<)?wu)N;Qkue(pb$lvW9KEY+ zpG-}oc&{hW;DYa_5<)&S3tR(*zmLz8(6?ZefCcC)f>TE>R5o?O3GrvKiJ`$u9ZyPm zoajMFK;z%S&pLJXF46O6_18Dsq-B0+Vu?e^4_(8)6ck3nbE#{B)fl3+)$K(-d=J%X zoqf`ur=?Oi)S9pO#8lP{v@!w5Y-E@9!>B#|D*$R_uY6JNflzZKpF&ocZqG6fmZQ%W z<6L1}T-ujoPK4qznP1iEywgMY`uyYAYjGwBX2o%#=tSR%Vm4Ll38!1*O3{a* zT~;c>0=~mClUxIRQiTegH-KsW&56p4FnV0NT0Xf)o}4ub+Sv?vSIsE{SjiO1Uy4y8!Fqr^)Zqp)~7?WKS-g z?JU6YYI4h^b5xG^pBGm`M(dUd{JQ>c$^PH$aAZ`Pc^jt1YpK#{gUcD>>$6*aH7d4x1E7SGQqM4@UQK;jWW15@+xYi2Ol}I+J2s zae?q&W&RIJC`60q0vvz0>8_sOLLoBeMmI!!^#vulDK zd_+P`xbnY2UINIoBj#xnZ`6W|```C695|-o7`VV+ujVTqOk?2O2LLn$TDNaqv*tam zi+T^k;so7)k5ar*`>?u@lm6O_bKw-~#wr@}IU$h-;(Gxp$!X21+ z9^CHl)|>o#!YnHM;G`l3JmE~&Hb+`#{SePaspwWmGNH zdFQS30(H4`p4mxwfv%IV(i?IqouLMzPXs7=z~_olazEQJiXyrDq?VNzx3p+tV@ z?cj%%$Z>bm_wx=^D|58@7GjHY+UnWAWQd)=5EUEp>q_zSYQ>`Q)=!T%waX;7Tc!k` zg&AA8v6XF}+aGQV{iVUarJJ@m0p#6~#PIgx1i6#6Lo%{_cU5PUqNbZ`;lq5|)y6u0 zsB7U7c37T1<42WAwTdaxQyeNY0R*ijpG~n40s|8)bKy(qqSpfr^_KhO^W1KPupNa|u$QGU z{>66(%}Yz}$z6OQ8Iw#a@iBSYOlwLg$hepLbaH4zq0HA?V(`jMQj$p{&d=JbBKof) zJ^<(Py8fX9$R}tH13Gm|d3Pn{=Kl4D$dhDCHY(M(v1wh9$>PMf=d3yS*mVq60YC8b zu`@FGL&Awd=J)#0&(&ee0tH`+^x#d-ETqS`U8Q@?!71Y>SryPkw~0)leeLihv1uqW z7qe#DmubJqy`{Fk4148`dy$l=6K&D~V;hayn)DumiK<=6O>i$jVn)8LRbzU&Pq@4z z_aN6eeHg;k8^)dQos@((+LT|^VnMR9y zcD8Q0rfoF}pAkX^x8=P=wF-0G*vMbl7XOmeL*$`$us)h*T-705Qrt!-*+I`qDQz&k zLCLg4x+ZqbQPAChszHhp7Z@2^sH9AY&3nX-nkCaM#?#!>oY)+3hh1Vn0y7u`LaY@G zmii%o>JUy;g-setun0%`p`O{cj_LKJ(2t&SA-r((Vx)mKsuRdBwJ2grb5-!PPc!eP<-$4UQave&3pZf6U zF;A)2jDh8Rx}W#Qg`%lBf^O|+lH>hyP)!|g6R$%&C+^(gt?hcS<*mte z@0iTXVbzf#9S}~1k)pL_Z3qTii$hI$+;6|}#E`n0c2`s*Jwi?O2x>fY-&T$Ns#0lw&b7mJ`;~AtV>zxy+7J>s;8?z=?=E z(|wP55i(-O*i4dVDz_t%`2q`_2neevL_Y^v^V-VHqdXP7JPpJr2^Ot$;T2l);P3** zi|HH0-+qYCM=yj=s4_-7-T2K}V>071x}yVsNIlYB{mW#41V3r`y?7Vc#m7wc5yOF??H0#g1v>`p1CK z0Z{8nrJqsdqM?*>8jsGB*(Ys*=+&7})tRUa+pXT~e8YrCj%|cMWX1c23|5fhkm-E% z75QQ&R){v+Sa=F`a<1c%lzCS^b7Q85IK%6U+kn7JXWuh=Kh7~;b= zp?CF`tIPLfNK;$4mSlDKAKAuRfM1bEGpRRUl=7%ibcJJIpV*6wC{xnPIQcow&+w!w)o>Um zpt(3U7H~2Z*>+-sJp0<#FI5#A3yWi^AAk!52KLAqXL;xOy|bMLQ!DGBwwpf<&AxA3 zkj?v3mDjm8oKJigRHWFU+B4On+UF&@5g*C)zP}{B{QXc0r5LLCQz~IAUDMN1PHe6S zsC0Dk-|60xY4YmPF>+b69Lvttheh~fgQrAeVBs}Wu`L4wIxeTfu}T7BDNbgIt&5J6qbdB zl5XU+4O(zr9bmYoFk$p%l&Fs8*j!4WVK#o}bB93F=R~?BG^b7kL-`-ny=PF9Yu~T!y_&rsO)0Vj1PM(*z)+V; zK)OH*geHWV5RlOOS}I6KdJQaT2?+^O5(uFzkzNH7S^|jlE?ufS_w1Qx-+O=D&&)gf zo#8{iWUde7I?mYqLW0q23LdDDOqohc1O| zqYkqTTfHn|i0ayAN?Ud4b=9_Fh}(J<)gI-3D<&(3uOBftJ6W8QVV7HXu)aZ^|4fG= z7K^cWI`n@9Y2>CWc8R9PMVfGquRtKsj+q7a%5bjG7SSd?L&~a={~BU!uG_b;uyCG# z@JUZY?TTLCS;MUW-bcXJa&ACMmk^R_^;X`y95%jXccrrpfG=-)lD1 z^1!;@m-e zq~>$6m-CALLE1c37wKZ_L7w#JiNkteEE#|u9g*l5p2*?0A9~VL#)0|UEI(=*T7iyB zCzn7S`pT5rwKhmyVdnl@b8j;eTS0a-=~-pAdnFOAjeAvP18CFSr#fC9UABm zp)S$nY>*LKr@CZ5dI*lc z;_F0~%5Qo)XfU{7^|q&V#CyG9!(FCb9^gBu5)B=>s(vS@UTYcUl&X#_#jcvF)8&24 zgt~0<0ngZzI3G2g;8Ly!d1qTX6M#__m9{!F9s$=(}Nk?$JGMmdIJ(;`_%8W0`Y7&ZlAtq)2o=DKsYJm61|GY>Sw3 zX?1EwqBkPr(tM!HufGk*C3#W`Ud?;6Bi*k!8ccuEnV)guu38e-luSGg@VLCQ_^ zs4AZ>(fFlmg^cyNv_7ts+wbMz9#^)1U;iLBL4uX1h{|jAOwBu1jH_NVRj~N=Rrp(% zx}4Y{jd7NV03q);pBjopV{DLL?I6EmJ)Ng#TdLK(zBwkW55C?hn7*fdwQ1N{uHr<% z!u|7eTFt0HB$6neb0MdUPL50pq3f%MeY!{x2j!&57WarHudrRE#BvzxTLuO5S3ezD z+B1WaIBydPrpE;}T@$QD>F_DsDde%>|Ajvw{rr(RdwId-Rm%et_2mX_xly68$*kT~ z+k(!e;^p9=w4yfgarMC)JC*&g=F3$lVU5F9vQ;tdCJTdAyh$Bi#lP@b_>z;#H(-}6 zzn0(etCCZ!Y=0|{8jy?-jfYEJvIFgv6VW}i^{^i6)=w4d1uD9HvZpnR7I(} zvlx5rmquEK5+l~IBvzH9ENO%IS8K0xpoxVt_#Mq~d^QoY=1rBD-|M#4d1v4w(P2$Q zhj}3@O`q`gm~t#r?G>+($V^e!SY(qb%{x!Qt~CL+mfts-|M53jL!HGU=R`NN2r^wB z8AR5lyK}F>Hy@EVDkd7DX6z18xvTMUj|M|#P3KJur~Lgj|Loj4T)M5EHFqn@`lmy6 z*}(S2_>8yR-%gU_vS<%w{J2#G<{Nud>5!;kVwi#c<@wUGzgC#GYauqwPesXb{n;SY zY_K#$aa6Q)7AXD_@~KkH>Y*ZqSLv;CAI6!C#Hq~p*f2px^E`Xm%N4y#i4iZWpJ5_j z^S!JN>eu+H{sQ44Z%$GmWyUvZ>4@U#u;oMC~+bFCS z?s=8QS|-97s1nEGawCUS1t<`nx0*mD7IiN=z&R^aF3g<7Yg5xb4@OjV$g3A&#KwqY z{Vg-!&#L4Vzr5BiRvMDeI(?=pe@DqvvE|FncW{=K^DU}LDFXYTHLpZgHeFJtza2eE z@%E_!^iQx0N1!YZizBrm%83Mx-~l-Zj@7@ghUwS%%59Ye4Y2=N|dVDzOiR$JIg%^~@9W-;c3$)!mzA z5>jff8M&5+_=%c zoA(n3M;wtQ!(Bq7%v=Va?iZiQY zr4L~_uERt~F8Z7FwQc7)XsFA&XHcOMlDy{k<~MB~dPb7?Df5g%w`oIi zqx`ZI+~S)szabnY%d=+&6?a=+K#aF_rl>lTI1(rwknw2(d&;5AZgqKe{;%DY`De2} zwlz%TybU22$fg;ertNn}Z?l%Z``!Lrr+YZp{;{2+gto01>ZO|KtVp}Jb@kngzbiU_ zx>EC2KOs&nXl)e-e@H#{BJGiyYEP>{cW7|)967yWt|Cd`(FRtWPh>17fYLk&iN2SOH7^@wUf9KPo4YTx8{Jnp$&^=W+Os;U--cb!bnQ++sxuci zjpVnZCcl;*4;{}AWdi%QG+iU-bGbFKhS5E7Iin<-}Y!0iL{&lox9`yD7q|a<2A~SV(@nTgh ze%u)afiLIfG9fm}^Hu`0fQOo3?qs_U09R|kYKz# zSnBb+F>lh?vEQU0UN!5XaO5)@@nCUNzdi3uLiC6Z#B`Ua|*bV>|7sq z?iM#a7E^!yPt{}497c$ErQ5p!={a_*HKnn)n5t}q&C@{3rRPEwHR+>Q(QMz6p~=ex zh$!LJ!--_ZMsU4~r24erSciw?US3}f(yxD92V$_anFhhA@W4Jvk2)u$3nYYOW|Kl} z<|gb~)SWq_0f>c0rjA`rt{$#*rp-@lqz6~k&*xg*H?w1;Xf`i?lOew-Om)j={IeOD zGaxGXQQFVWtlFP{S*09XAh(~jTIgFzxeaY6R4&sKbf(*yZ}msu=ckx0uFjC_rlsUuE#%~? zWAw(6R+uljmv1_6GaD`l&v-=ps+9KkcA8mWYg?^a* zaZUy(t^J{xJqNrtmcSI0S9eYBREMa0dHciL|HY79zK33_b!sbW9q-U9jMKept*2-# z?txLKbPW&;;42*l>$v_giS#=}x;omiw(^aRji>_`*Nr*~&qK6_w5GDUW%NjUm2MkS z@`x~JuL)5k_S4LFnn43`Cox|aZv!P0FiM7NVN&m$SW^HWkvHSF8uF#@DO`zae)XcJ zI7DCPhE%W z)-ybj#YPH56<&&s4R|bl4|NxesqCBs&GNpiTbm6IY85(__u@!Xm2(@HDre z^oZ=a7kZpvfaAt*g1cLN*!cF2cCmDoWTOP%hbMlTXzQ#oHZ_kD6W$CG27Q|SANqNM~(yvsjFoawPcbWJ%fhOwe zhQYi{-)6$zP!qM&25Vtvl;alH-O(<+1YZMe89vMn+5&o9<{LdRE_nE+K4mI#e7p=i z5cO=lIx$ZMe-c3}P%7X(n$G#z*W2)=bB?Tm*thb zLyuk#bk~(uNqg0K*Ipwo?FBtxZ~*pLhe@u47@C39msiAmm0Ix}omj9xe2(J<&6)f3 z@0vg-4N16-my9jtC=iF9P37icOF*EhL=c+<27%akOA|@*TO}aZu#e^LDzl#o_3oRD ztjb?jwdUq~Vql7JISD=xhu01BjsK+ecE!UZ;UvEFVycr=*(T37BmI65P)R>D@rkYQ z`}&j_n0wUdrM`RJRvB1lN9odxOlSIqB;ykwW{=?XOkEvw!=J@$=SA~;fOXl5>UQhu zb$F;>Xg5vQlN(U^WX82_g0A(Ta0x`e95Wq!yz(}EX1yw?tY3CDC~}NBfAr&=%Eb8V zhL42FNGKK9Ly90Ol?x^*eHj11q2Y3LHr94L(J&i-1Q4@y?` z0kr*6xu{+?xhsKAiYjHnXyW!K5D6}p1+WOT~J&e7* z);~(^-sLz;Tu4UB2cVp~7-pF>`naBV*vv_Ete>o z?PHiH-cQ-dkOv<2O(nTNh+{rBdFvst z5Lk8OB4^brEX?#h0)&B-Y&VH2UKav>d%knO`_azN7jxaM+%t*KOe#w3n)Ghxej3Gm zJsyRNSvq-oM}6OpyI+-X*T+9_n-|TU2%=UOy3xzipBsDPgBy1fJknO?dor?N4ub^p zo`*bCjMpcsdqhHD?2#Q?p>lkxMx{*c%WKO0uv)YX^& z5gPe#eiSACZ90!AJHLD#9KMYa-{922w$ zI85I&WCZKrAV`f*^^a*+)9VssLS)a-n8%1}_1WIjWA$xc(k;d&wPZ4#90Ke2;8`gs zE=5)UnKSC*whqht$H@?tSFZ>CvQu3pEr~dRn)R$Xs_37*DGzxo3r+G1>#=7&`;hXu z;)~gE*63w>zlErcT_|pd15<%n%BhSXQOYW$X4d-dAdPVl{H$z)39i}QO;-R(100YF zbROozfpo=A2SQAOZYj_Y*$29vcD+T}2&XY2JRS z9}DeqM^gvYjyy{8)0WXPBzK!%2mWfhys;6o`Vf+y7)+pzd@rd15EkY7N|7=^41sK< zj;iP%5-oNw_m7Q)g#B_cKU_-q{EF}$ScJCPPFa@dQQWpeq-+r_-o&$}b`ak6)#xT^ zdf`O*KzWO2_sAW7CM%1Zg?%&6C&>=29QU&Mz<~0Hu-GePGbwrH>pJWPHjP4{*F%C* z`}(zvC0!#T69b#a`{z%Q&ydu?v27MgC365*_(c>a8J4c^v_&;3n#DGFj7wy8P7Mwp zUMk(2k1j1*9kP0u2i#*b1z}bw#%hkCk=fGfRX%Jj)CP55_5|fN?VB%u}wE^c&XQ&H$&oKUL=F?RZQ$y z-{rh%G|UH-cc0Mh-Gd8CdYxM`G~?@g6dU8on+jEndR0Gp^;f0EWakvXBYXE8OR4W2 zz~0E=&as>Z8-vcQcGX{1QYd{7tECA=R!%-6kLF@36>R7R@m@FPQ5a&>x}0huXBVR- zC0BTo6^7nLDaCw(avbgTsyAPdx{f%O7HY`XLu=H^Pz`n3jT-KEACo zfp6dBC#XSQ{q93>|x_ zTm^;V1~bAf^h>>9Zoi|3q&?FqdN7$lq(h;r^wZUp>e&eN@m18>5AKmiLv;h;va#Zk0b>I2zTUA|CCPBAtN&7ayeDPyV~>s!i>bndogR6xhvI9Lm! zSs)2lMz^pq{MFg0Qn%YOzl&?gVraNSJ}Szf>wQR$dkjHZS`O?xsFU_ii<$$x)#$se zu%kd2ZS2!QK==X46yZDyhjRBmQq5isIyswDRl+R1=4Vt?BD+UiVM2q#Z^f!Yr+1)K z%fn!6_?e)47z6jEzVu+KGBWYA3LsL)N{q>PM=?{IbJ|DEPDM8?CHiR~%X;fTc20_F zePz>Vb-I*IJ1%btz#9R&IH>WH&+~KV*gwC``d^Q+e;GHIDy=uq9k)zzmT>20f6eT5 z`z`Hb;XP6Qv50|F?GwF*h_64+6>=E-(@A4FDs=-Ae=p6>4-~Z3-tkh2=)a&mbyK^F z(-T-6WS!AWcz>K5roaAi&TQHK!HcIUR!!AegJIVdQx4M4 z)Xbn*^tWr)m_Iv9(6iJM-g=z`^tu)V!h)7K{hj)e$5jumCZ#?MO>F8Zs=gl&S6KV) zadP$J9S{3^uikY`0*lGU8y@awS{uMZMR)ynncTI~^v2Ia=1oymI=Fy4%Z}+w4HiS3 zDiS%^`PM!sgLs-D4dLRyPowKA-C`zejIUP365oJrvE7Z4Ad~(zxiiN_fsXV%yGf*~ zq4Bof6SSZ01h((p2rI(gWrM$v0Qu!u<$FI!f-=gc)ZR06cO|h{7%z21txpzuz!C7d4ABEJu#dl7>A|Pz308ZYgLZqJx8Ru0ClkZjWtddve}8& z%f{8<%%Ho!?+qo)7CItW^(mR@{@rrQMYs*t-^H>b8sK3zQZiVN2kdruhyIO`-uR}Q zK$zj;;)OuCxFDTox^t*GPVp#t9(Fn>Dn@9w5H4fvq$=h5NJH&~nYSh?{(h)Z?0YDA zMY;VdCSe(q=;4Zv$1VgRdq3y(xirdUc;EGLgCs3)rlJ0pw=Z4s7 zL}<)8F!s}Ox$3_L;?Pz1@&vrf8}370~8N?*6-YZ`|E@Al&P4LX!qtp zXv68?TXm-PZlLy9+tF2}-fs!Ve8F(^p4Pj_GeWQYw6z?L#4xhve!PneeA+^_xcYj&-(vn z<+&E|k2a??)_lt8z-+#LxcB16IXw@h-QmQuSr3HHCT9>*%-Uq%<2;bu9)A4rZF*PA z>-c@~X|BJpVZ|5d*bU)%N`>ug>5c$PTk zx{MP(Z6E6>59!ceRyjVn==0;;#MKAh{r^#_`NZjsAE~=Ul;*`92-+m>s~#CwhP7C0 z@4vQ4{6#BLPQ+I^q8cs1x5D8^Q8`JiX4fC*{>pAVh>bYz;WR8c3XHGSb~BurR#o#^ z9;YM#thd!@{(SH}f>W|QyT8zJag(EjFP%hj@OIN@U6v+)eKh@ik8{{K6hZZrSQZjr z`u7j9U%>V3PFxM0K0C<&_|aYGYA84}pVQu* zt35h?Js|&W<5)5T>E{xtdm0y3tQmA<5dpO~<*1N?IwHPR-%>BhT?ADeYb6~wxGLBE zIA=;aMn;U(O%IDdl~Ud9(w-YNO*-;Pon8^Ru~>i50zd1no+wel$_~KxdCu4+l70&n z;~|*f6Bu~4Vb#_7VnM4;Snrb~Rq&IZH&`TNSBSr83X$zJU@<=TKnG z6dT_xTBt_6t5wwy+AjKWE_oBpS-eG`ZBl1B)x=U#TpGH$mW)yN39L;RT)+WBWa|FtM^0w>c22x zYEhLW z$E4D*s(p&RsV|hq9!km8?ADv&xa@jxidQq5YH>oy^ zDXul@0?7LA#g00Qhs^79(i^g<$$N^l0_NdU+ceV*3COcOh7YrSq0L%W4X7aoZ$s4j zNau|7MsE!C2<48Fz%6&)+sH4J{<+u`+Y$70hfNjjj)-E(R;t-eDM^vcFF=&;x{c9` zLxyl1t)5%rEoBzP)aOk6#b+lU7alkDt0LtQ5?2wpR0?WER(7no7x-bY_->Tq{7?B5IZ4 ziKsFzGOD&H*@knvY}?H=?it&8{#lODc*rCG&8)S|%pTzJ31F~YOX1-nw!liRV4&W2 zC&_8$Le?@*%>ukc#pQKY2(m}~0PcKE=zje92KlOthU9-FQqo(*E1EVvd_1J3a2LhX zh7HQPz4j>-n^GJSV9`9!=nrt=C+yMedQJ3n>D%=C^WQqX`05$tqC^OI)_R+ktbSAV zXlyCiVR>u{pVuMVCr4t{=4i;xWL~d!no^FN6@SW7D$mxp#uDqcpFM=N`sqHEo7g>e zvU`!!zV}{;hFNBnoy3NS6@)~T)5UX`-c4W|+5Mx7iU~!?t%`|(`ym!_e{C2!^F2~y zLLjilf#6MW+rx}bcfblEyAjE&BAAq|9DFE{kC>avY7sLd=`8l8YsH>7DfVuVlwVP; za%kTB(!ZRH%-2wThmI)Kz8L@Rabo*eC9`Rz2()dJ0v!37Z-bE<-WR2i`Fl>&dY9aO z0v!aetDE-ECM2bc{0fkF6bI`&n^uQF#qE4`pXCiqzhd~YOwm_RBh@bYTM3)siG+d; zirH#<3o(1#oz!du+n#JO9kgSgZnQ=R?;L^XrwMw??aziq6p261x$`eIES$X+nU~KO z8AG2xo1Son|CbPE$Ks?vX>H;3Ru3EdJLBBBpLBoVc97x@Z>S=Ok>_2U=u=Jm=3-lPcr18WMk;vxr!| zx59P$9q4eTvDk5;A#}e!!i{5=3rbtA5&7)a#3(&Ayu5zOo8-PxmbiW#-gELkfWOjz z66d-$MV4MYmaq8U_?8-CPa2QVTh|&~KFg%2xx@{GlD>`4Lj*N%^@dKl_&0JJGwd~B zxk5TtivxQ*D+uNTy`lZHiZiWl?2|MrMdk z)=L$qXIMGcltlx@c$^W>rGZI zs6EI9luVaPsht!Yx|gqQ>+IQRxY@KJT~_22z=}g4m5I{gU{hWhE<>?~1I-Q0Apr-f z1`bfor85EXAwFlsdm#e(7-f9S!d+kO!bb7a0|QH4GJA?1h(4u>ISw^5OUlOpP3jMd zoEoj&;W*#C^0@k=z4{F%$J#rEBcdCB1`+BzIUG}p@&&dJMX>|XKY=0a>})6-gX-t% zz(${LR^&8dLX45YS{QC-V}z)B(k|>nv#)bs%6|a}Ze@j|_>XnNQ|a`Y0Kw@LYrnJO(hHe_Zj59PF!8rbXjv#Zk}2jVF; zltyix{rcRcpXE^^gF}2zD`|=qy19H=Y6Erwp`#13GH)04zcrp8Z~7P?vm~q*t7oWZ zC^jk=rXh!^aPATG&m6QVTlU+HSaiZ@B{fLCOM_7{tjhy`r!)_hOhvC*`>f@;2+JD~ zr2W({WJNs-mh$7St==;;=5fn``b|FA3yWftr^u&0$XPdWP`eG{Tc@9gn!XR&u0 zg%!1lC|vV_$k&MPSO3KJ5A2kVo?=0#6Jj|wT7l3o3gqZO@E@mVxLoa_ma`g-h-2bP z#Prot3>v*NU*P`usH<<$_+;b9xg^OYT_e5E+dt0fPC1_CJuqe8i{F29_SSyCH-exL zT(rPBx?B@ELfZT>)#p}PFwA=r{VjF3tXA9CTkPp*^B}r;9e4VRN|^i(a^OQ8%UrrC zMsF|2!+s;ECZbLAmV>YMK+unK)eC1^22OsGyBE$TlJ+d_B;lZ(iDU(NdarKh?QWUi z@$0vFrsgLnoGmKVYo$m{xnL13d8~Y@nrU$)^GHHEe)q%c?iq&(#ZId3I?IBV*BHZs z4SRiYo^bfQ`||4w#NH|4uRk5fbEUnCpgne{LsFItpp`gZ+1uQ=oe>iZ)FK``q#kZV z3f5&;JW-C0&g-Pv`B_*nOnt}zCQKR;CGIGxh!)FhiX~y>pLx|kCkrzyyLDi?}*){5CZ zsc^tI-HZ0DN9w7?S~C4pfRoh=Vq>EK$!to^re@Eg#Cq7(-oz)nN3R?KQo+e?oTfxV z3dFoI*Xq3gre)VX89gSc*6x&kKNoDCIc|+kFzB8rkuNdtT;eCo#V_i>RdHFwZnH7F zblut-5c8_(5%=*UJQ8ORT4EtJ-VUSM?k>4-I*UBIM~H&7CeEv;L+#>m1XO6+?qp>A zte?31x5}x)j@m%=+g&F>TWddh`|a!7rFxZ*h!i`dO^0mTX3MrzM&JllPH6P%6QrQz$;LfZPL4`q3keRj?qT6FHt!6z)D!QJHK_t}B8 zD2qc##P;Ke-#GXFHJ#0j@!g{EL)8}H>rQ^dD}$6RcOg}|h4xjiQw?Pkw6!*l){uQ=v-RmMc=aEfHLO@Uc+U-GQWG<{xTRF7hM`Jv5k7m2H&t; zd&RrC<|}@kZ;YLU77uwwGp2;b9!Q>l}l)K*DNUkBS67~8ui`x%P97cd-XOo|KoDe4t@{`o}kGptM^ z7^WWHiiS*!SF{w}!lv7Da6V77;L$uB#B6MrBajIlu7}_ZP zdN-PUi|y*DvVjO{CghHmtPrs)Pa`<%C$Tr;n1PI7pO(H*uI-1OHkuw0UQ6S`11lzm z!}CD;XNlMM240T-ICnqd6r?%lc4WHr>h&4(w7YoRt3Yj~`AbC5o4r5O6$Xq<8ybsb%gSHiOKR} z!+q0lv$yvV-3XCij;_m85$!MSHV+HsB6LrG0Rc%l#q)FREx&WJeCPA$vup> zyTX7_;k3lZ4;<-K$pnlVF$QAv?ceMq^I!a&W%ALzpb#j&bzrPnGd{Eec%%K0>fwtC znDiT=x{$MH8I4Q#49O&JljV!B4U}^lb%HQscxrEVyg|o&?k2ir^JmxIPUdf|O&y|H z+zCmK=+404C z5WnOP0EqXNXMRH*7x>wZ0y?QM&Y02`o+&#|DaZlXo)k%}VerAk(76%Vw#Ilj~Ofthl4U62D|6@arC#|lEsm_BVL zb?gQ^5v7A&fKGgXp>@*^hVTKptFL;Dv98C_yZHsRAbHz)M?fxp)7FcWd+J z+$i|${%ZUYu)Lj1Fm+x~Njy6Ab$~}n3gf$k>4*2Cc9njHpCg2&(-9xIhWdD@tKeAQ zeG2u++FEXL!ZSmS&b(qSs`fBsA;cz{6u>1okFtrQnGGP!y1qgJcF_Sblct_!$+7r7 z6atA;^G-qu;Tt1SHuI*+H}>ACTlFVlhoJ*GbxwQr*T(6OUC0w^Al0i_<(Jq_@?^_p z>tMsb>tRzlon_8lc;g!HFB5E0fDxq%-DcHAcs%c?OwJ& z&MAInhB9{&_;!ANK?5t}87OA8GMB;*SWi1ZwNEKhRAiaMFe>u8)@*WndgG?VWzJWg z{(bCX%DgQrzZ0Caf93R{^x&>enn5l;~n*d9&|lVrg8O# zjFqFfmgwpD3RX*DA<>MNm)B@=yAX~%U(YWsA|4-y<~8fnbB4gn8inwaX?DK-7QuH{ zw3tK}S?emN$=~89evgAD2o&b}_rYsT7|%T?e?eD@-*_x7W6Wbw#TYhWc~r4HsA)JS zP98vlleCJC$wR283P<5o))4+{J3E}gOZN=K0zgbC;Z*kBj;=@QVHbz?IRn%)&XJ){ zFX99_iIW|T(3Fa({(2hrxZXW!$>+4@$2n#@I`i|)M+KPq$?kZf!^ES$8L`0AS1ogw zaE1jsUulMddb2 zfV}MeGS%lnk_$^}T;SLjwHC8|VIr4yYtm4Y?6TF}WX_V^&&{!?E`0VRWZF^iM>j}r zvG=V_&=q$PNLl8EnA(RBF3qlf(qErxw4J&GQU6rT-P+|Kp-M;#fiO1BlK@%(rHku1 zs9$I>ms5Oky-@xw!YA)+@(|o$p?|SgBrfQ3yxD58h23}6@!z^eZ&amtGn;zIDA5K$ z#rwue!BluMrmDPA_4m^d6#rA*4qJfTLSem{qz8Z_1GIf8iz%#7Bx2aRz^-xg{ZgNl zSU%;KNqA#&q;7|3p?r3p9B@0j@%7-N6_+%N+2z-$E8$P$HH_FRN@yb@*EI0A4{m2M zM-@CBRF$Tj?z!7|5_OpB5uZqkw-V&5-*kcaZJ^OjBOA3#6We@hu~9`AQWQ(R72>pd zD}gI<&AAVh19qGtO6gCXhi?J_$inV5HNLLI_Tf7tg*!fkXAM*S527Cr47zsC-Bqjj zIvAhU)P5Kh#~z!bWJrP6;hN<(Ch#2OxFHHuUR)|GK;o{an#UIBOi_^OvUKagB6a_iPF8f(#M@T&|N#hVTEBkO5I0|Z~VvT|G)Y1|4+fQ zOTy+~pk5#L!p*?sqM%SYli%7RHsq}DBM zuTwNuCd%HQo4sF=R(oC*+u4);v-`wG*b#81)_V7<^+}c7x&exZ(Bykyq7w&T-ImdUH#U`1jpsD^tE+p z$X#!EX?3jf>$r+^Jd4Gua9drnq*n(B{Yc~+AZ@x)BQ zf{G(sXVX;AP3JYsyzoqG5N~9gSVn$`srB&bPeVhOKnlpJh&YIxXSda*NyBnuL(;Cy z%XPh}>KcoBOJ8bsIZYG@?_O;)@?YY=b%?mXoNJ{qNDuGUH`5c9;N>izQH_xDFG!-> zvUp~p{#3H+fUbhLPjbj@U(`@cFWO&qI4gA72Ba*E0=Y>r z4>6lYAIrS1H@VQsxdFbFU|;ZL+ml4_uB(+9>~lw!%dIJqt$YAW7KQUxc6XLC44cb) z(>EF{Z7@7q@33>6R#BR^J90GX$Jk~0q0pn|^$`238d4+DSh?B;Jxbm-%;IyQGcUh$ z4S08HDy*BquH&fp2#D$M2K^c0qUi@{#}T#W7-ItPKEB(&=*`&E`uV&s!=jF{Fr#pb zk30FYT*Am*Np6Wa0U+`;g=yRkuq=^>Wp2HZP2@N}A@@5qRQI6j`A5 zIc&;PnTNNseb-6~O8Tr@6b#BL#emUeV&%~xa%zI)+Vrj~( z$vWjdF(qHuIf1}Y1-J9U+G9FsB%h*$4%74=f67*k^36XEzv@fPCu|_HrC}P@OhPVo zV#(Qf35zKNP%bimoVzC{y`T{9Jid}AI|rsq3~>$J;0@s!Ups6b=uE z<0+Ulh4+-#r=ReR6cjYVzS~qW!DfBL&3DYfK3Qdmaz`{V<5IM^L zqfl5jvWe+d+t!0mR2kJ|%i?0b~+!c$03!OG;Ytm-+as2lLxi z1&Th@+s-R2sfBPndM+R^$qf9W3V-~?Udj;VhxUm7#9NGD)0(ECj7{I}yQJ>XBgi|G zrpCtC#s}qSUd5-s5r!eqK8mi^j9VGH1xu&{r5FIBIHfgie!za4vPb9STB4pP#m6_N z|2#pZDtXHl)Ae)RNa1d|r>-VY&Ng4VtUS;q>yZnAK#Ov$FXhm4-^NvAH^4r zbk3%jStPI@_(@+h~GkDL47Mkpv=HRdgO7i!Yttt@+EWy=B5mQ+BuHdQ|Hl(-DQ6Z5Cp=#jl`85nqN! zYWbi|v1iItxYFs5=nno(INRz@?hup{+@>B{c{@6*Qpf+O8L;so^KJAk)0CRAybsid zzy=2QLlnVU_6_aj_M?&nWAB-#*gwzx_C-kJ)1UwK^t)7lDywPmvXe`m*pAwd7ZN) zh+tmhmE;ti=7Y)G*CYhuyLH6Yq_$y`}4No9sD$Ide}2x^>@cpFVn1UEA$% zEKtV^EHx~f&9p`0)1xKQGLS<@bykMYpVSogYu>jkkuGvS%>8v?S}dK5FI--_H%>|9 zlIviy>W-vq?`spfQhW0%Vpz2HAiq}9Rq2m&|60)BEv3fGeOjTX&VJrV^(W^HPQ<~C z?P5tIAgPjfohl(wRJ*ByzjPD)ttB>w>{i*Tp}D0i(C&LkDNLBXl5;~N$!3e^+mj7+ z|7t0C@^ea|TtMNx`fn1IK8m;)lm%nrbdDZ&?W+Fo!`zG4_5%lzp#C|yk2xZVkmCDT z?|ZQ)D%*v0pA_a-0g*V&_=&R2(y=gUBXQEz?lkbysPg;wVCRI{R7jPm;N{B+vR!ECWNqpxDf_<9uU>ro> z1oFq`Yn1a|n8fK46G~|`PqtSJTGd^(5Xj4`I-bMV%a&V|j117rYP{c=cHg~oy2zMm z{j^uJns@kvMtm!m)j;KfnzqubR5O>6im>>loeMo!N2{Hn^H<9pHv~HnsR|?>()wDq zpS29cE&x&@&(m)w$H!C(7ctola5q&o8$Y*<#MRW?2l&Y7seCKxBuWQkmpoIif`5bEr3_`< zT{Y|2_5IZ6RZ$A^0||q#ngn$HQtp~PO2bcuA|kXlFg-=dban?t4MK=vwO>739vFq? zY5df?Rhqe0UJ$&sE;+bf)yGA_T$IU|V|z>IQvEzBou&LCK$7Hb-LdAnwO2t#PYy4q z*o(I=el}sCyWo3QTUcTi31J`=GZAB@^yO-r7I+a*FDWW%T}8kBtrx>Dich&`yt1$l zCp1jv$vcFZq**Y$^fqiRC#wZmdD+@Z`t~=n0(F7;UvFL-%aKca(}fV!ukjLPD#MCy z`}5e9ONe<|fe`nsHC}w(7_Umh+2Hck@S^xg|H2%V&NkbgsyUDjcnt{5!*UXeA2U(O zeH@Q6kjr9F3if~G`#$fDzNLmG*w-5UL0(Mi51>7|1q9AWi zJ3w6qNof-HudK?lqhE^2yJ4Zxh2^Y<0Tm7k7^SEr9gWv%!NrEScNH7&-aYwA*P(`c{PK2yx~6kk zO@A56+v3i&RikJ!Kl!f>o$*-#CX(DugaHy@Vi3cWC*PA}=e~7eCnL9{7YY&o#L*2;KQ`IoBSI*wEJ{}&F z`|8#HN1HWk`z}oz#3`rfzNj`ky%Vvoc=kFealsxKR@8RmOX<0N`k;35Rn;TFXhHph z#bDf7()r_C&5uii^0}HFr`@jzGfa<~fy1Z$LBO+1E^{Hcepb?ia>V4Emi`V<>*I7G zE-_Jo(^&D|Ji&KmMx|{6Bp0VXy9zE?Hch+T5!aFs?ehz)lgJg!mBm zXI>~!f1ye*ozz3n#-k5bzxMv?U9ie+K+c307K_9@PhsjO>Z@<5_uhn_%J@=I>`S+g zz(cA!)G8fnU*{%o9;x`te?09Kbr8r8Mf_X=2509#N7^ale|z|Mb5xeD1I%qqSga7E z(k~T23zh0^@W|*C;&H$^%@gmnJ>}h@{dn8!vtxYME{+@X^a$b}o0R5GZm6&ICai=_ z(Pspq}$u=L){Bo(GBS1%%allNK|oQ+Ks^S z<+K}*aok;lT#4C}d&u^~UM7=<7fGIJ*r5yy_%_En80C=W3R2AA`2C!q1#4km+rEB3Wr9O(P?r zu9>&m2X8u*SHn8>L*l2QJ2jP{4$De|;LYDI=^7X=>DsaZQM%n&^UNZ320>Z7r2Fx? z;s+x@GpxF#dkP@I-v?FA)kbFlm~5rJarWM*^1m?=-BlE*H?3$Ju4+#6v7zIVu&o?= z^|k6V;^1VXb#pFGRbWO^Y*4DjTQhL2dhP~N`g(0flGB=*Zj;k)lShT_s-z7n1!j!= z1C4cW-I`~wkYl^<51m&lmJ>gT7H9J)POBWWZ?X|~Ksp{74NzP~9+o>tCD#fsrH z`5m$zpp0szz)WALhkfqjpb_h;yUn5M`xqH%j_o)>fy$_fyWR3;Jw~#gzAu6W>{Xd8 zD;=hyqX`;`YKKWH4WuKz5RAQS z&caJoM}DR}p|A7XbCsC&__I$jrt?VOlRxp9BA0?HwEpeD=hZw#oun6evL1z~F$_JM z?=)vhK}<1>mc1|RGH6#CsNO={Vh}EOH#Od9juQg~WV4P<>Is_cXZbssXd7AST`|l( zcq)tjP-Vf*CEdz_j@!z~52s&CB9)ZA!Y+sh+zf}fmW0SEaOmQ!SX?CBeJkVhTzRIl zPP@C{1#(;`QXo)o%ttuDnJmOQQ(Sx7y)b>~f9II?|DSk#zyF>GByU8p`Z+15!RGB^ zR+%p8Y^Y1WB|1+PiFNS0PfZ7}w@tGPicKGRy1rhk>!#M;^&hnUV@b_I(4=k8ZQ;Y; z>+Tz^5;t9MThVL<4gS75N$-@?0v?(0QnK$iRA2(@X^Sx*m~@FTdwDCzWGV88@$|^a zdoW<`=6@PBvxIK1WyK>UE&^wus9aW6jo<+28GE<7>`r2~muixNYk7T-oQb%%Vt^j^ ze3OG@hI9OKaDcfZ`<00L;5K@m;ToOthzS=$z))+vw7fPL4s{k`N~o&S&=;&@Ol_2($FX>nSKJ5sJvJKQcz-Pbxr;O7$7oq(GGMX`TO-=sOzv?OQc)$rL zDb^&^0g;CuqN-5^AUWLLuMNPKnmNDsoNAa+pUf{-AUgsK2O23S;F6AB>RppXo3ACn zSJ=3uYwq^3N;sx0VoRxRaa3sy>12d{GR?sEClKeOs7m|%`F3zsh+x$YN)>71IyOf} z*ctBPwIHLa0Nvu8+nHcqLVqa{=g&mnAA77)wjfQJ2p6T zCEWz-2F+75{S}e~W>Rsj!<-IxNxw%E%S#Fd*WKIJws&;+ieN0JKP!`rVUnz%Uk~T@ zR$iSs@Q$V=#Ca+?yDIGI&rej#9gF94hcGwX)>y20V7Y#V-~9klgd1vgAhUE|f+Y`@6TJ!c-5lyEb=}`>69yIGqUh?-Drde&h zkor!3(>*ZeHd~kT`A)Kt7@NfxD;<@6DKAj@&V-o+gW$&x?pv#48GQ?1zmy^{x(!$w z7~0V1TlqF#)^vqClP912rXi$Oq;ho{DlrryL#QBmb7K6g9+nrEg;C#ka88HB&vie@ zYoRh|+J4<8Rgl|QOZ|w9NV%3@Z-MD1A6MLEi*QIR9~F8uwXVpuAR_oy_LA-c;?-cS zSy>aNH9+Jfp6g-3R$1}<*mZ}}=!f_1k<6L{JO{^UDWpNeBPF%E>|+N>Z{K%-IE_)Iy?CjdXT^GcWns-Awf8B^ z<8f)!%wZ%YsufRu5t@uvrplE~+vBl4{&#O@rOhGxi*kGYbF@ z67R(%-1;dPM!XPu)93I4zr>^<#4v848()+sMjjo;#E18GFR9A#1nhs_ujjk3DBM4& zw7dLV&)r7qt#kD*sKDR)Ow}Z_w?jv0+HD`Zo%1P==s}uF!jjpb*$sZh<=QAei4C2s znI?*#wUP^8YWZ?w6c^#xB*CC>3V(7_P6fIJcQsOw2G@W)4`MYn$!!ZP%KhiukH-JH zc4VaSQ3sS})@h{G4;(LfVq}wal-=Ob4~xmgSb(wEw7uW7Wd*B8yIF-=PMni2>GFCU zvbo<=zZ}G@?crnR=4#ije*fUJ`*9YM$XVs6(M%47Kw|-?0)v!CK3kM6N^7%)Mk+a2 zQxvZ8SCrokJfkWV z7QcrKMJj0=7*y0*O%FK7`rjo4rk>1ty7WAm4s!1n+8WkOgM=o$fiCZh<8&AOpslWs zWUVMGPn)r7vAarlyxp5j)BKK#^R%Tx?_t?4%0EK{bR<;6}iwSpJzx;f>y@{F$?y+}6nDLv*DrA>c$G!sD*?B8_`hDqP8 z%9BOxX738G?SJ(=o?99|En8Xq*$|oIKYP^uZg&PU+3kC?eIpg(Hb`mU>Ax1N7-SUI ztoB@6VQFD7bE%!4rMq(8{Mg~QfZLnB{FbXba_?hz?7b5+%oyU@Ys_!NZq{2(;WEz# zqFUA!f>~ff}b)c?o#7lcD^uD9_9In%C4VUu_sria+Hx2H`Zl@ zdHVC~W2bgbv_M*^AS)e~)WEVVBq5dQO;vD(=avld81zx7R4;Fgx3t#5`kEx1lz;;^)CKhvredD{qa_L8YYns z4@})d_a>h=|H#&B9-ME6{Z5e!bz;?#ll=OK*sutbz%^Y&e5(YB07##(kL%=hv;A|# zs914(#19)wicWcv=hRt_&bqiM0*8O^0l1sk3NHo*wBC0}Rq>tU(pzl4mSDA;{dl*b zlIzd<{^_1o2I({xlv?yx$HY6&f})2wdac6L)b12d3Sel%ev`881S9&21_-(+FC1xU zS)`H2YX3a)816UVHXBi51n*H8THkqvA2(#xzm>;TVW=(YJ)gR5yV{qlooS_U&JESP8l8;h5SIAU#FI`9Q?1;*sTAi#zy`-HTJa|Zy&am z*0GG(xpy>D6Y`C>+H>R4nsf-!uog1rwQv(}$UB5mBf3ufdcJhXe__%$#1?#ZO)1P~#AsUJpRR@nO5Ho7WDO)ucLu$Zlf8HJ)=cizsf-mX3Xb&#w{+hZm z2V}l0!4T6Ekof||;ttXW=UEV>%B$t7Ms!deRZMbQy$2ANwv|$U%s2}X7oS+1r0`bc zEch-C?f*Osd;hvKlu_~+wl2BZafSNLeAvZs!|#&Ly@yiBhJ4~_Nc##1nu>fKq|3}Qsx8DPH1SDasO#qc$6q#!Ixx@e?q?F*C9a5nXe z)BN)%p8I!7w2cveChV30TR5o=il2kFN)}}oFo{oijL=PNZ+sloNtPV$PdIm?A!Q0J zX#Qh}I>>lXAR{o;QjKO%$K@?*h@#t3g*30Pw3$+JrJV95-LSCQbO+_S`OBGG!t0RZ z;&ya|1ohe`;zTyF7n48SKt&twK3jxA$6{!_o`5SO;qohT}L( zXxA?uTFF6rpyr$z%pyqu-AVb;mZuptl_=P!P}C zf(fVugB<51YWqcsrvrsIH_a2rpWb0A@QA-FEx*FvpUoizE(XI-K+2EL9Mb||gR)5? z2up3;_J%0Ih(-1N{FZ}AI^zdNS{fVK*5Q(Fq0odz+LbXPE-G4`kkz)3xAt<+mfPJ7 zC|;}&D38@9RXZRTpMm~#=QOc!Q?1}8<2m?LB-yboWE%-61gYyR1iGCbRguieges!J z*POmEKCfR?TrcVP#d|XJcBsWFUGaJ>MajLHv-jg2sso$%7KA(<+rlm4jn{D|>|9{p zzta9f{=kWDmKq!k${242%tCrySmObE5(Ak;o*7tu|2?7vNgv%Y31f|gb~nN+*{dyf z&=sD-$eHKzsr+$Bv;`J?+Z(4)W5^H!;VTWB-PfS6 z6Bc%&^n;D;q3vxX8p+o1e(!;*!rPhU$(u@XUF=o#v+}#5EWa1rFq@SPGzNrUi5Di@ zPy$<(_rUs}T{h<;q}G%JXGJX`yu-JKtNna4Xm^iU*YadaSt3B3@WAt1ZbC*Xt&c^r z-G?`bOlx+V#;Zx(v-+kjV}gg>$5vNMVoLGE4!5{x!4`0`ynw+D z8t@}b7w^DqKOhr?NlW(}Di#Eq4Tv_BMGD)~C|#hrsAJVKQ3E zPRQ2)+!9V8d!{|lYA&{mfxQrQ-F_CxWS~?@GwvH<)qKcyEiU;vmFMt6vgtaetSzu~ zW`vegoW;=il_{O*MnMHFQRj|^$+82QmvkiY{#~8Wg3u~b9Phb*uyg7q9V23FF$S_A z^Zb%7D&uRni(08sXoCS|o%<$=BBygd!cr7s(hB@1e=Nd4O?g=s5UqsD(I5uq(ho3)#2_4zZHE#U zka>P$BVCS%veZ_~nGET0=EH8DQrRKfe~lofLicI6*RP_Ao`eC7p{^VdYG<`y>|_H) z&du=UyBZEUxwP+MYZQ+>@%T{*zx z4^~`{N|{^SB5tGn=6}`XJMC}JBqXEYZ{p$<{G~9Mja7mikMaR%qcr9TbXPUB2+EOs z+<_Qvh=7#d+CRO)e6^Vt@$_UMA1UaH$eut{J8yozeMtv=g(HWIdsSGq5IMVlj;cL@ zoTOaRRs4mA8s;t@tWa+->b$GSdPH~BLa|-k1PG$-dqJ^?IIH@#rvI{pQ!tRC-bP^a zDUE}R6i&pUTbUYFv7497aPnG~?R`^dDlf)Vi@!;oDi@*A3j?daaPqw(E>s-F1 z18z3}_Vp#f&w(Hn02~1#2W8xWkDVG!1AyXAj;iB75#v6|YV$UT15c}u^^(IJ!}aOp zA4zfw$GQlt8Z~?P*}JkV3sbe?T`J@vg!VI|{ikU2pr}pAcJX;={`{6fi~+(R8|Zya z%s@;baQji_{JsNX zyZVZbj{m&u1ZN^Ss^b`&h_m2^eU!}t*Xgd^skqXEx*_G5Hfv}*YwW$ur}HhP*j=Z{ z?Zcgh2`o}@qw*{<5e3*v)uF6Jw*X1_D7*%kkJW`AXI!kQT9W zra;Yg4CHF)ZO+x`=>8&3y77g)TAEf{v_P!J4sIi={bBW5k-~b%2s>wN#INw7G##P& zmK^~Uv?V+jIz~2ik2y90)fMf-ytn73#~;ABKZ8=SUFU)z14G#M!tLY9>)2j&Q}_+S zL}i*@Xed`XgI}9PRyUp!fJ^FJ$0v3sb*RXw3w5v#%s6n()7IRIo1P__V&?6UKqQOP z^PE);5ELnDlOtrgjzhhlPtg=qwk1EAOp26))&8i6xs!x0FIm^)!nJAt=3S4*maUgb z)Vp^GNL)CILz9C(7-LiPX1Hv0g#(i09t5cykLieIS)Rk1$JU18lQxoOMMpEdu>wgC zx5`QrrQ<9h;w(I^-qNz$Cb|Fv-5q496j|!5ByHU#p?o7nyL)YjMWhBW&R=4v>^^(f zol`8Ek}&(TP^5gL)Hz9PpV>&c6>4P#DtSQ^nhmu=>4J12rfx8dahIfS?&n^KoSQ$2 zUBI=anhOuKF6k_Zy`JLUK)|{=wj9N3)SJg@nV_x6v5wiUeYIX~`v*vS-%0}5!(|+{`5%H z&$Bo{X6Y04H(QzwZ8ty)A|OkTJ9q$-5h`_35m~9h1ym}02^F-4$d;5P>?|eb7fmQb zMfsLQ**uVX1;whbiJE$Mb@UK}+vdfoP5tGY#Rvur`j*Vp&xN0BZY#lH$AMr_f_)W0 zvf>rU4QW4UMR(g>xz+Yynl(YN{Z5vr4}yew?Z79O2!Y>#VGK^`qPJ^T&q(J zb6b$kwrE*@>-D);Q3R20iB4vtCz|#;=BLdeqkgQnb(B!1-HxDOoMzg11?Wc&ZMng=v4K(<@HY@zE>Y&jnfvDM8VL_iOwW1#j zVvtF~)3T|Y3TX7qiLgLi`Kh?c7sOQxwr$D3$wDZ8-#7R*68Ca$Pqt1B{o$iPMKMf$ zx10|v-@4~VpJtKxIvutTZ?>-(CnBc>^Pm9&he*-2cnkBLLL;0Otis|OAM(Jh9+mD1 z8Ytgt`<&&#|0OYddTjHR;yXc@gJeQOY;LCJd9+Y2v2W!#)NH19jQXzMs6L@mcE-nf?=hNT=P}iA2mUBVXO8MJA zCvxP8Q}UWAZP>i`ue~)nRz5DYdX`q8BjqiPL1VIp<5ngX*NY{L+t41hGw@UQ8PAr_ zWm^!gCSY?8s~<qmpFABu z7M3K};Xp>QP*QF5@g`rp-+pdPyR^{sZG-?2Z&R>T!6oZpDfQv4%bJzhoA<#G8^^uY zZ)t))=~cNZAN`=>V-|!BjCsE$*8N6SZ?c3$`O`{l z(zN2@;^CUV$-Xq{tbM-zY_eY_zu5|%lGd0eVx}lh;1)>mpGX2CAz_tF3Vf9uL`+nw zsfRVPPINrks)@H>Q+zHfU9+ga;8gpM`tTb z_?z7f$4_XQ>Htm+e_HrZu`SDy-2kg2ZibuSI-d)f*H zZCuw8+LsAw^3oz>@9&&njj>)~{4yQ{cN@>meMN& zrX?LlG&GJG@<|3q>Q^f&Y22Ume1))>-)hF;PYVmYAsRP z1DTVC@89(ajeEJnF;y7r%zz3%yAAPcYgUqq!dSeo4zQv!6d!0xH(3<<$S=p--1zLh zpL#ZzVX))mzq(_G^EOZWoT$h&OYlm0;one<@b;-B3;t@b7YgdNagEv&7tC7;mN6$W zVe!jnX(F_~>zVSo1#vloeiH>A_xiM2G&_AeWutGcEeTq-M5o*1bqdqU9Y2+Ymk1de z@;ioW^b6RpAv1gOqGM8gKum+Crrvx71-5R9z46e3f+G?38|PQ0V{N;2YF+s``9?dg z?FeudkYnGmMJ~+GK0tGs7X}z`D;R08J@wsx>g(Am=-$*{iERKe^_G=I|NWEsw;^#^ z3*dsVlW)i~RQ9tn`70&jh@NGoxLVk?QJj=n(_yiU{Dc)})#I@&y5N!V(VfE&z^^?t z_TXT;eqI?5yVr#Z+^&3`#9GDNT$`ty>m%$R7(VelR?ESznX+ETiRB>sSjF{5MrK#P zTGuM7(sFQi^@{gY9~f51fUAY___K?7YV+J_=w}X$Eyy5Fgb{m=+hQg;QWl#nP3X<= zHim{Zk`c;p&6Mg(QRZYzB7WYHIB#26VzlY-NqddW-ckQ(N2$ayVPwh-8I&Pik6Y#+ zR&Ta?(NhLq+)P8@ZS&fXc^?1)k;m+4w<<>WbB=b8j2N3?-kg0{$tNmvoDAwjTk-U^ zU!L8^X)~kZ<0K2G%EU}9Qc8z+c?F)6D=4Y6&PcbmX!%V78%F#)g<}WA11rsDi^z2$K;}qU%=3*rkdR*BIO?*7C^-+K^it`jxtl$1T_axQv;JvgPNZ zMpoA$VET38RrDoYM_pvdUjUIrRkQu)QC<6~yR-_Y!#3b+bxGGMnjV)C53pFmB}Ymx z>BOacsFLh}L6#9P*4f_7vS=aoh`l%&?OQK6D=XowbZ8d$0gq~GsyZ}*$-j0eCH~mA zIlOs$V``3kN4!HJjJeAy)SchsPgyq)-7cZFvCWQD*IDDKCO2KIz;q16cx{Ma&NytJPjHj zFjZg-4%1M0umMb68v`szwZdUqH)O=iYp$OpSsz%yb>|DuB>chQ{Sshcv^+Z1;@St^ z#OU`+ItR85*S`qwSW3^@ekZ4gln~L`)%mc7P@>CLkwOqwl|x{*?PjM;GB?>U%nO-V;I! z)@JF$ybn`L2?hUm82wVliPH8gXZMo#fXOaTCl1u^@W;xe8=S3tTGTu8!S2HK;IS;W zceLBbCy6aHevStC@x=z=ylHjktPdA$=RUZOP90EaL7D#mYjy1l=`7XEY=*e>UBXtX>=(M^-FC&7fS?%YRyhS}-npE{HDN06Ac`jSJUCa!*g9DWpXQ!98 zkw#}``DYZJ3@QYqE+BKXg<)9iz21N1(Kl~+9G85Uq?Ak+ zxf64(47{7Y7YtN~-VQR*EB@A0NmAey6hFcG@0yJ2_Wo>g^)K;-`FF66DdaH#Hld=BmwQGg45E**2A*%_I+MGBF#0*Ic+(kwj%Keh;H&cByrc_N zxTL$%5p#-ZKd%SC;{HpzCH3I%yZ}H0p}hm_;=VRt%&jcA_NkgAe4modlVTNTtuFAM zye&OhTj5X@?-1|!ahorCz4;e1 zV~h0`!|4wyRqoBP2mMxgNp}~(v|~w}TlbL{AIBFz%rz$|m!1LioN&0+NsQv*YM@l3 z^dY?sO>F#|5{r8q0FRm))p+<8 zU5OdovPC{Wb`Yc1jZ+xZ_KHfh=vZ6@>`67gRNNR*QkJ zTTUuD_14OpnrC&_4DaM{Z@Psi)`F}&OpJzAPIaSCo`mbHM)8FT-eS;Jg2SDQA}Ow{ zM*L!SpmbFtKCEXQ*A~ZKcVn**-fjG1HxeetA$2 z?2p9>H~Z7l85Gn-_}gRKeO(vZ-ybVaC}|D45>h5b8$wmGf^!-2IPQAW@7Dh3I{V!G z(n$aBbteC>b@pkajo$BS&IECG(9bc;((;K_caNTtB_+Z;CKLoLv_a3ef}N?ie6Yn% z_ke}w&2MIJ$i)4Vj!q^#6KJ7^7XX0|rJlcCMFj)P?~?BOV79)G8NfF|XgNIQx|sRv zU$qo)80+)|HXbQBMyjGXt?m0!|Alf}-@;6;#s4HJGunowEE3Xzd-gofYw<#?`}U^O z*{BVg0gU^a40F}P#&f(!y#?HULqy_i`jh!zfYwRbIb z6!klux3qGsM^6IkVQ466lXP@;Nf)R>ev%4S^+gC`Y5!bFiyQQ!e$3~pm}cQrljyQ3 zl!;RqlG(DW$h50bjn} z!EpZ6zPcQd0_S_Cpe|lbM$J`D#xw~3; zY~f}gII|O_wST9UkhLQ1b|1DaTkKv};F>E=Aajb;jEz69^ao!*YcuUWb{w?eifj!R zDU}K^)+fHivf4HUWkf~|*YVn}9VHsYfnM~FSHso0tw)Eso)qvBe;GpTNA*=5pyVIR zO_GZHcPYdB%-l*56jt6Dpd6RmZBCD}P)ZxcDU8v;3HKoPJHwDwEVW`0*8R@!Y{h~$ zy)ef7$w@!x?i}x?YR`+C-pc7A@dSOAy8El^4zJ%|(X9C0k+V#0d)3}sKiz8C^>ctz zjtXu3bioJ?8*};^uG9fp9w;1ZU^aUOVf3gqo`s^emOLRA5|+^!?o1N>i}cFZ@HzWVUJka!jD% z7)N7&IVFF2KwUorib6vjyY0KoXDlb&VdXq3YHo#qNHG3(f!tR$yakc^l}+4Pe2 zzB@n}Z$6dVOjGo!Ch@J3SbgPWjm3Pr(fZ4ZOk6d+*$p-4iSP-0gHJZjI_SC3*JV1-5;NRE_hmd%O_U;RLHNvwOX|3XQ4ut94pRN$I(N z@bDCq*d-ab@&GRp*ZQ7I!mtDys%dCoAlH^;HV9U>xl1T$hW) zIr%Tf%2iE?5u=WC!I)9X{ARZr`lJzutc*f4$TW@MxW?0BXZ*;4}Zfe<>B|#V-1tM4$^UQ27szRe% z7UtE(yK8SgHu5h?MEfMN8b3UY5vbIlRk-)3mvRbEig13g(GwP4D@!zC!ho2-oSy3r zEQ3DP6B|QdZ{Z!2${#AuW^Na3=1cCOlM!yQ%J;q;JRXMBpZd#0K9lPCWKJ;DRMxGJ zjfXByl40a#HLFoW1DAk|g4a^ow_wxp_kdcsY{kLP5!sB(ip+1$G|5ohOWaS~uHWP# zi5#O+tx+T-k~FkS?B8_yE{y{l+~O38d5Yg9M~GmshH7vfkSWKXL$8_*uVBVe<(|d# zVYQCtv$EhO%7dBK!r+Ql?dx-S#pq?9orBi0#&9fK`v9~{)&g?6>YR&-@5>$c)SBZV zK(b7p6VEn&E@Zb5F|+5&f{IPt-pMzY8BOBlV4>*(?}ZwYGkVG4ZYsN4yVDM%*@mou zyQj2{LS^d>?XN4D8ueEeG-wT_JB=411(;?+F>(I0D}HK2@=mgT*_1V@gFp36tWL(p zEPrZHRu8TcesV8fKBiT93w_kXA<`Q;eQ$!~-MtFOu+&!CE20hWpj922L4sojuT2eJ zo4x2V28r$(2^t&E*k(nQJG$8ezg+#&XDw$#F~vk;JzB(n!6Of$oPCsybTIOJ`xgWKVa8Pz^J8^=uU8h@Mt#r#A(PA1v+(4!2(6FXM@ zvLCW*!eHEPN${&4n-Q@Kp6vl)?!Of;0xJSOlDu`P{vG$?LH_doSPoRWkT+4pRj4Xl z3lrEVBakp{YHx?Cov`Nj&mjr1Og;qkV<3rGZqxPS!Lc)*w=CNK&w-mc>EWWJah z;zR~hnNhnzf1h^0+IN;zft{U;CJp(ZGRJUn!xDI#L)1rwVT=2rlgcoGJR*M7yUWsM zV+Wnks%EFznl=?C*kyx&+ z8{3UH>8Oi$_kw*Z%^%JiR^0R)`Go z91ezU&vvCY8O2$rA)h6A&aM?+LXQ?e`9jz0N99WOBwf;3qs!lWgrP1*hW#d1RMJ_% z_6|Rjb$Zv(UflN|p#9od(B2@2+|tdb7x17bf{)$_-%YRR)B_>OJv7$8qK0H|*lsmVzH9#PvpJr!ui3%gRc%>a~8N>thpv-VYea*%=8W9x4bA z#ni6OHIHWotTvU7n$VC$U>_{=22s8g@pKdc5NQb7v?U}|GLI2(VB@V{4pXRF)%K!A zpRn!4;_6Hh+WFMj_D?HJjDz-o|M&2idYAsuCV|mC&f!dcvVAJVkot}XepfO>{e*#f zm8--stM5dQ@~?khvInd5)VRNm%Qwa*?#B_wA#~a*vCN!j8x2hUrjYzXoG0U@a}GKAbEhl&U0{sJ35D za5&3ByjmPppG+>%Cc}JBX)AwkPJgLp!CBCJ0a{sIS$ngFk6y&^&0#FE-F7ALR@9xN zdWua3SFD1XFJO!bF=kX+E>XToSYxThKhFPp5r9-37-@ijFger=A+zG|R^M(_q}n(udshR?js%1+Sd>pDOfn2zx%B z1XVw$C<&=nWnI$~+l68R(b$@rnpu@$Z~mMLYf-D(HT~z|vn8&p4p0#;g1fhXdmM;W z{sgo|5(=7$L~EGhMb>19S$@a5Y8B(at>-gXNE6=pb~WN`U+pAhaY0xIo=mxdfN4|8 z6ST)s9Ez)xlb)2hpbm;@9QA9*(1Y@@Fl)rD0@)~+WB3T0Oa(a1{a-=>xMeGz04X+D zI;Z~OYruOH&v-&mLwl7k(t>noL%bu;zJ-t28A@N$6^m2d6$3WZ^e*XYisCgZXrb-9 zP=ssuS!r8<0=2$vR_7-W*uA0Mm%snA{ihCkF#FlXUd6c|!stfC#NyZ{Z4zJ;C5Tsh ztYd@DsE;7W4a*UyK3RZHMw%sKyM41>4cbl~Qc#tla+Fe=!q6pe{-%|r1GJKB0Ih_2 zqBCNB3Q>xgMTu?2LnWUS&ivJ~G-~jij_zUHagUmC2qUe-bNGZ-q1e`XhOVRLf;az! zQ5@F&@|_tsdhHksex+sSWYV^_f$9sNi~AfFNDM7%uX^8H-dx2I`TxL8&+v~nwDGj;q{&cdOTUMYFOsW%!Al&l z$tD2il$`(YpudTosVHbTm&XQBK5mhzIK5D2h3w>Ks1w~zFhv=#o1;P`4lG^<8HMcv8Hu4~da`_t`K7{3$`Qi4CV-*3IK>mYVaG5Nizam*wS-duOZbD}AV zQaj3gLl7D_uKDf48Dx0p6yKw<8f?+^Z0&`I^h5JLCRW80p7=PQcGsAxh1Q!rEX!CE ztQN|87stew?|7&<06G^!DynoDKE?!$GSSfJS?W)D!=DV@g}x*0N+Rv`g0y`NHy|`V zgcn*z#t4=%^iB?o0vL5D)n^U>J^EIFJRn1@9A~r8-+`HY8i6z6zS(nBnNCwX&5Usm zWm(*6=~ZjhnxYO9!Ve0!QmonJ3Z91%FkPZM&u#{P+xt9df7u$|#6Qnf+g-4UW% zB{-|M@Ky$rf*0uZcS( zJMGODPBqr_r=e#Fvin8~2AExt#@4Ky);E}r{yL%NQ6*?Ou}_Fqkzf~s%uW}X*r^*QpnOfoKJ~|2gb=b3*QS5u;(+SQvuEhQc@3dcggTys`j4$YSIVRf^z8cmy(I<*L6T=R!R<)>+ z=2M=g$9Wd9&Vk)(SxXjIPbvSM2bCfXO+K*y)vf6 zlcS=5{!?-EgHYnUZf;+K+Y}Im`$VD8wx_0d9am{kg5#PiD8P763i(VODHdj}D+0ul zD!0^1;4lnrYLm`~nH@C>kqO|2c)(hH3gk*$8|4?Q7~Z+%hW>It*)daNyFRn0yQ}BE zHy$owOtIcQN0mD~ZtTXQ?~4mGn@-~%^wez*R{@r`gyFpIX|BC;G7L6 z8;@d_neT3=`tC_zMcfYv6aCGPKu&qHEb)&TBM>^xLK6g|-n>5T7did4l2y;f1`Pi2 z!pKM<4!UpZmeb5|1VT@{j&IuOLS6nC3M|X$vQ2d}`P-K=ucVcy5%ZuUFZ;rBOp#x- z@W?-d)u;7spQWg_(OLI+dg4^wkAyO`__0dYWS@H%TY>*5uRgc3NV(@{M`gL_DA-As zl5>GT6dSvUCtgP;&6$r>JJ=>3)FLT0ERiYADD@T6F)9xi@6z%wf@!3To}Yx~7gm)txbY>Oa~Fm3&Uc)5gmex-zNlE> zNuL`o>4cg99D6*+?vn21qLcd5K)upwqjQi3%xGAXWE%X2?X?mU@(zOHn1As?@}dgB z)4(qRs@lnhQ~(=&CqF0&oc^`%EM7cC0@TTCR0TyDDgkI_cgZ;VXBP(*=Q;?;4So}Z zM(Mc&P(E6YA1Xx^r>XGf1+F#^Akg>K$Kz`cm(Nn{_ZP)efpxKisS!BgEdX?pZWM6W5zL_ zGV1E8&W>b~%rWPJ&3PtKt+rA6acPhPiA29RgXP_a*Vnq9L4$AoHzfK0`RX@#(+bT5 z4j80(oJ8zjeXpi-{sr+Y7m%&ub|0K8yjL&%5kzG)p`x`Zs6@fiG=@L_=S%!*IP~2K zfI#E2BjS4P)?Nu&3efmG6n6lb*5)?f;Sg0Cv*&9%iToJtS_yVu9l(ho$Rs9`5`mCh{R`Ar;djA+sO>c^V z<{|rI2`*73d&og6n@2j(u#!z19ldX**AC{y8$_}-9q}I~{8I1s%`^B#pV71Tcq&#Yn+T^S4SvI4QPV(lmmuehkLp8iY;7=e=m|q1HX?d11@3)L8teZaU)Ih3x70^Jt3bM(Kr!6{NegB>zXN%~*1)!dJg%54ep& zKH)uKHo5zz>vJt{p%b=#2Kbi#btfM=ST2p7%tXz(*^csk-|nRbakQ-a^OZRd^y|Zc ztgAR1flNMfPPC4(o_wE>g^fcmd9L0vrsuh=7nNhuI^AswtwA)<*g5dLr4&Dk3e=iV z3h#Qk)eQP7wymf9Juh>A6)S3UXJZSVv799rkIZtRtP4%DHE^`XyXAgf*!qNS0)b3$ zkXtQU9jTS}m0hw@&1g7(G9wTLE##Gg7ZK@BHx0C?$9mv;Q)?_&5~?-r%!RjzWflso zA9dT(Y8&9Hcaf+Y8G7X~La}KL2N7=;wP*=XZ^^XzlPX-k8|%ZoX;{W?^K!mu#YWx2 zqo}mdUnbQ-1pUS%? z+Ff-hex7Xh>u4S%JUF@$ow0ljl))|H!mvk26Jpvus;b1YUs^A-`Wt@yDsU@LLDvG30F&4xzY z;;pFzpUl4MaoVVw)+wdc7z^o$G4To9tnx+GwmQTTw#eLhkF9IO4u?qmd^*f3a*@#_ z)M&z7^m+s5L!etL2;XPU;RERFyl*ybk{g5$D`wPqJ)x5|p?@r}rqq8}h?a_ujS4?u zzh<~9 zsR1dW7p0SsAb|uz9qEK7CA3hacaSc1?w+~lSKhnsTIbw#?jOJ3S|^LOSF*A<&wh5E z`u%Am5IXqgxhlL9O0{zv}#~noxUXvE0$e^}J&0NIo?N?vGCpuqo^c zT+rmVwp^pS8M{CF=(#M!UT3~e*zqDrFGi5Vn>^Z}1r8MXf(Wn*5zY+{7&e9#=9Rqi zwJtqByvgmbRoO`T;8;nP&(UOR9&EgVE04l;J z4+074()`*lGHFjXkO;{rWS2NG?Rz6g*1Od zz*hDuQ*6^Cqj#z-aP|O-USN=X|8`H}%l_*qYrOA}-o?_2;Tm$y@jw;KYSL=BF*)Vh zY8N>K-8&Sm?-Ig#iBxbv?eaP2unK>44My0 z$?6Nj_S%k@(BchVT=+-z<=YRx{l|Ru59`fp?w_}f^Tdbe*?8I7<=UlR@O^MRazPQI znyOlE7+71ke{q(wEccp~QjBn%ywa_r+|Zga&65~xCPw=42tZ43SU+ z;wa)Iw}Dlvc1Lkk2|t*rytC(>wmLz(MiI->DP=Rkf2Q;5?E0wI9$R^w>SL{K&LkVv z9=2vGcm9EKdPgcvyz^~$;Xh8;MT=ZrkaYj|i|A6jyIpBx?zoyeqxlmRoFyhOVF*>F z-qsnS1=SE{gP4fl)-u-$f^aMt9mQ&{@noa8=64O@qX&{abmURVhLp_l5u`NkcEkBL{}oDaixL*7_j^ zVSx(vVtA(1wkGp#OuIHsoqg|ionvY{`>79Fg}XG1(`-fUjAj(JuVb`^POGCBp7bGo zxx?YRW2GnIx3Q-C1x4JlPgY|Xwgq=R&fQ#^{d6ti;qFuU2?k>5YL``%;OHAsq@dRV z7!wR6QfUSVE}|EuUHEWV8SjG8 z0fw@No!bN@RqTP}pnTWj_=%yUQN^cZW4iSF(Gw~c{Q4^cuS?#{X%gkPw%x*u_L}BdzgQ&1i zL^tNJS1HvbVl4gzMA-2kAi_KU%OJu$XIuBYLF#T+dHGRmlj3@`d-do}f+ca|YnQ%S z)@c8c@=AVbA*4iYb*B5h^L6P!V{VlZkvb^llHH-Sr!<&DD_u$FvU(D%p^9Qk;XvYw2tS^`ddByG1exB^;(e z3DSEjXRJYkweVp0`<(oXm?*!+RFIpqwBIJe(i#!L$XFA{l3y$c+$%!g(VocR^jRP& z*hYn<>z5#o(Q1gMG5&q_31-w(QW=dHfWUUH<9=%254IN9H3x#<1JM z&w_47P1lGCl!=V64O76KVprv^lGx&?7YHO>-h!h~6cZz3ymEJ?U_IGbF<;GIL-FW1 zX(l#GMD%K!K|z_u6m*|ul)ZGKkTq##Q~ZH2$BD|6Ww30qfRJ>fC7atUne(b&r&QKF zXS zcBvB`jrK*r#u;0>PBrsWr?1$7RfJ32C?f%Gxg!DcxRDR8+ojj7XB9WEzlV3bSUq~z zx~-f1!2=u-NUu3bL~wMHSRe*v5UVi=Yr{TE&FcQ>-x(hxZ5?J#F0`>zIYyhz+^eZ6 zdnIB>yKr8!NjNo(|8<)4X~7B*ta`E&dKUU5{Z`HQgT8Y7!AeYszv^r6dP=JLasUvN z>k|*HjZyfK5*NRxvo}6Xwmx1=`g+c`-p zC;m24mlqf55Tz%dL|AS@Wi_0aOrj5`CA9c`iN=d10}R_oe_$zH6S}k-rGxUynVyC)UZf3zs_H|GSFT+?&k0jhdN6q19QMWSdnhJKWw4v`Ny<*41LQP=F zbQ^j+EeXpWRiM;gd)yhX?BKPv1i?6JYC+ui2YXu8L*Mx=y~?_^J2(#6?RzHC#m_7K z(XX!3@U4<=iIG}nN1I-|@{{%8n4k#|xQlI_hf;6RJ67vTa%^D2Tly&uK=E2W?pH|?x?!qGF*6+%a@p|8~(YWd>rn3kTP{2 z`(9vE$aDKZ`t@7GT~+?qtqlX*aflbsIH54-@kVhi9d=?z6RGsNpc@uVhJ2H~B6=eb z!Lr%FSSM@2^KC2HNX(*tXeNV?l&c|IP*%BkC}a zI{%ik`%Fee?PZPr^MR3QPZXw*GNv+@Exe8P+V;JHO1{V0J0ka^Nm6MXUr7i2Haf!+ zgj*JL_-5F=|7CmE=fI1)^dqx!Rpx>Zep1sf;^x8$}1d^ z(e-lT1aw1JiM2bxfvhBmS+U40d5ycD#}mJI0`bCCWdL2&a#fsalC0O8GvZ$pbdURw zp5OjsHvX^r?uzZ2`jO1QG^6hAVTkO+*$f~Y<9n#)c9uUE`jvN3k{6|QOqaOx+K}tt zD)SFB+ps?`BxG$IKLucsenaYxk9DQ`!!J*JE0~OzXaBM#7d$tVGrpHIk!c)%v>9mg zchxW5o|rxaA``Ld`xZVouLB_f^>y`Ad)(@4q|^y?x#`93M~=S~_a3zuo9c@-pEV-& zrU*k77cD47h>=On{;^btE>T~J0+hiWEfu=O)(_Dl#9yczG|G5o3K?YC>=fxeHOyE0 ztelmG(eg<*J>g`J!bMgdQcE4YshcP;D}?FQ^tG2|U;XEiAYxCI7awk>DkEsBw&EQM zY=iHP#KJnXFB|h{tZZCAbUZ0V01^m~$!C3PU;ey6JO`_6oX;NbZrL3vT$NsL=-P^y zKEoWiO^=68OjbEGBGw-7U%nJL{myP)eMh--x;+@6e7c>6?qPGMJ8Qq6o9w7(llN5p zxjT>z_HEn2&@MmuImTQjGZKF*ZR^b4_cS`W01qSy`|-$Xdf`@A?0KXKu%e{#Y0a@_ z=$==g5DXdrDbD8UUO@cdH}vf@2NU4{4n_11_NX(zw$AS{Zk)NZ5ALqk%RN)4cDnWF zh2=|Mfp#hIpH5Q7zcdk6!_*xr`oI5vxC?}OK5}XR=Irs`Ud~j}pi4pto8MOnpHwps zM;U$I;Q{WqLsb9_-9IYT_ak{O#c~E0y!LXD z+`9GeH^a|deE4AR;P?b{)(Nc72%(V2%RpoV*jI&$yg9i2`b_%}dYb<({GbeZsG4&A zCCJ2neR?yyouWbBk9!sRR?Yp($j;mm+;JbyuWcpaY-(x}T5b*O+a_+?)Zwf~) z3^gjuR`)6_SO?v4_3XXt3kf&#|AV4`ZrzcvMr&NASJs&h9Wq*gNOVyVgE7BTM5CXG z^fo%X)S8A2(p3g$4nC3%q>NX`vPBKtDU@M~ScSKiX+u&?62TR$vJO^h>0W(tHmek*5v#2v=U%EqRH z=!i_RZv6rdx)xDfOkDyDf4clRvpw=Y0UhcmMVFkDd0^xKo?@lac@1Dw5qhw7eq#&} zfO9`f*>jTpy|1VE?+*0$A>hbMJ$V8jJOB77E^dD0{^(~o^&ncvFwHF_mYye%@qX39 zDTf@pkt&|cyQo%I0&Q)*mS9RaG$Q7iU`dks#_}Ssp%xvD*a{QH! z>b84#Zsg64$?M5)+gpBV6uA4Ux6)BrlljY6435++o^f)X_h zBBio{Hb9xQvdE4a4sT7?5#r{b$hvk2^22(BXiKw+0GaAMFk97I_aDCxLenRfx*WD+ zRbK{=@I?i#us9wVuA8k}n>lPqd1~5p%v;|=R0M~xjE!k!PBL@MnhC`l;orUZh{&-- z87zIZl4KL*py|8t&~3zfk)%sP9=Ic$3{lJ)DQbzx$}u82D**`+#ysh4qyh~`aqha#SR~7n>m1ky z$H!(y@g`RMcQAg0wb9`+M7C+CB~{Ag1+Jz&@vsdW0`DEv(5a` zbuXY4<4=`ron^3^+Dou1&n}r17VQ-frHtPGc%{`islTQ&f;<+|Lc}+TJz&{Xzx&%# z;9K1elAfiDgHjnJxKeMJO0=c+74=qmbU(Poo& zze>^;Slsn(adJj0jj%I1mgk*a8Kg#e0Oz2AF-SY?+$1^Ie>gkEOBxdB=g-ukCybT%&MQ zd>|NHOx-g+X_3qhZe6l?-p)2>5!2(HjH)TGEDWx+PBpTO7KXU%=_na@VD%`X%wu3S zXc4zh)L_Enww1a^=7}wCuCPyJ=tNGrj*&n~l8yn15SDo|E%v!>7c>KP@hBd~ZA#Fg zru|jOTqkL;f~*KhWgTuzeRZ_`ZW61hc0W*Y4@nP^l*<@<1&!yFO**+NjpH&@8%7S-WDWnY&J5d_QSID|uPYCjdyOd!|g3%aw7h;{+rZIJt8L+!f&umFxKCW*S4fQanPL_`Su=qNdAy^9@eW zZGU!A6B6abhvT0OmB}l|B4;)hy{)Jk`QYKf5zT}@_F$cq)`=ezC0G=rH!ABf>%;~` zBVlOLsOH_vZV6(|&_u_)BURfxVlIQMkIuD_Hfldq24Hv)Wqk z0)`4%@ne!t>9HwG*B8oP$)a)hG{vI!^_McT3S@1Z;}W}G{_J1bYoK0!U~D2k6MfMS zb?mhExWnv=XR4)huZQ#2(9_PN6?x0MYHO_;`8x)(CeDQ7DjRnNxhw`toRzKVQjMkU zI-hZg(BOcO9IYI*zM<6dV+2992_Cr?fLoCma^XN5PpL#|QxwP3Y$fC$(u1(fXyzs| zD{-n?H~3rCv75)z$&lyPsdbCt&s9s9%Z$p#vKSf!$PD66Y~AVA2hUZ;y80g5<-7Nn z`OI)dj@E6>B~!CTl~p{-Y#82}Gtzh?qgA7%JRh@e85f(^Y5;%t%Wlz2e0l@Tn(r+0 zt`UFIgAXM?-z6$}Z^H57tW5MSulz7XQSlL4!@;QNiTvZ|htkTMl8_^ZdM0ogG>>A2 zVDl=6@de+=%UbTtUE_li?>ztW0&d7_Mt&^o9dgEI2ubEDUjMc6rt+uVoZrw+_CKig zi=R~u_!3Kp4z3Dcj&}O-D5{sB9W#74P+1b@R9vYwRLS9K>Yfl6`((FDVw9q% z=JaOQi=3CCW4fFdM9E@K@8tI`#}Fbp=26&(QH$%iTs{zv4=xLF&nGkuJ&p4=yBR2! zx@Wk=X=s5f47#2)Ra;f^;F+3!&9X15%gWQl61{#XT1O@6C*%Uxfj2z%!1#PqkL#ko<$R?}nT4cPL0GMo9PsH|O0lmN`?RF~IuFBTi`X>c7_ZGO+c| zd240OJay81i9QGruwrasCFPT!vgZ_81}u3t{+J$mQh!d43zzT z2)85gJzGaoA|A*scn>REV~P%-w`72NK=wI%4O}Sl6W{?|E1LI|4FWWA}OE zxa{7CZ8OzlUkwKT^K&Ee)&Vc`pBG-VXNN^E{&My<^hvmA;vy*|;XE<+yM<}Mxv%AU zh4Dw;>D%$Vv)RTTwbOkWWd~t)YxByGiY4FMiU4Vc{@L@QTWq0UgMhrfDX$wh zR6lsO>J`9r3CbLBZ&Y0cC~Bep5$PI_9r`4uDns~{9yHsUZ=&BuuVzj^n(d|a744pR zR&J}lI?#xni>Yu?@Lv69iI0#s5RT|`7?7O)(mp1i85A5Vq?Xz86i;_1JooH*0>@Vk z59xOZBt*Hu#Lc9m4x|Mjfm(dz#}T=7ooT#@|cbQhC)F0ssCyTev$LGW&xlb^BiIoMNv^M@a3}xVh?6 zegS^_k00&xybk*Nf7xd0$#@tO6X!aac**E1l78`n-lL5c(uxRrQSD!-kEr;7qAn+)zSef;Qmx# zjZaVKj?GAs`=y=Jt_PW2UfnrS9C!T%XfiI&yJL4X6hsLCAlF+q(Tm94X`tUxYY8=( z=cRgVFtFyZCYo5t2$XEabAiuok=;NGQG%VYK)183i~fh5NqL}7&h7&4o6 zJ|d0B!7}z>>CHB)R><#&90^tEqp=@U3gVq3w7-^#fk2!r)L6e@$yla8sD(vQ z^5x)%ae-97?8sVzrY1_kn-2%#|BUYI7dfvmiazU;kNZ)ScXgb1sSd!+?1lyu@FPu@ zna;?(tA%R3#-%Tp6767(Yo1HDS4K}hW zXmBc!*I0${t-as-ABFZRsx!>b$!$fUM+?FyilI-gU*midrrLF$RJH$kVfy2l)OlNi z(%p)q1AydOa#qB-n0+)ceK2r>7M@%F4ZsZX3We4`1qKuUV); z(Fsu2xGLpKZTi^K(%u(9z%Gh+vKMt~*kKF@FinMD&j66nh~mUv-ySmOVC9&S*1U`c zqF=Va=4FqUJ#^%7O!$fSWbmq#TWJMOskrVq4*AdBa4os}7cS%~404?od{;lY*{IGq z{=9g6xJc*1Y7y01DVa!g<4;%|akX zcF+!>wqGqj^JO*wc0(7f_7lHRbcPguS26kZh2-2gTAswd*hyze32_ZpeeeCYzJ8p2 zFN3kMZds7@hiXn6hq}L)AzV<1U0>azO+3@Qd3vL)h9O)S2^P|F{JJ5@u>$u4N7Z#w z=s`@-D|BaE9->XT^-RpdAcayKwr_x|Wq^qEOOfGlnfdJR@x9#O7 zYmgs1O7ng^7qjQm~xZG-jk(QP|N#7A(l&*)3 zSnNr1XJ2y7oso?}fZ0AHtrFPn6A~k%L?~$>m1s=qcyn6JI-m1B8)qQ8nl87OaQtY~ zz4pBwfU9Iz?d=$0JScU2f7ayjV`TT0TYdKoA5(NlInx`5j1-chkO4DG>%r3lIaX|& zmq0=OLW1^POJQ;8amp7kEeCMM8`P5F8*1ke%ejGZqjg{maV@~Pt7)UJ2WkmkAcN17 z4$rN%p6y|_7aj!BImX!W09tZ}X#--8l$6hSXS5PV$hj2=EYXTilYecztMK{>fgN#+ zq15&H5UjXp_ip}n>ezZ`ePXk0fXfdSCvmiied*ez8!|v}18%;+tS7KuVOll0DNhdU zH?Ls{%%IULgFlpYhZ>;)}GO38|W}>$CBtYvtZ;)ZvQY;k-nC0VSdmd)#;BG>FTso>pSIn z;dguW44fWT*WB2ISQ@N2_`#ekrP32N=kwmYvL$U=m^O16kT%JXUG28|_!%e~#%~$3 z@rwn+xvDD3fRjC@DX%bo%dl`yyS&#zX>3u`p;onR(pUdjmGf;(rsnMH&adoA@4xqv z+ZqyEsS&Z&Z*1ZG3Eewf$6L(V0%aRC9L38n`rQFLQ%`b5~ozeSURrgv5GF zpdwrWNuXAz{6g6n1>S5kq2^Ccv$Fy@dQI&Q-=)-8$T{D37=45Zf>_CEvFvvtUlM)N#(HZUT(@O7-(TS1z@6^@d@}9s2 z%S!yaKow9#^|+3`OmVR}-fky4IsKp9i~qnKv33wdFJ#u1yt*N5x6zYAm|4#bc&okT zI0X;b)VM(#^EXP9elkcO>z`eI^fDc1lYWKa6wiwG6|)clt*$UCiO*-VUs_iJ6)%OS zXXr;n;7YKXnznF6h}t7sT*4J08+)D~bMby=ikjZ(_;<9;UWGFK>~LN!hQ~(zN7(o>qjnTtys(YEynLEv40rEDIj&IepWc5W-pV?!tP#{28$ zqcabdIyx)|am2EE3~ADG`49@5Mkk%u{>7smh*ta$kM>*t-#yxSdo%}Nf?!LryILqI zJ##FH4sh`#2vI`0{sWY0#KG{IJ82Dt{)>1gxsTV_$~g~Giw!@Nk^N~P1rjgex5O)dc`kDl~zA5DrOw5Kjm0} zlXL^0!mAc#Y$~3)SVg%YN-2PfPCf0=tR-rt1PhhaZi^%fT&W!`?aFhvI#{oWfep}u zqnu>2%U8ITBZg`F&BAT-P$drxHb|rzH4+3|k$=~7q(n-++WD8cpXUC&AndnU(#GDQ zTU=OAF;a?oDrDJ|A}o$~Ws|j6iPg|6o$bQ&;dTAuSbVZrynTD`P}Y2D*7XBZ^r&=F z0DG)IjT8&F!H+nIGIb+yyEDa9DI z?^_cxgLqMGCWg(2h9Hu|mUp3W)a!$04u1L1xD4H%Qny~_pPvnY`*Um99m4%>PWe>0 zuk&MJani7u*twvTr_S&F##k2n z5Y7MW;q)GQW@M#V<*Z4wUv7F&`8LJz3`|=2KN_|FN2B)tO{4Y#M-`3uNW)9&s!@Wz zTtuJr=GYW(yf_wxz=}6(Jg(ra3OK3;>+!8z7zNC za#R>{ZrM~9Xhtbs5iMv& zKG15LhYjdtO~4iA6m{evxRNAq`#57aG`=|`NBSp)TgStqkIAvG%JNh2K6YS`+2^Df zPXnmily=+5=q$*EK)lyc4pwo;7hW$2d_6ln&Z*}ySs+4Wk*i#LcI;a`IG&LFC|N&* zY%7z1Q*9SWBF5Lj5I1^bk;wN{@PlH^hHaQfRX_5Y$U?04hL~RoE;Y?!L7{wO0@rGj zm%6SLs|D-T>fT+wIYT&%Rn2}(IE!! z++vgtn6kAko(j^3tC0)jgDUL%1pQWVwA77*c{*O{ZY9LPwP8Nltp+6Cv+L|?qll#R zMqj&F-J4)!yb0mM%^TlUS za|Vvn%s{9mlG;&{tlQc)Znk+nqaf*u7o25p1Wd1u&7iuK<&5hg}3S%-BH`oF>W`4neQiCkccHa)E{@-eTE>oQ*n|c zQ(qG)J6(KJ3%1;*04g3Dk6*(!PvP)4tP{P_#*Q0TBG?tf4?kO;tv{3q;vz$}u(*Lr zD^sJ;Wov>!UXY}xgv@G01;!yg*)quK3aH?Gwx5Gv_d9?7nj71-alav%G?3h_{1WH8 zNA%RO{QOAyg;*?!%9sBsIwrf&U(P0BNViSlBV%LF>UET!V|?w)NgS@IkhLST+rbwA zq1ebg>dIcwnp!Y4++wXByxDHZcK|9Luv6^_y8P zaSoB?^0{#{C-35OF=^%Bx31TTLOs$#^+v~v_x7t|-gmmjFB7$?uPr@FQIO~4{g*Ke zlwX>`b-tolJ=O{na9^2!q$FMCWo&G^I3=6aW)m_kkUH6>?&q0=0&_%FLsee(8r%O0 zP(J@3XyFSNW@WfgTwS@De;@)*g-k9TPebPAHCWn^5|a&4gLH3hfw##h#xlWW8N#`; zObB5;l`AnwAIT+epvLPqy!hjT_sq>7gZQgJd`C-|aOLeJj|MkywqMY{4DzC*y)r&1 z?mic~kq~2lYnaz{p?m|*u5&-yhrQh4tq()?<>bX@Zex!Uw8ZXE7%t63@!3t*{ycCo zjaHZkeu&ZT24D(C9TAc5G$$gvU(6fo@xj@H61myE3UB`^nF6y7G+(}zlc`I8RV2F4 zQ$1Rp9X%3nEyh-;hLuTh$trKRlle`FtE0=^@-Nn z>@z~=zSr;I!zOLZTe#M<3TWr5xPVik&RJg6rOt$?0BdHBGEH+Nf8zB%%+X|+IDg(@ zY|(r&q2vb6V3k{wI;O#JH@$MJ_12?5>d7_&sDFZ;=)%=d}0rqPu;!oal6tXt;{0d@GQom98QSo4q${^o#Wf)!f=LshL*zM&A$T7g?aW z-dNc0Jb1$CxYP)8qN468g#*~1nleOAXV+yI1e$DzNn;B)PStK`d zTe0G|p8Ex~Jn1mcT~h~A1U_WXbpOtWH!aUqj0}b-QIjFjrfW$Bk_42mn5UCU$VCG( z>rF1VZSdgJ)(vt*QA_NjMNH(9bjikpO2?+pf8F(etJi-uFr4y%brk$)SXLz*Azj=x zM-_kf!Q**a$2Bclh))K@czwmUgY5#ko<1oqDs7YT{-;ZVo}4k6 z5Tw9-gEV1ZOJn?~q?|lRhxVJa6`+2YAQ(a8P?49PVmCgDtZm+O5Y&QQ%1s|JkWD=9 z|2kwz9QZZ5mteJ0wF?rO3#WUq=^xGe-p$L-PJ>D}o4F!vx{brlbzs_^s;#>Gi#AJ{ zL)p(gbWT(Dha^J|&5yUYf`?UZADRq>;%)o3u87B?rXEl4H{Q>!PXWk?P6sA%gUW*j z#<=Ucir|UDPg%=uc;)m)<4^&WZ}S!$_-SzfD%WVMkZ2>}!Vah&eOgo#plaCjvjwr@Hx{t?%MdvG*_s8?k_W??PJ05vlj>Mjt6o<>W&-r zh3C_xC(XQpoF(#w9|v zGp87^Eegq-{Qi7?q%Nd!?X|jQtz9Wk&w6%Sne%#9Rpm6}KvxmIrQs_yG{oV3^Z=;8 z#OHyjBj?bweNUUh8J~~ybvX?N$y4nib?)5lRjAm}*^JhWj(#qVKQD+AAZ(A%Yd2@b z7C+9aY%XL3L*xW?INNrPVOc~-`RDSocjI$xC`2vlrvag#EAt>bumw?BzzNZ2QMF7hEvbVT; zR=CjOTRAORzLYf?W#<5E`Add;>LQ@LOFEBf^H4e>|F6s& zOr7)!*erG0_?CxaR+DshgEPmh`~4+PC^P%K&3dxBG#lQ_^6tRsPG4G$Hyfza$)yf? zAV1HOKU1UsvEZ(e@*rDqWWu%?TSZ$nBI{-9zE7L&s%1TQ zt9!pF3z|bh>h!w%}!?n!CkXztb=-3v7`RnBu9gpiQfR(u(6Lg_m`KGTFzh z${q)(H`Npw6%yMba8d0X|rEv=-&Nv0dFRMnkM{eiy-`)QF%%*SX#yyHr zrK6#tBadrmhPi72W~|(yr-41usYBS^De4Mex{EMEg4BhkBo(OeA;mcOjeve*kDFOAR1#a_Pc65cCrXq%&Y3j#!FulqJIUN7yWeU zosHBubJRRTDkAg6Xd2&^C||>q%w=w~;Pn096v7-LCQ&Ft5Ub3%h;gZo2h_IS$A%u^m^V;;VO+ zPIn)D;~2C-re2qZS(km!LdOUYpaz_Oc?O)@wlnxv*zpI53O8GM5u$19H!TE=J}9ulY7&y->Yc%1WPug&SPjm5fuXM_rev< z)na-7wd=Ih8a!Dh%+vF@M+(UD-w?b=%0uT$axeF14jFPF40%xLo~&VzKTan!oIrBr zEwx;Hhib3|^u4j{O)W36ZNxBvc-?t!Jdj#mj0+)1ldPss(y zgx6&qA}cQ5oh2?SJE^vOS7ycybGJrO-rdtremN1;+zlRoRoE`0$3JgDlx~#tKU&|t zSJz`L^rsopLw%gk&z<=W ze(A;2FS|IFOjil&*Zq`AZnQs)uqHn3O4MG<-A)~ClcRDX z#mv`h)?D|jt-dyLtFo-Le!1Zx+tSL(@3y|B=^)4EFF(I5p$w(fns%)4#`@Ry*?0pp z8N@56xws+a^fVH%iQ^7Jb_FhajF}wl^$)N%ZdikFhsySX`j+S z4ta#jjygsGS_35imgWg{VvBrIey{>pCwJ+)=RucI|(-sHq7g+H^!hEso>w5zY z1r2eZ`v(RANVdz$F4cmaKU(x_?M=6!f9fq|EDjn-o#^rWd0_w|Yk9x&KUL)a=ePfz zbRB@IkA$4HskwJNkABuUW+5f)5VrDUv0Q}Tao$%0YDMC4XY5c*Br*Vk+I z%^fP(u8Yjp3%@0@`l?^r#|z?KLy^VtydLEiy89nX%*RlLVN8&hct5N70>_(x@~*Y2 zcgt{F8Va^ZqVttXGQzsjM5l1&jXmy|juNWvnzi^4W^=obs1| z`l(RK`C0m;V>GrI5>1J2MBv|wqhbpfZ|`Zgjfn>~=+gnO;DakFR232I7^mklwzYSrer)Z%2~`oX>+wPi`<7)G_9BUN>5f zAD-4PX$i5)&}IM&@C>#fg}CXE#--Dsj3T=;Ab;Z7i4W?mX;b1#-Y_Uc=Jj%{PMy8v zt(Z+#6p=J?*vr*j+%&Fk*2`V%heqKG0-e1&+uEvk!R7jqONijz)09O=)Skt{M7rQ4?t5o;9=E|DIY9QLJ>|254UZ5MWxvT9=Z{0%L$O)wtV1iYa zYxm0ng`h$3^f%)pZcQ@?r+stUoXcyS+%>ux1`mu-7LS#+_L%xLqgOuAH{ymG-RGC9 z;lBfP>1wC?lrfzt@{z4JR+2;seD>jkD~+31OU!!3pUxODKDIQUuwES*S>u4$Rpf4% z#O6JlAX;Sy(78LmGqlQAV|74!Mn>ZMWi~UccNa$|Ci8tzNn{)AiiG(zYKFn_cd;7&frrt-2K^evsJ zz8z=dxyZ5jqf5UFaXX$YIx!BpD5fB|ye|dDtDB}UZr>aqb0}$*HKj~iGl5ScFYAsk zf3LbSA%=9jgGw+ct&18o;j5Xp&ri_&SU?lA79VRG9&uH&I;Jv`#)Dku3f^nITk^N= zfejndHYM*89SY%Dtreeo7v}`p7J}ks>p5bO-$oPDQ$PGQ0xDdXS>*bcq41ikZ}GAG zi2;`DZTFFXli^#tPf6(O1DOnE1BDM}w~Te<(L9MdN3jjGI}Qgob;b%dG8#KykZ^O$ zmI-1~@kL20`IFn8>2fCqMwVuR=$~?RdcuuN__klgGhY`l(X?1J|Aue*P?M6tDtLcfjr39enLlYoVEGlzL z`qAl8Lq__hDPvludRErHDw^xHgJ`+3`GUh0`EzE2?=7|l>KH&-(z!uuyT3M8B`D%d z?nh^P)^5zF_Z#)ztmO>E4~EO~jjSuJJKSC6GRt`JtTutg`*tUqH%`sEh;a!%>1@?h z5?POS>yAnO^A)FDvZG!Tkz0)2HS*S1t3H! zr}#}{*>vVm19~Dqpf@%@SN_}Ix7^F&e14?9t$t3p6-sQ}w>zu-OVSE0-DCad1;p9C zm~Y;@$iGkgpBxlp-dy4Z{hrY#BeFQ~<6MVH@F$f!JG9~fQy%;D{vFR=z@QF?$tHQ! zBGwCBtP?C&O)K|~HPYjd<;$_~ae_CjdlBykVe2-Z#7@*_cWx6cs9Ym}ub&dD0uH1i z((q>Y;E*S9f_^L--1Y~>PfxI^Q(P+8#l?lqeVd&tGv0ZD zfc0L9QpI5Vt0)8O{jzJBpC-Bh2}K2+G~O(RnnrKS%m2v(|F7`%KS4DY&n=Wcy#BDS zvn9-DVjmoz^KoitYofRO4ErU%Ri%qpUD5WO{uuyf(+d(!y39sj{BPX17=46yCu8vN z#J^HK;L(F)lc}GMS+;b}`drk<>iD?T-}WsB=4>F<={AuPs-OR@*>b%0|LNiXUFtu6 zm+h5Y=1#)(l6veh)gL^q%WN$ku(1!3Xp_D)i2of$MnsVbYr#H&PF;-^^*{X?U9WD0 zUA77e%VzSay~mni0pl->yUHzy8uQJAGcjeF`;6$WJ@`E;q9n>slkmOAqLwI=RE00# z;D13#W6$gk%rCeS&fdFw#(Q!B{N zJ9>^R1)}=IaUDKe@St4T9(1@q0dvMuvnEkcG6~Qjivym|u$jx~x^oa$1RqiLM3(1c zM|Ak*N%36<=-AkMqZywQDG(Yz7SdVi04js(x8aduPR~cO$q=_aZt&J_& zu|C89(X=jo<5F$@?SG@0{a3p*Y!ev36D1_hYCF{Z2i5wf?j4Jb*m)0cjT0-=N^ea1pB(n1FfB@hUhKmq{+BS;HP2niiTYN$%@ z-psjo&YAcA-p{@7Idks&nR$PcKiE5)y|UNythHBp%J++zWo29tLt}+6D1BA-=oyU>3TD6x`x!zqZG=Dt*|wcw-25jo0)IetrG<>N51gHU(mN=YXgh{yPNznqtL@ zXcwcXhgAnX*nWEdM#13+^;d=)VWV5ghgpp`X*()M5hX{A{6kP%60PGGDvVz~Ut#7v zZ~xEJzxjLI^ZfNkKmX08KlhjW+m@^a9SU_cHhrUxnLD?7?vQh_g1qRzEW&g2<57m^ zK17C5;+(wp!}PC$p2^&hIY?Rc=)0n@PkOa~bM0Pe>|M3}jM`9o?5Bu;(z)veM*{^% z(;s~jdc6BS{9CbGp|dP5yM_Z+TVN|+I@=tw;6qsmI#X<5({^Q#r>N-~alE ze?Oj^EDBpqW?@*fV6@-Q?Jct2Emo3p!_I9-8ZW(J%ceKI`;@x;%YVQB&ws)WdM~nu z?|-@xfmIJsycBeHI`;77c3SAHZ^Bafxp=X0i{0JE?JZoy{y0uDGZd2B^gCq!%DTLU zg=03J*DykPwg2|jg}%^FH{N3c)mMUaj=Cl zeAz)H;I=>m-R?Dc6q-8UqBxdo&m6XPA5hN@@6JwX{_(fZ`jemklV&?Rt5;_VvQJd- zj6eq>%;!KX_Gou98r9cojT2*S%S+&TV>bIb`C%V$A=h&%v5ITat^i||FHV$h40Lr%ps1`FH1L@(9LW0HkKZ>bb0=8t=j3LkkYzM}Ju zArPq1{Jh&>zEW|-)Go{WR@=bg<59BNTe3xo)d_)uz(0(b?>)*QiJH$P+>Dzixv~hSewtQin?R04J_K!!;m09>{-mL60kJAxGAJ+G- zWA-5ln_zxDBgub5nP5Hc)LGR8;Ix!##!NK??ThQm5nAZ=+aBm;;)pD7QTxPv;bq;0 zK$$|RLTS>zTm5KU?VPDwR@_f4VlsZcvuk+jcm%)rqxRInKo3^%I1xrC^Tx*^#~oUX z1JVvwHEa%I<@cfXQYrPZ^TV1l1|fQVR`OKyo_#B{VTIv{^hQ|j$Q8(Np!#J0xY#C$ z;0SPvN(76W^2gz9bvQB(AP06 z7$+9MQVPlj6ZUB{>==l8^K;m?)he+6T=fwgvv|5;Z~n-{GL#jt&_q8tHgj>OVZVGk zf8iv{ZU8Xdd}ed#6DB6vz{)L{TsS(0j10Cp90=;&JkBzbWtQwU${f|I|NCz%YN*K^ zEmG$9eqz~1y37tAaeX;vb%UxWLu=RxZ1|BEeS>wucYNcwbxW8LN@GqOsM`E|-uMEm zvbC#$YA+oc)O^MA;v|HjBs_QML}iqk zcH8Ze(}bi;;yC>Y+#KLYXF(cg-84RWuTB-}xGc}?? zgi{-099WP;)f2wk13)rt!QI=d5-R{riM}!y6IB|Eb_&W~;wLXsI=aI1AupyA`=r50 z5jkNHhdL!N%&RN?Usn~nu#ku{!Jo`izZ_F|$v+i%oNaozL?K3e z`?}?oXo(OH6UA1Xs|}6^E=ooPANx9q^o;g-F zHo{ChMxN@#>&-i@!^x4WMXqS{?F^#BYMXtZ3wjskd)tA1n&gO_CF0z$8(=MAy7NX6Z#-VRhIFb6ADIGJvvhClL~?cT(Pbq4ZLbIT1oZ z)n=B8F@HeHyu?0Yv?Jk5q;ssjC8ntk$-lAVxZ66l;*lBFIkDR!ar7qS$ZRk)_sg+H zMp%TJe}~^5bfBdEa!A*@(Qek4V|Saw1|rsqnl`qNu2de}T}3T#R9Bb=i|%L5=B+Cn zc}0IYR&im*AcDDiAmy~P_*x z?h|@}n+lBy1<$r^SZvxgeY6+!<=9!vBi=uV28_lsM{d_Hx>#hH z7P=Z4Y`1AKM#8pzm&R?v@>zfkBqD3*xxt4m)6USPBe%GR;bj#?KNaUjzuJ^c6OrzC z*?IsERv_|M0H1s0+VeVrin@Gk?9ZZCHptd`MpoyR@ID|6r& zeQCu6-`WmhY58lP-um1Tj!D;E$U+H-N1D3hE*6O$WYMeu6}yN0AcGST!nWZ*4~`DO z$A>uU`mQ*1_ShjtQkRV`MfP`iVrOT#|9b@dQPadK!7j zr@s4D9fIG2(@x3rS};9=+Wj?V@d!IXzSEvbnn{vPBWu7U3ue4a!aX zwbZ}*@z1c(|5tB=WB(*4>%Y7nkA1~y^>vs8pSHSoVE%S;qR8ud?Vk4@0sbpa7Dv<% zZ69-H67sTT!r+5pl!d-_%uLDB|MFV>msG>Ku$ZuGz}!Eq8@};|`{JR<>Q{$n{PU0I zs`8e`+0W;_o!d|~+F~K8lxv`JEdc+eXZ#5Z{j*l;e?ry#C#(FY@csTLW%~2oev!fm zTXQIEs17)_vgbtJZ&KF`TwDnp+t*=%jlWbcf~hfLHn9-FgLK7Th5NdQa`wwHA?1;c z=W$2N#i4D%FKqJ9U#OpT&m-EY+#HARww9<9nd;=bIRfjW8~z{vz0>Gu^ z>N5(M)vZ}vfY2j1OFUFZw9fp z#M2#mVeV@e#x{Dqx5GoDHwQ*H>$Z~Pz8w2LOur@s$F*oyrL%hr`Kv@H3<9~1bp5ND zXL$}s9v;5f{jNca_eMzPm^!@W@q;(?^#qeJ*S;{MmlAM}%=G-V*uVJkGAHh_Ad|}>{a${SyfR$AEDbnZYg8Hk4Fd{4U41^S{T6_B&jP~F0)IUMd zf0BFpPoRn4S;aqxTlsei`NuE*Px8+G@fGoVYxrjfBKo~D{^84ib#}~&#r_L{?)$$8 zT`daAdvkjOTwXtio2bh6*gL-G(6sE_04YQpwLg9Ft1#lO?;F-kDGk~d6Dz|JOA+lS z_HKRHUvXsao8NBao2|$WOy0Ln-cOF|Q&;WL`|;Oe|Ki8LEYE+02L8+P{NL0H{~DHO zJ{!62Pa)o?r-TPBQDRS~+z!=fFB~l|Yss7*>2+8Pgy|W)v3<*Je5c=pk{=TSm8{=8 zk|N>+O-(=y>I-9<8K`^pEZZG9BZ+FXd%Q4Zkz%YMqJ-v@O-LM(#rGiB0dZi(kZ&|? z+gih9iAv4*Q1@VTGbdm2Qul-FaWg$YB}8yzmWd5&dqK_-f& z3w+1x=Za*a8j^XRtYv5PS6l6#Sjx$&JrS}23r*V`RJ-gyy3zbuVa@J^wP}1|?P{Bh z{nFTbzQ6wamp1 zO5?<;+HtBO=M+OXaEp-^%D;(2;3Pag0K_wOv5Hr?sqkpakUhK+*d_ zH@KH5@pfd6$Q?a7&42_n*|BM4G0#n^MEpfJ-9@Bi4prBybH zqCn}=pn8lyAN-K%@XlCA#IT8XDPSS8I5%O%R0mT__33NL5$%4E^6>l>9c$|12T!T$ zQ~+)wVaGHi=ELoCD5E`A9lrN0H*w7PT`D4RdeQZ=Nfluv7jCtBeLNNCqH7HF*bH(kfiiKb z3gSdmUv5?@6j2y*x$Y^O52FXv2y4vj z1iL~~*U&;e5YAg~Iaji@vkqfiR~Ls?VbDEbjtnopq)?s)u3ihQc^U&1%F1nsblv8Y zDaL7+*I2sW>8)1G=qIS<$o70WrX6+TR5^QL0X9NH@)DjShuUnu=hG2l>U{3o|4Mqw zAIH-3RoVW7j9}xw9^Mwj`3G=)EtkBCWsAin1}DR0q7t_?F=G34z+s@h`{1sf=7KakC7Eg)$BI-Rr_)-ZV88EbH*R5`;@H z=@s9}zA)bJXRcU*SLHgd?@;nwUwXq7=6@#e3}6Vl5Ar^Q`i?QlUXvN$&rac(v*TIW zk-=l@6hN@{LGDDTdFsxU9ly1h-JbmVTk+VvvNFG_G_I`j)j!;;n=6WZt0zn~Pu?Vs8;PSciyW^Slf}utp4HCegJR&?q8?yJ5r%o?ayj02C z65kx1oKU8L-zBs!Z_hY?lKQkf!?m6V41UB1+BlVb)NEastvnY9-$~q6tv|qBKT*&3 z27Tl`zZxrmt^aW?Y_N2|J0f`1z~+*=NcBW&{?FA-)hRaJA$*^o`GVhHH`?b6T=87Z zVU~UbPH*k6RXzSo34bZ!ub%Lye;xc|f!GNn{h>aoo8$*i9cs7!~QH}6-t>QI>j z@6pw3Eko6$T%xMNT`P&O6B7}iWj4LQYU>qj^2K99=0DcyG8{ls$s;myGHP2*&K2dU zi;NwM!5Pq4os^Ktr$jV-G%n_0FCL^IW#(&Uu;g7&$UUi$=SNHQEFt^PJ@(?AIy1;F zX7nK-R3_`548-rYMf^REBn{jmbP+nF^FTSU%Lp>uw-6WurXgG)p~sU(m${%)dc`YS z9nY~i@^As!*zA3O_1WjcPq253+_{j;fLleAdX_p?XN-VgBhZ<313eYfcjVc3c*V~Z zFDd1ARp}pp%@RNMRg_=oUY`;O>%O%$%Gm1_N@ndZvSuG2$ul<_`U0!s?Zgi&hd8B| zQZ_Hyjx|QJsD61ffBvR@1eb>Qo6M@Vxvc483Z6;O?swLwj9(rSx0awSOwQ-*DMxt zt50`wJU1~V)b2>~z-QQ8{ilvDk55?$Rsxcb;#Zj_)*B6Mc?pO7q16uyR_}b8gmTzN z++)a=8x$a{CXArd8e@~MD(Yyu^u=VHH~Z**?SP$G*0aNJkEd4jUsP--cd+qMUn#5f zVDeL0s5ag4W-VOGz2GOm8Qar-Ge1H8nqK~zWB*!c{I%NpyGzcgH@2$gdx4JKi7sqZ z-fKyvV+%u}P@eP;Y>2wgVN#!OmZU=x+8s{9u-y^P2SFV>_XIHidUT& zHm?*famyVFNDSB}@o0wlR9IIxwzP_uFAuqhr#*|~FrRjVgvUjfkm31Qw1-{JX38ho zH~XaQnCAu^4a!ZCb63rOj?xV~-tjqj_}f4lKJy*&bas-E2V?>=PSw3O!hi=d7-^>c zkoqiFUD_vJ)SPqe5ZnsrPl8E-5Z!bkYIIR}VGT^WpVPScwr5?MOUZMEGZ3ooyh)%^ zZD27t6K?r2SExr`D5@te>4C2$D~93N$3|*l8@3V%CtzGwAl@I~;``#{LpTIjo(c>NwHm{?bJw&>gdl_wB|i zJ#JnP&hiNoR6D})v9=P~GuHMRAT?rnP$CXa?uG$ynjqLZKfeP=JEI}>;Pu??R?jhY z{QQ{aE2+m-usj6?L+LuK5vY`yr6cvymlrE$lLkuay5i!tWj`beunO|Ao2@x`>bOFm z*THNYv53Uz>uNK8<^{2RTkXAX%puY5>PGFTrpp3}qoCU;GdN($rxQt(3(m}pV|UFa zbUiaGcs`=6I3A@^l9N5xi1$lIqRCwTVQ-c6KI0V`Bc~GA6u0HJwkJWezHQk>V9`he z2XnGN+jqo9qf3qG&wCR?gMDA?s)bzLnim|Z%oG~74A!l`xa!JLyi`^|lV5Q(v3wc- zEhqb}coY#rG%<)REwq~iV@tC~(Y6tz3-X{Bfk8X&J!%(Us3@4g zbC7glrEN>sQTC)Oh46EqMrC+gAo;Fgrg)<8r^GT7-TolKeI-i=(L5)Q5{RGQ-krUy zxJDv%kGepuE=Mk8X3Qby6gvuo=-#Q_;81YEvt5Tog3PvwQ!+*2aic-83KC#eKW0a&ZRAVo4LlS0CBAJ5uIpVC}UxP7FgHkd6x zBCdcn@GigW&^H+DJ6;$KNw&;BIj1+-_b}QRy8I$4A>nE5J&AHWkU8dSCckHWu_B7Y zMMf&WpET`fr4v{bU${@_wBoa-ni0$zB?N%US=Q;JKmXY#?U`Ck=puJ<1C zalHb8RGN6gQX?eq3h_7HnA=imMb3+yA8BpzeyVRLJv0&vsU_NXseQj-5njRB!uKX5 z=*|)TBMBPcS1~nZhijir4bd_UOWq4JmtA-HHV;upEDz3v%qhbvvBES|k7r_+&M+fC zEvm#?St@Aaokr|%MY5?mf9>;*%k$BtK#58sE4W@X)ib`)3FmJ`27!vBGTd9_VqN81 zUlEp+LT`vQ6GXTA-YZ^F7wogX;wU@p11jBVzq@H}znRHoq!raU^cyaOWv)U}U-gJQ z3A8N4l!WUBOa|qnuBFe<#4W=V6YP3<2l&^~Xt7vt7>mt-?wVQS4U3LWXYrpmqO*IQ zcYYZwPoA3g5Uy&tOzarTtMfjYPEs3#S~TMc9R)}j2?2*{rLWwKC*k@mzZoelHF}_> z0}?hUu1d)YXE(U6=8;AiEDwA_Ou16)WF%KKngAMnk}3F!*5A28xSI7bo9vC}MFhvY z@&%p=fZJEv_i>>JZX-|)AbGNKO;#*zwcdV3q&xE}IEY zcq6ihYIv2nL@O@t8r>;>6w?NjCj$Xb=s}NMho-rA4;iq@vTuUXOuL14<$L2sFT}3* z5afm7Rtm+T#-)eKZ9Z(COfJI{xaXb1 zm+eb!_BaPozZePE^njYt4=<(@j|e*CG-KYe=Q z^}&icIiS~=)3aur19bDp|6`N?oqzseLUNDmDc4haA*ky z7W$~Z>Res5oPfO^5o5QCFnx%JwT_h=g511}O)9zyG0_1oW2UFB6)#9ZHSLmkf-kR+ zRS=!ugtvYlC1f^|3YB{BdbYO@%}-vZW~C>o$!jO-RN^8(bEWaV-soEQ57l+${rdiX zszh#wz0$RlEL>@{`6`iG4Yqks93(BTp;# zM84Tm%6n-2NJHnY#y~&Q#!?W6RHRvK41e~KFOoG5kTQ#;(xW=~tW@Hit{!~t5@%4t z6;B^1k=igC?^3`NKpsPyHC-)jycaQ8@8nrL!0KyN`B#a>#r-3EMsLsaxm-bHF2*au zYtq=n9N4o_%|o--JU%iy8VWkSxs7JTX#Emi*Y-q|8Yv!dQcAoz%3?XV2^dJz%LknE5;v1Td0Urps z2@U~)`AmwVBWo$%bhYUAb%n$l zx_Jv2b0GQMm-sjA_hK~P|D7KF_b>4sm!)%8+sa$!{>-R3>C@GU8Rnk7>#m$EZ$tAa zu^#%iX0E-IS^3#@amc@D;_Z>g&yKjvn1@5xhuj86=x8k&>NE+q=zM)_chSBum(zWt zduERMLL5h0m@SoX7Io!bLXfbiGtaEu{S0^`>!SmUB4%?WYG#6IZ&ni$){kx?Gb=m%WV8XlZ_E@-W3J%f99+eoR`RQ|f$g|!%C7cMzIyW`R* zCvn+K(!lYo_N}x>B>|+C0m<{;^paK@hGVU5%C<)$H!ju9Rk-!`-P5rZ>^YI`pJRV| z8lbK6dJC50kSvFM;q)m0wI10@c?? zJH54h06mvNH>0&oyME057Se8;7>$h{AaY&ZPyzrnI3G5f8mIs+uj2{#jL(h;nzT%J z*zm?8iI9?Kns99Bk>@krUwYH=6KfnvN5icNTS1Si9pq~ z8}B~w1oqvgNxMSK<1z}(GDzq?IrpnA0KZMP22E##LF0)9iSucsb{mV?GUBDuByJvG z3GWtjn5*Es%Rcy>>2jbBKk2kUCR+Pr=%w9IB6Ikf#0pUg^PJO?hh2WIBsEy_^83n) zOz>k=5qD?1z*JmCkPqiczV8DXi~>}1Qka{q-zs0JRXTq&UnkVk>3zIRVU(1j=<4Ar z?RwuhRT-XbfS}sKMDrDjyKh-?RV{gB{giu#^HFqCUU-Q2*F=%hk|bUC^OAHoeR5UG z=L#O|T{17eZ6SMP!6FVNVxm8wQ46^ZSy-X0t7{C}Q-S9U+-gy^CqNpO1^$-sVK_pT z1@l(WGGneP4A1Xe#0J`bsx+%JL5=|~RNV%<2Ej;g$0aJN*O&p~R)`H0vfkBF)K4xn zi-ptbd+&jU6_XHco`V~h2+c3v37RxD)*9BN1I*8wUQIL|s!G0Ags6J&p;=^yfN7fb zGpiaTO0gyS(kjwaVaJiTN692bniN*zIW!Fp>8Qo^6}jBb1$2O0G};yTmmgfVXf^E1 zsy-1jb+^uJ$j)NvicfJgbl+WZ4Zi1g0NLBJVpe|&%ldS!)Dhh;47S0G^OEF)uDkyVouMY zl-uNhwSqIHh*~n1I(&w^rH%)IEqwBdD=Q}%$S;G=EqS$z(OprrxwEP~HFdypqeG3g z4zpk*35xbbA~$>)7KJ5%w6`8elF-d_7}t=Bk5hy9VTZr$zDiiTFQvl@3LCC36&2^i zmi3IHl7wi7Gf)db&)U-fRzgx^0uEI1f+2X5@f|u$FOl~JR=B+g^vTQC(#q04#67*H z)N{CwQ$MBCkKJ>qcng*KSsLsvFDF$sT4Cthnm40IwZ5pH@Y9^naj6D0Ov$ZLArlhB z?bkgDr}vl2yR7DbF4Ko=Mlc>8&N)b4>kh94(E925eWc>^8^%T6C99`KB_9Bsz5x-K zIX1i=nW1L^03W0j692|6CV!JnBauY9JE_B!2qwFFouhSEnRP|PK0QG9Lo_=hEPn1N z%%H|P;)p-bu7wm1!mSZ_V#o39O}N(v^W6dA?qDT#F5dyl-Hz|<{#rodos+Fxu-$h* zjGJ8e?xzYeq9-(^Oe71-K4OPp^BS^m{y#H){R^basp%++4mvZxjq>jj;J39@PD)M+ofM9>n@WF~ zkEzJ5wO%xK>&>!HMb1zMhLc1wfzeh76r-wKUJXnT9b^h7F5A1=O5|=+jB$3546tIi znHHKKi$x2sFYsg0{1T}kc6JUI5Xdt!Y6xU)zw{y_b}B#wES2on-g7x6oLOClY!zKF z@Jvd0l#8U@Znm#*T(@2NM#4-`ivD{2+}O={yK*u$dDF6iW&cmz5IIto!_ohP5AxFu`c0BXzm zrM4;AZYCGd-InuH+$mhArIRAdQn!T*(=2`aar%j$Rg<)~TLs-+hXi=bg09m$V66b- zE^iRKaa(b5jTtP@7{tlRV$4KF$2`|$YA(rS-q+HLn^xr~fyYFSZ&PSJ<6NSt=h+Vb7=7w)=IKa`#NF)j% zho|^su12N0=5(ibb2w)`ZWrB+9NdkJ=o0+sz+xefP5NO{MBiRu;=8OOqYS0{i@nIM z5eE~iQ>SeL_4o^;MSL0NsTDGb2~n%jT1tunK^X$qqX+OyAlLNSa?WzsM3&&u(a|w) z-ieEgqtQf`{9HMlTxVitUu|Ay(K8-DzUG=(I~NVHxiwa&x=?JlQ>iCuccqakrGT<0 zaDhn5k#;yS-O&Y)?~=&EQZDoPjym+tf}}3~bhXD5GIj*U!r2@^`A?CRhBM%{!(P+x zyKCVYV}};69AT@Aihg!+d;)_5)|e-{8J6c<(iHu%>wuEU+?la(qC$n?v_2Ls9qXkK z6~yDRB(E|%=PjJ9yk$v&xgf-=_v^m?SbuSiM2?Dn9_>9W?_HUbKcw8Y29_`0Q{6-u z@Fb_*^A}x)L_F+$Xk4euR8W%8(5v*W6@glYVLhONNo}KwRZ=k0Rqo=}N^x>r8$AOA z;&q$$f#ZHsbCsSB(WB*bTXi(AEo>?qNp&wm5{-qPXbfd?d9bMM z7jiCW%=)Xb7+D|u_+dbjfE%VM_wnqpp-y$IsMNc}yT1{_6t$H-&w94BM<%_79zq|6 zggc#E(cJT^tliU4L1yam$J(cSy}Am=sT#TZ3ib6$EZ&)!EYBP;TVA_AdoVmu0aZul&*z(|Gsy(RZ3xT;GvTD`JkQNhvy)ezzpHOE*YHjQ%OBGJG+P~ z;xKA|Xgw%N=alhhTJ-HDUQW*-5Beo5qIm^2llHbHE?TL}$UDJT)1IJsDZ*$t>$wk$ zBo5maY8KOuPUM{Y3!@E4uf*3F-h>cYgdP^6sskKw)cVgXR;WErl7i_ za`yU-H1}G#AQn8DiLye_3q9@`10>(~n;J-|YFv_c7I^|}R=LD7QtDmCm)>CQ;Q*aM zyz#D?@tXHX6Xnd+6fN2X5;+s%wep7q_{fkg7S|P^ty~k1Mx!SmhQkv0a+weCq4PDW z4#I){OG`L{vZ+m=wO-xFa;M}5gDk6vX99?Fo02kz0+_t3`mwn3D+!inOYp2}?ERP3 z#q+Mt`@Mc@yV9e%Y2kGz$Sbsg><0#1r_Hgaa|BUP?92<&mtzJ-Jk$AQf%r;UY=y-~ zT})+)(Kn+!VC0^fywwHI5;$x=kZFYxU%1X7kP>fg<7zE=89jzsy3I%d;~tCQN&p{! zqpj+*DpLl*7#W+{*3yQzQqa$P9r(oElHxeSQ=!=eHlQ2$Ef$6_%aTyVIRlmu^Lne? zZ%Z(lndoaj6k|}@B2Ubf6dz@Bl_8rX-8H-gqn6Dn@ml0^pg?sIS1C|H&`v0BDM`#? zNFXr*sI{dXIjdT(pPxC4btAK8NMlI4THjlrW5;gU2nKvxQA5TMmU{@f;<4xD7#-I% z3Dv|5DpF)S=*~&8V~i9Wtg}aZG+DkMCpwe~@)F^%v>?e?y{eu^a0X7EGKKn3!i8%I z^*~ADrSdMR+VIOGWi!uKaUVqHM#7mfEPR=T@}ZnJ3V7;*{BMACVg?KHndCTgbGK8lyo8{ z+0G2^hvD=a7|^7ms@oP4-rn1 zwgF<8d=Xl0`F@av?IJ#vm5wRD>0MhzrWhtS{@-y8{$}|5dtZ)!OpJ?9PYB|Wew$JT zO9lmj~#bx2U z#L9arm(;{Qq{ai~EDGZ+cBbtT%k2iIyHx8A zmRzohlwd81xXwJ2n|{2st;-j)t@(CQ>^7~z$pMi#oVnk(W;Ma-t&+3nHoT;AlLvu3 zG_aH6pRBap`3B)x6-dR{nT=6QI8RW351_#D82om--}J^Cz@Su*U+$Za+|D)ki4QfH zf`l=!=|0}n$gT!`@^UG9LTOk1<|oU zY3^EgtZTKE#HxXP3Q=RFmfA;LTl!>Rpwdsj*l|Krg}~AhzPIDtdx{O3Q^C+E12Uc$dX|=wkT+sytHwSq~ z?e0-Ep~H)z!_C}xqcUvE+&0In@AoF&b4J%L!dv7FcS+7=DQg}M279=eX2oSq&0wEf zbt!F~L=bP1)<&?f;ZHorg)0L2KVNlF24~P^42d9)903nlNeavL*`f2G=`*kEv3K~g z8|T6u;%zN_E*r|mey@cY0zUZuE&jf|Fd)<4DuhvO-%McZ+gzm>fs|l{+Y`|8@(5E? zRR@htUz7U4%nbY7fC5;(r311aNDd&(iDM_(6;?DJ@Xjf&c#mV}$e?cI`Y%T8`oN0P zdA=VBCV#IZ@QH{GEA^a8Z^4fa*#1!CcQ4~jf!~eeDKjsw9<+dOj(j&B>s8$Da{VY;L$C`)PeKW4BMu%klYSOkZlF@Y0#>m5 z-Q`{#m7XC@ZxVl0MG%Q4vm4Pf5?lA8BsMr+t7Sm7qmu!E&9rO|X|TdzJT@*=-)O@h zkgg~QH9Os0b3?kIJtpTq@5-A#?CUhI?u!|0cb*x=hxS5Dhz3n89`}70CTSt1>sw`~1O?UbuM#*&K2o!-`T zb22vGHJP=e6fKz(XZNL53bgr{zZ(y^>nGVn_CN5mj1OpqMO%$6YR_g{bz4~%-R-7U zAi#c8W*ud@JaQ{(!(Fu%>Gzv&x}MfEYY1XIeBg^Fy6TFK@W_bn>2=By*;57U;YZK7X}#qr&pd;e22I>ivx>~{T!_V1n!F^71}bQkj~`^qjlw#S@s zbFcD)WCz!Y#81vn57sed!q)V(8rwkELKrW~D%)b#sH*a<61Gw4*7yMhiR^7ORxQVd zCo@T-RYAP8tr!yZtfa!7mPVjze8L&YJ5Ve1A5=N zqMo!bIbZQf%=uYhZSd4km0-wt*Frt28LC~P%-j9tn46QX(&M+6)yE7d&@aa@dJNRw znR%vNc~W$_l2{I&(~en$kgQm&ZCl`d7qzlz#UL(FT&vw-=J>W)ohu3j?l8atT}ynG zDu5@Hk^|CSV|@89Uj-i&-ksTH5vDd={$w;YYg(^7@M7Djc{A*5>*>wwvI^sQtNKJX zz=cFj+3ePte33^&JcBE8*4Nf`w8>YnCRGL<*G}q|_m23ga&BI6r!dFn>-uXOer(md z{JL$YDDG1Scc~3;nGaI7y?X%P#+pS5(UFCPERTyKCpIgU^HwqCOw4nm^_uB37b5g} z{2Z(4i3S)yzqgHmPJsbt^X-ftxfSK6XBqUc{NPL z8q|F5Ijo2wcXZ9h`42-KPPnW$j+3VlRxguLX^7b3M)((zZA!FFy9_I>K9z(>-OkdKG@A-Uc6SJS%xRaD1-T8x+ zHYP}0jcN;D5zv_YT@ma1(Y+2VxsIGXs)1Oo2hZ1W2{ zy&Sl==R`b$9CSp5U_jG)5t&1f9+aV|#J)3#6y6r5x(|DaTEv4BoYIQ`Ss&%%FtV`v zlLDeGvzF%7Rj8lx51cw*;Qn42-l=7dF(vCUbxYsrQO!#UClgv-Ck7;NK}K=j7_rRQ%Yk{i_Q8!Q&qT*YS9T z16lt%TeSTy>EYgBr|X5*B0_e!?*3(ywjIe(Kxb9uB29OMZo-J=zU$>1g+ZnnD~&i* zTR{SyMi86+L8&LOPdIaH=b(BXXw0xy8Qr(CRnOoo3>yb;zY`nBJENgLL(PdKf^PM) zz<~O-6KQ>KrOejE#q)1IQ817gjY<;-#04c5XN=XQ#~$TaNRAIB4Tfm=jY7Ie{vwx+ zQDx6UG#0I_S{?&QuPX4)(@TX6mS0XrOR)%=r2P`Nj6oD!MjNE7_{sn&Q{f{N>Fg&R zKj&uVRJ?W;CRsf&JwsMc;od423R##`&Wd&Xlwj+iPBW83lPiU-G;iEHS956tiW!AAa% z+dQus$|N}Mbl(e~!Jor?4#slpU2l6OXoBu^c;$GltkF<$I5f+hTt{-ha!(iPTirLZ z2$d%7nJgGqk4hi_8(=*L{VM;nz93ZuC+z%CW+pb%yz84KzYVuUYKv-dF%G29dMmF0 z3{*IM*8BS3wU;c|CVe}ZDA#VAT6d{s+H5g%mfTKjzzL{hRvxGqkWMZ!XI?vu>8VZa zl~u;88&PX1PP-A;)}0he;wuTIBcQRn^u7*}NPQ*TR+T1j=@Gh@7%PRf8ryM1=hOYH zB$_~|Or^)fWQQtOC8fu`uSWo5MXH%YV5f6&nNKoGy^9jgN+ex_V|gn<;=)hSPPx5M zzxSJcWeEfc3CU#b88F>Kd@P+iV|)%;U{;tqqTA2%QqW>zq*K;=fWTwNPRH5tc_=Ef z0(V93MkmzF&=|g_Rcxg+m~M_i9hTp)2Pi7u)LX*Y+@X~{bnZ&#lyol(1-S)RD!8K^ z3o;ZpvMVdT$!0Ttt34e7^Q3Dn)b63`ZV&C;ecltDl*FmIt6!T7uD2|NQ!1ehcz`9J zf#jvu&TBW;njl?*ZLF>qki`9%t_FsdCv_{p_zU@Sp7h|974K=kNIQlPG+}p>q1cN=L`}SHYwgmO!Qrx%Z>I zxV$y~ej%VK_x7XUsIg3eiz9(aMiZ+5`G90QPW*;_QE!@|`A%d;dRzOqClEin@C2om zj1$Wap;D&rqs?iR^ZwA{JJJR9AWIw=p5@z|t>=E{g%L_k=``a`l6FC2tY${fkS$sw z`R;g;-_z*$G0?-k$Bw}!MLjIvKe9k47AubS05$sQ;}!aplU{fk6%xbDj_j(tr$!{_ zc&l%Bt(CwmN0W5Mf*fz-cxL@3e7xz)2B#!IZ{p(mYG+nrUTjJsLe-?%C6n6P7B|jk zL4af)C7KDXRoMcYWfaw65JwUQm7v7SO%cUpDfu}=Y?Kfw`BAX^I|Pv5E~m7zJ8D*V zdd{#Vh{@iWliX3R>hSH#!gq5%OsVH0W$R=HP9VRRx_qxR;A-%5zl&YN8n;qvoAd7L zl49MGPmI0YA0tLuN|+mX@d~(L`IG~GLRcconOf8ZZP*;eWo^d(b^bJ1duJ^UrJzdP zB3VmOORv+)#>DK3a^8SD9peP;kfoK`=xT8+HY>3`wVN-#QG6A95I05B9DpwdyP&$E z;^^}iZJZySE`KsVVMf=qPst`~q#EeC<26=EBTMzv5#Or%)K?`!sI_UJJk8r17KuYX z1pTtQ+`Eu;rqYV~K`qrtK`<3l-!4vGQvO_!>E&0W*!W;;wWr14A{iOLrgN9t zB{)k7(>`vlxnpVWW@h@*Gvf~#s@>+qc<(wXR}e^w6?KST~+Y8F%es)c-+8C0%{lw7h$4NR=QBsHJ53h+s%S< zc;g$Fe_5J)Mzd_c>|HQ%X-*C#ddrAqOUDlI6Im;Eel#XG=DBQc)3np|&C6NNR(MJk z1E2mlC+2q4V37K^jRj+Zm`MZkPC1>yYP~_6I$K&nDr1br;0a-*7CQ9~d2n4Fld7kA zS43fpnWFRJ*nBufN%51$78>KgX?mjVL#`Pp`kKAQoW)d7ugaz?h@)4|jU`sO$e=ELZX=t*O)00hem44F13D~Kzy%$;4DRCn6&q? zu%y_&@1B9mXIf=!aqz=-iSH85`;B(n!3Hx3t>rX2u8Ei21ik@jCG+B3v*Yy1#@OQi z2?~e<>29_7o^n#TLs6nt<*Zoc@$Txal*V=6Af>|anJm*2t#XCRuA*qQB6V4{KIwEJk0N>o)Lg{%BoV`Dk5A&2V5u zHR6T-)??DUZ3UVDNY(U?aAEY2ZSjOHN;C&sg!VVt=QP|iS(G8{yF%RwixLRN7|YGl zkCR|l6tu8&Tk%_)C8sp-o&jp#UprOpAPpE-lZx_R*O+Taw170+S5-JUey5 zEnWxgcy~hJjUM-0g-bEkt9HuAWvr!l>QIveDC)Q43yEq|9k@0wm3_w+on`~~Q}K<} zrSda2-F2XD#Gs|ka>IQ@AuDgF(3jMaO6+oInXvK*S}Q{!gft~`qhd>;Dqf}dlx}vf z6g5^Tjkq9Qhr2>fyHyt44dfT!I~9SP`o9ZaLKr8A~Hq4?fBMk)j!xcItzW)=X278I z>iia)BMP~^*vg8b%F=4Lu6y2ZaM_fiw@j$abE?y5?GP%T;`Ji-Bmv*|<74gEVcV3I zC~gL^xZFFtI8Flu($JKacQsSfI#Xt@ZSI0vE@*BwrMNEv zg36+kiYACAD3(ieU6$sG#~ug9pI({BoY3^Zj|f-zQxIz^;n0w|AGZ*-z~4mti&77MRa(Cw~bo35);v7;(`W z5jJVq`(Zuu^&=izJ{ufybE<;`Z8m9#5>`>s0yb`#%7C>D1(znaaoI8#Ky!uQ?lNq| z-4qfN4$q{>vAw34Esvc1F3oRR5xgSE>3M*ig+wb%4=DPG@O(UOt z!<=i}uq~;6pUeB7W>;@_n%>6vo6!&}U>J^!c!_&Dpd*7YBT-9QWtwxjG~8q( zWnww30tU>`f$4VE4r1~_gE7}s(-ymmQ`q1O279Tm!tZZ>*XI-ecC|O}7wiPoJ_!rK z5L$y7O)Xj<(+1!Csn^j_XCmpoT6k}j?fNJC;b$i&v{XyBYVPsNifSAL*Q$+ghQNFl zq76e-Z0aPFoZKAC(7i$($A+{_pK;n4z%8wlV@@T*H^?qDHa|_Jj9|5X-H244=21%~ z!=-LIS5jviG%DbcIsPZ_1`G%uL?%_{c^`%ub*%RrWmPqZkA3{9h?o_PB8*MzZXPRv zqNaDH*w63{WE{v)xW=xgPe=;B7(!o(a%j611y1HNipnt zNCb9LrE^BKzFdY^9xN<=^7-t-({rTa+OT6s-Zgt04-^@-#3=h2*1r#XY;dC&g=p=K zuI(-yBONiCd84k^>|H0YC)~j22`97@2t|;fRw#^tfzwyrofaIm;ou+9X0kDWCOX$y zA<&D+)&N)^Wj|TIIln4X?r(TysxmjNFfsjYnkZ2CJ@9^EpKnm-q-Jzz>s4|3#!I1~ zl!et}taRE)RhA4B1=(=bN%-l2d0lGyjfvF#-ThsQR@bT>?hY%WqO@KH#11Sh^QR+t zjaFvhxI0W4p!f}X*6$BT4S|vxKLt%uksAoP(J> zeF6=T<|-UoZr^t;Io&i4_OeH?H^E>`6{*7XMKxjd1rvFMZQ^XXkgNM*pBvF0hYion68AwxQ1|dU^&HGE}B^N z9;3eRuIXNpI2AL+Q4xp@hebRb$!v6E|KcYOoa*p`4N1jp_La0$*@IWCjc5Z6s%uYpi5J)m6K3G!J8 zB%dCrr?~Rz0gl$t(Aj}wx>H-di3bk{z9^qJ^3V7EPe5_nkma?gvX&>>N%Jiv|Ng~- zHoi<62Q==UO6uzvG-#s=mqtV2+-9m!2(8~%@vX9$z(sSIb(m-64jWuAiL9G7l-{>k z_+F?LVJECzDkyQkCD~{`LhB154B4ttN*FjDo2kOSH~H?d6D_)#g~5ikQGdUlwrajq z>P^AYw#<_K@626MIUc8;tiNl0t$hvcrn9dBIa`g<#KLcO8I;5tv7_MEz4|6sBBDMG zp_v=eAFWDpu_9k+V#OW5y`Z4CFAXzMTDT>F_en%kYq62*hmKogjs|zT7jZ(Tv2+rR zEp`OO=qQ?`wBhbAHAKzLK0db>U2VEIW3!QJ+oMp5?bk9vb2lN67dBANzji|E^mJTi z-F!Rvt+^`Jm=`ztH-pYXZ&(2Q(oxa|R|{@5Xc;PjUi%b*<-54Vn5dFp!46V$uZMnY z0+g<*XT_N#xza#LT1wgiDIc7G-iZhpR0u$TAY6ymmg1JF796|DtDS5SweYU00NC-q zF{!dnJ?Ef8Vi^6W#-g5J&1ZBq_A2TYE@v1@QLS_KK6$zJ451Yt4o7j_0cgf3BU)Ks z1}Jw5eMX~)XmA1&b^A5SU`Ad+1QJy>h0RWFQUEqSk~FRHJDUdlf^fism}?7Q|GTS= zyB~%N!(Q9OotaW?(0Q88mUO+EpFF5Qd-6Lec+Dmfuh%V&xr`AX%AB%7)!f`KpZ>Af zU#3Of z4VS$!KOiqY#46rp_h@An%rNq}jVr*4B=IQ-yw{_%X|U8P^yx9xH{P}b)G7q1${tSS zWdHMnQ_|v{7D({^%uO5?-aQ6{DG$g|KVzx?)h+v*5C6px%@|$EANwCvPV5o&rLh7> zOfs-Bdg4Boe^#I9V$8FC0CuL?)S@nXEQv!VC*%+zNh%;2_rxGEdB5ws z5^y8y0PKY>EgL@(on9uaO&W0hMym{o$Q`WB*!Tbqo3F%&D1Rb`l>OpkHH9D~dklC4 z{!&ObHqM!c^QW@Tr#(%}F8+6uzdH+Maaue#ILDUPTCAZ@QNV;y0crY+ zm8Dm82Tz&((cN9qbzM=DmXUj|UR@DW9mYV=EU%{%@AvGuvVi zG19C4(`YZBH^-XG2{lJ$v;>$pP3q@~=8xocFE%eVMAH-^ z`QvMA{>E@1wp8TM6ehscIrgJXxNzL8OM@?`{&3^0(oc*{wYH0X%JEz+Pm@=K9uiyq$r;lu}2_Q$3Ht8Ujd9(vm%9YW3yQr}~ZK z;o2*$_|7(K+=d~Oc*LL%J$GfWpp%&Dn<8CqQi$h~QKoSgzW2y|bAIMjYWGvy+diG$ zT^g@~`=yhlsNA-7^XJWynJv&~>kNZRE{n>tIn}v`I>wr#6xK!(n}$I{UB^`aHWux~ zS`MsHT@_88AvQUp(J%^P1Ek7zSQjX#J_fLFtEM!em!B4Q-$%@i`WP@SnGz~_S60~q z=M4>$s(F)m?RBf;(v|KQSrFpBpF{^A5N_1Wa#7tWUQV@&?o(V zyK!~@ou{W_`b~ynjsu)q*h^X{dNvx7%dpqNRbf8bKvwM-`BXA#^7*K@dFgb= z2;25IctLtP&pQnK$vuA=Z|$e{05TJ5(fD9MGI_*t^*7Y9!vl(Gwaq!9vtNQvx|Iin z%LH7b--8SuP8RyexKqfPm9v>2;!)e>EO<;`8E5MQIny!poPtFOho(r>(Q z)APxpYs0e14QSoT!rF*6XfG!M*P6#QY?enPJcLf$g1~5QV*U|!$nTGmOLhB!ZJk#q zmRsI}uYq{6Wj_BjhBLv$>f)3%cA(9%-1zW`TzD7g@x|@ru5JQj4D;i^H^PoxDHM)= zzt$?w=&D@s8_tgft|6GQ2HTibhV2ismUEklMpn&(QS`@MxQ(5tA?*D&Uo(U7{~oYu z+>cGk#X0F@w&{PcO?_(HZ*O`#-QeE`eu&zEFJ6m$b5b>A66QNGeeSU~kn)#Ld~at; zw^_%+$F4MuHQm;SG(GWrV+uJ3|5|GYG~fE)15xmgZVQ1U(dt`KZ_ggZII@^4Kz@A~ z1=sw9wiw9Pti%C-b8I+?56bRyhNorC-FuVS7c1C!N~plXQ5v~6NX^o1aC?(-p>$x! z-a8Plwo6LF&GwXet*SJLM!2i_ztE;m7&q=t9u4_d_!prjFy~T8(5{2xk+Xg0v>u93^4g7a=)}goGMaHf ze+jC=wE#UGki)@*@kX8ce?ySZikJTEt^HQ(p}NOWPi(rd7Tli;M8u*lRG2Eec+ne*RN`M`o$(+KVx@e!8>? zI$7=BQm{9gSLCpHncurvs|^>pa`|gj!g`^ga$+*NeNr=^@s{M4%YwH#KorUfBEg7k z6SA>r6eD6j8CZm9LEkWQI`^nCbonkCZu5o+O7Q%3!}QDXL%P3wz9yW@ciRiPxy1V` zjb7F##!&J$V)V9fG8DyYmJR1i3Hqx$Tik>*41E`sDAARaqm*{3O>bqaywHGhLsSnvAp(;+r$#>W!NaFB|I^>?&&|({3^9^$89da zRYx;t!RTS?9|@-nUx0o)wX6lA$3PI|0vs%VctK@1tmptc zxda6OIP8GIOJ10gmDZ&75|Q2YR~p6@g~b*4REOCu8t6e6FuUh=;k>6$n@dNbO{mqZ zEHd2p#SME2ZdS=#V-~m$0dDcv@IF;#oSYb#qwB5xe9OKB>xW-HliJo16cT_DK_XI2a zv1JrIi}2v$bcYWuD)?gn+h+%CL5F3RNrxo0#{LOf4yV0TekJPF+)CkXJlMEUT04JgGLDXEJBzAfjfM~XiQ16nTsq3VcP zkin0^x=c$ri2*R#)Y9k{fsn26Y3QR8yq}{Td!7?3M!`K6zQ_8zND{OupZ%3C*o8DB zUcFo#&EIc+(mb^h&sX;AA4l&@)-)|a*Ysst;iGrmHRE9#akR$e83|jyz+5%yGaJ1I zKGR9Mke^ZVC@&(gvFBb$zqZB#lI1dFVGyJOXmKQrZhMdVHh->+p>IKDe;+(&0DY}F zN3(csfaAs!YlphKbglim99m1(5{yG6?Z<17(`ljWB=CAo%#lr>xUrB06033t|f}vN18$GpteU*eP%P z;sQhs8I|RwcXo42S|U4_7EN1C^9DW&|EX@$94pO{U6!UpdEiTGj4Z=Tl`-Csufj3y zdF%(owZ1+$1OS)DK4i|P?^x~mO_S#tNwU}Bu|F? z>glRj2mU-A7*A^M9QbzsgrJ`)cJ{m>=)IQ$S+lam4qo`!&xrlR$q;l>QHqBZJ(!D? z5o#SBkAb^^gDU)~4boo1mqD5b;zAur_`3P#)WP3oRr-g_@KJ)s2i^yBF)DajV;QjA zR`h+tXJ{H}RfcS0M@5oC&J|SKdug(J7L4^l&Y&6{ za-3q`w29W>$uSwXJi$M8j+j_&icDMdw^RVMu_!xZm+DW>KKKZPZk@BP$7&8kVm{E; zf^XlifB3_xCTm6Cd7JQX_t!x=t?g&^=si+wfdRDvL2VNu2n5;|AuyN)V*g+H4*tjdOCSU`zoDd#AhRE&bkDV9z!C<3Yulm_4KNSe9%C2 z#gaszI6z_ooP&9puu;|cMT>Hu7&!$18;&rCkVk~T4iju z^!*gA)OR-~gg5tOJ^bBEwT3*Q<%L=0&)?J0TcKw*`iq6J(w5HfU&!K#BbK;TK8q*q z#f}Jq)GaV-dCoy+on5`aa!DAZ&^)=`BHl*S7LWad@(B9jc-n#&2`x9x$rFYCc~n4R zjIP|0d+IQv;?=jmS^kZR^gPq8_=aEV{^66V=#NN;^m)^-PtkTkKUs4_J+TN?N3960 zqBO~xzI_A%Y{Vs0a^xFdm3vW}&zMPoi?uVlm52?k_meBpG`ruX5nhriAMjpnm!8RdyV56r{!hx6gY^@uClnhS zjtvZKM^ozh>xxbxN{cX7owd><2m@BcUpu4O@^RIIZI9H$`|}a?JFPk{gTJmZCMF5t z5Ilz!3Wt?&OM@Lgf9VS>-tlV(dA0n2Hyg4q{^-YQ$`gKpjyS5Bc67Oic{oYrf7&i*^&Gm+R=$x*k;Gl(mCp~;(A4zPP91l6Q>5%^ z3|CAzeIwH*@qpENNxNSd7yERrd;O)xpBI*u!yVI12O^bl#-hl>rb9+$r@B9MF^!~% zy1NZcwcqfMiZ9YV-nx8+^XnO-g%NDRiRg2ItIw;jhHjvfWDM0qPDXr(^;e(L<`-2U+pP~dkDPwe*1h0&ztM-^qs?#l3QNF7 zM*>e>(3`oGcxxb}5?ewaIPoyqyQ&}bR4a*6KD94I#frJ#az2y(hD^;f>2*+)-=1bA zwr#|-PCY9#h$tEl$YihjQC`<{!0~D?kF=bCTn13jsUJ^;Ge;?hHsLc(4g!lN(o5o} z2$L5^Uxy0MlquW%9)-IvZE`$PpYb?(yfMDKJY8^oZlWd&d!?lz{LJYSOC5XKOiqelY1dmFq6!s12R65qq`A z`M)gg5mwZ+2O(bvqb~gLhA}e)l!6ze4{Q%=ZH_64&5UrJ2xm^g8DAGP4ektFP1xod zY)`u~k%@`TEJ_Y7jYl^R33t-3pk}sX$xqePN82ONyv-ih!0Z)v_soJvG#T${;@{y>oOpSc_e~e9hiz%Y zkA!%>>3P#*gf2!C*VnJP33_VAfPAqV_6+CtSG|qL>+IQc{0%DRYj$K3rngDSx*&4s zuAjq)wL6}TZ+0s7My!Y0;rp5}` z0%0D@h}V1nS&~3eQdFX7O+8g7ehY`)T#QL_=rwZ-;I#ZiLGK=Y_rr$N!34qNFhY9DZ=YLSzHWMmQK(!u2Xu1` zpk#G27QrG!@LBr_c)UxH9@heuV@Z(oCdGp8F4E~NwgYeRb^cG~?X!@(jhGb-MTIe_ zc!od!G(B^$>nT6|VdI_G&I1g^oUpwYngXh4}x;JJ*=0ZWm;dbUwt zcAG_%EhS*LIHl4sZ%LW*vyyM$h`0h(D^(pT%R zXX3(#{GtCn0G(__4(G3~vT+M@tk7jv0T$B%>(CkwYfvG-A&`VHeQKwIe(t=_GOt&4 zx#j5zFmZms9&UC1&xNxON4Ekr$)%g4R>O`L9XkH<2|H1cd^;=nZQI{HpxKE95`@!p zk^XdOyv$6(U;FQY)4iN%+aK80wljZ8FWkU4j+rQWQMaQ&Aj4FM2}|>N>Pm{=rqPxJM(K7nBhvKM`Ym!4cGt z8Ng>NDiJGOacSazlmR%7UZJS|L z;P_+%*8sW@9yL_om#$rGA;9CPYnQOAL$2Zc2B-}2C=H*G5Qvsp$vf+{WIq`$v=Xn* z%ERaDSgNv%-m}wKFIcrs+wh=>Se->g?STED$1j;Bim(1wzp{+D-+uzqIy$)925}qI zNvM8CHb0mfc-NEk2$m}1AJhD>%U&puGXyz3bvGTHo%WVLN>K2#+-#P`^yWk*^riD~ zXnGPuZ)5u#t%S-Sg1@q5J+KLUB8*O6>#9>8xH+OZ zh-pgAasC#IumZoxN9-hyP0&OrnN{$t>aa{AMAS1v$D+v1;sQfY>~rpmL5MR9Ili3q zb{NDr_Sr#j3O&Z?ScUecGyS)w@K{cwr7o!~K81o46b+Hyj{1B3L3#2{{N>Hlx22kY zS4UQ?JuN%o_?-ja4^n%)Evw!g-0dHy6(w~BJoQ*0ox1x=WD2}5uW$6B6O*|soF+6} zP0;ufq-uJz07DSK+k50iwUF9O<(>%8W0X4B9VfaQq}QoKjE9{*M;T{;Nd0hsWQ#dXC#(HCX47BO=S>sXeD~m(y8|`B*wJuih zN9mz!OVY+0inVq zNUS~`l#B~7(;4`63#C^ddY?85*4Cay>X~0LR*e1l=56g{b5~7-_emHS=#4Dk;K)!J z%3VXqM#@CZtGoC1MTN48@$lZO6RG}YMJGh-4TMc;xc8AqqQCy5Ij#9lvsR!v^*NA8 zu!Q$Mnqe0Dn|;;(6lU@-+|TNzy|pQB4|O5-kxZ5QdrWCnk{8dT1Nt!i-iGe5NH><{ z!>IZtGP*#oqyb88o5Z_C2~5ETA7Fz9S2PShIUdhSJAgft;EEagAcGi2`QmCwv*F41o?hrXM19duh29_Y9;c4m&+sNY zEtY>A@PyQMMk++!8&v7I9(c|=&id*n(nGT+{GQRe%*X%6>sfy!P>W~xzp6Q-)Hr|0 z(GervL$uH1jMcLE`cINmyFg+nfWexYD|i>+;_r$l6nN#jI{IP&H^8niU#kkJD)K%~ z+Y4+Dcbdb$%V6u=Wl=riEAT-P+2p{$g_vu~V)^8W1MKTiB1$X2VMcs5wM~-;uP++# zA}lqJ98QS@Z(eHp2!Niw_Qko$*Y%P~d0?5wyxNeKm|eZ~2j+E=ZI1102mYWYnd9;3 zC3=ZTsnGG!WTaVQS)<2ULc5P+>tJ=fp;eo+7CACGOhXsFO)A4Lz7A(m2OI_Z*(qt& zEXSMEYme-EiEMW9UgyRd)gHr}-(3vpHoTF%`O`O`&6wLKGwm_ELg1xO_-rmcknLzI80(_ zXhkypa1{yGtNymtQflDo*tz`)xm%XoZ@1>hC85QyY0M=yiB4Zsdh6Gt@?Eo{;(6m@ zNn|e|e$G{AcI+Z~OKr-@mV0Ltb-sgtbYS-5?xa81C!#89ucvQVm(AwXnym$p zt9T#UwII&1j8<4}Rpn@Ydh|wBxOreH{XC%JdY$uaUo8=PL)3&`RJcU4_mx^hP6=*- zA&-_EEn6;oUJq^Z2RS>NX{!JKgth-)Nzlj$=hT@Dzld$W`aQG9GQGQr&?dNk{#0yd z{?ty!A=n>Ke}g|54b%4Dle?W1%gQ$qLIy$(9dRY&+_A}bEd!(V_4|^IsPFhhU8D7lmlq#3R zU1Blk+5Rud?ck$b8b%w1>gf`m^M$U98j&`!hZX-FoELQ#bV4bsz3Vwac(GGQCGFHu z)m#1qiogN|OV23CWp;wl*9Dr#uswW&$7MB2Bxs;^l$g2`ttfz9H;NJ~!mh=pqB(*B zXW-NhoVX~b52WudCIar%8@W1l z+kNQ$z4y)aI3=J``EFH4P%()y-tFjQ{7Sc&|KQacewf&^W}z<+7AimE9=ui=!152s zM@5_WANc`fHSaLu^-2+JvtR9b!`5a!sAll^Sgg6+F6u-Hs_B&%F3P)2S%Fk}w8dYq z-z~-?fD5&@A9~Kw7qy6;i-Gg;Q6$T(piD1P&_6(O#;=L@ij!te6@on0POtrg@Eh5t!EXMfTwM_1^;@k?1C8hwfp z-u)dD(Fhs4j+DiYuL3kmMyYVpKk7l#`5IA2$v^6WG+U9Kmc~kgdJw}t9d55q_cZCN zb#r#^I%<~Wsnbor7*P;Ky(K^lkwq`?Q4b$&5+}r`Lcv~q-Y*QvFuQW?u5|)^E1F=( z&F{_ZsLyZ)l-vNreDa1`2#}p)p6aQ`!=1_z&0xHD`U52{+3Exsdrq~J8tpa8D-?}G z>2y7WcZDKK)oE#?NwHsK0Z7??mt-e+GJIRCQTO6}Y^=ZH!@gSQ;-?ojY`;^$L6Fm? zZ%gDG8Pv@Cjq`?=)TCFTowB&Vs046zEwJ?{#ucB#tjDaZ>hl!IEt!Tth7W3TnRHen zg^TXUE~ZsD6&?TT2F`xrI-RdsJktQM!^(}*uI?u=27)s(mcgmPGr2dC9IDSLpsTY^ zdf_$%SJ){n1Hl0Snin$SEUp99j+{`Q`3yDrxJB#ibQE|FO<2Z$moWu*W(JX^&An_I zc|UXwTY_Py9nYiV6U#DS9=Oo+Q zRg>Q{U?Lr)0zo++cj3Y9aiA}7q9&2&Hovl!@0!8+vF!uCx{%3UxwCnO3Kb|=!YM~e zzv(C{8H&Pqu=`K?(Y+-XY^2Ta5cbmRb;6TB^M1=iFnvL#*gvkymEYkBdD}Oq`$Cs# z6A~qF0W$>=j0R|1mSfpSLA}rA=495L^|P+6yIeJSgSLo35HZw>2?l3w^#d%dh1AAD z+KsBlwk!|TR-Xh?*UHn(=LAk!Cx4t?v88C{r7q!8Sf*V z629y+UKfElNruhaZ|{Cp&(6UmexAgB_Q_#SCP*fuLkXb-JRzpUnrSAt5{{Z%_a|2% zIP(=RCV>Q4YYH=M*ADZ;Y1U3onR>(i-nwtUGy=hwNK6n1)ag^6#<-qrd7((l33idx$0pwIvg3#pSB zW9TXu8n}7QTYuhs-rzkAIGrQ4^N!?@(7PkIhWov(X>a-{VP@;uGKq$qJ6jiAS@iOV z+fg*zuB{ToUb`O!Xfl|Ee{`lT+T(x=Bzc2kY7{Q2My8MqiyO$(hY3pH5l5%;#kva7 zcuS1o7+);UBFJf8kjV9Jx%IOsYxC)3xeq_vBOE|q9GV5mlyh{L-4)$snG$@ z3FnyD93ej%23W-9=hK~vPTT}37|r>~rKPDPri>L#L*8SDE|&h_aZP!N;{1Hj zLQT!DI?FawSP`>-6(70PZ<%@F-$E=c<7I<)t4a8>hZ zw{kTgp`hYvP*J&_+D98w$SO@5cER~c+ ztaGgz_boDd-j|)c|Kk3UA1~Fw`^YD%rwN4G^IImZiT5?rHC8s_+Y+2xXgb4_2DiaH zwz-fYY}nRzxwSF9>i(m@XS-m)P?x@Ti7%95eF8_CiFYJ8T_M!GKQ zh4`)jy#YGGXhCtfRL@jhf^8>-PKmj>Y@11~8SPT1WDdwX-CwN%do!bGfk%nEx2vye zuQSXOehgjZs~iT5SNLE?;8o7W;)Kf8^ed=pma&r2M8lhu4uh zf1A`!?zj!R%WXjCDD`@@{?;kZ6ZUSp0}B|RhkH2$fpB8qXd-N^Xajo7XT#gNgOu%; zM{YjK$%NK6I@;>5UZN55IoXPn%5HR{k7>;lfS>Z|ZM^)nA6_GH%_*yNMz?n2SOBENH`iC_NMPv`Hn&Z9deNQaB-+R~jE?H}9O>5gKq5Ppc zhAkgh{*JTHV|OZcP8Ju|?$U+ZOSUijnE7z$t5kEUDJB3^lF=8_j3=E)z^fYj!t zj-2U8dUYn}u`?Kc0;akd5Bw_!5yD_|q$dCK$mGC*|M}9qMi8#?xQ4mebDPmJ2OE9zUnl^S4=l(C+Ok z-yRR;NOLHw=SwwJgf&WEY_~QM%n4EV*`|N-8?4!*Y%e_CiVF|*S`Fduoe-A&y4H;R zv3Ycbi*d(?g_=xNj>M$gIejL4SR}}jI|3Xs*BS>*LqY(&&QHhAKd*7Wm6!d_U|0+k zo~BusD9Fx&(UGCYaA(2fn6P#FGWqxtPUp_59Jn$#JY#w0`dG&GnZ1X=a$r(?({|>&&w~|} z!qFOZ0g*cu?RN0@J0-PR`)Y{rR%bqA9@=_ex$0oxtTZn#_K1Ffi@_I)wW-D`+nG%d zouRMlV$=Mw1qiuf0?dA~GVNdaTQcWXD8@CQqNKYUaQUn?gLkBOiIZK^k8=GXf<#MO zz^gA3HA^xssiy4&H#zNb$MD$rT6$IXkoU0I>5Y6NoL%FpN&DYS274S^*EzrcPVa#O zKm4}ive@=&KDgq~8jLax@KH0zchc6IHHyd(BThL2Y6up&{E&-jeHVJ_V@xUYAN1N7 z8NQ-LgJ3_%$UTPUh5dsszPu6?VQ{V;@4SIU^m;?OyB+h%45+Fqj8M2;ui$#H$jt1c zqcaKxT_H2_OWzq9#G_=V>F1-{jVib`C_U!-9%^yFHvcP**WRp1tmTgyQ^0`>ct+w+ zLwlK7%pl%G7+ztgDaD>d*sqqeQ{H zDiE&P(AFn0j7A}8J%X&d@0)e^a$Bu~lN;Lh&mX#K<9@o!(1v_}<1S+W6$=oYcIkYx zMgnNzw6YwLGG(day04CZ0q@9*vyy8kA=iYX=?Px*=P>6`Uw}BJ2dIB_Q-NyUTpR<9 ztMc-~D^$r3lKh(Ym4xF@PvI9{F9bEIb+}30O!c}AoDY2t-VH1JuSGu zPknWSxsNw^_?=raG+S%PDY&=MS^4_E2M*IBJY5+eNn+~TI}c77x;LX%sDnf#PhZg% z3_hy4Kz-||1-jdF4!9UQJlb`a5u)^?8Klne)lym0ly6K8?r?d*w1rPSRe=tA!J}fd zBE7=#ryW7>n|RdPTJ6-)I?Hng)uj60V{W5<&$aaeiodUl^sOSE6jK-mOMdWRjS zYd^eyNV&AlIqKBE30CbYtvN1(miKnr^^ncHFnWRH>nK#V!__5^Ab)-#t`PKl9-gp3 zOv^y-?L!8%#QqyF>%U4D@00xYd-SzganD@L!3yd-fq`(`?Nh&u^0o`yZ?s1bygpmj zDqWcqz$C^(*+h!Z7@wA;$W6*M(J7OJ*bX=>qQ!6#n;!K2)ks6WsuD7IvdAe~Yw`GQ zbd_;o)oQ-niInR6%@b&MHp>sYpt(ep+C2Ihx0vgAt;2awzdPpVJJV&mTpF)#xA||{ zY{NtD?F2z+g72RphquY;-xCZ=QJHD)+#MquuFab22XK;+_;`4l#8oRkLX%U@3PM5c zG#Bu|xOnuv$<8|!}i8dBSObJdJ4ijwP z;eOM7a|OVVFTNwMHn*ue7k4$RChy$9_P)Zz$GU%tH_{1B%dHu+fQkbX)^koZ0fT;N z>!qtZiHoq8YiS;57N<1sMuT6CoyZPVC9qpGtA$5<@qi&6(uRdgns1RaTqq9vRybIi z=-8?V@I9=$4W{;mODlG?_H*s5J^{28`=2%1L2H@QKqoIvRXK#(h;-0jR9ryyS~7o5}Wqzf8! z;7rEEgHveEz^{Lm3i&S`Uqdk7Fceg<)8{LbX)_CvQq@dcuNfs)pg=+i9<3|qR-Nx1 z-~SpI^)2*2VaF#Ahvr9gK~!L9J77s?QBbYlcgYc`=|u;XuUboivZAikuV*rOs8~v| z)SiWt4S&yi(H~Gd6Bcjke6J3e(Oba{n`XplhLW8b((XTQ(@}p z!pw9*zJ>C@86(AQ_`Y^MNRXGwYPAC74}0}{Or-3s5e=e`C`da^fA$*B4Q(W4!=9Qx zx_@Q;(BU3S_f8x0`(dcd3*nDDh~xpU;Cb~P^WCfu^`7sjrl8k852*;6l7gL#6rPGW?Vil~?*_f@@Ps<(C}<$?S?MbHc)uK(;GD@7+7pcy9WC@WJ3pDe>Fw}zs4Gm& z&7!4bJ5T}_1N?;9nej9Gl6<57Pap(tQH|ru3Se>)3SxmP&20}6tO{mXDH7RypM|>} zqXe>bgWj-#TBy0@s34`9L^5($02@Wi!?eu^`6?;~p6(US3KM%XVz3vXyTA?tHTGIVh~}e+C!e{-4GJKJWHQJ>Ew47l zEc5Tye5tn9#M(M3nn{nnkZAGW1NwW{X0sl$hO|iaz4z>D>kG~{WS@v zFGrD2>FEJv?_Wxye!1pgYz5!K`%*+~-6y#J9&k(WSw`IDxJj@fKYucOeq8ur5L-H4 z!iRndekbS5HnD&bTfp@Yx&QDeKTRH28eJPYg!4@Rl$0EN+;4aG`7F%qBZ3daB(lup zUs0R*$~}C zZm*7w>E!Wjd-ld^2i^KuQ_FT_U5q@t&yj;0q5&Y?0fTKo=EbWiACOk8a@rOSHu+Kz3J%jic- z?c{kPvqJc`?QpYIa<5r&5HGb4(LJVZrT{uGb~JJ9lw(bx!Sc@bsXd*k#jc;eT&N`y zvg_)19p#xxyN(45bzj`-D}dJ(R4y2jbfsF49;M$o+s#dM>oRd~=feCi$MR#w1azJS zWjngSb$a{Vp()@>oc52DS1cwzY^NSEp=xy$7ngL--F|d~2Kec>q@4&-#F;vmsxS&x zr~|m&V({uN9ur;GBumhIP|f7Y4Hb#PBQmxQGv6h2E;A?W+VhXLH3AM8s8Y{$gttQC zjEW!j=-xKYe>07YxK+{PUMCdfS9`b=OsiJB88i+9^c;h=jgE4Fd|#hl48&UQ7nCJ= z$(30`Lo5(^Yfx&&tCYVRwN&)df7*kY%g7mwY?hZm*cZ54uz}j9?zE+{U1AEmD1#6^ zA;vividG{Uv|7-}F~kT|^L-}Tyb>t`1{ zp9Aq6FaFod5r{m*N1Ihg)`n-ZMOZ#s2&MKAdu6lE(HLL<$dNeAF7EI$_H4C zRN*MN^5S4og%bXO_c0@S%?(J8Zkz949LF$2g9d<}?9@sl>1sh=&IVS|oJ=b1GB=II z`Ec_A)Lp%td?X#G8+}@T$3Nb);!7Oh9VJE2HxfEsF?jvxEP+ch^H~R zUL^0MX=#OyAfo&kjM?i{GNOR(y%205F|E+6{S)A_DV4AK>)GBAQ4{^EQ=(W;)!tO%2A{@Wc;_n?(yJOpG|UO1u54s4C)R2Q>qA&=eV&K zRU4O}iYH`)q_{HSG`HZeaZ{Wga1}T6#tn-e*UmS z)r?Zga}}Lk+uNn)&NU0}6-_Aq0$2(+92p&fcjgX{-hiFviCjGmNDjP+WSlL9L@b;s z1bg&+E3dP;cAk7esX+9BSygnAUhr!mA66R{5@P5op$i_TM6K!{vC>6d-T?G8Z`X~s zNVa1I+XQ}k7Z{=KcaQ^QWtek)yNGVtCoueN4}`dU*EjR1%o? zVeFP~-r0(YjY4xQKeAH=?T2`Msx-W(>?}7JM#JZTXzn`e69SK(AV!t*q1B-cgPK*F z3o9k=cO|O&!=b=M48Iy0+M}I=QjC(w(xb)z7QI@0XP0{Ztsa-HBZZa%s<^>c$ z8=$vMtger}Ac@iZzOwSg>nO5_=6QqS%fFjT8$g zwwRn0jiO*sv7zR~E?5Ezibg##RxF7P6fGqLu*SKuT4SiOrmrLZ^kQ1=doJ~3@YBR>Ek^k!g7p|Q}{+0ccFcqFmH zXRd+D*>{=OC#_Dsyt*3GEAOZ$4Bd(MjkX#`&s@Pvn^GQ?io}t{byDB`e>sX5*{h+= zLl3IMEX2A(?V+PWS&eCtx-WdlBfGKTqjDdJnpyJ!T|{A+!_wfc#!zs<4&#zT3zeQc z&?V7FB~NE1d1sFog%yG9>DXV-Ugu%gV?8=6v{skrRbBUALGPboUk1wvwtYRWd^&62 zSs4=K~w?&_f+YfF$o3YzKUi$tq-)Q&IY9mbl7#lgLigWJX$e*`!yshKLF zAL@yOsxce@9YqJT$T6V86M{`u`nGtN@edO_5Cc82UHbmdUdiM=%z&1irgXJ|^ z`MOlzJpcyyc7alJ7eNkf2o#nSrQTFF7qh6*ozM#}tSPX_G8y?!oF>ry;Oe|dTU#Eh*8u?ngM@GHw{>uM^#_wSUi)Dj?=3RObNxgO z@t4D;sM(akW<|>E?||L7c@@>OAIxQUo=ACmF$Kzr&(sOQrF$PVGoK~Gt5Zsi#4BIg zI;$eYGl3w}LFSQ*YqCS$kJl}Q(V$76&xg~H=EMs_Sv+%6mn30RX>BkP?W~L^d!1Px z-*dakA;HXj5T0x$Jf^NY&_4A`eo5))e!6ne(K$elhsnqUilxf1m?#ypCKYDNj+y|$ z$JkzhiZuo4x=mu8%KDRM6M#k_us_Umq^DoY40YbHa^s1U2`~b~Wo7T->ZyeO3V74b zkjpTosXwy)V#89jYdX2ke(Bh>MYi|zD;eF#3$F_FD*}|IMhZq|zBT0Df@xy0SS=~P z$Tv;S2N#4zBbdS2X|EH@cPn#5@49*XTSZI#M zsA<_Hy8K(rA1TD5J08S9=!P9*V;8n!)l=T>8rZJZ6j_-0^WH-TAc4*X?3y^ zrKAPl<5rl0@DtyDe%Rc5&xfW|tU4OU`erUec^A^6^xWL3c**W4h0}5 zaMWnW$o7yo4=ZMKtQ(d&n+o#|+4;$6++#@V`d4>d6;SK93VB50$j=ilettco7yVw& zXc>>C!7@0iA+xK}H&7jZUef{T$#%^Cj&JooIhtk9S68D`Y56uot-HJuo-U_)r=&d0 zGTA}7Zo1byV#aPK;guuCm+r^zLrT*cK_8?o^b~9pY zdyj;rQbM+xq3ZfrU{MZ2@CY?8D{&vbDRydb8XMVAu5_Qe5ong=c;Ut$2eMp(Kr! z6&0lA@R)1)RZ>Wb-pz~~4pYcf^+HM5!mzo+8gjs4TtQ()l7Y{@uhdOM&g7fN^-luuw)hz@opJcTyq7W7FZNajV^U0d0Et^6@NJ@`7Nml04Xae>UN&4ey^Z%ErssG{A|9^nN zymBlkkUyDwSPz8sIV)%81X^wQ9`>)4Rp(C(V?)!0W3S8HMz+<^2GoY7o>=zdB9)hF6H^4X=%D zt>m|uZLt$41ans6Yx+OsxYPn`Ak7%-M1o*ZkwU{5)a0R2lp!ZN5Gzf>K^iDa?aXQ;`;wQ6aI1OlMSzT4&6tDH16+ z-<3VMMm|}mVmRz9G$uWkDG*@%LHtF0k$WHDcp-a8b|P;A2T|g-B6$eqfW3k*v>=%Ed3^GG*-rNr zD~C{{)ZMaVAH1MorzXqD$uxUYH__Ahaf( z1>*(R&Ay)}ULFB(5?J=tjk!yNalHXgLoO@U@c9eZVZn!cItfm$Sd+bmeBEB@&}1}y zPu;D{7tu8;>@{2}LBV;2n+&GvKHL5c1+QdsOGfWnt1(>I62q+i?iRFkZQ-gk-krnh z6zinN?HJKQD1;(xf!<84Mm%B52@FO*p?2dx>dHmwRbMMRZSz=UsZnG-XPy#5K5q%X zk?|L`FikoO8DU%w0gPPgMxUb!>t$Hno!S(l-?Fb8n^j?49IN&>x?&Dk8>`jkWM!?E zmhVwx`gX6Jvvy3dsU8FsDJ;!DQfM=_>WpkxrDQzbvC_LqNzfhkfB;<|bgI=Urx*3M z_)mL-1NLZ=ERddI#Os}p7CFZ3V~>*kkLtW_Eq0Guxp@U5Zgr2%s=j5Hvo^0 zQ*epaxr_{}ZEybr&kV1L+jVGP_L394MPumOib%kl__SBAUe{^Kj6~pR>oVC5=^^tw zIoCbrzB*e!h+MXmkQH9Ln#-OWxGff$mG6eIaH#KW({1zvyZYc0V`O3pneI#65iZBH zUGtRve7Q9#B``g#Zf<6mfGj4{YK~YX^9bQ>s&w9) zScZ7J*oXpKxB6lf@=IdRWS7Mg?=958sB{9@B+%6RW&(#Hd?tIP;eO&M_U-f?hgy|e z!DRn`{q*n77hO71Ol(%2c=plzPq=lBq-1iXmnwb9%32RTbFceq$I8go*CZb)wIv7N zfLHY*xL5bAzh>1tJX8p*VV^Ap%H>jEdMm~Gp;v~*F;l;xzoltsEmVr7S~}&6Av*E;N(J?GPT)1n)fQ6R0)W?3!P19JrNK9=0d~0yl>uXR zIlSOq(EuogN=|Jq>JMNmDq`|>0&Fb%$i)kw=N4XeSrLZ=U)LtV3*6xB1v_#7HlxD? z#aZ>}w9Xy_8xJW*<4{>w*;`^q*RU&%y(?!Qe!TyiOY!tACws6dNV1a`0SxG2Dfnjw znz_8N@EvFu5Yh(45gFdZ6kz?B;+;w<%~jX-{C=Ltph#*2ZcKkYXp$!`SAj~ zKtZtCQdyRvVBvC`G0k^CwK?X3M6&-e=>BgC`Gb3HLxX>|7?}*IDf;I~6C2>>GT>lS zIkuFc*)_%a&8VEm>*9j`lv%i{;VoueUeOR$b58+%il?Qt=NEF#6-jg@kxp3@UeM0@J0tV_ z0NGD`236O8Wa(S*cDYV-YytnZ%MF4m4%r3H8*g!om-u)-UR>JAEATQ? zs)rn-45g7w&fA)8aEv%9e$ehdE~LD zYW*~$x2qY5Z9}DaJFDE#Tu|qt(x3Sgtvm!J<*%lu{$7u*MhME9c6&HYob8yKs%%=u zb^R!;f+OTAim9bVxFKa;bv;_(pIp9-tm9l2$o{5c-m(Mr9B#n{CVOMcSOad9Q(UkgpfeazveRs z4woxltJ*;MJSmBDPVRfM1EO-(=uww}{MbLl>MaLW|EbgJA6srNp(>(=LUsqyWk81% zQv>}Hj)8ZYmUPCB4?aqgw|Dq~yHE)eybzic5{OK6OXr#M>d(}oRX{-{CH4E8yq!bH z#e(m*`^I(V(yh)`s&`o+T^^>+?@@^W0iv(iOzYLof# zdd(@*Ck@zBechTSmVCU)U8h?=j%~(x*>=sC9*d)9QBpOu5I3CSsL*z|>wD!T3&%IU zE39a%+WNs7KcZgFhlE_&d0^3TJz$BuERQ54TW1H;r?Y*?wkAMHx;JObVUqbf?hKhl zq-#=ur7QszW3b1SdOFKhUR73nn{XJI@=Y+5u-p9VV-U2b-AC)s+RTp617$7N1Y}YK zWaQmDnb(DkB#HjGzRfBHZY0>)VibnzSJonvaFyv$N?I}%_edY%9SfeBbEJ;Z^wI6Z z0GB2|1w5PF{Ybsb=7*Z_+8w^}>5B1p%P*z!wgbl@fm!cv&uU#d811+Jo)a47hSvNFm3?vjvSzH)8V4(kf_EF^V84gzFR*`dps}>aC!@0A=tIO(rO(Z*+t!v60t+0b?D@He;@l2y!xVKvn zYJ|#Cj7$%tQ~z z#@@4zMy)36d1_{EjB_(l0|};U2B|I^Ks5)t=-g~x4w!)84z&$H_%e)|{X_#}9H}*a zd?~*)ms5!wKV*XkkPC`Vvnsueivl_%eQOPnjit1sAYCAtsTGi{%q<4UJuel9Ue76E zR`H9Nhy~?DSIl5$-{%$73g*`2HApz?d{*R7lw#? zQgY?O9WC}4`j+TgtBPGCE4e7e-1sw+sv(a{SAKbW@REJeYx=y_MJ}wNfU%}2|8~$Z zP>hq|gRqqGqKzOyeu~C2&jlrwPp}s|?=bR_j~QNhf!D0xC9gy-tOoV%L5CJCIq^Pb zf9eG-bjajaKFmIHk=pRP+Q*Ulx}Z$X`w<~3u2I8R?)<(tKm9=udy(dFA4s28hmy_{ zUBt=&>d*wm28p*UA1;P$H&LwE&PPu(JLD}QC^^g(Kj0_!+y^2=G@xIrqBpn+Ff135 znIM_%@Gp;@c47BUC%wW9^GBSUswc+(`{`dMKm+xV$PTZHlIAe!=IbNAn@(P71}x|e zv)%kqPC$Lh@cQfa`ZNsQT$d2-SOd z&sJQ|U-bu7!fEUHDq3Zr*rFCN0O7w3uTX4j_yX{LiHHPlI7-!vEE*Ftcpeh6d1|lq zvymLZ+LI)Bsnu_n2F^2jt$n1{Y0Bi^UcpuuoHp*I1UlZjj{RYIJ;EyGZG@MlVN#Cu ztm(t?hPaWQ)(+jkm-*9rkb!aOvQkzf^CD0ZbYDZG(^^AuGwmLSF0`csr>Ji6yhSFI zbt!r3G0aW>zhb0D39ZPRoIjZ~YZKsV>#Coq2Gcte9hO$fd1V+E{8g3_d>^ zG4e~47Au)=PN$-koPj9Vuw#5atO@5=^6k%|y+eygF}?0r{rxQ+3ey&rQT^KaaA2aT zx!FETY|yA{eDM~{Aw`m1C#R{s=t#qxFf^rHfm%{9Cu)6<$GHFLzW$#l?z&DLu@`@y zm|iH-tPuT?;NL{!iNzYm&xTDcCmy-IE=$d{p2*v^m1Yb!7ENd;i?+SX#a#aCA{nfp zbCFzg8;$an7A%X^k^e&l4>hYoE~Ew=p9ANGnn!`}?Otxmf^O8DQ$~iJgWc=r7>$Zb z^!V5TTmX_1@iYyzNxc<@Jggd=T_nhF<)Cio1&K0a#E3 z2cf#|wF8D&4kqLa2KI~0Axp>kOleY1K$lB3KE%dsf{wRNuRk;2OaVef7i3>Lhd6#- zV0H&hkU~y%^=dvAPy5%e2lIW{f8KVXu*xdZpK0{*IvF9fB6am{^MLi`@B=|5lvCcK%Goy1o&Nv9Zwe{G(~Scv^}n3Lm6 zOjk)wy;|?Dj{DQVE32f|x4gSp5=Jo~!CU)n=A~7`UY(odNvI=2yo=>bZ19 zgN}Dy4fWc_4$T1K_jN1ZAzkH=wI*km^0L00atvN3zRGhzt`k8&o;L#cae!)fB1WDi zr|Xn^+-##&w?)B+C_!i2pxMzG1=Cv2vSG?DbV_hN!sPAU4kjj7K7NF)Dpr4Uy-`mR z&8`GTayPk6iL=@pAG`NlT4!6{ zb5X=f%4*mJ<3l>eEp;iT0?_3l%}EYTye3_-VFSanCa#s_Y^%w{T#Ip(npb~e9Hu7c z)>~^d)x~W^^VaU9u?Q-W2w(Yo;yQ)YV0_y##AHTGr=5jJVk%$Ogkwv84 z`Yg`CPR{d#fMt0-Lm=JB$kmMy$;Jr;X?uRnO*WBl4y@ z{sSJZ<-JKjQ_Ls{F{YHfgOas3zZzH^x&_@g4hnm+j<^3Oe@pUt?CiJIHH6fCU9KIa zO*bNEhNePdyjTcUxV*^lyuQWY82mM_2xSB^yBwKa>#LE{?(nXP(rT9t;dow9q$o3` zxw`tixft6bUW^=UM>m;XL(qpAVS%nbJ-ii1mE+wjRn&}q9f^s!0c~%RfP&a9U3s;G zOj&Yq`{CIy`$yHwfnUC!S>$#t)!02jjW;#0y#Y-{;AooGszmS@&ldRd!hw0t4SG#4 z$@BHX`e$ich@UI$=;BGE&v_GO`hPW-1-sVqX&!1}ZXR3cG!*u3t{)pi8e5WScbIrs zDN-ZhzJHw|f#myW^_>6Gyp5&_E$Q*#&ex_WZ!d2IOqInC9=+=Zw(3<8B_%=tOsvxe z3&ammfmf=@>(0vX?My7MerTBQd|Xs3H#l$}-3_^q22GwW^%CmZldubqy_ptW@3|It zckrsS$f0AGbg}NJ ze^8BO2^k}+ziR3?M&wipc>B7SR>d*|v^?CvCk-05*ySOEO9v3ogzEJ;$W7dk(d1$P zTqklN`;b#2wAJ3$P_SM;BOfe91~-rkybY zx-2dx#gkT`sr8XkQWTbJNv8D}nYi)2vPFSs}dd7;-&j<%ZN0^ttQmk>q`kkm%;fFdY}r{iwXi zyCCuO%SIJhXXfL6QuES3^s!%9>lV*S63o0O*DMlur&zu0 ze^&F@E`bXH5N$YCEW0D;g&s(v;DoW3Q+dpr8SQwYe^1l3RG7}=pC^I?#Pfpmf7R?n z?n{q>0%i+n3LblHGd|sKk>8eUo0WHlh zbdecVxiD)+GZ3r_u^@P?xe$wgiHJEVU4GzPpc-C4bJV%lQ^Mno*)Tiu?)}5>FVBdf;{`*pWD=<^a#=s&!8d+3n{UyqoLGq< z(v2?|)!TR(;LTuRm+O_2Gp|L?TMF-Rjm;H`(CdIO88yXCV_xVCF@(-E8g;Kh1NhOL zw=1?8>%DG%?;bYS;^{>}4W6}MQFn6#zm3N(ju`URM&gYyMRu>6?L~UWp&8&0G%7zm zCoh%C+y}9l?m6sP>W($A-llI#ks)|K6u38{qLKFU0}cFOw6<_&CUUT1ve|stK&lkVRLAACCh@WhW>?wSPOjk{k{?~;X9 z-(edD>sCR?A;7SkOF4b4vXQqO+~=g(@d96w%1p)%)PbY3fe<6xL=o`;>l^4islW-I zqv!GLiX7x@Z#`}z=yX!uCgm}>A!5Gkn_rZL!Ny1qC+n7dZ%=n&%xboPI3Yg8BsB(~ za#uLu3W}(jv}dY#)L`zbJ}TX@n2fP@uU?OA+;aZsuj*w3Ex^O8U5~)SE{Uo}3?Kv3 zXvT}e(b$~)H&J_8WPkCQr|Zh7U}cx|nO~0`fOx$a+E% zm-;1r6E8FHHJz#*qt&oiv)u)i2l=-`BUhU)NK<4j6GJuZ!DG}yoC@Tw%c&30Z*%xW z$TVHo2s7ltX%yD^)V(0j7JE6axkQ<0%g@K;5j)7i9g{F)BdZOtYsE1S6P&JiSzss+ zt|z-3)iF-E@x(v=_3*bVgD$TfnNda|MgRUgN%t76-zul{q?_A9zV97Q;(mxlUbyqT zSCJNfuWA)!cg|0+do7_6EMQ? zc0}&Q#intogr*)Xcdox;9-gKQ)*uuizP8oC$}x&#fLY(J%Wz1im`SIjY?DSp5TmZh zq$bs_1CQzB*BqgAZ&-JxMk?k7aJ?u}z#tfbDjsc}-kE!QXZ6*XLtj>UV2j!MRns-T zxnPlW#%g#y{WZpu)amQ0nUrwd%K*O-nlF>HT$4*p}q(pdIV0)vy(VmAj*c zZ>$ns{VJ-zJ~q0`A8ILtk<_i~*e`X9dfeG?bHb5R8VWi4#Z}x5Xz-P8@UG{sK~X-@ z`f{ZQ-#xYoQ-~S{+>&-5YMvkKn-X;nLzYUDAMCJECQEK_7xr9uMuLD1n3clh;Z3x+ z{-i6qH?*;zjr^#d3q;l&R*Y}7v#q8wJT*0}+oW%AL_jVEWMi|+i}PIAhr_NvPN|%o zB~9K5+T!+UKcMwPD;*fsSH35w9o*}B){iXkw|1y-D2b;@Ly17prw$sAq2(-#0F{{l zl_!=*&#xtGu9X8_y|v$=!Cw+iIBVve~dw$$}c6b#-B^LAv6WE!kgtQMCzPp=LMeU~HD?*EJVH2k`TJR|a4V zBh{oz?}F76uv;p(*-GWz%#X7L;WOKKD4(UwU^rcS0mC2X1G4KyD;1wj>y_-a)b5-q zKo`nZhAIdf=q|YHcJh^tp0vArPT5*!Z8xG7wpXzniQ3rcP*E=%q&qZ!8#`&>5K@lQ zd@rrguYp7x3wTG;_`!l;G=k%q+bn zt)&X^O702(LwVv}icsDs?h4(mfrb5ZA(Nq2V~MvjUR<2! z+|=s2)%_REkFJGiugD9|M0l9j1ZA163yaJh9l4hsT2G3Kl+ibQi0IOc;qv6w{19dl z%MR_b#<)C&APs)cg2t++G3d5pbReAaN#;uxOr&kFgP8B__~!9U0`R1yYuQK%q)tJ% z=cSGSir+QEdJ4dWd!J?28d+T~Y&;D4(v@2 zbt=?5Vg3s-H+EPb164M0|5WLJtjGrGDOjHxDBD%WrM!YxBo!3QdT3qd!gcHuQ(#xu zOP33uxX~xZToe-X`V zJoa-#Trl@%KIA4uckT?hDJ4=W(f0l3Y(=5mm{rAs!LLAEMV7H+OJblKK3f{34&hrV z@q80v2XF)G8XAvyt?T&$Kf3ZxGv*hX1Gf{-ZZ*Z|d(J2xMCIzinUNEZc5iB^jdABj znfEte(CX(MUNDc)Yw0&=m2XRRlwATm5iaR_^(6~bkjBH;k`3^vjXVqNBw_-ZnxHt4 z|4-pdoO7~9x%G)GI^>0=B6lPzy(_Bg#c zFEW4k-X!z`y2FCKj*Wp36p24-A!TWi83?q>rLEtt4p{y zD>4YHk>c1yCc8=LmTFvm!GO4kN`xJQWl{`hmS)o|EY9>@lX!rl^;oqmN#G+DWvY6A zu(}fx*wPaLHTPxA;_aO%^CS?Z46l`^b@Sc2%802xKCqLNYiX=)ofc-$E2c{ z*4Br|!BxT;;~DOu<#Jy|NWy-V`8jjWzw5t?Os>e#+52`1o!facB}DcW(Hv)Ut@gR2 zozy)c;&6K1YL9IC1Bb$uKHdk50xO3+=!jcsXNvgXm&M&D;&ZMJ!sqc$6%GiP*&M76 zfHz8^^QEKX;1WcGWNF9(F45SyEljb9S9cQ}tBNr{IU~fuFWx%2n-)!%678&>IIO_% zb1(G_Vy;QvJ`nT^E$T#amxi+Rd0R^gg0DbzR&G)&z^ZzF98(qH{IEoDsEdw_ zPlemciK)|5hfN*qjD50JcTT#qXSskUeOn#sxZzP@j@=5>&p?~AY6Ub=*PcOuGA@Q<--~y zXa}C^w1cw^+b6GNjObJyKj*OrA=d92hrsd8pH=rkVRt=)faP8^r?3DI#b(hfml`bW z28s90+yyFAl~6*jaj_r$i)>T~r0O7BHKU16S%(2l8%;`JmV+6Gc8wPk#ZYFC_Db-V zb$tkDoHD%m@#ty2Tj;!Xo$(C^qb{C~iy0b98ac!i^>%x|sqFAXoD=rU)EA{UvJ7q@hUch9yE37P}%=FL}eo?}s`@bb-hR5#NOetT`OKpeMj^mOc^>t;QB1SEm zj$?@5@rnJYX!Wev{brJ2Khu07q99f=K0Mdlq@qUicVc(}!Krl0R!@_^;Zfxyf^Aks zKkKX@SU7xv=vqZ9*&QA6V-s1cL340MC$HZ};YA@In@deEo?^T_CpfxZJ?TxGKr|!) z1@w{-O8H8`$)3MuMVtUq6=?!oL!G@5>EvcnLbsAp93mthQLGK zgtD{Z8P%Z9D?^{`3xGh%q8xj0Z90w!Ea63jfp~PsLO$r|!c(xbtcP$LQzKcE>L%?% zKTxY@Zq=6?8SyIBy7M-V#4F%)f1WsjtEg^_n|vL0OWSlyW|t71r#=D^`gx+gDm7^$ z|@6Y*GAn0p7Dh!yYcP*_cAcwDkWc*;dl1k>sZ8LmoA`Pt8sPS$ z!pnF8yJJ0(+6fICHtB6i%*5ry7{{!}Y-`DzD;E9j{pauAp&4XM($1%OfxUDEuZkPM zHQ8OB*QDIVXY9F$cOa^qXEsH^*5=b`mI&xrB*YE2H-*}zudhBgBWu>arF|PUN61cQ zTD?b=bt1;+(FZFO>U#FHPr->3z@xM$OXZzO8^^3CAF^L{`)|J9yR)9)w?A@j zr>Won=ZUcohi$~4CqBJCWHSEPt3>@g5g(yY8${a)L?5|N9Jl?7T3me5QgtBz24ydf?Jc0p?jx8%G zVIDB9WMd2D_Tp) z9XN=MJcms-*tOvJJZ+p+@B4eJb}EB!f5(}-cMhCcxn(pZvka6}52$<0Sx}he^x1mt_NbP;E~2ae z{MQFb47$A`p8|#W5qfsA6qn&`#n^0vmOCJ_6X?l60x{XRfC4qGGiht@D06IEoDVO) zrN_-?*G`PM25_4xN&#q>zYSyqKZ&bLzDM=x4*Pi3Uc7(f*?jHZ=X-0D!YY5q1k3(f zHFnL<=Bm#=>v3Pb^O@x?_sZ)N{X0mi4uIQ)s(0EAJL7irsRuH}2o*GTRiYMWao?pu z{R>U3@Q!xUf0;0PG1o3L$}k{Tf|pLhtKxFjRv&9sgSWahW%Q{uGr*vZ3}5kjMckm3 z_iNGn2wj~3Wz)c9Hmgx+h*myX}Pt!7RZcVU$|gTDex z;yBWKVsV@|Vygl-%1N|5X$b6_QL|J-IYdg{QUH+^v@6tqpb%6uVL<+mK7VW5u+DiX(3m!<4fPJ9;v$ub> z_=`S;5Aj=OE;6;*wrU(9o_Fh2wCr`Vzgd`iob3l2(-DqEJCRAlPGeQ5CR;nFn2m0m zeNMMX21jF+mxczq1YJP}UXFIQhR`x^!M=`>oGUZ~_n!21M#y;$9_LGQHgxb1^IgmV~kY=qisa+q71C@>H*ov(G*x_-HHb19LZA@s0jx zJJ%W-6--pSi2=`j!&6O6mCq46ZgLzumpaX2cX_&xH+*f%@2phxxpMo*A6$B(KPMHZU{#m%vi6vb&tk}I_;K6P+HBmBvW%}0NvW;=GM88}--D}=A5i1Z&xhSgQV zfsuHU1wh4XdgC5x%gXggdiNjCYi%F&LV8uXTb#y+c&j3qPtL zq6)X{zdS8{xH1vCe_b{DNUV3?6&A-yx$X6RRsFfzEB{r{iAV=~`P@AZ8 z)5lrzx-?;irWZ(IzxR(l#5n{@pUoMPcM93&PJHyoOqkMFk@J^{T~?#Sj61PzAr0{P;(P(P0QDe zQwjZ*u4N65AroPSon9W@)U*>M~_K%!p-BAtw#x%y4Gkn#Fz-Pm@Z?ee&rlDf-` zg#U-eidi#rYs-A`&2POLu**Nn2=`@gsm+eb`}#~xtS4X8JC_4Kb)4ex>aJlDHGnjn zdv1r(Hm^J6IOx6-zC7NM57|<4U!Fa1Rc#kTwq8MYIc1Kr=h^eFg~)!}hXrX6z+CA4 zy_^?TYhPoF7V_kH*SWQjG(BzFQ;pv!>AT_R_8qY7kA9rign=yVkRq+!$HDSD@^L)=;5c;nj)_>(kt22IWBMPhyMzm@x96#jYaLg< zCjOz7U?+UDeJEO9+^5WoQb5NCM)4i$f*2~GD;w*ghDe5ihw+s{MjdH*2|!sVrS9&i zD+z|sW!_rh@v9PXxVSl=@<##Vl#D0|^8On!oonaDWCBK`gq5-UL8YTcXhrO&vM0_z za>g}hHZSGvxxegR3pzi6YLA&!>}7UiHD=P^v)}vLynaiS$iGESTpQQMdzCvfNEPx*9*L;2?kQ0IMYogqEFkz3j?Zx3pTS3(a+Ut^rqw_OEoSfP*=oE>}5 z>S6HUkP^nK((lSXa?KMx~2nXRD-srf4Xm}=<9 zTTfpF4RQJVf3zH62`Pb?P`%TqQ|RfYtL)6{gu?1CcGjH>Tqoa@+ ztOWz!T33}A!rJQ~(Q3H4dANaCn@U#=5G*d0rzbwdTC~ce1hB;~bW|jMzmz&#(H#4p z@tf6e+U;+x(){>G`45C#f1Z#-q~8CxF5;RrQJ0kSB*3O~bs^pn^&;yWbXsuI<5~!2 z{&F}$tgG3*jIeF04DK8XsRF+jv=*2y_PO}XJZqRP)GnZ%4kS3luQ`l5!0(_+%ALNr zQSHKqzEVdP8Iod*k|B6KAKu8QIZtKYCbic-n0Rtnczn4f&@}P-M-4~KN9VC$Cq6;g0^l}=jeg_5Gr+VzgaW;xw|pVirQo6 zfjmd+j8h!PSlP;KnTWTNh8{ooG#7)A+B9h*XNG#v#Kj{l^Pu>s2-RD?M6dW^W%>liQe>9FOIE)oy|kWMQRMd0L8mv(an>KK9t)t==VJvmg|BgRhwY=!mV^s4YC)Yp zZhZby_Y$Q&RTiY6ujipz_QW-gBM9X+D^WuEl(hK()SKPlL5^O4g<{;~eEfPTR`B+kgQ{#4k!nG{N!%)FLTy{R z2)Y67)0}E!A`Ok%ZF6qyO1Go*3M8DZ05haJuUF(^d;yvF=Cgl<}U+vfIb+fUslRuM;=kuiMu&42B(A z7k(LcyU<5$n+#orCOHKB2wbVDN~TWTNAgT-iq5&c(wY1My;d8?Efld|@c+X;*Z=jj zGw!Q*4%GUm#@;>Ok5(T)o_?Lz5V~&=a9l9^Y*Qmo|ZqW(Qw$cV3TY+Yk>nB3=KFm;FE7 z8n>&a6igXLI!^aS3!Ccou*}INS*dk9RM`rRIja_3k}ao@;Vk@zAghi?1tHosHq^LS zOrU-||J*vB^0aqHxmUkn3mSf>n$gp&$5Wd};@~g1ZCKZitfT;Y|9TRo1UHGH*b_L} z68$Vg$HN9=#}byq>_cTx*X7yfd7j}JY~4k&A*EtIzBD;;;`{}6(vIg`*phf4ufW9O zuMLXWdGe-lP2=M_MfzN+;Y;4bBQ+iy>ZHkKYWEMwa--B|Cn4(cG+pOpOq=zhO+J&L zLj$+Z6s4zh%U$bGH&N_yOF7bg^)cODIf{C_0Rk@X!af99NCz^*LqFF)FSl(5&uo>1 zBWO!q)jMf%ivznH6V9N$+BulUZT3pcpoTb#8iUWl&vlO=OL~ge^3!7+(sNj08HjTeT3^M1z+`3#>V8b1FZl zKes%UUFVL>*7ZNO4}BA>aC7HaGCq|gEZ~!_HQE4A=(Ww-%Jrly9g=Haxn{H8m*58$w%*c`~ZCX{>ivw)y*r z*KfW?8)QHyUgR+y5gzmVn)xp?OhQ`g_U?bwVv-of&I-n93AvtL@f@3z-xG`m16KAb z#vW!1ej$c^u7Qm00;>|Uas(9u9a|o^XhrE)A}FQTvKdwCFwzx_qN4rKhw}tPzPWVD zUqg|;N#Ie6a;OEzthDXZ5OUp+z`#4i`uat-v78pX6qQ~zEb-hE6-c$|;|E&4nX?<7 zEe0v^wpO9S!mL4V7L`0xO;2x5lE6Z6Zh zo-La!(4l-LLuiWor3wyJ(mkWHDAz6YKKKG*>N2ChFsj&?ko=jhcY)-E7n#Ro&rvbU z^2QiNIj2JJ;^7OTTjw6AOvydjt%*h{$f`GN)7;9a%StKgq@d;FEv&hY+dw)feEs8i zwfWEnz_~QE2pwvNe7AxZKbVSrd<8ar%U*To(*9Wf&aoa!%&=X+`TP~lI;=6DgR-8e zxO6V#h7aL?arT~HO{{&`w)fuKUXfl^sssX3LPu|uUJVdRLO@C=2^~TQ@2!H;f(cE! z0tt{1kN|;DxAcxcLP;nhy-P<>_LJu?c;EHR*L;|@CbQ<6`CaFE9LZwlCdN$UCED(& zI4(Gv120GbBAIXZat6B~xT};fndbOR^_|J4B=bl4`pyA4|8b;5d0kv(PgN!c$rfAAcCD86EFflm3>F zUE++iiA@Cfl9~WlASuW(%|u20>-NhQQ`BaT%9!R&k>3? z;w>;9z@uy<&oAU}jFnM;R_viVASW9<+^FXs-YvL4^B= z(;z5UOkD@c!>n}suGb_NW>iUJPcjGz$pE#VpN#HekRc{qUk?YOLP7d@U$1+R%0G|W z18qqN%?)z83agyMyq3$ye(D-U1Ha&;*x6ZiCZj1HDbl^fU4g5}&&8%M9^X6^Ssidt zB|w*N*<61diZlZ0MP**j#C9#MaOqrwGAdg~6W9vYM%Z2C#4JPSujfWGV3RjL#y*uD zT)rldY66`+KXWCOkg7W>f-#7Tvl-Xck@_vBExJW$lhwOM+@pqREWe=XrO3K1j+j)i zmkEMdHn=4B$`F?^~h8#HQh z6YzD!lHPt%IVmS+^$f&&CA}`ssf_RJ%}tt-Up31u+kJFo?7uw(q-+4KF)Sf0=X0Y% ziz8U;bBhsl*>AwWWX7JT4kXg9cQ(bDV2oTb8kGVT$b*-lR ztAC-4B^%ipG0PfDN=;01*5;daoK?4KKmSCBa)Lc8?v#FB-3~oj@{D5!gWsNCjPz95FmAh(WibV`g1n=-wV#czpbU@Mhez=-}qJIf2-!m_f}*#i4A@_#;o-P zyIzIoC?u_fH(|grC<;qmVz#;YbdayWW(ecQmrZ?`Ak}yQzVv zuMePGWoU8l*AeL8^e3kCEx7%mcWgT!9ndY@KmUEK$h~YbUEU}GDZP3)-VBj}ZA@#9 zM5+8JC{%k+Tl+0fT&{&mZ)JpkFG5gyEt4{c$*JbsDh*SR=S$daTj$Zux~ycBe_Z?* zYTRhumW)Y21JmBtUIG&Am&JgLAh71k`nhmz2e4#6m=owCLz^Zx_O5zm|hneg0%z)s3lNd;`B8**RjLk^aDIQ2~bleKI(3ifb3lMtKmuy#F+ zT{uETTUBmX%^so|$2qymV3-Rj8ptg`#au-K9=uKXNGSdrjH3@rjuqK+yIBV@$VgSn zRJjdVTYp_pTg1?6cBcP_7*&ij7?^D`g>CN2HE+|%KhBX3L&=8+hO`e@;8SHJ zlk#8&px7hFhD1kyDSU9jq_3b8qabZC?@tu<3uMIH@ zxDH03sGjWFbBcJ5f{Oh7&?YP)>T#XpzD&u{FoREjV&dnlDrXjQ243?~Qh}WFx*yPB zDU0~rGmv#!@sv**81fnO4)CSMYP-^B*iZVi0P3hi z>H0Sek>y+84$^MJK&-JiOM~Z!Q+*&@vA2G?UvNTlhKg~&)O@&g2>Pu{c#R%6RZ5}j zMPO;8EgtANxfus6Zv+5MP%uxjpq6ohC38Hjb_#Cyqo^NW;~?j zQsZtdKL49^G_=5McG+kA`VVs}8}`gUwH@6yWfW4s+Vin?4G^&$P?J`-PW`9bwqFFA z5~bv@C7V1DB!Rg+9-wHTj5XtZFn_6nxDzv`!IMvfYM{o7Nliw7QYACyZu2dcxE|Re z?g;~3nz@C#4c~9oj?`|3MD#Xj1)mp8U_MIOvz{>zyMb*VC2HUPiEaahmkd_*!qqrjLQJHlZS6nwmAwVn&Nv zwwv%u#t%S}ah5HBIMJdkMQxQNhQUQ90LcrceC-R>(0;e^AipR>|IjRBu=}w=F;4Wb zZ;J0^W?)&y_R^Epe=jsqReVTw@**Jzr!?QT?>v)fbik5a1~~j`k`XD(ZaNT$s)vXA z=IQk=s4G7+AkDziUm{lAE!+AxUZ8b&_Htq-p-0x%}h|{ruZD=KJIP zj_~l#8zBv1-d;25uN`M*#iT*O-tAX;6T0fQio}bZRP@2Q>AU@aEdlX2HIOlm)a1p@ zsPwJU9c}+wlA0lXLhfdm9+~|CH)!F~D7HYe8r?k@`*PhQ)jjNfg25N%t4j8Q=|hB4 zV=s1?y>0R3EJsajkr{NY_Hj>sapVirqmP_HrkzNZ$1vwOjVi z@g#qqy@(}!cv0`@&=|}FrhN}v)^D^Xp?g&FDcjAsnMBID(y^7`Bwov`!W(eU}%w{j455RBIia4(LGA zt#qEVBTyt|Gb}U*wp+8P>)0n;)5Uq=uS;lNd)wcZ8V+r=#tDpbnzSP0whc2R@Vfht z^@nxjRWjqS;#JZC3wlaD63Nkq&Y)47F@Fh6Mh-Wx0!qg?2Yr2HF?~C+8QFx|`XN;b zhqE)yFl%dFHEILo<&`Gkj;&3EaUXp(g3&>2slKNgKQ|x0ujLvV zoaP-DpO_mw%N%D}M!m< z^jIgUq&Rs4L%pmC7p>wBEd5YeVk%k~MOMN3PY3vDka%xI^zp1DMrW(%&YUgkPYTy! ze9DIW#Z)%Y4L@&=5t%>itrK~=#2UI!izCq-_P|E$MdDcam?Sn7C|jt z>+YuGh83l$7#2o5R~_5iN}hY&Fqcyj25Yo!nDeI*}_uZBQn2wE=1=ly?i>M8EXjW+I~L*MdRy94(kbaYofQpLnxfAs~y z$J94=j5e^qsX*1U*{zHN7Bg{XX*P}iYNXDe6{5lOS#*AvL7SoSaZL~4@WU@NDMi@` zerwsq#CI8Tsbuuac&Qq=Q7Axj0E!m5t|o3>9-79Vd&M~+LhtXSDo z79$10R$QYRlIk2BgR!~RfW>|%F`*-3ZI8?2H!oNJOo>SgaXK@?QbH?Vjsg9qf4@Dv z`(gG{%c~dXBlR&=aRM8NpB8Jh-wVR$Kh}dhccg!Pn;+X2d9n>n>i9w1@BZ(<7kpa} zkJ>{|tK0=mE`2jUE})y3DD=uEbr&rW?)!!0PK$8Mq_uau2UZa&WFac?`7KA)_c3|i z$nx^c+kzu zS)2--WSX%(d?FDlD-BW(`brhAhWE>wGzD8hXN4Y{BP^8r?FATFBR5I5;u*hoN@H>V z+oZ2g|IpA-tnovFi5fIjPUD+uPs*HAP&968p{g|((K*P7a$>n9okmZHepP>ZF+MLU&0QTp6feUq^% z4;v5jhSlJDi|)nZjxCWQv;436Dh>M`HRgYb|EPL7ucG+}G7^!Y$%wl~gf?yo)6#4s z+xivNlWDS=cWTp;TD$dJW-1YhCX}rmIw{) z4Cj916lO$&hdNxg61x*A$b}?zk_sA1q*Z=gxR5whRj?EK$B{lV<$Ev6d&6Mm(GdGi zP4SX!5B#<(t%hRzA4b2A@0)v5^QvEVuvNfoWOh2|<;TbYRQHcBE;Wr&yexfkjdfL& z_X4JXbcUseCqyzITkDuJg5tFM45X(8IN?60U zrb*3_igDp5s~`UWMYIm8|Gn1T`*zT`fngi>&nI6pTQY)ViL>l(Y3#9|pX5qXq&j4? zWzNipEoP!@_)*uVLPK|yEh*J+g)eh`2!cVvNT%}+tXUatO;2cS?f!ijYvIaphtM)*gwpOFzLzCq*r{OkgiwaIiX$inpaBc?Y6}$@5J9+qRuk!gi+yb7N9k~WU|9C>{M z3Lr~w4Bg<{x;h&&4|8e`%fV2xZ*sTRAW$uH_Ry=nD->x62@(%6pY#p^d z{7DjRVYclMg)~yjF7Cgyic0$)BGi98t6RnkizKh_oNfIG~0YXw16Nr*>QQ} z8e4trp6Id_#h~#sJ^1L@*(%Zt{x-;afcHL?BA}%2v(+_^$0?6PR~`+%PqwTZ?KPM@ z5S-#$ZQM3r+@bVJt%6(w(=3OEFf!5Bl#KDy@EpChiS;cQp{7y7PV>A42J|a6^|9)N z*>Z8xLEJ(KpPwH0SI08#MpPi7^3R*6b3CeNZU#`(z);3$4IZTQ_}_DnM&#@JSC!`w)YW%QLm1(nsN(2hY?iyaeWH`{-1wvRNCoE zLA3iw2W2*O%C9j&_x|(8kaT%ucFUpE&1t!H^V=ZPCf*;;mf2#)t9=pIloQ4-Y9hBm zhg^?rts&Oq7F-NDRJfIMh`148#f_1UqZ=uynzkhS>=q*t`v z?606+_67bTICU4WYkaT~^1?OihHP?`reDa(@mS`a?*)>IKCK^>)_z?!bFW8_s5=R5 zpnkpPecw-9(i2=9sZLe$7132mqI7K-D1dWGNBxaiEu+m_lSUws^d z_6-_@F;qy|*09#}9pL)nl2*C|x*f-(KBurFchKX{PXn-p>pVO5DTln(E!X}&yO z8yNRx)_s%*wOmFQr~{8s77*W7%o#{~Acd;_puE1TH%~`s*LXtF@MA&-wJJFT)-PSA z))A%U=GX22DZJuSEv)>gx4;5k<_m@iS~7y1ZYt$=lm`2`5c-#*K0hVqjPtus>c;es z)qRf^s=uAGp~5_OHKX<~RlX(h=cRx&arSxrCbF|-4L#sgk4Fi2hPDIHL(E4B-m?;U z1y6zH5Jj;o*jmZ*`Ibw zGXaa~iPhDB%vXc_7n{?Rpg9mJ?kZqZwRw7A-|}WdFg8_G_gJ$6<$`kY1#>544R!q> zC0RA;jgh=E&jKTT7Dm)D24a=Di{SX~);528-m5mZFPcS)JB=DOnY|+(9cN65FmZSN zMleavd^wWu*0cbqQ}esEN@!gT-xM<&I_u$!W&^$F)$QoUf4T!38$W!0*6|oWjqR;dbQeN_5MP(Bu`DSP$ zN%7cXAHz!9JMrr%dO^$vnSKs+O`4YR62vT=#=q$(7uUC^I5sr^Z14B^CIt_&m@s+H zOjWRcVzpxxww~@{{;=1m!8C#+6OjL(`s*VTgEBX@Rhs85jW$qd*#r6^L}f$hIbIJW z+zb%QP)qkB0*74;d+qzAD)R;wU`D;P(b3MfOU=#C;RWIiFO5{x?o$=*UnCHk_hc=H z!JV{<2=OZGT1bVZ?F4n^4yscNkHtu4p;X5CDsQI#i~Fx^DFg1B9>zyy5{#o&-AOG} z&K**AH?6SREVX0cgRbzEO~Vwxsn&GMt^r8j0|~m@+yohnijbZ$@ugB(y`X$-%2WSt z|Iy&}b0aSX^@w%S%VTtR${uXwPgU{a=5WhO<4z;vOwq&aWFcF6W-qthy4rwhs$U?< z9?F0zbX2&t!k~q9ITBE0S9_C7t%oU!A}wn^?YRqfu0f3{ zP^UVoV|c9V-K_1QzP+SQtwLnLkw)9`twQSG#QrNM{ za&P^r>fYx^CH+DK`(-K9?c2Y*)y*1P=1m{3KMB&Ft9@MiJ9MhKbz+A&^%#EmcBT~` z-Ov2Zo{UE|zny8>IQ;j*^m+Sc!FCYrTmM@O&ֵM{)QFFbAt!rkQbD_~Tx8z%5 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