{ "cells": [ { "cell_type": "markdown", "id": "2d6582ed-04c1-44bb-9dd8-042d46bd8a7b", "metadata": {}, "source": [ "---\n", "title: Executor quickstart\n", "description: How to use the Executor primitive in Qiskit Runtime.\n", "\n", "---\n", "\n", "# Executor quickstart\n", "\n" ] }, { "cell_type": "markdown", "id": "b91b019e-f1d9-4a7f-9c5a-68ead8bf2a6d", "metadata": { "tags": [ "version-info" ] }, "source": [ "{/*\n", " DO NOT EDIT THIS CELL!!!\n", " This cell's content is generated automatically by a script. Anything you add\n", " here will be removed next time the notebook is run. To add new content, create\n", " a new cell before or after this one.\n", " */}\n", "\n", "\n", " \n", " The code on this page was developed using the following requirements.\n", " We recommend using these versions or newer.\n", "\n", " ```\n", " qiskit[all]~=2.4.0\n", " qiskit-ibm-runtime~=0.46.1\n", " samplomatic~=0.18.0\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "e82a5b3c-eed9-41fe-8940-e88838101ca3", "metadata": {}, "source": [ "Similar to the [Sampler](/docs/guides/get-started-with-sampler) primitive, Executor samples output registers from quantum circuit executions, but it does not have any built in error suppression or mitigation. Instead, it's part of the [directed execution model](/docs/guides/directed-execution-model) that provides the ingredients to capture design intents on the client side, and shifts the costly generation of circuit variants to the server side. Executor follows the directives provided in circuit annotations and options, generates and binds parameter values, executes the bound circuits on the hardware, and returns the execution results and metadata. It does not make any implicit decisions for you and gives you full control and transparency.\n", "\n", "\n", " The Qiskit package does not yet have a base class for the Executor primitive.\n", "\n", "\n", "## Before you begin\n", "\n", "Some of the code examples on this page use `samplex`, which is part of the Samplomatic package. Therefore, before running those code block, you must install Samplomatic, as shown in the following code block. For more information, see the [Samplomatic documentation](https://qiskit.github.io/samplomatic).\n", "\n", "```python\n", "pip install samplomatic\n", "\n", "# For visualization support, include the visualization dependencies.\n", "# pip install samplomatic[vis]\n", "```\n", "\n" ] }, { "cell_type": "markdown", "id": "9112ddbd-7101-4cac-a53f-5ecf492bc8d4", "metadata": {}, "source": [ "## Steps to use the Executor primitive\n", "\n", "### 1. Initialize the account\n", "\n", "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", "\n", "Follow the steps in the [Set up your IBM Cloud® account](/docs/guides/cloud-setup) if you don't already have an account.\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "c0b08867-a635-481e-ac4f-52359382c94d", "metadata": {}, "outputs": [], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService, Executor\n", "from qiskit_ibm_runtime.quantum_program import QuantumProgram\n", "from qiskit.circuit import QuantumCircuit\n", "from qiskit.transpiler import generate_preset_pass_manager\n", "from samplomatic.transpiler import generate_boxing_pass_manager\n", "from samplomatic import build\n", "\n", "# Initialize the service and choose a backend\n", "service = QiskitRuntimeService()\n", "backend = service.least_busy(operational=True, simulator=False)" ] }, { "cell_type": "code", "execution_count": 2, "id": "ec105ea7-d806-4333-92af-2d7c578c67d9", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "print(backend)" ] }, { "cell_type": "markdown", "id": "89c4ffd9-acde-4b1f-8ada-fc39b7a708ed", "metadata": {}, "source": [ "### 2. Create and transpile a circuit\n", "\n", "You need at least one circuit to use the Executor primitive. It can optionally have parameters.\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "7671b4dd-b031-44b7-bd4a-48dd39fb93f4", "metadata": {}, "outputs": [], "source": [ "# Generate the circuit\n", "circuit = QuantumCircuit(2)\n", "circuit.h(0)\n", "circuit.h(1)\n", "circuit.cz(0, 1)\n", "circuit.h(1)\n", "\n", "# Using `measure_all` automatically creates the necessary\n", "# classical registers.\n", "circuit.measure_all()" ] }, { "cell_type": "markdown", "id": "127d6de9-084e-47d5-82d6-f2197c0bd74c", "metadata": {}, "source": [ "The circuit needs to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). Use the transpiler to do this.\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "7a98fb20-8731-43f3-a81c-fb2bc8cba9db", "metadata": {}, "outputs": [], "source": [ "# 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)" ] }, { "cell_type": "markdown", "id": "172b3622-adbb-43f6-9cec-b70dc72094e0", "metadata": {}, "source": [ "### 3. Initialize a `QuantumProgram`\n", "\n", "Initialize a `QuantumProgram` with your workload. A `QuantumProgram` is made up of `QuantumProgramItems`. Typically, each item consists of a circuit, a set of parameter values, and possibly a `samplex` to randomize the circuit content. For full details, see [Executor inputs and outputs](/docs/guides/executor-input-output).\n", "\n", "The following cell initializes a `QuantumProgram` and specifies to perform 25 shots. Next, it appends the transpiled target circuit.\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "eb6719cf-c7f1-4265-8602-9a65071a2dd5", "metadata": {}, "outputs": [], "source": [ "# Initialize an empty program\n", "program = QuantumProgram(shots=25)\n", "\n", "# Append the circuit to the program\n", "program.append_circuit_item(isa_circuit)" ] }, { "cell_type": "markdown", "id": "da542e9b-f143-4651-ab3d-86fb54c066ab", "metadata": {}, "source": [ "### 4. Optional: Group gates and measurements into annotated boxes\n", "\n", "Grouping instructions into boxes and annotating them is the primary way to specify your intent. In the following example, we use `generate_boxing_pass_manager` and its twirling parameters to group two-qubit gates and measurements into boxes and apply twirling annotation.\n", "\n" ] }, { "cell_type": "code", "execution_count": 6, "id": "245a4574-3ce9-4f77-98c8-af32cde8ac01", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Generate a boxing pass manager to group gates\n", "# and measurements into boxes and add\n", "# a`Twirl` annotation.\n", "boxes_pm = generate_boxing_pass_manager(\n", " # Add gate twirling\n", " enable_gates=True,\n", " # Add measurement twirling\n", " enable_measures=True,\n", ")\n", "\n", "boxed_circuit = boxes_pm.run(isa_circuit)\n", "boxed_circuit.draw(\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "2b2fe4a7-2a1c-489e-9063-3084edfc2517", "metadata": {}, "source": [ "### 5. Optional: Build a template circuit and samplex, and add them to the program\n", "\n", "Next, use the Samplomatic [build](https://qiskit.github.io/samplomatic/api/auto/samplomatic.build.html#samplomatic.build) method to generate the *template circuit* and *samplex* pair. The template circuit is structurally equivalent to the original circuit. However, its single-qubit gates are replaced by parameterized gates in order to implement the prescribed annotations (gate and measurement twirling, in this example). The samplex encodes all the information required to generate randomized parameters for the template circuit.\n", "\n", "After generating the template circuit and samplex pair, use the `append_samplex_item` method to add the pair to the program.\n", "\n", "See the Samplomatic [API](https://qiskit.github.io/samplomatic/api/index.html) documentation for full details about `samplomatic.samplex.Samplex` and its arguments.\n", "\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "47bbeef2-2d85-4495-b740-2e64eb9066b7", "metadata": {}, "outputs": [], "source": [ "# Build the template circuit and the samplex\n", "template_circuit, samplex = build(boxed_circuit)\n", "\n", "# Append the template circuit and samplex as a `samplex_item`\n", "program.append_samplex_item(\n", " template_circuit,\n", " samplex=samplex,\n", " shape=(num_randomizations := 20,),\n", ")" ] }, { "cell_type": "markdown", "id": "3733cce7-15d5-4c04-a1cd-0bf83e94aeaf", "metadata": {}, "source": [ "### 6. Invoke Executor and get results\n", "\n", "Run the `QuantumProgram` on an IBM® backend by using the `Executor` primitive with default options. See [Executor options](/docs/guides/executor-options) to learn about the available options.\n", "\n" ] }, { "cell_type": "code", "execution_count": 8, "id": "b767050c-0299-4100-8be4-b73b0587e088", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Initialize an Executor with the default options\n", "executor = Executor(mode=backend)\n", "\n", "# Submit the job\n", "job = executor.run(program)\n", "job" ] }, { "cell_type": "code", "execution_count": 9, "id": "a341681d-0704-4800-af65-e49b7627bb36", "metadata": {}, "outputs": [], "source": [ "# Retrieve the result\n", "result = job.result()" ] }, { "cell_type": "markdown", "id": "e649245b-633d-4123-ad55-9971b9366433", "metadata": {}, "source": [ "The result is of type [`QuantumProgramResult`](/docs/api/qiskit-ibm-runtime/results-quantum-program-result). See [Executor input and output](/docs/guides/executor-input-output) to learn about the result object.\n", "\n" ] }, { "cell_type": "markdown", "id": "a6e149b1-de4f-41bb-b972-0781f082fa45", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * Try some [Executor examples](/docs/guides/executor-examples).\n", " * Understand [Executor input and output](/docs/guides/executor-input-output).\n", " * Learn about [Executor broadcasting semantics](/docs/guides/executor-broadcasting).\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3" } }, "nbformat": 4, "nbformat_minor": 4 }