diff --git a/docs/guides/monitor-job.ipynb b/docs/guides/monitor-job.ipynb index 4b9f7ff0ca6..04fb14a70ea 100644 --- a/docs/guides/monitor-job.ipynb +++ b/docs/guides/monitor-job.ipynb @@ -13,228 +13,422 @@ "\n", "# Monitor or cancel a job\n", "\n", - "View a list of your workloads on the [Workloads page](https://quantum.cloud.ibm.com/workloads).\n", - "\n", - "## View job status\n", - "\n", - "Go to your [Workloads table](https://quantum.cloud.ibm.com/workloads) and check under the Status column for whether a job has completed or failed.\n", - "\n", - "## View remaining usage\n", + "This guide explains how to monitor job status, view usage information, and cancel jobs. You can access this information both through IBM Quantum Platform and programmatically using Qiskit." + ] + }, + { + "cell_type": "markdown", + "id": "866ed6ab-a597-402e-876a-8315ac5ed9e6", + "metadata": { + "tags": [ + "version-info" + ] + }, + "source": [] + }, + { + "cell_type": "markdown", + "id": "bb84ab8e-6db9-45d6-bb59-2f06f38d9965", + "metadata": {}, + "source": [ + "{/*\n", + " DO NOT EDIT THIS CELL!!!\n", + " This cell's content is generated automatically by a script. Anything you add\n", + " here will be removed next time the notebook is run. To add new content, create\n", + " a new cell before or after this one.\n", + "*/}\n", "\n", - "Go to your [Instances table](https://quantum.cloud.ibm.com/instances) and select the tab associated with the plan you want to view remaining usage for. Total time used and total time remaining on your plan is displayed.\n", + "\n", + "\n", "\n", - "## View metrics on number of jobs and workloads submitted\n", + "The code on this page was developed using the following requirements.\n", + "We recommend using these versions or newer.\n", "\n", - "Go to the [Analytics page](https://quantum.cloud.ibm.com/analytics) to see the total number of jobs submitted, as well as a count of batch workloads and session workloads. Note that you can only see the Analytics page for accounts that you own or manage.\n", + "```\n", + "qiskit-ibm-runtime~=0.46.1\n", + "```\n", "\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "view-status", + "metadata": {}, + "source": [ "## Monitor a job\n", "\n", - "Use the job instance to check the job status or retrieve the results by calling the appropriate command:\n", + "Use these methods to check the status of your submitted jobs, retrieve results, and view details related to the job and its execution.\n", + "\n", + "\n", + " \n", + " The job instance provides several methods for monitoring:\n", + "\n", + " | Method | Description |\n", + " | --- | --- |\n", + " | `job.status()` | Check the current job status |\n", + " | `job.job_id()` | Get the unique job identifier |\n", + " | `job.result()` | Retrieve job results (blocking call until complete) |\n", + " | `job.wait_for_final_state()` | Block until the job reaches a terminal state |\n", + "\n", + " \n", + " \n", + " \n", + " Navigate to the [Workloads page](https://quantum.cloud.ibm.com/workloads) and check the Status column. Your job status appears as one of the following:\n", + " - **Pending**: Job is waiting to run on a QPU\n", + " - **In progress**: Job is currently executing\n", + " - **Completed**: Job finished successfully\n", + " - **Failed**: Job encountered an error\n", + " - **Canceled**: User canceled the job\n", + "\n", + " Click on the job name or row to open the detailed view. In the details panel, you can see:\n", + " - Job status and timestamps\n", + " - Execution details and hardware information\n", + " - Results and any error messages\n", + " - Job metadata and parameters\n", + "\n", + " \n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ee0318b6-0bfd-4f0b-b980-4e233a2d5d7b", + "metadata": { + "tags": [ + "id-status" + ] + }, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", - "| | |\n", - "| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n", - "| job.result() | Review job results immediately after the job completes. Job results are available after the job completes. Therefore, job.result() is a blocking call until the job completes. |\n", - "| job.job\\_id() | Return the ID that uniquely identifies that job. Retrieving the job results at a later time requires the job ID. Therefore, it is recommended that you save the IDs of jobs you might want to retrieve later. |\n", - "| job.status() | Check the job status. |\n", - "| job = service.job(\\) | Retrieve a job you previously submitted. This call requires the job ID. |\n", + "service = QiskitRuntimeService()\n", "\n", - "\n", - "## Retrieve job results at a later time\n", + "# Retrieve a job by ID\n", + "job = service.job(\"\")\n", "\n", - "Call `service.job(\\)` to retrieve a job you previously submitted. If you don't have the job ID, or if you want to retrieve multiple jobs at once; including jobs from retired QPUs (quantum processing units), call `service.jobs()` with optional filters instead. See [QiskitRuntimeService.jobs](../api/qiskit-ibm-runtime/qiskit-runtime-service#jobs).\n", + "# Get job ID (useful for saving for later retrieval)\n", + "print(f\"Job ID: {job.job_id()}\")\n", "\n", - "\n", - " `service.jobs()` also returns jobs run from the deprecated `qiskit-ibm-provider` package. Jobs submitted by the older (also deprecated) `qiskit-ibmq-provider` package are no longer available.\n", - "\n", + "# Check current status\n", + "print(f\"Status: {job.status()}\")\n", "\n", - "### Example\n", + "# Wait for job to complete (blocking call)\n", + "job.wait_for_final_state()\n", + "print(\"Job completed\")\n", "\n", - "This example returns the 10 most recent runtime jobs that were run on `my_backend`:" + "# Get results\n", + "results = job.result()\n", + "print(results)" ] }, { "cell_type": "markdown", - "id": "c67f78c5-a199-456a-a9e3-35c518b28f50", - "metadata": { - "tags": [ - "version-info" - ] - }, - "source": [] + "id": "view-usage", + "metadata": {}, + "source": [ + "## View remaining usage\n", + "\n", + "Track how much of your plan's usage quota remains.\n", + "\n", + "\n", + " \n", + " Use the `service.usage()` method to get usage information for your current active instance.\n", + "\n", + " \n", + " \n", + " \n", + " Navigate to the [Instances page](https://quantum.cloud.ibm.com/instances) and select the tab associated with the plan you want to check. The total time used and total time remaining on your plan is displayed under the *Usage remaining* column.\n", + " \n", + "" + ] }, { "cell_type": "code", "execution_count": null, - "id": "ee0318b6-0bfd-4f0b-b980-4e233a2d5d7b", + "id": "usage-code", "metadata": { "tags": [ - "remove-cell" + "id-usage" ] }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "d305ck0ocacs73ajagvg\n" - ] - } - ], + "outputs": [], "source": [ - "# This cell is hidden from users\n", - "from qiskit import QuantumCircuit\n", - "from qiskit.circuit import Parameter\n", - "from qiskit.transpiler import generate_preset_pass_manager\n", - "\n", - "from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2\n", - "import numpy as np\n", - "\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", - "my_backend = \"ibm_torino\"\n", "service = QiskitRuntimeService()\n", - "# backend = service.backend(my_backend)\n", - "backend = service.least_busy()\n", - "\n", - "# Define two circuits, each with one parameter with two parameters.\n", - "circuit = QuantumCircuit(2)\n", - "circuit.h(0)\n", - "circuit.cx(0, 1)\n", - "circuit.ry(Parameter(\"a\"), 0)\n", - "circuit.cx(0, 1)\n", - "circuit.h(0)\n", - "circuit.measure_all()\n", "\n", + "# Get usage information for the current active instance\n", + "usage = service.usage()\n", + "print(usage)" + ] + }, + { + "cell_type": "markdown", + "id": "view-metrics", + "metadata": {}, + "source": [ + "## View job metrics\n", "\n", - "pm = generate_preset_pass_manager(optimization_level=1, backend=backend)\n", - "transpiled_circuit = pm.run(circuit)\n", + "Get an overview of your job submissions, including batch and session workload metrics.\n", "\n", - "params = np.random.uniform(size=(2, 3)).T\n", + "\n", + " \n", + " Use the `service.jobs()` method with filters to retrieve information about your submitted jobs, such as how many have been submitted, whether they were batch or session workloads, which instance they are associated with, when they were created, and so on. The following example looks at the last 50 workloads in an instance and outputs how many were batch or session workloads. It then lists out job ID, status, tags, and date created for the last ten jobs.\n", "\n", - "sampler_pub = (transpiled_circuit, params)\n", + " \n", + " \n", + " \n", + " Navigate to the [Analytics page](https://quantum.cloud.ibm.com/analytics) to see and download data, such as the following:\n", + " - Total usage\n", + " - Usage filtered by instance, quantum computer, and user\n", + " - Count of job, batch, and session workloads\n", "\n", - "# Instantiate the new Estimator object, then run the transpiled circuit\n", - "# using the set of parameters and observables.\n", - "sampler = SamplerV2(mode=backend)\n", - "job = sampler.run([sampler_pub], shots=4)\n", - "print(job.job_id())" + " **Note**: You can only access the Analytics page for accounts that you own or manage.\n", + " \n", + "" ] }, { "cell_type": "code", - "execution_count": 2, - "id": "03946d0d-aeac-45d7-9e8e-6af38e40e758", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "ExecutionSpans([DoubleSliceSpan()])\n" - ] - } - ], + "execution_count": null, + "id": "metrics-code", + "metadata": { + "tags": [ + "id-metrics" + ] + }, + "outputs": [], "source": [ - "result = job.result()\n", + "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", + "service = QiskitRuntimeService()\n", "\n", - "spans = job.result().metadata[\"execution\"][\"execution_spans\"]\n", - "print(spans)" + "# Get last 50 jobs to calculate metrics\n", + "print(\"Job Metrics:\")\n", + "print(\"=\" * 60)\n", + "all_jobs = service.jobs(limit=50, descending=True) # To retrieve all\n", + "# jobs, replace with `limit=None`\n", + "\n", + "total_jobs = len(all_jobs)\n", + "session_workloads = sum(1 for job in all_jobs if job.session_id is not None)\n", + "batch_jobs = sum(1 for job in all_jobs if job.session_id is None)\n", + "\n", + "print(f\"Total jobs submitted: {total_jobs}\")\n", + "print(f\"Batch workloads (session_id = None): {batch_jobs}\")\n", + "print(f\"Session workloads (session_id != None): {session_workloads}\")\n", + "print()\n", + "\n", + "# Retrieve the last 10 jobs\n", + "print(\"Last 10 Jobs:\")\n", + "print(\"=\" * 60)\n", + "jobs = service.jobs(limit=10, descending=True)\n", + "\n", + "print(f\"Retrieved {len(jobs)} jobs\\n\")\n", + "\n", + "for i, job in enumerate(jobs, 1):\n", + " print(f\"Job {i}:\")\n", + " print(f\" ID: {job.job_id()}\")\n", + " print(f\" Status: {job.status()}\")\n", + " print(f\" Tags: {job.tags}\")\n", + " print(f\" Created: {job.creation_date}\")\n", + " print()" ] }, { - "cell_type": "code", - "execution_count": 3, - "id": "897d35cb-140a-4587-a687-97982a01d846", + "cell_type": "markdown", + "id": "retrieve-later", "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[0.2260416 , 0.8747859 , 0.44361995],\n", - " [0.94700856, 0.96826017, 0.98426562]])" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], "source": [ - "params = np.random.uniform(size=(2, 3))\n", - "params" + "## Retrieve job results at a later time\n", + "\n", + "You can save job IDs and retrieve results later, even after closing your session.\n", + "\n", + "\n", + " \n", + " If you saved the job ID when you submitted the job, use `service.job()` to retrieve it later. If you don't have the job ID, or if you want to retrieve multiple jobs at once (including jobs from retired QPUs), use `service.jobs()` instead, with optional filters.\n", + "\n", + " See the [`QiskitRuntimeService.jobs`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#jobs) API documentation for available filters.\n", + "\n", + " This example demonstrates retrieving recent results run on a specific backend.\n", + "\n", + " \n", + "\n", + " You can use `job.properties()` to retrieve backend properties, including error rates, at the time of the job execution.\n", + "\n", + " This example demonstrates backend properties that were current at the time a job was executed, including $T_1$/$T_2$ times and error rates for a specific qubit (0).\n", + "\n", + " \n", + "\n", + " \n", + " `service.jobs()` also returns jobs run from the deprecated `qiskit-ibm-provider` package. Jobs submitted by the older (also deprecated) `qiskit-ibmq-provider` package are no longer available.\n", + " \n", + " \n", + " \n", + " 1. Go to the [Workloads page](https://quantum.cloud.ibm.com/workloads)\n", + " 2. Use the search or filter options to find your job by name, date, or status\n", + " 3. Click on the job to view its results and details\n", + " 4. Results remain available indefinitely in your workload history\n", + " \n", + "" ] }, { "cell_type": "code", - "execution_count": 4, - "id": "38176ecc-64fe-4dbb-a9fa-bd0ca2942920", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([[[ True, True, True, True],\n", - " [ True, True, True, True]],\n", - "\n", - " [[ True, True, True, True],\n", - " [ True, True, True, True]],\n", - "\n", - " [[ True, True, True, True],\n", - " [ True, True, True, True]]])" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], + "execution_count": null, + "id": "retrieve-code", + "metadata": { + "tags": [ + "id-retrieve" + ] + }, + "outputs": [], "source": [ - "mask = spans[0].mask(0)\n", - "mask" + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "\n", + "# Uncomment the next line to retrieve a specific job by ID\n", + "# job = service.job(\"\")\n", + "\n", + "# Or retrieve multiple jobs with filters\n", + "# Use `limit` to retrieve a specific number of jobs. The default `limit` is 10.\n", + "my_backend = \"\"\n", + "recent_jobs = service.jobs(backend_name=my_backend, limit=10)\n", + "\n", + "print(f\"Retrieved {len(recent_jobs)} recent jobs from {my_backend}\\n\")\n", + "\n", + "# Get results from all jobs\n", + "for job in recent_jobs:\n", + " print(f\"Job ID: {job.job_id()}\")\n", + " print(f\"Status: {job.status()}\")\n", + "\n", + " # Retrieve results if the job is complete\n", + " if str(job.status()) == \"DONE\":\n", + " try:\n", + " results = job.result()\n", + " print(f\"Results: {results}\")\n", + " except Exception as e:\n", + " print(f\"Error retrieving results: {e}\")\n", + " else:\n", + " print(\"Results: Not available (job still running or failed)\")\n", + " print()" ] }, { "cell_type": "code", "execution_count": null, - "id": "4415838a-04da-4a8e-8fed-4c062d186ec7", - "metadata": {}, + "id": "55afa300-0af7-4f5e-8b32-c32b6ba39621", + "metadata": { + "tags": [ + "id-backend-properties" + ] + }, "outputs": [], "source": [ "from qiskit_ibm_runtime import QiskitRuntimeService\n", "\n", - "# Initialize the account first.\n", "service = QiskitRuntimeService()\n", - "# Use `limit` to retrieve a specific number of jobs. The default `limit` is 10.\n", - "service.jobs(backend_name=my_backend)" + "\n", + "# Retrieve a specific job by ID\n", + "job = service.job(\"\")\n", + "\n", + "print(f\"Job ID: {job.job_id()}\")\n", + "print(f\"Backend: {job.backend}\\n\")\n", + "\n", + "# Fetch backend properties at the time of job execution\n", + "properties = job.properties()\n", + "\n", + "if properties:\n", + " print(\"Backend Properties at Job Execution Time:\")\n", + " print(\"=\" * 60)\n", + "\n", + " # Get T1 (relaxation time) for qubit 0\n", + " t1 = properties.t1(0)\n", + " print(f\"Qubit 0 T1 (relaxation time): {t1}\")\n", + "\n", + " # Get T2 (dephasing time) for qubit 0\n", + " t2 = properties.t2(0)\n", + " print(f\"Qubit 0 T2 (dephasing time): {t2}\")\n", + "\n", + " # Get readout error for qubit 0\n", + " readout_error = properties.readout_error(0)\n", + " print(f\"Qubit 0 readout error: {readout_error}\")\n", + "\n", + " # Get all properties for a specific qubit\n", + " print(\"All properties for qubit 0:\")\n", + " qubit_props = properties.qubit_property(0)\n", + " for prop_name, prop_value in qubit_props.items():\n", + " print(f\" {prop_name}: {prop_value}\")\n", + "else:\n", + " print(\"No properties available for this job\")" ] }, { "cell_type": "markdown", - "id": "59195a9f-8df8-46f7-9ea0-c3a9b8eb3cac", + "id": "cancel-job", "metadata": {}, "source": [ "## Cancel a job\n", "\n", - "You can cancel a job from the IBM Quantum Platform dashboard either on the Workloads page or the details page for a specific workload. On the Workloads page, click the overflow menu at the end of the row for that workload, and select Cancel. If you are on the details page for a specific workload, use the Actions dropdown at the top of the page, and select Cancel.\n", + "Cancel a job that is queued or running. Once a job is canceled, it cannot be resumed.\n", "\n", - "In Qiskit, use `job.cancel()` to cancel a job." + "\n", + " \n", + " Use the `job.cancel()` method to cancel a job programmatically.\n", + "\n", + " \n", + " \n", + " \n", + " 1. **From the workloads table**: Click the overflow menu (three dots) at the end of the row for the workload you want to cancel, and select **Cancel**.\n", + " 2. **From the job details page**: Click on the workload to open its details page, use the **Actions** dropdown at the top, and select **Cancel**.\n", + " \n", + "" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cancel-code", + "metadata": { + "tags": [ + "id-cancel" + ] + }, + "outputs": [], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "\n", + "service = QiskitRuntimeService()\n", + "\n", + "# Retrieve the job\n", + "job = service.job(\"\")\n", + "\n", + "# Cancel the job\n", + "job.cancel()\n", + "\n", + "print(f\"Job {job.job_id()} has been canceled\")" ] }, { "cell_type": "markdown", - "id": "c2abeb3d-4e4a-4c90-be59-16ec0e1be783", + "id": "next-steps", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", - " - Try the [Grover's algorithm](/docs/tutorials/grovers-algorithm) tutorial.\n", - " - Learn more about [Sampler execution spans](/docs/guides/sampler-input-output#execution-spans)\n", + " - Review the [`QiskitRuntimeService` API reference](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service) for additional job management methods.\n", + " - Explore [execution modes](/docs/guides/execution-modes) to understand batch and session workload types.\n", "" ] } ], "metadata": { + "description": "How to monitor or cancel a job submitted to IBM Quantum Platform", "kernelspec": { "display_name": "Python 3", "language": "python", @@ -251,7 +445,8 @@ "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3" - } + }, + "title": "Monitor or cancel a job" }, "nbformat": 4, "nbformat_minor": 4