{ "cells": [ { "cell_type": "markdown", "id": "008d2ceb-f6fa-42f6-a7df-6bd604775278", "metadata": {}, "source": [ "---\n", "title: Get started with the Estimator primitive\n", "description: How to use the Estimator primitive in Qiskit Runtime.\n", "---\n", "\n", "# Get started with the Estimator primitive\n", "\n" ] }, { "cell_type": "markdown", "id": "49f269ba-e11d-4e5c-bbba-9d4a10540ad8", "metadata": {}, "source": [ "The Estimator primitive computes the expectation values for one or more observables with respect to states prepared by quantum circuits. The circuits can be parametrized, as long as the parameter values are also provided as input to the primitive.\n", "\n", "This primitive has several built-in [error mitigation and suppression techniques](/docs/guides/error-mitigation-and-suppression-techniques) techniques, including dynamical decoupling, Pauli-twirling, gate-folding ZNE, PEA, and PEC. It also supports a `resilience_level` option that allows you to easily configure the cost and accuracy tradeoff.\n", "\n" ] }, { "cell_type": "markdown", "id": "b7e96291-0925-4d7f-81a8-a7738549477c", "metadata": {}, "source": [ "The steps in this topic describe how to set up Estimator, explore the options you can use to configure it, and invoke it in a program.\n", "\n" ] }, { "cell_type": "markdown", "id": "818a2b3d-3950-4a28-8e37-39959c56484b", "metadata": { "tags": [ "version-info" ] }, "source": [ "{/*\n", " DO NOT EDIT THIS CELL!!!\n", " This cell's content is generated automatically by a script. Anything you add\n", " here will be removed next time the notebook is run. To add new content, create\n", " a new cell before or after this one.\n", " */}\n", "\n", "\n", " \n", " The code on this page was developed using the following requirements.\n", " We recommend using these versions or newer.\n", "\n", " ```\n", " qiskit[all]~=2.3.1\n", " qiskit-ibm-runtime~=0.45.1\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "bafa61f0-c049-4ee6-ac76-a0ed97e67caf", "metadata": {}, "source": [ "{/*Verified the v2 examples 2/29/24 - updated 10/29/24*/}\n", "\n", "## Steps to use the Estimator primitive\n", "\n", "### 1. Initialize the account\n", "\n", "Because Qiskit Runtime is a managed service, you first need to initialize your account. You can then select the QPU you want to use to calculate the expectation value.\n", "\n", "Follow the steps in the [Set up your IBM Cloud account](cloud-setup) if you don't already have an account.\n", "\n", "\n", " To use the newly supported [fractional gates](/docs/guides/fractional-gates), set `use_fractional_gates=True` when requesting a backend from a `QiskitRuntimeService` instance. For example:\n", "\n", " ```python\n", " service = QiskitRuntimeService()\n", " fractional_gate_backend = service.least_busy(use_fractional_gates=True)\n", " ```\n", "\n", " This is an experimental feature and might change in the future.\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "71d62ba2-b1ba-405a-b304-5bdd7ec5e11b", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "ibm_fez\n" ] } ], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", "service = QiskitRuntimeService()\n", "backend = service.least_busy(\n", " operational=True, simulator=False, min_num_qubits=127\n", ")\n", "\n", "print(backend.name)" ] }, { "cell_type": "markdown", "id": "d894fbe3-3ea8-4db0-908e-95790b560ddb", "metadata": {}, "source": [ "### 2. Create a circuit and an observable\n", "\n", "You need at least one circuit and one observable as inputs to the Estimator primitive.\n", "\n" ] }, { "cell_type": "code", "execution_count": null, "id": "c0ad8982-d19b-46d4-8a2d-dd30357c0e52", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ ">>> Observable: ['IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...',\n", " 'IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII...', ...]\n" ] } ], "source": [ "from qiskit.circuit.library import qaoa_ansatz\n", "from qiskit.quantum_info import SparsePauliOp\n", "\n", "entanglement = [tuple(edge) for edge in backend.coupling_map.get_edges()]\n", "observable = SparsePauliOp.from_sparse_list(\n", " [(\"ZZ\", [i, j], 0.5) for i, j in entanglement],\n", " num_qubits=backend.num_qubits,\n", ")\n", "circuit = qaoa_ansatz(observable, reps=2)\n", "# The circuit is parametrized, so we will define the parameter values for execution\n", "param_values = [0.1, 0.2, 0.3, 0.4]" ] }, { "cell_type": "markdown", "id": "84b42c6f-d80e-4cff-8e34-03affa566a97", "metadata": {}, "source": [ "The circuit and observable need to be transformed to only use instructions supported by the QPU (referred to as *instruction set architecture (ISA)* circuits). Use the transpiler to do this.\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "abefc665-24a7-466e-a9ec-67cac6a50ebd", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ ">>> Circuit ops (ISA): OrderedDict([('rz', 4472), ('sx', 1884), ('cz', 1120)])\n" ] } ], "source": [ "from qiskit.transpiler import generate_preset_pass_manager\n", "\n", "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", "isa_circuit = pm.run(circuit)\n", "isa_observable = observable.apply_layout(isa_circuit.layout)\n", "print(f\">>> Circuit ops (ISA): {isa_circuit.count_ops()}\")" ] }, { "cell_type": "markdown", "id": "b53e9ab3-7d87-4dd5-b362-138b24cfa73b", "metadata": {}, "source": [ "### 3. Initialize Qiskit Runtime Estimator\n", "\n", "When you initialize Estimator, use the `mode` parameter to specify the mode you want it to run in. Possible values are `batch`, `session`, or `backend` objects for batch, session, and job execution mode, respectively. For more information, see [Introduction to Qiskit Runtime execution modes.](execution-modes) Note that Open Plan users cannot submit session jobs.\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "961508db-e534-4fc9-970d-7babcd6c39ef", "metadata": {}, "outputs": [], "source": [ "from qiskit_ibm_runtime import EstimatorV2 as Estimator\n", "\n", "estimator = Estimator(mode=backend)" ] }, { "cell_type": "markdown", "id": "59b13a43-0c9f-4fdb-a379-af5115c153e1", "metadata": {}, "source": [ "### 4. Invoke Estimator and get results\n", "\n", "Next, invoke the `run()` method to calculate expectation values for the input circuits and observables. The circuit, observable, and optional parameter value sets are input as *primitive unified bloc* (PUB) tuples.\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "f1a60bad-cf09-4136-aa1a-4482759b3aea", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ ">>> Job ID: d76cm768faus73f14eg0\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ ">>> Job Status: QUEUED\n" ] } ], "source": [ "job = estimator.run([(isa_circuit, isa_observable, param_values)])\n", "print(f\">>> Job ID: {job.job_id()}\")\n", "print(f\">>> Job Status: {job.status()}\")" ] }, { "cell_type": "code", "execution_count": 6, "id": "c817cce5-4686-43d2-89a1-ed0842d8ace3", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ ">>> PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray()), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': False, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})\n", " > Expectation value: 28.628978416256825\n", " > Metadata: {'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}\n" ] } ], "source": [ "result = job.result()\n", "print(f\">>> {result}\")\n", "print(f\" > Expectation value: {result[0].data.evs}\")\n", "print(f\" > Metadata: {result[0].metadata}\")" ] }, { "cell_type": "markdown", "id": "d38dd409-e0d8-4749-bb22-58ae9a53d26a", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * Learn how to [test locally](local-testing-mode) before running on quantum computers.\n", " * Review detailed [examples](/docs/guides/estimator-examples).\n", " * Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum Learning.\n", " * Learn how to transpile locally in the [Transpile](/docs/guides/transpile/) section.\n", " * Try the [Compare transpiler settings](/docs/guides/circuit-transpilation-settings#compare-transpiler-settings) guide.\n", " * Learn how to [use the primitive options](runtime-options-overview).\n", " * View the API for [Estimator](/docs/api/qiskit-ibm-runtime/options-estimator-options) options.\n", " * Read [Migrate to V2 primitives](/docs/guides/v2-primitives).\n", "\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 }