Run jobs in a session

There are several ways to set up and use sessions. It is recommended that you do not run a session with a single job in it.

Set up to use sessions

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

from qiskit_ibm_runtime import QiskitRuntimeService, Session, Sampler, Estimator
 
service = QiskitRuntimeService()

Open a session

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

Session class

from qiskit_ibm_runtime import Session, Samplerv2 as Sampler, Estimatorv2 as Estimator
 
backend = service.least_busy(operational=True, simulator=False)
session = Session(backend=backend)
estimator = Estimator(mode=session)
sampler = Sampler(mode=session)

Context manager

The context manager automatically opens and closes the session.

from qiskit_ibm_runtime import Session, Samplerv2 as Sampler, Estimatorv2 as Estimator
 
backend = service.least_busy(operational=True, simulator=False)
with Session(backend=backend):
  estimator = Estimator()
  sampler = Sampler()

Session length

You can define the maximum session timeout with the max_time parameter. This should exceed the longest job's execution time and be within the QPU's limits. This timer starts when the session starts. When the value is reached, the session is closed. Any jobs that are running will finish, but jobs still queued are failed.

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

There is also an interactive time to live (ITTL) value that cannot be configured. If no session jobs are queued within that window, the session is temporarily deactivated. To determine a session's ITTL, follow the instructions in Determine session details and look for the interactive_timeout value.

Close a session

A session automatically closes when it exits the context manager. When the session context manager is exited, the session is put into "In progress, not accepting new jobs" status. This means that the session finishes processing all running or queued jobs until the maximum timeout value is reached. After all jobs are completed, the session is immediately closed. This allows the scheduler to run the next job without waiting for the session interactive timeout, thereby reducing the average job queuing time. You cannot submit jobs to a closed session.

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

If you are not using a context manager, manually close the session to avoid unwanted cost. You can close a session as soon as you are done submitting jobs to it. When a session is closed with session.close(), it no longer accepts new jobs, but the already submitted jobs will still run until completion and their results can be retrieved.

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

Cancel a session

Canceling a session immediately closes it, failing all queued jobs and preventing new submission. Use the session.cancel() method to cancel a session. Any jobs that are already running continue to run but queued jobs are put into a failed state and no further jobs can be submitted to the session. This is a convenient way to quickly fail all queued jobs within a session.

with Session(backend=backend) as session:
    estimator = Estimator()
    job1 = estimator.run(...)
    job2 = estimator.run(...)
    # You can use session.cancel() to fail all pending jobs, for example,
    # if you realize you made a mistake.
    session.cancel()

Invoke multiple primitives in a session

A session can handle multiple primitives, allowing for various operations within a single session. The following example shows how you can create both an instance of the SamplerV2 class and one of the EstimatorV2 class, then invoke their run() methods within a session.

from qiskit_ibm_runtime import Session, SamplerV2 as Sampler, EstimatorV2 as Estimator
 
with Session(backend=backend):
    sampler = Sampler()
    estimator = Estimator()
 
    job = sampler.run([sampler_circuit])
    result = job.result()
    print(f" > Counts: {result[0].data.meas.get_counts()}")
 
    job = estimator.run([(circuit, observable)])
    result = job.result()
    print(f" > Expectation value: {result[0].data.evs}")
    print(f" > Metadata: {result[0].metadata}")

Run two VQE algorithms in a session by using threading

You can get more out of a session by running multiple workloads simultaneously. The following example shows how you can run two VQE algorithms, each using a different classical optimizer, simultaneously inside a single session. Job tags are also used to differentiate jobs from each workload.

from concurrent.futures import ThreadPoolExecutor
from qiskit_ibm_runtime import EstimatorV2 as Estimator
 
def minimize_thread(estimator, method):
    return minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method=method)
 
with Session(backend=backend), ThreadPoolExecutor() as executor:
    estimator1 = Estimator()
    estimator2 = Estimator()
 
    # Use different tags to differentiate the jobs.
    estimator1.options.environment.job_tags = ["cobyla"]
    estimator2.options.environment.job_tags = ["nelder-mead"]
 
    # Submit the two workloads.
    cobyla_future = executor.submit(minimize_thread, estimator1, "cobyla")
    nelder_mead_future = executor.submit(minimize_thread, estimator2, "nelder-mead")
 
    # Get workload results.
    cobyla_result = cobyla_future.result()
    nelder_mead_result = nelder_mead_future.result()

Check session status

You can query a session's status to understand its current state by using session.status() or on the Jobs page for your channel.

Session status can be one of the following:

• Pending: The session has not started or has been deactivated. The next session job needs to wait in the queue like other jobs.
• In progress, accepting new jobs: The session is active and accepting new jobs.
• In progress, not accepting new jobs: The session is active but not accepting new jobs. Job submission to the session is rejected, but outstanding session jobs will run to completion. The session is automatically closed once all jobs finish.
• Closed: The session's maximum timeout value has been reached or the session was explicitly closed.

Determine session details

For a comprehensive overview of a session's configuration and status, use the session.details() method.

from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator
 
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
with Session(backend=backend) as session:
    estimator = Estimator()
    job = estimator.run([(circuit, observable)])
    print(session.details())

Next steps