Skip to main contentIBM Quantum Documentation

Introduction to Qiskit Runtime execution modes

When Qiskit Runtime was introduced, users could only execute circuits as individual jobs. As different types of quantum workloads emerged, the need for different scheduling strategies became evident. The execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your workload to run efficiently within your budget. There are three execution modes: job, session, and batch.

Job mode

A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify mode=backend when instantiating a primitive. See Primitives examples for usage.

Batch mode

A multi-job manager for efficiently running experiments comprising multi-job workloads. These workloads are made up of independently executable jobs that have no conditional relationship with each other. With batch mode, users submit their jobs all at once. The system parallelizes or threads the pre-processing step of each primitive job to more tightly package quantum execution across jobs, and then runs the quantum execution of each job in quick succession to deliver the most efficient results.

A sets of jobs being run in batch mode. The classical computation part of each job happens simultaneously, then all jobs are sent to the QPU. The QPU is locked for your use from the time the first job reaches the QPU until the last job is done processing on the QPU. There is no gap between jobs where the QPU is idle.
How a batch works
Notes
  • 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.
  • The queuing time does not decrease for the first job submitted within a batch. Therefore, batches do not provide any benefits when running a single job.
  • Batches do not work on simulators because simulators do not have a queue.

To run in batch mode, specify mode=batch when instantiating a primitive or run the job in a batch context manager. See Run jobs in a batch for examples.

Session mode

A dedicated window for running a multi-job workload. During this window, the user has exclusive access of the system and no other jobs can run - including calibration jobs. This allows users to experiment with variational algorithms in a more predictable way and even run multiple experiments simultaneously, taking advantage of parallelism in the stack. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources.

A sets of jobs being run in session mode and the other is being run in batch mode. Between each job is the interactive TTL (interactive time to live). The active window starts when the first job starts and ends after the last job is completed. After the final job of the first set of jobs completes, the active window ends and the session is paused (but not closed). Another set of jobs then starts and jobs continue in a similar manner. The QPU is reserved for your use during the entire session.
How a session works

To run in session mode, specify mode=session when instantiating a primitive, or run the job in a session context manager. See Run jobs in a session for examples.

Notes
  • The queuing time does not decrease for the first job submitted within a session. Therefore, sessions do not provide any benefits when running a single job.
  • Sessions do not work on simulators because simulators do not have a queue.
  • Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead.

Basic workflow

The basic workflow for batches and sessions is similar:

  1. The first job in a batch or session enters the normal queue. For batches, the entire batch of jobs is scheduled together.
  2. When the first job starts running, the maximum time to live (TTL) timer starts, and does not stop or pause until the end is reached.
  3. The interactive TTL timer starts after each job is completed. If there are no workload jobs ready within the interactive TTL window, the workload is temporarily deactivated and normal job selection resumes. A job can reactivate the deactivated workload if the batch or session has not reached its maximum TTL value.
    Note

    The job must go through the normal queue to reactivate the workload.

  4. If the maximum TTL value is reached, the workload ends and any remaining queued jobs fail. In IBM Quantum™ Platform, any jobs already running will run to completion. However, if you are using Qiskit Runtime on IBM Cloud®, jobs won't run to completion if doing so would exceed the instance's cost limit.

The following video illustrates the basic workflow, using sessions as an example:

For full details about the TTL timers, see the Maximum execution time guide.

Next steps

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