104 lines
5.5 KiB
Plaintext
104 lines
5.5 KiB
Plaintext
---
|
|
title: Sessions
|
|
description: An overview of Qiskit Runtime sessions and when to use them.
|
|
|
|
---
|
|
# Introduction to Qiskit Runtime sessions
|
|
|
|
<Admonition type="caution" title="Important">
|
|
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.
|
|
</Admonition>
|
|
|
|
<Admonition type="note">
|
|
Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead.
|
|
</Admonition>
|
|
|
|
## What is a session?
|
|
|
|
A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. 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.
|
|
|
|
<Admonition type="note">
|
|
The queuing time does not decrease for the first job submitted within a session. Therefore, a session does not provide any benefits when running a single job. Additionally, sessions do not work on simulators because simulators do not have a queue.
|
|
</Admonition>
|
|
|
|
## Advantages of using sessions
|
|
|
|
There are several benefits to using sessions:
|
|
|
|
- Efficiency: Multiple jobs from a single algorithm run can be run sequentially without interruptions.
|
|
- Flexibility: You can submit jobs, check results, and submit new jobs within an active session without needing to start a new one.
|
|
|
|
## How sessions work
|
|
|
|
The basic workflow for sessions is as follows:
|
|
|
|
1. The first job in a session enters the normal queue.
|
|
2. When the first job starts running, the _maximum timeout_ clock starts.
|
|
2. Subsequent jobs within the session are prioritized over other jobs, reducing wait times.
|
|
3. The _interactive timeout_ runs between the jobs in a session. Every session has an interactive timeout value (ITTL, or interactive time to live). If there are no session jobs queued within the ITTL window, the session is temporarily deactivated and normal job selection resumes. A job can reactivate the deactivated session if the session has not reached its maximum timeout value.
|
|
<Admonition type="note">
|
|
The job must go through the normal queue to reactivate the session.
|
|
</Admonition>
|
|
3. If the maximum timeout value is reached, the session ends and any remaining queued jobs fail. However, any jobs already running will run to completion.
|
|
|
|
The following video illustrates the session basic workflow:
|
|
|
|
<video title="A user starts a session job and becomes the priority user. They submit jobs to the QPU while other users wait. After the prioritized user's session finishes, the next person's jobs can begin processing." className="max-w-auto h-auto" controls>
|
|
<source src="/videos/guides/sessions/demo.mp4" type="video/mp4"></source>
|
|
</video>
|
|
|
|
|
|
|
|
To find the session timeout values, follow the instructions in [Determine session details](/guides/run-jobs-session#session-details). To set the session maximum timeout value, follow the instructions in [Session length.](/guides/run-jobs-session#specify-length)
|
|
|
|
The default timeout settings are listed in the [Maximum execution time](/guides/max-execution-time) guide.
|
|
|
|
For instructions to start a session, see [Run a job in a session](/guides/run-jobs-session).
|
|
|
|
<span id="ends"></span>
|
|
## End a session
|
|
|
|
A session ends in the following circumstances:
|
|
|
|
* The maximum timeout is reached, resulting in the cancelation of all queued jobs.
|
|
* The session is manually canceled, resulting in the cancelation of all queued jobs.
|
|
* The session is manually closed. The session stops accepting new jobs but continues to run queued jobs with priority.
|
|
* If you use Session as a context manager, that is, `with Session()`, the session is automatically closed when the context ends (the same behavior as using `session.close()`).
|
|
|
|
<Admonition type = "note">
|
|
When a session ends, the QPu finishes running any job that is currently running.
|
|
</Admonition>
|
|
|
|
## Usage patterns
|
|
|
|
Sessions are especially useful for algorithms that require classical post-processing, where jobs submitted within the interactive time-out are processed immediately. If you want to submit jobs in a batch instead, see [Run jobs in a batch.](run-jobs-batch)
|
|
|
|
Example: Run an iterative workload that uses the classical SciPy optimizer to minimize a cost function. In this model, SciPy uses the output of the cost function to calculate its next input.
|
|
|
|
```python
|
|
def cost_func(params, ansatz, hamiltonian, estimator):
|
|
# Return estimate of energy from estimator
|
|
|
|
energy = estimator.run(ansatz, hamiltonian, parameter_values=params).result().values[0]
|
|
return energy
|
|
|
|
x0 = 2 * np.pi * np.random.random(num_params)
|
|
|
|
session = Session(backend=backend)
|
|
|
|
# If using qiskit-ibm-runtime earlier than 0.24.0, change `mode=` to `session=`
|
|
estimator = Estimator(mode=session, options={"shots": int(1e4)})
|
|
res = minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method="cobyla")
|
|
|
|
# Close the session because we didn't use a context manager.
|
|
session.close()
|
|
```
|
|
|
|
## Next steps
|
|
|
|
<Admonition type="tip" title="Recommendations">
|
|
- Try an example in the [Quantum approximate optimization algorithm (QAOA)](https://learning.quantum.ibm.com/tutorial/quantum-approximate-optimization-algorithm) tutorial.
|
|
- Review the [Session API](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.Session) reference.
|
|
- Review the execution modes [best practices.](execution-modes#best-practices)
|
|
- Learn how to [run a job in a session.](./run-jobs-session)
|
|
</Admonition> |