diff --git a/docs/run/max-execution-time.mdx b/docs/run/max-execution-time.mdx index 987c7a5007..70171ba925 100644 --- a/docs/run/max-execution-time.mdx +++ b/docs/run/max-execution-time.mdx @@ -6,7 +6,7 @@ description: Describes how long a Qiskit Runtime job or session can run. # Maximum execution time -To ensure fairness and help control costs, there is a maximum amount of time each Qiskit Runtime job and session can run. If a job exceeds this time limit, it is forcibly canceled and a `RuntimeJobMaxTimeoutError` exception is raised. If a session exceeds its limits, any queued jobs are cancelled but any jobs that are already running are not. +To ensure fairness and help control costs, there is a maximum amount of time each Qiskit Runtime job and session can run. If a job exceeds this time limit, it is forcibly canceled and a `RuntimeJobMaxTimeoutError` exception is raised. If a session exceeds its limits, any queued jobs are canceled but any jobs that are already running are not. ## Job maximum execution time @@ -46,38 +46,11 @@ print(f"Quantum time used by job {job.job_id()} was {job.metrics()['usage']['qua The system calculates an appropriate job timeout value based on the input circuits and options. This system-calculated timeout is capped at 3 hours to ensure fair device usage. If a `max_execution_time` is also specified for the job, the lesser of the two values is used. -For example, if you specify `max_execution_time=5000` (approximately 83 minutes), but the system determines it should not take more than 5 minutes (300 seconds) to execute the job, then the job is cancelled after 5 minutes. +For example, if you specify `max_execution_time=5000` (approximately 83 minutes), but the system determines it should not take more than 5 minutes (300 seconds) to execute the job, then the job is canceled after 5 minutes. - ## Session maximum execution time -When a session is started, it is assigned a maximum session timeout value. After this timeout is reached, the session is terminated, any jobs that are already running continue running, and any queued jobs that remain in the session are put into a failed state. You can set the maximum session timeout value using the `max_time` parameter: - -```python -# Set the session max time -with Session(max_time="1h"): - ... -``` - -Additionally, there is a 5-minute *interactive* timeout value. If there are no session jobs queued within that window, the session is temporarily deactivated and normal job selection resumes. During job selection, if the job scheduler gets a new job from the session and its maximum timeout value has not been reached, the session is reactivated until its maximum timeout value is reached. - - - The timer for the session’s `max_time` timer is not paused during any temporary deactivation periods. - - -### Defaults - -If you don't specify a session `max_time`, the system defaults are used: - - -| User account type | Primitive programs | Private programs | -| ----------------- | ------------------ | ---------------- | -| Premium | 8h | 8h | -| Open | 15 min | N/A | - - - A *premium user* here means a user who has access to backends in providers other than ibm-q/open/main. - +When a session is started, it is assigned a maximum session timeout value. After this timeout is reached, the session is terminated, any jobs that are already running continue running, and any queued jobs that remain in the session are put into a failed state. For instructions to set the session maximum time, see [Specify the session length](run-jobs-in-session#specify-length). ## Other limitations diff --git a/docs/run/monitor-job.mdx b/docs/run/monitor-job.mdx index 85e4078638..4de9de1886 100644 --- a/docs/run/monitor-job.mdx +++ b/docs/run/monitor-job.mdx @@ -20,6 +20,7 @@ Use the job instance to check the job status or retrieve the results by calling | job.status() | Check the job status. | | job = service.job(\) | Retrieve a job you previously submitted. This call requires the job ID. | + ## Retrieve job results at a later time Call `service.job(\)` to retrieve a job you previously submitted. If you don’t have the job ID, or if you want to retrieve multiple jobs at once; including jobs from retired systems, call `service.jobs()` with optional filters instead. See [QiskitRuntimeService.jobs](../api/qiskit-ibm-runtime/qiskit_ibm_runtime.QiskitRuntimeService#jobs). diff --git a/docs/run/run-jobs-in-session.mdx b/docs/run/run-jobs-in-session.mdx index 0a8015e74e..d422e0e62a 100644 --- a/docs/run/run-jobs-in-session.mdx +++ b/docs/run/run-jobs-in-session.mdx @@ -46,7 +46,7 @@ sampler = Sampler(session=session) **Context manager** -The context manager automatically opens a session for you. A session is +The context manager automatically opens and closes session for you. A session is started when the first primitive job in this context manager starts (not when it is queued). Primitives created in the context automatically use that session. Example: @@ -83,6 +83,7 @@ with Session(backend=backend): ... ``` + ## Specify the session length When a session is started, it is assigned a maximum session timeout @@ -95,7 +96,7 @@ You can configure the maximum session timeout value through the (int) or a string, like "2h 30m 40s". This value has to be greater than the `max_execution_time` of the job and less than the system's `max_time`. The default value is the system's -`max_time`. See [What is the maximum execution time for a Qiskit Runtime job?](max-execution-time) to determine the +`max_time`. See [Determine session details](#session-details) to determine the system limit. When setting the session length, consider how long each job within the @@ -108,21 +109,53 @@ with Session(service=service, backend=backend, max_time="25m"): ... ``` -There is also an interactive timeout value (ITTL, or interactive time to live) that cannot be configured. For premium accounts, the ITTL is 5 min, and for open plan accounts, the ITTL is 2 sec. If no session jobs are queued within that window, the session is temporarily deactivated. For more details about session length and timeout, see [How long a session stays active](sessions#active). +There is also an interactive timeout value (ITTL, or interactive time to live) that cannot be configured. If no session jobs are queued within that window, the session is temporarily deactivated. For more details about session length and timeout, see [How long a session stays active](sessions#active). To determine a session's ITTL, follow the instructions in [Determine session details](#session-details) and look for the `interactive_timeout` value. ## Close a session -When jobs are all done, it is recommended that you use -`session.close()` to close the session. This allows the +With `qiskit-ibm-runtime` 0.13 or later releases, when the session context manager is exited, the session is put into `In progress, not accepting new jobs` status. This means that the session will finish 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, +therefore reducing the average job queueing time. You cannot submit jobs to a +closed session. + +This behavior exists in `qiskit-ibm-runtime` 0.13 or later releases only. Previously, `session.close()` **canceled** the session. + +``` python +with Session(service=service, backend=backend) as session: + estimator = Estimator() + job = estimator.run(...) + +# The session is no longer accepting jobs but the submitted job will run to completion +result = job.result() +``` + + +## Cancel a session + +If a session is canceled, the session is put into `Closed` status. 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. + +### For Qiskit runtime releases 0.13 or later + +Use the `session.cancel()` method to cancel a session. + +``` python +with Session(service=service, 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() +``` + +### For Qiskit runtime releases before 0.13 + +Use the `session.close()` method to cancel a session. This allows the scheduler to run the next job without waiting for the session timeout, therefore making it easier for everyone. You cannot submit jobs to a closed session. - - Close a session only after all session jobs **complete**, rather than immediately after they have all been submitted. Session jobs that are not completed will fail. - - ``` python with Session(service=service, backend=backend) as session: @@ -131,9 +164,11 @@ with Session(service=service, backend=backend) as session: # Do not close here, the job might not be completed! result = job.result() # Reaching this line means that the job is finished. + # This close() method would fail all pending jobs. session.close() ``` + ## Invoke multiple primitives in a session You are not restricted to a single primitive function within a session. In this section we will show you an example of using multiple primitives. @@ -181,6 +216,54 @@ with Session(backend=backend): print(f">>> Expectation value from the estimator job: {estimator_job.result().values[0]}") ``` + +## Query session status + +You can query the status of a session using `session.status()`. You can also view a session's status on the Jobs page for your channel. + +Session status can be one of the following: + +- `Pending`: 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`: Session is active and accepting new jobs. +- `In progress, not accepting new jobs`: Session is active but not accepting new jobs. Job submission to the session will be rejected, but outstanding session jobs will run to completion. The session will be automatically closed once all jobs finish. +- `Closed`: Session maximum timeout value has been reached, or session was explicitly closed. + + +## Determine session details + +You can find details about a session by using the `session.details()` method, from the [Quantum Platform Jobs page](https://quantum-computing.ibm.com/jobs), or from the IBM Cloud Jobs page, which you access from your [Instances page](https://cloud.ibm.com/quantum/instances). From the session details you can determine the [maximum](#max-ttl) and [interactive](#ttl) time to live (TTL) values, its status, whether it's currently accepting jobs, and more. + +Example: + +``` python +from qiskit_ibm_runtime import QiskitRuntimeService + +service = QiskitRuntimeService() + +with Session(service=service, backend="ibmq_qasm_simulator") as session: + estimator = Estimator() + job = estimator.run(circuit, observable) + print(session.details()) +``` + +Output: + +``` text +{ +'id': 'cki5d18m3kt305s4pndg', + 'backend_name': 'ibm_algiers', + 'interactive_timeout': 300, # This is the interactive timeout, in seconds + 'max_time': 28800, # This is the maximum session timeout, in seconds + 'active_timeout': 28800, + 'state': 'closed', + 'accepting_jobs': True, + 'last_job_started': '2023-10-09T19:37:42.004Z', + 'last_job_completed': '2023-10-09T19:38:10.064Z', + 'started_at': '2023-10-09T19:37:42.004Z', + 'closed_at': '2023-10-09T19:38:39.406Z' +} +``` + ## Full example In this example, we start a session, run an Estimator job, and output @@ -203,8 +286,6 @@ with Session(service=service, backend="ibmq_qasm_simulator") as session: estimator = Estimator(options=options) job = estimator.run(circuit, observable) result = job.result() - # Close the session only if all jobs are finished, and you don't need to run more in the session - session.close() display(circuit.draw("mpl")) print(f" > Observable: {observable.paulis}") diff --git a/docs/run/sessions.mdx b/docs/run/sessions.mdx index ddb7afea7a..6caeb5a3df 100644 --- a/docs/run/sessions.mdx +++ b/docs/run/sessions.mdx @@ -1,6 +1,6 @@ --- title: Sessions -description: Describes what sessions are. +description: Describes what sessions are. --- @@ -63,62 +63,27 @@ already running. Internal systems jobs such as calibration have priority over session jobs. -## Iterations and batching - -Sessions can be used for iterative or batch execution. - -### Iterative - -Any session job submitted within the interactive timeout, also known as interactive time to live (ITTL), is processed immediately. This allows some time for variational algorithms, such as VQE, to perform classical post-processing. - -- The quantum device is locked to the session user unless the ITTL is reached. -- Post-processing could be done anywhere, such as a personal computer, cloud service, or an HPC environment. - -![Iterative session execution diagram.](/images/run/iterative.png 'Figure 2: Iterative session execution') - -### Batch - -Ideal for running experiments closely together to avoid device drifts, -that is, to maintain device characterization. - -- Suitable for batching many jobs together. -- Jobs that fit within the maximum session time run back-to-back on - hardware. - - - When batching, jobs are not guaranteed to run in the order they are submitted. - - -![Batch session execution diagram.](/images/run/batch.png 'Figure 3: Batch session execution') - - -## How long a session stays active - The length of time a session is active is controlled by the *maximum session timeout* (`max_time`) value and the *interactive timeout value* (ITTL, or interactive time to live). The `max_time` timer starts when the session becomes active - that is, when the first job runs, not when it is queued. It does not stop if a session becomes inactive. The ITTL timer starts each time a session job finishes. + ## Maximum session timeout When a session is started, it is assigned a *maximum session timeout* value. You can set this value by using the `max_time` parameter, which can be greater than the program's `max_execution_time`. For -instructions, see [Run a primitive in a session](run-jobs-in-session). +instructions, see [Run jobs in a session](run-jobs-in-session). -If you do not specify a timeout value, it is the smaller of these -values: +If you do not specify a timeout value, it is set to the system limit. -- The system limit -- The `max_execution_time` defined by the program - -See [What is the maximum execution time for a Qiskit Runtime job?](max-execution-time) to determine the system limit and -the `max_execution_time` for primitive programs. +To find the maximum session timeout value for a session, follow the instructions in [Determine session details](run-jobs-in-session#session-details). ## Interactive timeout value -Every session has an *interactive timeout value* (ITTL, or interactive time to live) of five minutes for premium accounts and two seconds for open plan accounts. The ITTL cannot be configured. If there are no session jobs queued within the +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 deactivated session can be resumed if it has not reached its maximum timeout value. The session is resumed when a @@ -132,18 +97,74 @@ words, a deactivated session does not block the creation of other sessions. Jobs from this new session would then take priority until it is deactivated or closed, at which point normal job selection resumes. +To find the interactive timeout value for a session, follow the instructions in [Determine session details](run-jobs-in-session#session-details). + ## What happens when a session ends -A session ends by reaching its maximum timeout value or when it is -manually closed by the user. Do not close a session until all jobs -**complete**. See [Close a session](run-jobs-in-session#close) for details. After a session is closed, the following occurs: +A session ends by reaching its maximum timeout value, when it is [closed](run-jobs-in-session#close), or when it is canceled by using the `session.cancel()` method. What happens to unfinished session jobs when the session ends depends on how it ended: + + + Previously, `session.close()` **canceled** the session. Starting with `qiskit-ibm-runtime` 0.13, `session.close()` **closes** the session. The `session.cancel()` method was added in `qiskit-ibm-runtime` 0.13. + + +If the maximum timeout value was reached: + - Any jobs that are already running continue to run. + - Any queued jobs remaining in the session are put into a failed state. + - No further jobs can be submitted to the session. + - The session cannot be reopened. + +If the maximum timeout value has not been reached: + +- When using `qiskit-ibm-runtime` 0.13 or later releases: + - If a session is closed: + - Session status becomes "In progress, not accepting new jobs". + - New job submissions to the session is rejected. + - Queued or running jobs continue to run. + - The session cannot be reopened. + - If a session is canceled: + - Session status becomes "Closed." + - Running jobs continue to run. + - Queued jobs are put into a failed state. + - The session cannot be reopened. + +- When using Qiskit Runtime releases before 0.13: + - Any jobs that are already running continue to run. + - Any queued jobs remaining in the session are put into a failed state. + - No further jobs can be submitted to the session. + - The session cannot be reopened. + +## Different ways of using sessions + +Sessions can be used for iterative or batch execution. + +### Iterative + +Any session job submitted within the interactive timeout, also known as interactive time to live (ITTL), is processed immediately. This allows some time for variational algorithms, such as VQE, to perform classical post-processing. -- Any jobs that are already running continue to run. -- Any queued jobs remaining in the session are put into a failed state. -- No further jobs can be submitted to the session. -- The session cannot be reopened. +- The quantum device is locked to the session user unless the ITTL is reached. +- Post-processing could be done anywhere, such as a personal computer, cloud service, or an HPC environment. + +![Iterative session execution diagram.](/images/run/iterative.png 'Figure 2: Iterative session execution') + + There might be a limit imposed on the ITTL value depending on whether your hub is Premium, Open, and so on. + + +### Batch + +Ideal for running experiments closely together to avoid device drifts, +that is, to maintain device characterization. + +- Suitable for batching many jobs together. +- Jobs that fit within the maximum session time run back-to-back on + hardware. + + + When batching, jobs are not guaranteed to run in the order they are submitted. + + +![Batch session execution diagram.](/images/run/batch.png 'Figure 3: Batch session execution') ## Sessions and reservations @@ -157,9 +178,19 @@ recommend that you set a realistic `max_time` value. ![Diagram showing which job runs next in the queue.](/images/run/jobs-failing.png 'Figure 4: Job selection diagram') +## Summary + +- Jobs within an active session take priority over other queued jobs. +- A session becomes active when its first job starts running. +- A session stays active until one of the following happens: + - Its maximum timeout value is reached. In this case all queued jobs are cancelled, but running jobs will finish. + - Its interactive timeout value is reached. In this case the session is deactivated but can be resumed if another session job starts running. + - The session is closed or cancelled. This can be done using the corresponding methods or upon exiting a session context. +- Sessions can be used for iterative or batch execution. + ## Next steps - - [Run a primitive in a session.](./primitives-examples#leverage-sessions-and-advanced-options) - - See sessions at work in the [VQE tutorial.](https://learning.quantum-computing.ibm.com/tutorial/variational-quantum-eigensolver-using-estimator-primitive-and-sessions) + - [Run a job in a session.](run-jobs-in-session) + - See sessions at work in the [VQE tutorial.](https://learning.quantum-computing.ibm.com/tutorial/variational-quantum-eigensolver-using-estimator-primitive-and-sessions).