Batch
class Batch(service=None, backend=None, max_time=None)
Class for running jobs in batch execution mode.
The batch mode is designed to efficiently perform experiments that comprise multiple independent jobs.
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 usually minimal delay between job, which can help avoid drift.
- If you partition your workload into multiple jobs and run them in
batchmode, 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.random import random_circuit
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
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)
# generate fifty unique three-qubit random circuits
circuits = [pm.run(random_circuit(3, 2, measure=True)) for _ in range(50)]
# 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)]
# 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” tutorial.
Batch constructor.
Parameters
- service (
Optional[QiskitRuntimeService]) – Optional instance of theQiskitRuntimeServiceclass. IfNone, the service associated with the backend, if known, is used. OtherwiseQiskitRuntimeService()is used to initialize your default saved account. - backend (
Union[str,BackendV1,BackendV2,None]) – Optional instance ofBackendclass or backend string name. - max_time (
Union[int,str,None]) – Maximum amount of time a runtime session can be open before being forcibly closed. Can be specified as seconds (int) or a string like “2h 30m 40s”. This value must be less than the system imposed maximum.
Raises
ValueError – If an input value is invalid.
Attributes
service
Return service associated with this session.
Return type
Returns
qiskit_ibm_runtime.QiskitRuntimeService associated with this session.
session_id
Return the session ID.
Return type
Optional[str]
Returns
Session ID. None if the backend is a simulator.
Methods
backend
backend()
Return backend for this session.
Return type
Optional[str]
Returns
Backend for this session. None if unknown.
cancel
close
close()
Close the session so new jobs will no longer be accepted, but existing queued or running jobs will run to completion. The session will be terminated once there are no more pending jobs.
Return type
None
details
details()
Return session details.
Return type
Optional[Dict[str, Any]]
Returns
A dictionary with the sessions details.
id: id of the session.backend_name: backend used for the session.interactive_timeout: The maximum idle time (in seconds) between jobs that is allowed to occur before the session is deactivated.max_time: Maximum allowed time (in seconds) for the session, subject to plan limits.active_timeout: The maximum time (in seconds) a session can stay active.state: State of the session - open, active, inactive, or closed.accepting_jobs: Whether or not the session is accepting jobs.last_job_started: Timestamp of when the last job in the session started.last_job_completed: Timestamp of when the last job in the session completed.started_at: Timestamp of when the session was started.closed_at: Timestamp of when the session was closed.activated_at: Timestamp of when the session state was changed to active.mode: Execution mode of the session.usage_time: The usage time, in seconds, of this Session or Batch. Usage is defined as the time a quantum system is committed to complete a job.
from_id
classmethod from_id(session_id, service=None)
Construct a Session object with a given session_id
Parameters
-
session_id (
str) – the id of the session to be created. This must be an already existing session id. -
service (
Optional[QiskitRuntimeService]) –instance of the
QiskitRuntimeServiceclass.If
None,QiskitRuntimeService()is used to initialize your default saved account.Raises:
IBMInputValueError: If given session_id does not exist.
Return type
Returns
A new Session with the given session_id
run
run(program_id, inputs, options=None, callback=None, result_decoder=None)
Run a program in the session.
Parameters
- program_id (
str) – Program ID. - inputs (
Dict) – Program input parameters. These input values are passed to the runtime program. - options (
Optional[Dict]) – Runtime options that control the execution environment. Seeqiskit_ibm_runtime.RuntimeOptionsfor all available options. - callback (
Optional[Callable]) – Callback function to be invoked for any interim results and final result.
Return type
Union[RuntimeJob, RuntimeJobV2]
Returns
Submitted job.
status
status()
Return current session status.
Return type
Optional[str]
Returns
Session status as a string.
Pending: Session is created but not active. It will become active when the next job of this session is dequeued.In progress, accepting new jobs: session is active and accepting new jobs.In progress, not accepting new jobs: session is active and not accepting new jobs.Closed: max_time expired or session was explicitly closed.None: status details are not available.