Merge branch 'main' into fake-backend-methods

qiskit_ibm_runtime/batch.py

@@ -23,46 +23,54 @@
 class Batch(Session):
     """Class for running jobs in batch execution mode.
 
-    Similar to a ``session``, a Qiskit Runtime ``batch`` groups a collection of
-    iterative calls to the quantum computer. Batch mode can shorten processing time if all jobs
-    can be provided at the outset. To submit iterative jobs, use sessions instead.
+    The ``batch`` mode is designed to efficiently perform experiments that comprise multiple
+    independent jobs.
 
-    Using batch mode has these benefits:
+    Using the ``batch`` mode provides the following benefits:
         - The jobs' classical computation, such as compilation, is run in parallel.
           Thus, running multiple jobs in a batch is significantly faster than running them serially.
 
-        - There is minimal delay between job, which can help avoid drift.
+        - There is usually minimal delay between job, which can help avoid drift.
+
+        - If you partition your workload into multiple jobs and run them in ``batch`` mode, you can
+          get results from individual jobs, which makes them more flexible to work with. For example,
+          if a job's results do not meet your expectations, you can cancel the remaining jobs, or
+          simply re-submit that individual job and avoid re-running the entire workload.
+
+    All jobs need to be provided at the outset. To submit iterative jobs, use the ``session``
+    mode instead.
 
     You can open a Qiskit Runtime batch by using this ``Batch`` class, then submit jobs
     to one or more primitives.
 
     For example::
 
-        from qiskit.circuit import QuantumCircuit, QuantumRegister, ClassicalRegister
+        from qiskit.circuit.random import random_circuit
         from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
-        from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler
+        from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler, QiskitRuntimeService
 
         service = QiskitRuntimeService()
         backend = service.least_busy(operational=True, simulator=False)
+        pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
 
-        # Bell Circuit
-        qr = QuantumRegister(2, name="qr")
-        cr = ClassicalRegister(2, name="cr")
-        qc = QuantumCircuit(qr, cr, name="bell")
-        qc.h(qr[0])
-        qc.cx(qr[0], qr[1])
-        qc.measure(qr, cr)
+        # generate fifty unique three-qubit random circuits
+        circuits = [pm.run(random_circuit(3, 2, measure=True)) for _ in range(50)]
 
-        pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
-        isa_circuit = pm.run(qc)
+        # split up the list of circuits into partitions
+        max_circuits = 10
+        partitions = [circuits[i : i + max_circuits] for i in range(0, len(circuits), max_circuits)]
 
-        with Batch(backend=backend) as batch:
-            sampler = Sampler(batch)
-            job = sampler.run([isa_circuit])
-            pub_result = job.result()[0]
-            print(f"Sampler job ID: {job.job_id()}")
-            print(f"Counts: {pub_result.data.cr.get_counts()}")
+        # run the circuits in batched mode
+        with Batch(backend=backend):
+            sampler = Sampler()
+            for partition in partitions:
+                job = sampler.run(partition)
+                pub_result = job.result()[0]
+                print(f"Sampler job ID: {job.job_id()}")
+                print(f"Counts for the first PUB: {pub_result.data.cr.get_counts()}")
 
+    For more details, check the "`Run jobs in a batch
+    <https://docs.quantum.ibm.com/run/run-jobs-batch>`_" tutorial.
     """
 
     def __init__(