196 lines
11 KiB
Plaintext
196 lines
11 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "3fdd7eec-a38a-4835-9fbc-9e15b09c17d2",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Workload usage"
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "720c96d9-4903-4eea-ae7a-19c34208150b",
|
|
"metadata": {
|
|
"tags": [
|
|
"version-info"
|
|
]
|
|
},
|
|
"source": []
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"id": "46a0a6e0-dee7-4ac9-91b2-399e7a51623f",
|
|
"metadata": {},
|
|
"source": [
|
|
"<span id=\"usage\"></span>\n",
|
|
"\n",
|
|
"\n",
|
|
"<LegacyContent>\n",
|
|
"<Admonition type=\"note\">\n",
|
|
"This documentation is relevant to IBM Quantum® Platform Classic. If you need the newer version, go to the new [IBM Quantum Platform documentation.](https://quantum.cloud.ibm.com/docs/guides/estimate-job-run-time)\n",
|
|
"</Admonition>\n",
|
|
"</LegacyContent>\n",
|
|
"<CloudContent>\n",
|
|
"<Admonition type=\"note\">\n",
|
|
"This documentation is relevant to the new IBM Quantum® Platform. If you need the previous version, return to the [IBM Quantum Platform Classic documentation.](https://docs.quantum.ibm.com/guides/estimate-job-run-time)\n",
|
|
"</Admonition>\n",
|
|
"</CloudContent>\n",
|
|
"\n",
|
|
"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.\n",
|
|
"\n",
|
|
"* 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 (time spent by the QPU complex to process your job).\n",
|
|
"* Batch usage is the sum of quantum time of all jobs in the batch.\n",
|
|
"* Single job usage is the quantum time the job uses in processing.\n",
|
|
"\n",
|
|
"<LegacyContent>\n",
|
|
"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.\n",
|
|
"</LegacyContent>\n",
|
|
"<CloudContent>\n",
|
|
"The reported usage 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.\n",
|
|
"\n",
|
|
"For paid plan users, usage determines how much the workload costs. See [Manage cost](/docs/guides/manage-cost) for details.\n",
|
|
"</CloudContent>\n",
|
|
"\n",
|
|
"<LegacyContent>\n",
|
|
"Your usage has different impacts, depending on which channel you're using:\n",
|
|
"\n",
|
|
"- For Qiskit Runtime on IBM Cloud® users, the usage determines how much the job costs. See [Manage cost](/docs/guides/manage-cost) for details.\n",
|
|
"- For IBM Quantum® Platform users, this translates to shares. The [fair-share scheduler](/docs/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.\n",
|
|
"</LegacyContent>\n",
|
|
"\n",
|
|
"<span id=\"failed-job\"></span>\n",
|
|
"## Usage for failed and canceled jobs\n",
|
|
"When a job is failed or canceled, the reported usage is as follows:\n",
|
|
"\n",
|
|
"* 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 amount of usage before the workload failed or was canceled. Thus, some failed jobs do not appear in your reported usage and others do.\n",
|
|
"\n",
|
|
"* Session mode: The reported usage is the wall-clock time from when the first job started executing in the session until the session terminates, regardless of the number of jobs that fail or are canceled.\n",
|
|
"\n",
|
|
"<span id=\"view-usage\"></span>\n",
|
|
"## Determine a workload's actual usage\n",
|
|
"\n",
|
|
"After a workload has completed, there are several ways to view its actual usage:\n",
|
|
"\n",
|
|
"- Run [`batch.usage()`](/docs/api/qiskit-ibm-runtime/batch#usage) or [`session.usage()`](/docs/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\"]`.\n",
|
|
"<LegacyContent>\n",
|
|
"- Call the [GET usage](/docs/api/runtime/tags/usage#tags__usage) REST API directly to see the total usage across all workloads for your account.\n",
|
|
"</LegacyContent>\n",
|
|
"- Use [`GET /sessions/{id}`](/docs/api/runtime/tags/sessions#tags__sessions__operations__GetSessionDetailsExtendedController_getSessionDetails) to see usage for a specific batch or session.\n",
|
|
"- Use [`GET /jobs/{id}`](/docs/api/runtime/tags/jobs#tags__jobs__operations__GetJobByIdController_getJobById) to see usage for a single job.\n",
|
|
"\n",
|
|
"<CloudContent>\n",
|
|
"<span id=\"instance-usage\"></span>\n",
|
|
"## View instance usage\n",
|
|
"\n",
|
|
"You can view an instance's usage on the [Instances](https://quantum.cloud.ibm.com/instances) page, or, for those with the proper authority, the [Analytics](https://quantum.cloud.ibm.com/analytics) page. Note that the pages might show different usage numbers because they calculate usage differently.\n",
|
|
"\n",
|
|
"The Instances page shows real-time usage for the last 28 days (rolling), up to the current time on the current day. The Analytics page usage is re-calculated hourly and includes the last 28 full days; that is, it shows usage from 00:00 28 days ago to today, at the top of the hour.\n",
|
|
"\n",
|
|
"</CloudContent>\n",
|
|
"<LegacyContent>\n",
|
|
"\n",
|
|
"## Estimate workload usage\n",
|
|
"\n",
|
|
"After submitting a job to the IBM Quantum channel, you can see an estimation for how much _quantum time_ the job will take to run by using `job.usage_estimation`. Quantum time is the duration, in seconds, a QPU is committed to fulfilling a user request.\n",
|
|
"\n",
|
|
"Alternatively, you can view this information on IBM Quantum Platform by opening the job details.\n",
|
|
"\n",
|
|
"<Admonition type=\"note\">\n",
|
|
"This only applies to jobs that use primitives.\n",
|
|
"</Admonition>\n",
|
|
"\n",
|
|
"Example:\n",
|
|
"\n",
|
|
"```python\n",
|
|
"from qiskit import QuantumCircuit\n",
|
|
"from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler\n",
|
|
"from qiskit.transpiler import generate_preset_pass_manager\n",
|
|
"\n",
|
|
"service = QiskitRuntimeService()\n",
|
|
"\n",
|
|
"# Create a new circuit with two qubits (first argument) and two classical\n",
|
|
"# bits (second argument)\n",
|
|
"qc = QuantumCircuit(2, 2)\n",
|
|
"\n",
|
|
"# Add a Hadamard gate to qubit 0\n",
|
|
"qc.h(0)\n",
|
|
"\n",
|
|
"# Perform a controlled-X gate on qubit 1, controlled by qubit 0\n",
|
|
"qc.cx(0, 1)\n",
|
|
"\n",
|
|
"# Measure qubit 0 to cbit 0, and qubit 1 to cbit 1\n",
|
|
"qc.measure(0, 0)\n",
|
|
"qc.measure(1, 1)\n",
|
|
"\n",
|
|
"# Run on the least-busy device you have access to\n",
|
|
"backend = service.least_busy(simulator=False,operational=True)\n",
|
|
"\n",
|
|
"# Generate ISA circuits\n",
|
|
"pm = generate_preset_pass_manager(backend=backend, optimization_level=1)\n",
|
|
"isa_circuit = pm.run(qc)\n",
|
|
"\n",
|
|
"# Create a Sampler object\n",
|
|
"sampler = Sampler(backend)\n",
|
|
"\n",
|
|
"# Submit the circuit to the sampler\n",
|
|
"job = sampler.run([isa_circuit])\n",
|
|
"\n",
|
|
"print(job.usage_estimation)\n",
|
|
"```\n",
|
|
"Output:\n",
|
|
"\n",
|
|
"```python\n",
|
|
"{'quantum_seconds': 4.1058720028432445}\n",
|
|
"```\n",
|
|
"</LegacyContent>\n",
|
|
"\n",
|
|
"## Estimate usage before submitting a job\n",
|
|
"\n",
|
|
"While getting an accurate local estimation is complicated by the extra operations done for error suppression and mitigation, you can use this baseline formula to get an approximation of estimated usage:\n",
|
|
"\n",
|
|
"`<per sub-job overhead> + (rep_delay + <circuit length>) * <num executions>`\n",
|
|
"\n",
|
|
"- `<per sub-job overhead>` is an overhead of approximately 2s per sub-job. This includes operations such as loading the payload into control electronics. Your primitive job may be divided into multiple sub-jobs if it is too large for the execution engine to process all at once.\n",
|
|
"- `rep_delay` is a [user-customizable](/api/qiskit-ibm-runtime/options-execution-options-v2#rep_delay) option, and the default is given by `backend.default_rep_delay`, which is 250 microseconds on most IBM Quantum backends. Note that lowering `rep_delay` decreases the total QPU execution time, but at the expense of increased state preparation error rate; see the [Dynamic repetition rate execution](/docs/guides/repetition-rate-execution) guide for more information.\n",
|
|
"- `<circuit length>` is the total instruction length. Each instruction takes different amount of time on the QPU, so the total length varies from circuit to circuit. A measurement, for example, can take 56 times longer than an `x` gate. `backend.target[<instruction>][<qubit>].duration` can be used to find the exact duration for each instruction. A typical circuit length is likely between 50-100 microseconds. If you are using error suppression or mitigation techniques with the primitives, extra instructions might be inserted into your circuit, which would increase the total circuit length.\n",
|
|
"- `<num executions>` is the total number of circuits times the number of shots, where the circuits are those generated after PUB elements are broadcasted. If you are using error-mitigation techniques with the primitives, extra circuits can be run as part of the mitigation process, which would increase the total number of executions. Advanced error-mitigation techniques such as PEA and PEC come with much higher overhead because they require running circuits for noise learning.\n",
|
|
"\n",
|
|
"If you aren't using any advanced error-mitigation techniques or custom `rep_delay`, you can use `2+0.00035*<num executions>` as a quick formula.\n",
|
|
"\n",
|
|
"## Next steps\n",
|
|
"\n",
|
|
"<Admonition type=\"tip\" title=\"Recommendations\">\n",
|
|
" - Review these tips: [Minimize job run time](minimize-time).\n",
|
|
" - Set the [Maximum execution time](max-execution-time).\n",
|
|
" - Learn how to transpile locally in the [Transpile](./transpile/) section.\n",
|
|
" - Try the [Submit pre-transpiled circuits](https://learning.quantum.ibm.com/tutorial/submitting-user-transpiled-circuits-using-primitives) tutorial.\n",
|
|
"</Admonition>"
|
|
]
|
|
}
|
|
],
|
|
"metadata": {
|
|
"description": "Explains what usage is and how to estimate how long a job that uses a primitive will take to run",
|
|
"kernelspec": {
|
|
"display_name": "Python 3",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3"
|
|
},
|
|
"title": "Workload usage"
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 4
|
|
}
|