Sessions migration guide

docs/api/migration-guides/_toc.json

@@ -44,6 +44,23 @@
           }
         ]
       },
+      {
+        "title": "Qiskit Runtime 0.20 changes",
+        "children": [
+          {
+            "title": "V2 primitives",
+            "url": "/api/migration-guides/v2-primitives"
+          },
+          {
+            "title": "Sessions",
+            "url": "/api/migration-guides/sessions"
+          },
+          {
+            "title": "qiskit_ibm_provider to qiskit_ibm_runtime",
+            "url": "/api/migration-guides/qiskit-runtime-from-provider"
+          }
+        ]
+      },
       {
         "title": "Qiskit 0.44 changes",
         "children": [

docs/api/migration-guides/sessions.mdx

@@ -0,0 +1,91 @@
+---
+title: Execution mode changes
+description: Learn about the changes to execution modes (sessions, batch, and single jobs)
+
+---
+
+<span id="execution-modes"></span>
+
+# Execution mode changes
+
+Jobs can be run as single jobs, sessions, or in a batch: 
+
+- Use **sessions** for iterative workloads.
+- Use **batch mode** to submit multiple primitive jobs simultaneously.
+
+## Best practices
+
+To ensure the most efficient use of the execution modes, the following practices are recommended:  
+
+- Always close your session, either by using a context manager or by specifying `session.close()`.
+- There is a fixed overhead associated with running a job. In general, if your each of your job 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 IQP [Jobs](https://quantum.ibm.com/jobs) page, or you can  query it by using  `qiskit-ibm-runtime` with this command `job.metrics()["usage"]["quantum_seconds"]`
+
+- If each of your jobs consume 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](#divide) or [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, running smaller jobs in parallel might be more cost effective because of reduced wall clock time.
+
+
+## Sessions
+
+Sessions are designed for iterative workloads to avoid queueing delays between each iteration. By default, all sessions now run in *dedicated* mode, so that when running a session, you have near exclusive access to the backend.  Additionally, sessions are now thread safe. That is, you can run multiple workloads within a session. 
+
+<span id="two-vqe"></span>
+### Example: Run two VQE algorithms in a session by using threading
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from qiskit_ibm_runtime import  Session, EstimatorV2 as Estimator
+
+def minimize_thread(estimator, method):
+    minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method=method)
+
+with Session(backend=backend), ThreadPoolExecutor() as executor:
+    # Add tags to differentiate jobs from different workloads.
+    estimator1.options.environment.job_tags = "cobyla"
+    estimator1.options.environment.job_tags = "nelder-mead"
+
+    cobyla_result = executor.submit(minimize_thread, estimator1, "cobyla").result()
+    nelder_mead_result = executor.submit(minimize_thread, estimator2, "nelder-mead").result()
+```
+
+### Extended sessions 
+
+Before this release, sessions were terminated after the active window, as shown in the following image.
+
+![This image shows four jobs.  Between each 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 completes, the active window ends and the session terminates.](/images/api/qiskit-ibm-runtime/SessionTTL.png 'Figure 1: Session behavior prior to extended sessions') 
+
+With extended sessions, the session pauses after the active window ends. The session is resumed if more session jobs exit the queue. 
+
+[This image shows multiple sets of jobs.  Within each set, and 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.  Another set of jobs then starts and jobs continue in a similar manner.](/images/api/qiskit-ibm-runtime/ExtendedSession.png 'Figure 2: Extended sessions')
+
+## Batch
+
+Submit multiple primitive jobs simultaneously. When batching, classical processing is done in parallel. No session jobs can start when batch jobs are being processed. 
+
+<span id="divide"></span>
+### Example: divide a 500-circuit job into five 100-circuit jobs and run them in batch
+```python
+from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler
+
+max_circuits = 100
+jobs = []
+start_idx = 0
+
+with Batch(backend):
+    sampler = Sampler()    
+    while start_idx < len(circuits):
+        end_idx = start_idx + max_circuits  
+        jobs.append(sampler.run([(circuits[start_ids:end_idx],)]))
+        start_idx = end_idx
+```
+
+## Sessions versus batch 
+
+[This image shows multiple sets of jobs.  Within each set, and 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.  Another set of jobs then starts and jobs continue in a similar manner.](/images/api/qiskit-ibm-runtime/SessionVsBatch.png 'Figure 3: Sessions compared to batch')
+
+## Billing
+
+* Single jobs are billed for the quantum time they use in processing. 
+* Sessions are billed for the entire active session time. 

docs/run/_toc.json

@@ -44,6 +44,9 @@
       "title": "Execution modes",
       "children": [
         {
+          "title": "Introduction to execution modes",
+          "url": "/run/execution-modes"
+        },{
           "title": "About sessions",
           "url": "/run/sessions"
         },

docs/run/execution-modes.mdx

@@ -0,0 +1,38 @@
+---
+title: Introduction to execution modes
+description: An overview of the available execution modes in Qiskit Runtime; sessions, batch, and single jobs.
+
+---
+# Introduction to Qiskit Runtime execution modes
+
+There are several ways to run jobs, depending on your needs.
+
+**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.
+
+[**Sessions mode**](sessions): A dedicated window for running 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. See [Run jobs in a session](run-jobs-in-session) 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.
+
+## Best practices
+
+To ensure the most efficient use of the execution modes, the following practices are recommended:  
+
+- Always close your session, either by using a context manager or by specifying `session.close()`.
+- There is a fixed overhead associated with running a job. In general, if your each of your job 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 IQP [Jobs](https://quantum.ibm.com/jobs) page, or you can  query it by using  `qiskit-ibm-runtime` with this command `job.metrics()["usage"]["quantum_seconds"]`
+
+- If each of your jobs consume 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#divide) or [session](run-jobs-in-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, running smaller jobs in parallel might be more cost effective because of reduced wall clock time.
+
+## Sessions versus batch 
+
+[This image shows multiple sets of jobs.  Within each set, and 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.  Another set of jobs then starts and jobs continue in a similar manner.](/images/run/SessionVsBatch.png 'Sessions compared to batch')
+
+## Billing
+
+* Single jobs are billed for the quantum time they use in processing. 
+* Sessions are billed for the entire active session time. 
+* For batched jobs, you are billed for the time the QPU complex is processing your job. 
+

docs/run/run-jobs-batch.mdx

@@ -9,14 +9,18 @@ description: How to run quantum computing jobs in batch mode using Qiskit Runtim
 Batch mode can shorten processing time if all jobs can be provided at the outset. If you want to submit iterative jobs, use [sessions](sessions) instead.  Using batch mode has these benefits:
 
 -  The jobs' classical computation, such as compilation, is run in parallel. Thus, running multiple jobs in a batch is significantly faster than running them serially. 
--  There is no delay between jobs, which can help avoid drift.
+-  There is minimal delay between jobs, which can help avoid drift. 
 
 <Admonition type="note">
     When batching, jobs are not guaranteed to run in the order they are submitted.
 </Admonition>
 
 ![This diagram illustrates jobs submitted in a batch.  It shows five jobs, numbered 0 through 4, in a queue. The jobs are a mix of Estimator and Sampler.](/images/run/batch.png 'Figure 1: Batch execution')
 
+There are multiple ways you can reconfigure your jobs to take advantage of the parallel processing provided by batching.
+
+## Example: Divide a list of circuits into multiple jobs and run them in batch
+
 The following example shows how you can divide up a long list of circuits into multiple jobs and run them as a batch to take advantage of the parallel processing.
 
 ```python
@@ -28,11 +32,23 @@ with Batch(backend) as batch:
         jobs.append(estimator.run(circuits, observables=obs_set))
 ```
 
-For a full example, see the following tutorials:
+<span id="divide"></span>
+## Example: Divide a 500-circuit job into five 100-circuit jobs and run them in batch
 
-## Next steps
+You can run multiple jobs in parallel by submitting multiple jobs in batch execution mode. 
+
+```python
+from qiskit_ibm_runtime import Batch, SamplerV2 as Sampler
+
+max_circuits = 100
+jobs = []
+start_idx = 0
+
+with Batch(backend):
+    sampler = Sampler()    
+    while start_idx < len(circuits):
+        end_idx = start_idx + max_circuits  
+        jobs.append(sampler.run([(circuits[start_ids:end_idx],)]))
+        start_idx = end_idx
+```
 
-<Admonition type="tip" title="Recommendations">
-    - Try the [CHSH inequality](https://learning.quantum.ibm.com/tutorial/chsh-inequality) tutorial.
-    - Try the [Grover's algorithm](https://learning.quantum.ibm.com/tutorial/grovers-algorithm) tutorial.
-</Admonition>

docs/run/run-jobs-in-session.mdx

@@ -142,10 +142,6 @@ print(f"Result2: {job2.result()}")
 session.close()
 ```
 
-<Admonition type="caution" title="When the root job is canceled">
-Note that when you cancel the root job in the session (the job which has the same ID as the session), the session closes and fails any remaining queued jobs in the session.
-</Admonition>
-
 <span id="cancel"></span>
 ## Cancel a session 
 
@@ -203,6 +199,25 @@ with Session(backend=backend):
   </TabItem>
 </Tabs>
 
+<span id="two-vqe"></span>
+## Run two VQE algorithms in a session by using threading
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from qiskit_ibm_runtime import  Session, EstimatorV2 as Estimator
+
+def minimize_thread(estimator, method):
+    minimize(cost_func, x0, args=(ansatz, hamiltonian, estimator), method=method)
+
+with Session(backend=backend), ThreadPoolExecutor() as executor:
+    # Add tags to differentiate jobs from different workloads.
+    estimator1.options.environment.job_tags = "cobyla"
+    estimator1.options.environment.job_tags = "nelder-mead"
+
+    cobyla_result = executor.submit(minimize_thread, estimator1, "cobyla").result()
+    nelder_mead_result = executor.submit(minimize_thread, estimator2, "nelder-mead").result()
+```
+
 <span id="session-status"></span>
 ## Check session status