Run jobs in a batch

Use batch mode to submit multiple primitive jobs simultaneously. Following are examples of working with batches.

Set up to use batches

Before starting a batch, you must set up Qiskit Runtime and initialize it as a service:

from qiskit_ibm_runtime import QiskitRuntimeService, Batch, SamplerV2 as Sampler, EstimatorV2 as Estimator
 
service = QiskitRuntimeService()

Open a batch

You can open a runtime batch by using the context manager with Batch(...) or by initializing the Batch class. When you start a batch, you must specify a QPU by passing a backend object. The batch starts when its first job begins execution.

Batch class

from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler, EstimatorV2 as Estimator
 
backend = service.least_busy(operational=True, simulator=False)
batch = Batch(backend=backend)
estimator = Estimator(mode=batch)
sampler = Sampler(mode=batch)
# Close the batch because no context manager was used.
batch.close()

Context manager

The context manager automatically opens and closes the batch.

from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler, EstimatorV2 as Estimator
 
backend = service.least_busy(operational=True, simulator=False)
with Batch(backend=backend):
  estimator = Estimator()
  sampler = Sampler()

Batch length

You can define the batch's maximum time to live (TTL) with the max_time parameter. This should exceed the longest job's execution time. This timer starts when the batch starts. When the value is reached, the batch is closed. Any jobs that are running will finish, but jobs still queued are failed.

with Batch(backend=backend, max_time="25m"):
  ...

There is also an interactive time to live (interactive TTL) value that cannot be configured. If no batch jobs are queued within that window, the batch is temporarily deactivated.

Default values:

To determine a batch's max TTL or interactive TTL, follow the instructions in Determine batch details and look for the max_timeor interactive_timeout value, respectively.

Close a batch

A batch automatically closes when it exits the context manager. When the batch context manager is exited, the batch is put into "In progress, not accepting new jobs" status. This means that the batch finishes processing all running or queued jobs until the maximum TTL value is reached. After all jobs are completed, the batch is immediately closed. You cannot submit jobs to a closed batch.

with Batch(backend=backend) as batch:
    estimator = Estimator()
    job1 = estimator.run(...)
    job2 = estimator.run(...)
 
# The batch is no longer accepting jobs but the submitted job will run to completion.
result = job1.result()
result2 = job2.result()

batch = Batch(backend=backend)
 
# If using qiskit-ibm-runtime earlier than 0.24.0, change `mode=` to `batch=`
estimator = Estimator(mode=batch)
job1 = estimator.run(...)
job2 = estimator.run(...)
print(f"Result1: {job1.result()}")
print(f"Result2: {job2.result()}")
 
# Manually close the batch. Running and queued jobs will run to completion.
batch.close()

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, batch, SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
with Batch(backend=backend) as batch:
    print(batch.details())

Reconfigure jobs for parallel processing

There are multiple ways you can reconfigure your jobs to take advantage of the parallel processing provided by batching. 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)

Next steps