From d23fa543ef60c194ddce223b50740894a287dd22 Mon Sep 17 00:00:00 2001 From: merav-aharoni Date: Thu, 16 Nov 2023 01:24:36 +0200 Subject: [PATCH] Migration guide for IBMBackend.run (#1214) * First version of migration guide for backend.run() * Typoes and spacing * Added examples of Sessions * Spacing * Spacing * Spacing * removed unnecessary quotes * added missing quote * Fixed code blocks * Updates in migration guide * Release note * Fixed error * Added new file to toc * Fixed spelling * Fixed spelling * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Added explanations following review * Added comments in the code * More consistency in names, such as IBMBackend * minor wording changes * Editted text * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * Update docs/migrate/backend_run_migration_guide.rst Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> * address remaining comments --------- Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Co-authored-by: kevin-tian Co-authored-by: Kevin Tian --- docs/index.rst | 2 +- docs/migrate/backend_run_migration_guide.rst | 96 +++++++++++++++++++ .../migrate_backend_run-06c4b0579f28061a.yaml | 4 + 3 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 docs/migrate/backend_run_migration_guide.rst create mode 100644 releasenotes/notes/migrate_backend_run-06c4b0579f28061a.yaml diff --git a/docs/index.rst b/docs/index.rst index 43060ade5..a5164039e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -98,7 +98,7 @@ Next steps Use Sampler to design an algorithm Update parameter values while running Algorithm tuning options (shots, transpilation, error mitigation) - + Migrate backend.run() from qiskit_ibm_provider to qiskit_ibm_runtime .. toctree:: :maxdepth: 1 diff --git a/docs/migrate/backend_run_migration_guide.rst b/docs/migrate/backend_run_migration_guide.rst new file mode 100644 index 000000000..d62eebc26 --- /dev/null +++ b/docs/migrate/backend_run_migration_guide.rst @@ -0,0 +1,96 @@ +Migration guide: Migrate ``backend.run()`` from ``qiskit_ibm_provider`` to ``qiskit_ibm_runtime`` +================================================================================================= + +The Qiskit Runtime interface includes two packages: +Qiskit IBM Provider (the ``qiskit_ibm_provider`` package) and +Qiskit IBM Runtime (the ``qiskit_ibm_runtime`` package). Until now, +primitives (``Sampler`` and ``Estimator``) +were run in Runtime. Custom circuits that were manually transpiled and used ``IBMBackend.run()`` +were run in Provider. + +In this release, we add support for running custom circuits using ``IBMBackend.run()`` in Runtime, +so users can run all programs through Runtime. + +This guide describes how to migrate code that implemented ``IBMBackend.run()`` +using Qiskit IBM Provider to use Qiskit IBM Runtime instead. + +**Example 1: Straightforward execution of IBMBackend.run()** + +.. code-block:: python + + from qiskit import * + from qiskit.compiler import transpile, assemble + circuit = QuantumCircuit(2, 2) + circuit.h(0) + circuit.cx(0, 1) + circuit.measure_all() + +In Provider, the code is: + +.. code-block:: python + + from qiskit_ibm_provider import IBMProvider + provider = IBMProvider() + backend = provider.get_backend("ibmq_qasm_simulator") + transpiled_circuit = transpile(circuit, backend=backend) + job = backend.run(transpiled_circuit) + print(job.result()) + +In Runtime, the code is: + +.. code-block:: python + + from qiskit_ibm_runtime import QiskitRuntimeService + service = QiskitRuntimeService(channel="ibm_quantum") + backend = service.backend("ibmq_qasm_simulator") + transpiled_circuit = transpile(circuit, backend=backend) + job = backend.run(transpiled_circuit) + print(job.result()) + +**Example 2: Execution of backend.run() within a session:** + +This section of code is identical in Provider and in Runtime. + +.. code-block:: python + + with backend.open_session() as session: + job1 = backend.run(transpiled_circuit) + job2 = backend.run(transpiled_circuit) + print(job1.session_id) + print(job2.session_id) + backend.cancel_session() + +Sessions are implemented differently in ``IBMBackend`` than when using primitives. +Therefore, we cannot run a primitive and use backend.run() within a single session. If you specify both, one will be run outside of the session. + +**Example 3: Primitive session containing backend.run:** + +In this example, ``sampler`` is run within session, but ``backend`` is run independently +of the session. + +.. code-block:: python + + from qiskit_ibm_runtime import Session, Sampler + with Session(backend=backend) as session: + sampler = Sampler(session=session) + job1 = sampler.run(transpiled_circuit) + job2 = backend.run(transpiled_circuit) # runs outside the session + print(job1.session_id) + print(job2.session_id) # is None + +**Example 4: Backend session containing Sampler:** + +In this example, ``backend`` is run within a session, but ``sampler`` is run independently +of the session. + +.. code-block:: python + + with backend.open_session() as session: + sampler = Sampler(backend=backend) + job1 = sampler.run(transpiled_circuit) # runs outside the session + job2 = backend.run(transpiled_circuit) + session_id = session.session_id + print(job1.session_id) # is None + print(job2.session_id) + + diff --git a/releasenotes/notes/migrate_backend_run-06c4b0579f28061a.yaml b/releasenotes/notes/migrate_backend_run-06c4b0579f28061a.yaml new file mode 100644 index 000000000..fc290de6e --- /dev/null +++ b/releasenotes/notes/migrate_backend_run-06c4b0579f28061a.yaml @@ -0,0 +1,4 @@ +--- +other: + - | + Added migration code for running ``backend.run`` in `qiskit_ibm_runtime` instead of in `qiskit_ibm_provider`.