Migration guide for IBMBackend.run

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

docs/migrate/backend_run_migration_guide.rst

@@ -0,0 +1,89 @@
+Migration guide: Migrate ``backend.run()`` from ``qiskit_ibm_provider`` to ``qiskit_ibm_runtime``
+=====================================================================================
+
+This guide describes how to migrate code that implemented ``backend.run()``
+using Qiskit IBM Provider (the ``qiskit_ibm_provider`` package) to use
+Qiskit IBM Runtime (``qiskit_ibm_runtime`` package).
+We demonstrate the migration with code examples.
+
+**Example 1: Straightforward execution of backend.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 the 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 will be:
+
+.. 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()
+
+The Session for ``Primitives`` (``Sampler`` and ``Estimator``) is currently different than
+the Session for ``IBMBackend``. Therefore, we cannot run a primitive and a backend
+using a single Session.
+
+**Example 3: Primitive Session containing backend.run:**
+
+In this example, ``sampler`` is run within session, but ``backend`` is run independently
+of ``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)
+
+**Example 4: Backend Session containing Sampler:**
+
+In this example, ``backend`` is run within a session, but ``sampler`` is run independently
+of ``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)
+        print(job2.session_id)
+
+

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`.