Improvements to execution modes docs (#2105)

Improve documentation about execution modes; specifically clarifying the max timeout information --------- Co-authored-by: abbycross <[email protected]>
Qiskit · Oct 14, 2024 · 5865b1c · 5865b1c
1 parent b7e0301
commit 5865b1c
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 61 deletions.
diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json
@@ -365,6 +365,10 @@
               "title": "Introduction to execution modes",
               "url": "/guides/execution-modes"
             },
+            {
+              "title": "Run jobs in a batch",
+              "url": "/guides/run-jobs-batch"
+            },
             {
               "title": "Introduction to sessions",
               "url": "/guides/sessions"
@@ -373,10 +377,6 @@
               "title": "Run jobs in a session",
               "url": "/guides/run-jobs-session"
             },
-            {
-              "title": "Run jobs in a batch",
-              "url": "/guides/run-jobs-batch"
-            },
             {
               "title": "Fixed and dynamic repetition rate execution",
               "url": "/guides/repetition-rate-execution"

diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx
@@ -13,71 +13,63 @@ The `mode` option requires `qiskit-ibm-runtime` 0.24 or later.
 
 **Job mode**: A single primitive request of the estimator or the sampler made without a context manager. Circuits and inputs are packaged as primitive unified blocs (PUBs) and submitted as an execution task on the quantum computer. To run in job mode, specify `mode=backend` when instantiating a primitive. See [Primitives examples](primitives-examples) for examples.
 
-[**Session mode**](sessions): A dedicated window for running a multi-job workload. This allows users to experiment with variational algorithms in a more predictable way and even run multiple experiments simultaneously taking advantage of parallelism in the stack. Use sessions for iterative workloads or experiments that require dedicated access.  To run in session mode, specify `mode=session` when instantiating a primitive or run the job in a session context manager. See [Run jobs in a session](run-jobs-session) for examples.
+[**Batch mode**](run-jobs-batch): A multi-job manager for efficiently running an experiment that is comprised of bundles of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously.   To run in batch mode, specify `mode=batch` when instantiating a primitive or run the job in a batch context manager. See [Run jobs in a batch](run-jobs-batch) for examples.
 
-[**Batch mode**](run-jobs-batch): A multi-job manager for efficiently running an experiment that is comprised of bundle of independent jobs. Use batch mode to submit multiple primitive jobs simultaneously.   To run in batch mode, specify `mode=batch` when instantiating a primitive or run the job in a batch context manager. See [Run jobs in a batch](run-jobs-batch) for examples.
+[**Session mode**](sessions): A dedicated window for running a multi-job workload. This allows users to experiment with variational algorithms in a more predictable way and even run multiple experiments simultaneously, taking advantage of parallelism in the stack. Use sessions for iterative workloads or experiments that require dedicated access.  To run in session mode, specify `mode=session` when instantiating a primitive, or run the job in a session context manager. Learn more about sessions in the [Introduction to sessions,](/guides/sessions) and see [Run jobs in a session](run-jobs-session) for examples.
+
+## Choose batch or sessions mode
+
+Generally, you can use batch mode unless you have workloads that don’t have all inputs ready at the outset.
 
 The differences are summarized in the following table:
 
 |     Mode     |                  Usage                  |                                                                                                        Benefit                                                                                                        |
 |------------|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Job mode     | Quantum computation only.               | Easiest to use when running a small experiment. Might run sooner than batch mode.                                                                                                                                     |
-| Batch mode   | Quantum computation only.               | The entire batch of jobs is scheduled together and there is no additional queuing time for each. Jobs in a batch are usually run close together.                                                                     |
+| Batch mode   | Quantum computation only.               | The entire batch of jobs is scheduled together and there is no additional queuing time for each. Jobs in a batch usually run close together.                                                                     |
 | Session mode | Both classical and quantum computation. | Dedicated and exclusive access to the QPU during the session active window, and no other users’ or QPU jobs can run. This is particularly useful for workloads that don’t have all inputs ready at the outset.  |
 
-<span id="best-practices"></span>
-## Best practices
-
-To ensure the most efficient use of the execution modes, the following practices are recommended:
-
-- Always close your session or batch, either by using a context manager or by specifying `session.close()` or `batch.close()`, respectively.
-- There is a fixed overhead associated with running a job. In general, if each of your jobs uses less than one minute of QPU time, consider combining several into one larger job (this applies to all execution modes). "QPU time" refers to time spent by the QPU complex to process your job.
-
-    A job's QPU time is listed in the **Usage** column on the IBM Quantum Platform [Workloads](https://quantum.ibm.com/workloads) page, or you can  query it by using  `qiskit-ibm-runtime` with this command `job.metrics()["usage"]["quantum_seconds"]`
-
-- If each of your jobs consumes more than one minute of QPU time, or if combining jobs is not practical, you can still run multiple jobs in parallel. Every job goes through both classical and quantum processing. While a QPU can process only one job at a time, up to five classical jobs can be processed in parallel. You can take advantage of this by submitting multiple jobs in [batch](run-jobs-batch#partition) or [session](run-jobs-session#two-vqe) execution mode.
-
-The above are general guidelines, and you should tune your workload to find the optimal ratio, especially when using sessions. For example, if you are using a session to get exclusive access to a backend, consider breaking up large jobs into smaller ones and running them in parallel. This might be more cost effective because it can reduce wall clock time.
-
 <span id="usage"></span>
-## Sessions versus batch usage
+## Batch and session usage calculation
 
-The reported usage is the time a QPU is locked for your workload. Failed or canceled jobs count toward your reported usage in certain circumstances - see the [Failed and canceled jobs](#failed-job) section for details.
+The _usage_ reported on the dashboard or by using the API is the time a QPU is locked for your workload. Failed or canceled jobs count toward your usage in certain circumstances - see the [Failed and canceled jobs](#failed-job) section for details.
 
-* Session usage is the time from when the first job starts until the session goes inactive, is closed, or when its last job completes, whichever happens **last**.
-* Batch usage is the amount of time all jobs spend on the QPU.
 * Single job usage is the quantum time they use in processing.
+* Batch usage is the amount of time all jobs spend on the QPU.
+* Session usage is the time from when the first job starts until the session goes inactive, is closed, or when its last job completes, whichever happens **last**.
 
-To find the usage time for your session or batch, in `qiskit-ibm-runtime` 0.30 or later, run `session.usage()` or `batch.usage()`. If using an older version of `qiskit-ibm-runtime` (>= 0.23 and < 0.30), the usage can be still be found in `session.details()["usage_time"]` and `batch.details()["usage_time"]`.
+To find the usage time for your batch or session, in `qiskit-ibm-runtime` 0.30 or later, run `batch.usage()` or `session.usage()`. If using an older version of `qiskit-ibm-runtime` (>= 0.23 and < 0.30), the usage can be still be found in `session.details()["usage_time"]` and `batch.details()["usage_time"]`.
 
-If you are calling the REST API directly, the usage time is the `elapsed_time` value returned by the `GET /sessions/{id}` endpoint, for both session and batch workloads.
+If you are calling the REST API directly, the usage time is the `elapsed_time` value returned by the `GET /sessions/{id}` endpoint, for both batch and session workloads.
 
-![This image shows multiple sets of jobs.  One set is being run in session mode and the other is being run in batch mode.  For session mode, between each job is the interactive TTL (time to live).  The active window starts when the first job starts and ends after the last job is completed. After the final job of the first set of jobs completes, the active window ends and the session is paused (but not closed).  Another set of jobs then starts and jobs continue in a similar manner. The QPU is reserved for your use during the entire session.  For batch mode, the classical computation part of each job happens simultaneously, then all jobs are sent to the QPU.  The QPU is locked for your use from the time the first job reaches the QPU until the last job is done processing.  There is no gap between jobs where the QPU is idle.](/images/guides/execution-modes/SessionVsBatch.svg 'Sessions compared to batch')
+![This image shows multiple sets of jobs.  One set is being run in batch mode and the other is being run in session mode.  For session mode, between each job is the interactive TTL (time to live).  The active window starts when the first job starts and ends after the last job is completed. After the final job of the first set of jobs completes, the active window ends and the session is paused (but not closed).  Another set of jobs then starts and jobs continue in a similar manner. The QPU is reserved for your use during the entire session.  For batch mode, the classical computation part of each job happens simultaneously, then all jobs are sent to the QPU.  The QPU is locked for your use from the time the first job reaches the QPU until the last job is done processing.  There is no gap between jobs where the QPU is idle.](/images/guides/execution-modes/SessionVsBatch.svg 'Batch compared to sessions')
 
 <span id="failed-job"></span>
-## Failed and canceled jobs
+### Failed and canceled jobs
 
 When a job is failed or canceled, the reported usage is as follows:
 
 * Job or batch mode: the reported usage is the time the QPU was locked for executing your workload until the time it failed or was canceled. Therefore, if the failure or cancellation occurred before the lock, the reported usage is zero. Otherwise, the workload's reported usage is the value that Qiskit Runtime returns as `consumed`. Thus, some failed jobs do not appear in your reported usage and others do.
 
 * Session mode: the reported usage is the wall-clock time from the when the first job started executing in the session until the session terminates, regardless of the number of jobs that fail or are canceled.
 
-<span id="ittl-by-mode"></span>
-## Interactive time to live (ITTL)
+<span id="best-practices"></span>
+## Prepare to use execution modes
 
-The [ITTL](/guides/max-execution-time#session-maximum-execution-time) in batch mode is one second for all instances.
+To ensure the most efficient use of the execution modes, the following practices are recommended:
 
-The ITTL for a session (Premium Plan users only) is 60 seconds, unless there is an instance-specific configuration that dictates a different ITTL.
+- There is a fixed overhead associated with running a job. In general, if each of your jobs uses less than one minute of QPU time, consider combining several into one larger job (this applies to all execution modes). "QPU time" refers to time spent by the QPU complex to process your job.
 
+    A job's QPU time is listed in the **Usage** column on the IBM Quantum Platform [Workloads](https://quantum.ibm.com/workloads) page, or you can  query it by running this command: `job.metrics()["usage"]["quantum_seconds"]` in `qiskit-ibm-runtime`.
 
-| Execution mode | Instance type (Open or Premium Plan) | ITTL |
-| --- | --- | --- |
-| Batch mode | Both Open and Premium Plan | 1 sec |
-| Session mode | Premium Plan | 60 sec* |
+- If each of your jobs consumes more than one minute of QPU time, or if combining jobs is not practical, you can still run multiple jobs in parallel. Every job goes through both classical and quantum processing. While a QPU can process only one job at a time, up to five classical jobs can be processed in parallel. You can take advantage of this by submitting multiple jobs in [batch](run-jobs-batch#partition) or [session](run-jobs-session#two-vqe) execution mode.
 
-*\* Certain Premium Plan instances might be specially configured to have a different ITTL.*
+The above are general guidelines, and you should tune your workload to find the optimal ratio, especially when using sessions. For example, if you are using a session to get exclusive access to a backend, consider breaking up large jobs into smaller ones and running them in parallel. This might be more cost-effective because it can reduce wall clock time.
 
-<Admonition type="note">
-You can also programmatically query the ITTL; see details on the [Maximum execution time](/guides/max-execution-time#session-maximum-execution-time) page.
+## Next steps
+
+<Admonition type="tip" title="Recommendations">
+    - [Run a job in batch mode.](/guides/run-jobs-batch/)
+    - Read the [introduction to sessions.](/guides/sessions)
+    - [Run a job in session mode.](/guides/run-jobs-session)
 </Admonition>
diff --git a/docs/guides/max-execution-time.mdx b/docs/guides/max-execution-time.mdx
@@ -46,21 +46,37 @@ The QPU calculates an appropriate job timeout value based on the input circuits
 
 For example, if you specify `max_execution_time=5000` (approximately 83 minutes), but the QPU determines it should not take more than 5 minutes (300 seconds) to execute the job, then the job is canceled after 5 minutes.
 
+<span id="batch-max-time"></span>
+## Batch maximum execution time
+
+When a batch is started, it is assigned a maximum TTL value. After this TTL is reached, the batch is terminated, any jobs that are already running continue running, and any queued jobs that remain in the batch are put into a failed state. For instructions to set the batch maximum TTL, see [Specify the batch length.](./run-jobs-batch#specify-batch-length)
+
+Batches also have an ITTL value between jobs that cannot be configured. If you don't explicitly close a batch, it is deactivated after the ITTL expires and can be reactivated at any time until it reaches its  maximum TTL.
+
+| Instance type (Open or Premium Plan) | ITTL | Maximum TTL |
+| --- | --- | --- |
+| Both Open and Premium Plan | 1 sec | 10 min |
+
+To determine the ITTL and maximum TTL values for a batch programmatically, use the [`batch.details()`  method](run-jobs-batch#batch-details) and look for the `interactive_timeout` and `max_time` values, respectively.
+
+<span id="session-max-time"></span>
 ## Session maximum execution time
 
-When a session is started, it is assigned a maximum time to live (TTL) value. After this TTL 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-session#specify-length).
+When a session is started, it is assigned a maximum time to live (TTL) value that determines how long a session can run. After this TTL 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.
 
-Sessions also have an interactive time to live (ITTL) value between jobs that cannot be configured. If no session jobs are queued within that window, the session is temporarily deactivated.
+You can set this value with the `max_time` parameter. For instructions, see [Specify the session length.](./run-jobs-session#specify-length)
 
-To determine the maximum TTL and ITTL values for a session, use the [`session.details()` method](run-jobs-session#session-details) and look for the `interactive_timeout` and `max_time` values, respectively.
+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.
 
-## Batch maximum execution time
+| Instance type (Open or Premium Plan) | ITTL | Maximum TTL |
+| --- | --- | --- |
+| Premium Plan | 60 sec* | 8 h* |
+| Open Plan | sessions run in job mode | sessions run in job mode |
 
-When a batch is started, it is assigned a maximum TTL value. After this TTL is reached, the batch is terminated, any jobs that are already running continue running, and any queued jobs that remain in the batch are put into a failed state. For instructions to set the batch maximum time, see [Specify the batch length.](./run-jobs-batch#specify-batch-length)
 
-Batches also have an ITTL value between jobs that cannot be configured. If you don't explicitly close a batch, it is deactivated after the ITTL expires and can be reactivated at any time until it reaches its  maximum TTL (usually 28800 seconds, or 8 hours).
+*\* Certain Premium Plan instances might be configured to have a different value.*
 
-To determine the ITTL and maximum TTL values for a batch, use the [`batch.details()`  method](run-jobs-batch#batch-details) and look for the `interactive_timeout` and `max_time` values, respectively.
+To determine the maximum TTL and ITTL values for a session programmatically, use the [`session.details()` method](run-jobs-session#session-details) and look for the `max_time` and  `interactive_timeout` values, respectively.
 
 ## Other limitations
 

diff --git a/docs/guides/run-jobs-batch.mdx b/docs/guides/run-jobs-batch.mdx
@@ -58,14 +58,18 @@ with Batch(backend=backend):
 <span id="specify-batch-length"></span>
 ## Batch length
 
-You can define the batch's maximum time to live (TTL) 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 batch starts.  When the value is reached, the batch is closed.  Any jobs that are running will finish, but jobs still queued are failed.
+You can define the batch's maximum time to live (TTL) with the `max_time` parameter. This should exceed the longest job's execution time. This timer starts when the batch starts.  When the value is reached, the batch is closed.  Any jobs that are running will finish, but jobs still queued are failed.
 
 ``` python
 with Batch(backend=backend, max_time="25m"):
   ...
 ```
 
-There is also an interactive time to live (ITTL) value of 1 second that cannot be configured.  If no batch jobs are queued within that window, the batch is temporarily deactivated.
+There is also an interactive time to live (ITTL) value that cannot be configured.  If no batch jobs are queued within that window, the batch is temporarily deactivated.
+
+To determine a batch's TTL or ITTL, follow the instructions in [Determine batch details](#batch-details) and look for the `max_time`or `interactive_timeout` value, respectively.
+
+For more information about these settings, see [Batch maximum execution time.](/guides/max-execution-time#batch-max-time)
 
 <span id="close"></span>
 ## Close a batch
@@ -83,7 +87,9 @@ result = job1.result()
 result2 = job2.result()
 ```
 
+<Admonition type="tip">
 If you are not using a context manager, manually close the batch.  If you leave the batch open and submit more jobs to it later, it is possible that the maximum TTL will be reached before the subsequent jobs start running; causing them to be canceled. You can close a batch as soon as you are done submitting jobs to it. When a batch is closed with `batch.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
 batch = Batch(backend=backend)