Restructure execution modes

docs/guides/_toc.json

@@ -381,10 +381,6 @@
               "title": "Run jobs in a batch",
               "url": "/guides/run-jobs-batch"
             },
-            {
-              "title": "Introduction to sessions",
-              "url": "/guides/sessions"
-            },
             {
               "title": "Run jobs in a session",
               "url": "/guides/run-jobs-session"

docs/guides/error-mitigation-and-suppression-techniques.ipynb

@@ -243,6 +243,7 @@
    "id": "e5dcab7b",
    "metadata": {},
    "source": [
+    "<span id=\"pea\"></span>\n",
     "## Probabilistic Error Amplification (PEA)\n",
     "\n",
     "One of the main challenges in ZNE is to accurately amplify the noise affecting the target circuit. Gate folding provides an easy way to perform this amplification, but is potentially inaccurate and might lead to incorrect results.  See the article [\"Scalable error mitigation for noisy quantum circuits produces competitive expectation values\"](https://arxiv.org/pdf/2108.09197), and specifically page 4 of the supplementary information for details. Probabilistic error amplification provides a more accurate approach to error amplification through noise learning.\n",

docs/guides/execute-on-hardware.mdx

@@ -42,7 +42,6 @@ expectation values of observables corresponding to physical quantities or cost f
 
 ### Execution modes
 * [Introduction to execution modes](./execution-modes)
-* [Introduction to sessions](./sessions)
 * [Run jobs in a session](./run-jobs-session)
 * [Run jobs in a batch](./run-jobs-batch)
 * [Fixed and dynamic repetition rate execution](./repetition-rate-execution)

docs/guides/execution-modes-rest-api.mdx

@@ -17,7 +17,7 @@ In job mode, a single primitive request of the Estimator or the Sampler is made
 
 ## Session mode with REST API
 
-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. More details about Sessions can be found in the [documentation](./sessions).
+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. More details about Sessions can be found in the [documentation](./execution-modes).
 
 ### Start a session
 

docs/guides/index.mdx

@@ -50,7 +50,7 @@ With Qiskit Runtime you can choose to run your quantum programs on IBM Quantum h
 Qiskit Runtime is designed to use additional classical and quantum compute resources, including techniques such as error suppression and error mitigation, to return a higher-quality result from executing quantum circuits on quantum processors. Examples include dynamical decoupling for error suppression, and readout mitigation and zero-noise extrapolation (ZNE) for error mitigation. Learn how to configure these options on the [Configure error mitigation](./configure-error-mitigation) page.
 
 
-Qiskit Runtime also includes three types of execution modes for running your quantum program on IBM hardware: _Job_, _Session_, and _Batch_, each of which have different use cases and implications for the quantum job queue. A Job is a single query to a primitive that can be run over a specified number of shots. [Sessions](./sessions) allow you to efficiently run multiple jobs in iterative workloads on quantum computers. [Batch mode](./run-jobs-batch) allows you to submit all your jobs at once for parallel processing.
+Qiskit Runtime also includes three types of execution modes for running your quantum program on IBM hardware: [_Job_, _Session_, and _Batch_,](/guides/execution-modes) each of which have different use cases and implications for the quantum job queue. A Job is a single query to a primitive that can be run over a specified number of shots. Sessions allow you to efficiently run multiple jobs in iterative workloads on quantum computers. Batch mode allows you to submit all your jobs at once for parallel processing.
 
 To quickly install Qiskit Runtime, run the following command
 ```bash
@@ -79,7 +79,7 @@ pip install qiskit_serverless
 ## Qiskit Functions
 
 Qiskit Functions (`qiskit-ibm-catalog.QiskitFunctionsCatalog`) are abstracted services designed to accelerate algorithm discovery and application prototyping. Explore the [Qiskit Functions Catalog](https://quantum.ibm.com/functions), including:
- 
+
 - **Circuit functions**: Services that include transpilation, error suppression, error mitigation, and post-processing techniques that take abstract circuits and desired measurement observables as input. With Circuit functions, users can discover new algorithms and applications without needing to manage transpilation or quantum hardware performance.
 - **Application functions**: Services that include entire quantum workflows, from mapping classical to quantum, optimizing for hardware, execution on hardware, and post-processing. Users can prototype industry applications with domain-familiar inputs and outputs.
 

docs/guides/manage-cost.mdx

@@ -9,7 +9,7 @@ description: How to manage costs of running jobs on QPUs when using the Standard
 The IBM Cloud® Quantum Standard plan is not free, except when running jobs on simulators. Use the information in this topic to help you understand how much you’re paying and how to limit your costs.
 
 <Admonition type="note">
-  The information in this topic only applies to those who are using the Standard plan for Qiskit Runtime on IBM Cloud.  There are no costs associated with IBM Quantum&trade; Platform Open plan.
+  The information in this topic only applies to those who are using the Standard plan for Qiskit Runtime on IBM Cloud&reg;.  There are no costs associated with IBM Quantum&trade; Platform Open plan.
 </Admonition>
 
 ## Set a cost limit
@@ -44,7 +44,7 @@ These are the fields relevant to cost:
 
 - **Billing cycle usage**: The amount of _quantum time_ used by this instance during the current billing cycle. Quantum time is the duration a QPU is committed to fulfilling a user request.
 - **Billing cycle cost**: The total cost of running jobs during the current billing cycle.
-- **Total usage**: The amount of quantum time used by this instance since it was created. 
+- **Total usage**: The amount of quantum time used by this instance since it was created.
 - **Total cost**: The total cost of running jobs on this instance since it was created. Only administrators can set this value.
 
 You can view your billing cycle on the [Billing and usage page](https://cloud.ibm.com/billing).
@@ -60,7 +60,7 @@ These are the columns relevant to cost:
 
 ## Estimate the cost
 
-You can estimate how long a job will run, and therefore its cost, by estimating the job run time.  For details, see the [Estimate job run time](estimate-job-run-time) topic.  
+You can estimate how long a job will run, and therefore its cost, by estimating the job run time.  For details, see the [Estimate job run time](estimate-job-run-time) topic.
 
 ## Set up spending notifications
 

docs/guides/primitives-examples.ipynb

@@ -59,7 +59,7 @@
     "isa_circuit = pm.run(circuit)\n",
     "isa_observable = observable.apply_layout(isa_circuit.layout)\n",
     "\n",
-    "estimator = Estimator(backend)\n",
+    "estimator = Estimator(mode=backend)\n",
     "job = estimator.run([(isa_circuit, isa_observable)])\n",
     "result = job.result()\n",
     "\n",
@@ -440,7 +440,7 @@
     "pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
     "isa_circuits = pm.run(circuits)\n",
     "\n",
-    "sampler = Sampler(backend)\n",
+    "sampler = Sampler(mode=backend)\n",
     "job = sampler.run(isa_circuits)\n",
     "result = job.result()\n",
     "\n",

docs/guides/run-jobs-batch.mdx

@@ -6,22 +6,7 @@ description: How to run quantum computing jobs in batch mode using Qiskit Runtim
 
 # Run jobs in a batch
 
-
-<Admonition type="caution" title="Important">
-The way batches 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, batch calls made in earlier versions of these packages will fail.
-</Admonition>
-
-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 usually minimal delay between jobs, which can help avoid drift.
--  If you partition your workload into multiple jobs and run them in batch mode, you can get results from individual jobs, which makes them more flexible to work with.  For example, if a job's results don't meet your expectations, you can cancel the remaining jobs. Also, if one job fails, you can re-submit it instead of re-running the entire workload.
-
-<Admonition type="note">
-    When batching, jobs are not guaranteed to run in the order they are submitted. Also, while your batch jobs will run as closely together as possible, they don't get exclusive access to the backend. Therefore, your batch jobs might run in parallel with other users' jobs if there is enough processing capacity on the QPU. Additionally, QPU calibration jobs could run between the batched jobs.
-</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/guides/batch.avif 'Figure 1: Batch execution')
+Use batch mode to submit multiple primitive jobs simultaneously. Following are examples of working with batches.
 
 ## Open a batch
 
@@ -153,7 +138,7 @@ with Batch(backend=backend) as batch:
 
 
 <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.
+  - Try an example in the [Combine error mitigation options with the estimator primitive](https://learning.quantum.ibm.com/tutorial/combine-error-mitigation-options-with-the-estimator-primitive) tutorial.
   - Review the [Batch API](/api/qiskit-ibm-runtime/qiskit_ibm_runtime.Batch) reference.
   - Understand the [Job limits](/guides/job-limits) when sending a job to an IBM&reg; QPU.
 </Admonition>

docs/guides/run-jobs-session.mdx

@@ -6,16 +6,12 @@ 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.
+There are several ways to set up and use [sessions](/guides/execution-modes).  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:
@@ -26,6 +22,32 @@ from qiskit_ibm_runtime import QiskitRuntimeService, Session, SamplerV2 as Sampl
 service = QiskitRuntimeService()
 ```
 
+## 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()
+```
+
+
 ## Open a session
 
 You can open a runtime session by using the context manager `with Session(...)` or by initializing the `Session`
@@ -78,8 +100,22 @@ To determine a session's max TTL or ITTL, follow the instructions in [Determine
 
 For more information about these settings, see [Session maximum execution time.](/guides/max-execution-time#session-max-time)
 
+<span id="ends"></span>
+## End a session
+
+A session ends in the following circumstances:
+
+* The maximum timeout (TTL) value 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>
+
 <span id="close"></span>
-## Close a session
+### 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.
 
@@ -113,7 +149,7 @@ session.close()
 ```
 
 <span id="cancel"></span>
-## Cancel a session
+### 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.