Skip to content

Commit d36daea

Browse files
committed
Restructure usage page
1 parent d56e6ee commit d36daea

7 files changed

+42
-50
lines changed

docs/guides/_toc.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -408,7 +408,7 @@
408408
"url": "/guides/monitor-job"
409409
},
410410
{
411-
"title": "Estimate job run time",
411+
"title": "Workload usage",
412412
"url": "/guides/estimate-job-run-time"
413413
},
414414
{

docs/guides/choose-execution-mode.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,5 +72,5 @@ In this case, all jobs (which are related but independant) are available at the
7272
<Admonition type="tip" title="Recommendations">
7373
- [Run a job in batch mode.](/guides/run-jobs-batch/)
7474
- [Run a job in session mode.](/guides/run-jobs-session)
75-
- [Estimate job run time.](/guides/estimate-job-run-time)
75+
- [Workload usage.](/guides/estimate-job-run-time)
7676
</Admonition>

docs/guides/estimate-job-run-time.mdx

+36-44
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,43 @@
11
---
2-
title: Estimate job run time
3-
description: Estimate how long a job that uses a primitive will take to run
2+
title: Workload usage
3+
description: Explains what usage is and how to estimeate how long a job that uses a primitive will take to run
44

55
---
66

7-
# Estimate job run time
7+
<span id="usage"></span>
8+
# Workload usage
9+
10+
Usage is a measurement of the amount of time the QPU is locked for your workload, and it is calculated differently, depending on which execution mode you're using.
11+
12+
* 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.
13+
* Batch usage is the sum of quantum time of all jobs in the batch.
14+
* Single job usage is the quantum time the job uses in processing.
15+
16+
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.
17+
18+
Your usage has different impacts, depending on which channel you're using:
19+
20+
- 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.
21+
- 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.
22+
23+
<span id="failed-job"></span>
24+
## Usage for failed and canceled jobs
25+
26+
When a job is failed or canceled, the reported usage is as follows:
27+
28+
* 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.
29+
30+
* 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.
31+
32+
## Determine a workload's actual usage
33+
34+
After a workload has completed, there are several ways to view its actual usage:
35+
36+
- On the IBM Quantum Platform [Workloads table](https://quantum.ibm.com/workloads) in the Usage column. From the Home page, click *View all* on the Recent workloads table. The Usage column shows actual usage for completed workloads.
37+
- Run [`batch.usage()`](/api/qiskit-ibm-runtime/batch#usage) or [`session.usage()`](/api/qiskit-ibm-runtime/session#usage) in `qiskit-ibm-runtime` 0.30 or later. 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"]`.
38+
- Call the [GET usage](/api/runtime/tags/usage#tags__usage) REST API directly. The reported usage is the `elapsed_time` value returned by the `GET /sessions/{id}` endpoint, for both batch and session workloads.
39+
40+
## Estimate workload usage
841

942
After submitting a job to the IBM Quantum&trade; channel, you can see an estimation for how much _quantum time_ the job will take to run by using `job.usage_estimation`. Alternatively, you can [view this information on the IBM Quantum Platform user interface](#view-usage).
1043

@@ -59,47 +92,6 @@ Output:
5992
{'quantum_seconds': 4.1058720028432445}
6093
```
6194

62-
<span id="usage"></span>
63-
## Workload usage
64-
65-
Usage is a measurement of the amount of time the QPU is locked for your workload, and it is calculated differently, depending on which execution mode you're using.
66-
67-
* 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.
68-
* Batch usage is the sum of quantum time of all jobs in the batch.
69-
* Single job usage is the quantum time the job uses in processing.
70-
71-
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.
72-
73-
Your usage has different impacts, depending on which channel you're using:
74-
75-
- 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.
76-
- 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.
77-
78-
<span id="failed-job"></span>
79-
### Usage for failed and canceled jobs
80-
81-
When a job is failed or canceled, the reported usage is as follows:
82-
83-
* 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.
84-
85-
* 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.
86-
87-
### Determine a workload's actual usage
88-
89-
After a workload has completed, there are several ways to view its actual usage:
90-
91-
- On the IBM Quantum Platform [Workloads table](https://quantum.ibm.com/workloads) in the Usage column. From the Home page, click *View all* on the Recent workloads table. The Usage column shows actual usage for completed workloads.
92-
- Run [`batch.usage()`](/api/qiskit-ibm-runtime/batch#usage) or [`session.usage()`](/api/qiskit-ibm-runtime/session#usage) in `qiskit-ibm-runtime` 0.30 or later. 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"]`.
93-
- Call the [GET usage](/api/runtime/tags/usage#tags__usage) REST API directly. The reported usage is the `elapsed_time` value returned by the `GET /sessions/{id}` endpoint, for both batch and session workloads.
94-
95-
<span id="view-usage"></span>
96-
### View the estimated workload (job) usage
97-
98-
After a workload is submitted but before it completes, you can view its estimated usage (how much quantum time the workload will take to run) in two places on IBM Quantum Platform:
99-
100-
- On the [Workloads table](https://quantum.ibm.com/workloads) in the Usage column. From the Home page, click *View all* on the Recent workloads table. The Usage column shows the estimated usage for pending workloads.
101-
- On the workload's details page. From the [Dashboard](https://quantum.ibm.com/) or [Workloads table](https://quantum.ibm.com/workloads), click the ID to open its details page. The estimated usage is shown in the Status timeline.
102-
10395
## Next steps
10496

10597
<Admonition type="tip" title="Recommendations">

docs/guides/execute-on-hardware.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ expectation values of observables corresponding to physical quantities or cost f
5050

5151
### Manage jobs
5252
* [Monitor or cancel a job](./monitor-job)
53-
* [Estimate job run time](./estimate-job-run-time)
53+
* [Workload usage](./estimate-job-run-time)
5454
* [Minimize job run time](./minimize-time)
5555
* [Maximum execution time](./max-execution-time)
5656
* [Job limits](./job-limits)

docs/guides/manage-cost.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ These are the columns relevant to cost:
6060

6161
## Estimate the cost
6262

63-
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.
63+
You can estimate how long a job will run, and therefore its cost, by estimating the job run time. For details, see the [Workload usage](estimate-job-run-time) topic.
6464

6565
## Set up spending notifications
6666

docs/guides/max-execution-time.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,6 @@ For instructions to work with these values, see [Run jobs in a session.](./run-j
7676
## Next steps
7777

7878
<Admonition type="tip" title="Recommendations">
79-
- [Estimate job run time](estimate-job-run-time).
79+
- [Workload usage](estimate-job-run-time).
8080
- Review these tips: [Minimize job run time](minimize-time).
8181
</Admonition>

docs/guides/minimize-time.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,6 @@ There are several ways you can limit the amount of quantum time spent processing
1717
## Next steps
1818

1919
<Admonition type="tip" title="Recommendations">
20-
- [Estimate job run time](estimate-job-run-time).
20+
- [Workload usage](estimate-job-run-time).
2121
- Explore error mitigation in the [Cost functions](https://learning.quantum.ibm.com/course/variational-algorithm-design/cost-functions) course.
2222
</Admonition>

0 commit comments

Comments
 (0)