Skip to main contentIBM Quantum Documentation

Batch

class Batch(service=None, backend=None, max_time=None)

GitHub(opens in a new tab)

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.

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 minimal delay between job, which can help avoid drift.

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.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
# 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)
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(qc)
 
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()}")

Batch constructor.

Parameters

  • service (Optional[QiskitRuntimeService]) – Optional instance of the QiskitRuntimeService class. If None, the service associated with the backend, if known, is used. Otherwise QiskitRuntimeService() is used to initialize your default saved account.
  • backend (Union[str, BackendV1, BackendV2, None]) – Optional instance of Backend class 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

QiskitRuntimeService

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()

GitHub(opens in a new tab)

Return backend for this session.

Return type

Optional[str]

Returns

Backend for this session. None if unknown.

cancel

cancel()

GitHub(opens in a new tab)

Cancel all pending jobs in a session.

Return type

None

close

close()

GitHub(opens in a new tab)

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()

GitHub(opens in a new tab)

Return session details.

Returns

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.

Return type

A dictionary with the sessions details, including

from_id

classmethod from_id(session_id, service=None)

GitHub(opens in a new tab)

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 QiskitRuntimeService class.

    If None, QiskitRuntimeService() is used to initialize your default saved account.

    Raises:

    IBMInputValueError: If given session_id does not exist.

Return type

Session

Returns

A new Session with the given session_id

run

run(program_id, inputs, options=None, callback=None, result_decoder=None)

GitHub(opens in a new tab)

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. See qiskit_ibm_runtime.RuntimeOptions for 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()

GitHub(opens in a new tab)

Return current session status.

Returns

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.

Return type

The current status of the session, including

Was this page helpful?
Report a bug or request content on GitHub.