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 <kevin.tian@ibm.com> Co-authored-by: Kevin Tian <kt474@cornell.edu>
Qiskit · Nov 15, 2023 · d23fa54 · d23fa54
1 parent 6cc8197
commit d23fa54
Show file tree

Hide file tree

Showing 3 changed files with 101 additions and 1 deletion.
diff --git a/docs/index.rst b/docs/index.rst
@@ -98,7 +98,7 @@ Next steps
     Use Sampler to design an algorithm <migrate/migrate-sampler>
     Update parameter values while running <migrate/migrate-update-parm>
     Algorithm tuning options (shots, transpilation, error mitigation) <migrate/migrate-tuning>
-
+    Migrate backend.run() from qiskit_ibm_provider to qiskit_ibm_runtime <migrate/backend_run_migration_guide>
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/migrate/backend_run_migration_guide.rst 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
@@ -0,0 +1,4 @@
+---
+other:
+  - |
+    Added migration code for running ``backend.run`` in `qiskit_ibm_runtime` instead of in `qiskit_ibm_provider`.