diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 1c8500746ad..ba1c9f65dce 100644 --- a/docs/guides/_toc.json +++ b/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" diff --git a/docs/guides/error-mitigation-and-suppression-techniques.ipynb b/docs/guides/error-mitigation-and-suppression-techniques.ipynb index 2d23bdd2b21..7f79ac0da16 100644 --- a/docs/guides/error-mitigation-and-suppression-techniques.ipynb +++ b/docs/guides/error-mitigation-and-suppression-techniques.ipynb @@ -243,6 +243,7 @@ "id": "e5dcab7b", "metadata": {}, "source": [ + "\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", diff --git a/docs/guides/execute-on-hardware.mdx b/docs/guides/execute-on-hardware.mdx index c5814114201..e1b43501565 100644 --- a/docs/guides/execute-on-hardware.mdx +++ b/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) diff --git a/docs/guides/execution-modes-rest-api.mdx b/docs/guides/execution-modes-rest-api.mdx index b1562565858..d46d72be9ae 100644 --- a/docs/guides/execution-modes-rest-api.mdx +++ b/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 diff --git a/docs/guides/execution-modes.mdx b/docs/guides/execution-modes.mdx index 2f62a3f09eb..8f411c67b93 100644 --- a/docs/guides/execution-modes.mdx +++ b/docs/guides/execution-modes.mdx @@ -5,73 +5,169 @@ description: An overview of the available execution modes in Qiskit Runtime; ses --- # Introduction to Qiskit Runtime execution modes -There are several ways to run workloads, depending on your needs. +There are several ways to run workloads, depending on your needs. Execution modes determine how your jobs are scheduled, and choosing the right execution mode allows your jobs to run efficiently within your budget. + +## 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](/guides/primitives-examples) for examples. -The `mode` option requires `qiskit-ibm-runtime` 0.24 or later. +The queuing time does not decrease for the first job submitted within a session or batch. Therefore, sessions and batches do not provide any benefits when running a single job. Additionally, sessions and batches do not work on simulators because simulators do not have a queue. + + +## Batch mode + +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. + + + 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. + + +![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') + +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](/guides/run-jobs-batch) for examples. + +## Session mode + +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. 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. + + 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](/guides/run-jobs-session) for examples. + + +Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead. -**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. +## How long do workloads run? + +The amount of time an execution runs depends on the values for maximum execution time (or _time to live_ (TTL)), interactive timeout (or _interactive time to live_ (ITTL)), and, for Qiskit Runtime on IBM Cloud®, the specified Cost limit. + +**Maximum execution time (TTL)** - Determines how long (in _quantum time_) a session or batch can run. This is the smaller of the value set for `max_execution_time` and the QPU-determined job timeout value. Quantum time is the time spent by the QPU complex to process the workload. This timer starts when the first job in the workload starts being processed and continues running until the value is reached. After this value is reached, the workload is terminated, any jobs that are already running continue running, and any queued jobs that remain in the session or batch are put into a failed state. You can set this value with the `max_time` parameter for [batches](/guides/run-jobs-batch#specify-batch-length) or [sessions](/guides/run-jobs-session#specify-length). + +**Interactive timeout (ITTL)** - This value cannot be configured. If no jobs are queued for the active session or batch within that window, the workload is temporarily deactivated. A job submitted to the session or batch reactivates the deactivated workload if the maximum timeout value has not been reached. + +For full details about these values, including how to determine the ITTL value, review the [Maximum execution time guide.](/guides/max-execution-time) + + +The time your workload actively runs is probably different from the amount of wall clock time a workload takes. + + +## Basic workflow + +The basic workflow for batches and sessions is similar: -[**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. +1. The first job in a batch or session enters the normal queue. Note: for batches, the entire batch of jobs is scheduled together. +2. When the first job starts running, the TTL timer starts (and does not stop or pause until the end is reached). +3. The ITTL timer starts after each job is completed. If there are no workload jobs ready within the ITTL window, the workload is temporarily deactivated and normal job selection resumes. A job can reactivate the deactivated workload if the batch or session has not reached its TTL value. + + The job must go through the normal queue to reactivate the workload. + +3. If the TTL value is reached, the workload ends and any remaining queued jobs fail. However, any jobs already running will run to completion. -[**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. +The following video illustrates the session basic workflow, using sessions as an example: + + -## Choose batch or sessions mode +## Choose the right execution mode + +Utility-scale workloads can take many hours to complete, so it is important that both the classical and quantum resources are scheduled efficiently to streamline the execution. Execution modes provide flexibility in balancing the cost and time tradeoff to use resources optimally for your workloads. There are several aspects to consider when choosing which execution mode to use, such as _usage_, overall execution time (TTL), and time between jobs (ITTL). + +The the benefits of each are summarazed below: + +- **Batch** + - The entire batch of jobs is scheduled together and there is no additional queuing time for each. + - 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. +- **Session** + - Dedicated and exclusive access to the QPU during the session active window. + - Can run multiple experiments simultaneously. + - Useful for workloads that don’t have all inputs ready at the outset, for iterative workloads that require dedicated access, and for algorithms that require classical post-processing. +- **Job** + - Easiest to use when running a small experiment. + - Might run sooner than batch mode. + + +### Recommendations and best practices 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: +- Use **batch** mode to submit multiple primitive jobs simultaneously to shorten processing time. +- Use **session** mode for iterative workloads, or if you need dedicated access to the QPU (quantum processing unit). +- Always use **job** mode to submit a single primitive request. +- Because sessions are generally more expensive, it is recommended that you use batch whenever you don't need the additional benefits from using sessions. -| 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 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. | +To ensure the most efficient use of the execution modes, the following practices are recommended: + +- 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. + +- 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](/guides/run-jobs-batch#partition) or [session](/guides/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. -## Batch and session usage calculation +### Usage -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. +Usage is an important consideration when choosing which execution mode to use. It is a measurement of the amount of time the QPU is locked for your workload. -* 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**. +* 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. It includes both classical and quantum time. +* Batch usage is the sum of quantum time of all jobs in the batch. +* Single job usage is the quantum time the job uses in processing. -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"]`. +![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 on the QPU. There is no gap between jobs where the QPU is idle.](/images/guides/execution-modes/SessionVsBatch.svg 'Sessions compared to batch')\ -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. +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. -![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') + +To find the usage time for your batch or session, in `qiskit-ibm-runtime` 0.30 or later, run `batch.usage()` or `session.usage()`. When 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 call 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. + +Your usage has different impacts, depending on which channel you're using: + +- For Qiskit Runtime on IBM Cloud users, the usage determines how much the job costs. See [Manage cost](/guides/manage-cost#manage-cost) for details. +- For IBM Quantum Platform users, this translates to shares. The [fair-share scheduler](/guides/fair-share-scheduler) prioritizes instances with the most shares left. Thus, the higher your usage, the longer your next job stays in the queue. -### Failed and canceled jobs +#### Usage for 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. +* 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. +* 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. - -## Prepare to use execution modes +### Examples -To ensure the most efficient use of the execution modes, the following practices are recommended: +#### Run a quantum variational algorithm -- 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. +Running a quantum variational algorithm typically follows this flow: - 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`. +1. Prepare the ansatz. +2. Evaluate the cost function on a QPU. +3. Take the result from the previous step and run it through a classical optimizer. +4. Adjust the parameters according to the output of (3), then go back to step (2). -- 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. +In this case, if you were using job or batch mode, each job generated by step (2) needs to go back through the queue. This drastically increases the experiment length (wall clock time) due to the queuing time. It could also take longer to converge due to device drift. That is, every iteration is supposed give you a better result, but device drift could make subsequent results worse. -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. +In addition, if you use [PEA](/guides/error-mitigation-and-suppression-techniques#pea) or [PEC](/guides/error-mitigation-and-suppression-techniques#pec), you can learn the noise model once and apply it to subsequent jobs when running in dedicated session. This usually doesn't work with batch or job mode because the noise model could become stale by the time the next iteration runs. + +#### Compare error mitigation settings + +To compare the effects of the available error mitigation methods, you might follow this flow: + +1. Construct a circuit and observable. +2. Submit primitive jobs that use different combinations of error mitigation settings. +3. Plot the results to observe the effects of the various settings. + +In this case, all jobs (which are related but independant) are available at the outset. If you use batch mode, they are scheduled collectively so you only have to wait for them to go through the queue once. Additionally, because the goal is to compare the effects of various error mitigation methods, it's beneficial that they run as closely together as possible. Thus, batch would be a good choice. You _could_ run these jobs in a session, but because sessions are generally more expensive, it is recommended that you use batch whenever you don't need the additional benefits from using sessions. ## Next steps - [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) \ No newline at end of file diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 6550d6c16cb..b3cab6ecd5f 100644 --- a/docs/guides/index.mdx +++ b/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. diff --git a/docs/guides/manage-cost.mdx b/docs/guides/manage-cost.mdx index da219e91eaa..3d8f7c7d953 100644 --- a/docs/guides/manage-cost.mdx +++ b/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. - 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™ Platform Open plan. + 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™ Platform Open plan. ## 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 diff --git a/docs/guides/primitives-examples.ipynb b/docs/guides/primitives-examples.ipynb index 236d8ca14be..1e98beee348 100644 --- a/docs/guides/primitives-examples.ipynb +++ b/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", diff --git a/docs/guides/run-jobs-batch.mdx b/docs/guides/run-jobs-batch.mdx index 93ca7b40e8d..726d8a0ee0b 100644 --- a/docs/guides/run-jobs-batch.mdx +++ b/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 - - -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. - - -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. - - - 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. - - -![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: - - 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® QPU. \ No newline at end of file diff --git a/docs/guides/run-jobs-session.mdx b/docs/guides/run-jobs-session.mdx index afb275409b4..d58a58d80cd 100644 --- a/docs/guides/run-jobs-session.mdx +++ b/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. Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead. - -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. - - ## 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) + +## End a session + +A session ends in the following circumstances: + +* The maximum timeout (TTL) value is reached, resulting in the cancellation of all queued jobs. +* The session is manually canceled, resulting in the cancellation 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()`). + + +When a session ends, the QPU finishes running any job that is currently running. + + -## 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() ``` -## 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. diff --git a/docs/guides/sessions.mdx b/docs/guides/sessions.mdx deleted file mode 100644 index 2c4e26b82fb..00000000000 --- a/docs/guides/sessions.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Sessions -description: An overview of Qiskit Runtime sessions and when to use them. - ---- -# Introduction to Qiskit Runtime sessions - - -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. - - - -Session execution mode is not supported in the Open Plan. Jobs will run in job mode instead. - - -## What is a session? - -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. - - -The queuing time does not decrease for the first job submitted within a session. Therefore, a session does not provide any benefits when running a single job. Additionally, sessions do not work on simulators because simulators do not have a queue. - - -## Advantages of using sessions - -There are several benefits to using sessions: - -- Efficiency: Multiple jobs from a single algorithm run can be run sequentially without interruptions. -- Flexibility: You can submit jobs, check results, and submit new jobs within an active session without needing to start a new one. - -## How sessions work - -The basic workflow for sessions is as follows: - -1. The first job in a session enters the normal queue. -2. When the first job starts running, the _maximum timeout_ clock starts. -2. Subsequent jobs within the session are prioritized over other jobs, reducing wait times. -3. The _interactive timeout_ runs between the jobs in a session. 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 job can reactivate the deactivated session if the session has not reached its maximum timeout value. - - The job must go through the normal queue to reactivate the session. - -3. If the maximum timeout value is reached, the session ends and any remaining queued jobs fail. However, any jobs already running will run to completion. - -The following video illustrates the session basic workflow: - - - - - -To find the session timeout values, follow the instructions in [Determine session details](/guides/run-jobs-session#session-details). To set the session maximum timeout value, follow the instructions in [Session length.](/guides/run-jobs-session#specify-length) - -The default timeout settings are listed in the [Maximum execution time](/guides/max-execution-time) guide. - -For instructions to start a session, see [Run a job in a session](/guides/run-jobs-session). - - -## End a session - -A session ends in the following circumstances: - -* The maximum timeout 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()`). - - -When a session ends, the QPU finishes running any job that is currently running. - - -## 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() -``` - -## Next steps - - - - 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. - - Review the execution modes [best practices.](execution-modes#best-practices) - - Learn how to [run a job in a session.](./run-jobs-session) - \ No newline at end of file diff --git a/docs/migration-guides/qiskit-quantum-instance.mdx b/docs/migration-guides/qiskit-quantum-instance.mdx index a593b8d600a..3e7b7499c6a 100644 --- a/docs/migration-guides/qiskit-quantum-instance.mdx +++ b/docs/migration-guides/qiskit-quantum-instance.mdx @@ -131,10 +131,10 @@ primitives expose a similar setting through their interface: | Measurement error mitigation: `measurement_error_mitigation_cls`, `cals_matrix_refresh_period`, | No | No | Sampler default > M3 (*) | No | | Job management: `job_callback`, `max_job_retries`, `timeout`, `wait` | Does not apply | Does not apply | Sessions, callback (**) | No | -(\*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, see +(\*) For more information about error mitigation and setting options on Qiskit Runtime primitives, see [Advanced Runtime Options](/guides/runtime-options-overview). -(\*\*) For more information on Runtime sessions, see [About Sessions](/guides/sessions). +(\*\*) For more information about sessions, see [Introduction to execution modes.](/guides/execution-modes) ## Code examples diff --git a/docs/migration-guides/qiskit-runtime-from-ibm-provider.mdx b/docs/migration-guides/qiskit-runtime-from-ibm-provider.mdx index dce8c2b42e8..8b43a9b9a38 100644 --- a/docs/migration-guides/qiskit-runtime-from-ibm-provider.mdx +++ b/docs/migration-guides/qiskit-runtime-from-ibm-provider.mdx @@ -16,7 +16,7 @@ Use the updated code to save accounts. The new syntax accepts credentials for -Qiskit Runtime on IBM Cloud or IBM Quantum Platform. For more +Qiskit Runtime on IBM Cloud® or IBM Quantum Platform. For more information on retrieving account credentials, see [Install and set up](/guides/setup-channel). ``` python diff --git a/docs/migration-guides/qiskit-runtime-from-ibmq-provider.mdx b/docs/migration-guides/qiskit-runtime-from-ibmq-provider.mdx index f801343371b..c1449613a4b 100644 --- a/docs/migration-guides/qiskit-runtime-from-ibmq-provider.mdx +++ b/docs/migration-guides/qiskit-runtime-from-ibmq-provider.mdx @@ -7,7 +7,7 @@ description: How to migrate `backend.run()` from qiskit-ibmq-provider to Qiskit This topic describes how to migrate code from the legacy IBMQ provider `qiskit-ibmq-provider` package to use Qiskit Runtime -`qiskit-ibm-runtime`. +`qiskit-ibm-runtime`. ## Changes in Class name and location @@ -60,11 +60,11 @@ Use the updated code to work save accounts. The new syntax accepts credentials for -Qiskit Runtime on IBM Cloud or IBM Quantum Platform. For more +Qiskit Runtime on IBM Cloud® or IBM Quantum Platform. For more information on retrieving account credentials, see [Select and set up an IBM Quantum channel](/guides/setup-channel). ``` python -# IBM Quantum channel; set to default +# IBM Quantum channel; set to default QiskitRuntimeService.save_account(channel="ibm_quantum", token="", overwrite=True, set_as_default=True) ``` @@ -143,7 +143,7 @@ provider = IBMQ.get_provider(project="my_project", group="my_group", hub="my_hub -## Get a backend +## Get a backend Use the updated code to specify a backend. diff --git a/docs/migration-guides/qiskit-runtime.mdx b/docs/migration-guides/qiskit-runtime.mdx index d8b7aa4de62..87f193ca96d 100644 --- a/docs/migration-guides/qiskit-runtime.mdx +++ b/docs/migration-guides/qiskit-runtime.mdx @@ -67,8 +67,9 @@ See the following topics for instructions: - [Get started with Estimator](/guides/get-started-with-primitives#start-estimator) - [Get started with Sampler](/guides/get-started-with-primitives#start-sampler) - - Explore [sessions](/guides/sessions) + - Explore [execution modes](/guides/execution-modes) - [Run a primitive in a session](/guides/run-jobs-session) + - [Run a primitive in a batch](/guides/run-jobs-batch) - Experiment with the [Submit pre-transpiled circuits tutorial](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) \ No newline at end of file diff --git a/docs/migration-guides/sessions.mdx b/docs/migration-guides/sessions.mdx index c584da1ef01..ed83d635b24 100644 --- a/docs/migration-guides/sessions.mdx +++ b/docs/migration-guides/sessions.mdx @@ -10,8 +10,6 @@ description: Learn about the changes to execution modes (sessions, batch, and si Utility-scale workloads can take many hours to complete, so it is important that both the classical and quantum resources are scheduled efficiently to streamline the execution. The improved execution modes provide more flexibility than ever in balancing the cost and time tradeoff to use resources optimally for your workloads. -Workloads can be run as single jobs, sessions, or in a batch: - - Use **session** mode for iterative workloads, or if you need dedicated access to the QPU (quantum processing unit). - Use **batch** mode to submit multiple primitive jobs simultaneously to shorten processing time. - Use **job** mode to submit a single primitive request for quick testing. diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index fd36d64455c..f1cfc03bd3f 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -207,9 +207,6 @@ notifications: - "@beckykd" - "@abbycross" - "`@blakejohnson`" - "docs/guides/sessions": - - "@jyu00" - - "@beckykd" "docs/guides/set-optimization": - "`@nbronn`" - "@beckykd" diff --git a/scripts/config/internal-links.json b/scripts/config/internal-links.json index d849e558ab4..ec26064a37b 100644 --- a/scripts/config/internal-links.json +++ b/scripts/config/internal-links.json @@ -1684,19 +1684,6 @@ "#when-should-i-use-qiskit-serverless" ] }, - { - "path": "docs/guides/sessions.mdx", - "anchors": [ - "#advantages-of-using-sessions", - "#end-a-session", - "#ends", - "#how-sessions-work", - "#introduction-to-qiskit-runtime-sessions", - "#next-steps", - "#usage-patterns", - "#what-is-a-session" - ] - }, { "path": "docs/guides/set-optimization.ipynb", "anchors": [