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.
Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead.
The way sessions are started within Qiskit Runtime has changed. By 1 April 2024, upgrade to qiskit-ibm-runtime
version 0.20.0 or later. In addition, ensure you are using Qiskit version 0.45.0 or later. Starting 1 April, session calls made in earlier versions of these packages will fail.
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
- Try an example in the Quantum approximate optimization algorithm (QAOA) tutorial.
- Review the Session API reference.
- Understand the Job limits when sending a job to an IBM® QPU.