Skip to main contentIBM Quantum Documentation Preview

Run jobs in a batch

Important

The way batches are started within Qiskit Runtime has changed. By 1 April 2024, upgrade to qiskit-ibm-runtime version 0.20.0 or later, or qiskit-ibm-provider version 0.10.0 or later. In addition, ensure you are using Qiskit version 0.45.0 or later. Starting 1 April, batch calls made in earlier versions of these packages will fail.

Batch mode can shorten processing time if all jobs can be provided at the outset. If you want to submit iterative jobs, use sessions instead. Using batch mode has these 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 usually minimal delay between jobs, 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 don't meet your expectations, you can cancel the remaining jobs. Also, if one job fails, you can re-submit it instead of re-running the entire workload.
Note

When batching, jobs are not guaranteed to run in the order they are submitted. Also, while your batch jobs will run as closely together as possible, they don't get exclusive access to the backend. Therefore, your batch jobs might run in parallel with other users' jobs if there is enough processing capacity on the QPU. Additionally, QPU calibration jobs could run between the batched jobs.

This diagram illustrates jobs submitted in a batch. It shows five jobs, numbered 0 through 4, in a queue. The jobs are a mix of Estimator and Sampler.
Figure 1: Batch execution

There are multiple ways you can reconfigure your jobs to take advantage of the parallel processing provided by batching.

Example: Partition a list of circuits into multiple jobs and run them in batch

The following example shows how you can partition a long list of circuits into multiple jobs and run them as a batch to take advantage of the parallel processing.

from qiskit_ibm_runtime import SamplerV2 as Sampler, Batch
 
max_circuits = 100
all_partitioned_circuits = []
for i in range(0, len(circuits), max_circuits):
    all_partitioned_circuits.append(circuits[i : i + max_circuits])
jobs = []
start_idx = 0
 
with Batch(backend=backend):
    sampler = Sampler()
    for partitioned_circuits in all_partitioned_circuits:
        job = sampler.run(partitioned_circuits)
        jobs.append(job)
Caution

If you set backend=backend in a V2 primitive, the program is run in job mode, even if it's inside a batch or session context. Setting backend=backend is deprecated as of IBM Qiskit Runtime 0.24.0. Instead, use the mode parameter.

Determine batch details

For a comprehensive overview of a batch's configuration and status, including its interactive and max TTL, use the batch.details() method.

from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
with Batch(backend=backend) as batch:
    sampler = Sampler()
    for partition in partitions:
        job = sampler.run(partition)
    print(batch.details())
Recommendations