217 lines
9.1 KiB
Plaintext
217 lines
9.1 KiB
Plaintext
---
|
|
title: Run jobs in a session
|
|
description: How to run a quantum computing job in a Qiskit Runtime session.
|
|
|
|
---
|
|
|
|
# Run jobs in a session
|
|
|
|
There are several ways to set up and use [sessions](sessions). It is recommended that you do not run a session with a single job in it.
|
|
|
|
<Admonition type="note">
|
|
Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead.
|
|
</Admonition>
|
|
|
|
<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>
|
|
|
|
## Set up to use sessions
|
|
|
|
Before starting a session, you must [set up Qiskit Runtime](./install-qiskit) and initialize it as a service:
|
|
|
|
``` python
|
|
from qiskit_ibm_runtime import QiskitRuntimeService, Session, SamplerV2 as Sampler, EstimatorV2 as 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.
|
|
|
|
<Admonition type="note">
|
|
If you open a session but do not submit any jobs to it for 30 minutes, the session automatically closes.
|
|
</Admonition>
|
|
|
|
|
|
**Session class**
|
|
|
|
``` python
|
|
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.
|
|
|
|
``` python
|
|
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()
|
|
```
|
|
|
|
<span id="specify-length"></span>
|
|
## Session length
|
|
|
|
The maximum session time to live (TTL) determines how long a session can run. You can set this value with the `max_time` parameter. This should exceed the longest job's execution time.
|
|
|
|
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.
|
|
|
|
``` python
|
|
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 max TTL or ITTL, follow the instructions in [Determine session details](#session-details) and look for the `max_time`or `interactive_timeout` value, respectively.
|
|
|
|
For more information about these settings, see [Session maximum execution time.](/guides/max-execution-time#session-max-time)
|
|
|
|
<span id="close"></span>
|
|
## 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.
|
|
|
|
``` python
|
|
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()
|
|
```
|
|
|
|
<Admonition type="tip">
|
|
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.
|
|
</Admonition>
|
|
|
|
``` python
|
|
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()
|
|
```
|
|
|
|
<span id="cancel"></span>
|
|
## 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.
|
|
|
|
``` python
|
|
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()
|
|
```
|
|
|
|
<span id="mult-jobs-in-session"></span>
|
|
## 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.
|
|
|
|
```python
|
|
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}")
|
|
```
|
|
|
|
<span id="two-vqe"></span>
|
|
## 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.
|
|
|
|
```python
|
|
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()
|
|
```
|
|
|
|
<span id="session-status"></span>
|
|
## 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.
|
|
|
|
<span id="session-details"></span>
|
|
## Determine session details
|
|
|
|
For a comprehensive overview of a session's configuration and status, use the `session.details() method`.
|
|
|
|
``` python
|
|
from qiskit_ibm_runtime import QiskitRuntimeService, Session, 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
|
|
|
|
<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.
|
|
- Understand the [Job limits](/guides/job-limits) when sending a job to an IBM® QPU.
|
|
</Admonition>
|