Batch Jobs

qBraid-Runtime/qbraid_runtime_batch_jobs.ipynb

@@ -0,0 +1,141 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Submitting Batch Jobs with the qBraid Runtime\n",
+    "\n",
+    "The [qBraid-SDK](https://github.com/qBraid/qBraid) can submit a list of circuits as a single batch job. Passing `as_batch=True` to `QbraidDevice.run()` sends the circuits in one API call and returns a single `BatchResult` instead of a separate job per circuit. This was added in [qBraid-SDK v0.12.1](https://github.com/qBraid/qBraid/releases/tag/v0.12.1).\n",
+    "\n",
+    "> **Note:** Batch submission requires a device whose profile reports `batch_job_support = True`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "\n",
+    "%pip install --upgrade 'qbraid[qiskit,visualization]'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import qbraid\n",
+    "\n",
+    "qbraid.__version__"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit import QuantumCircuit\n",
+    "from qbraid.runtime import QbraidProvider\n",
+    "from qbraid.visualization import plot_histogram\n",
+    "\n",
+    "provider = QbraidProvider()\n",
+    "device = provider.get_device(\"qbraid:equal1:sim:bell-1\")\n",
+    "\n",
+    "if not device.profile.batch_job_support:\n",
+    "    raise RuntimeError(f\"Device {device.id} does not support batch jobs.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Build the circuits\n",
+    "\n",
+    "A batch needs more than one circuit, so we build two with Qiskit. `bell` is a two-qubit circuit and `ghz` is a three-qubit circuit — both are standard entangled states. Calling `measure_all()` adds a measurement on every qubit so the device returns counts."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bell = QuantumCircuit(2)\n",
+    "bell.h(0)\n",
+    "bell.cx(0, 1)\n",
+    "bell.measure_all()\n",
+    "\n",
+    "ghz = QuantumCircuit(3)\n",
+    "ghz.h(0)\n",
+    "ghz.cx(0, 1)\n",
+    "ghz.cx(1, 2)\n",
+    "ghz.measure_all()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Submit as a single batch\n",
+    "\n",
+    "We pass the two circuits as a list with `as_batch=True`, so they run as one job instead of two separate submissions. `job.result()` returns a `BatchResult`: `result.num_circuits` is how many circuits ran, and `result.results` holds each circuit's result on its own. Because the two circuits have different numbers of qubits, we print and plot each circuit's counts separately rather than combining them."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "job = device.run([bell, ghz], as_batch=True, shots=100)\n",
+    "\n",
+    "result = job.result()  # BatchResult\n",
+    "print(result.num_circuits)  # 2\n",
+    "\n",
+    "for i, circuit_result in enumerate(result.results):\n",
+    "    counts = circuit_result.data.get_counts()\n",
+    "    print(f\"Circuit {i}: {counts}\")\n",
+    "    display(plot_histogram(counts))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-block alert-info\">\n",
+    "<b>Copyright Notice:</b> \n",
+    "    All rights reserved © [2026] qBraid. This notebook is part of the qBraid-Lab-Demo repository.\n",
+    "The qBraid-Lab-Demo is licensed under the Apache License, Version 2.0.\n",
+    "You may obtain a copy of the License at <https://www.apache.org/licenses/LICENSE-2.0>.\n",
+    "Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
+    "</div>"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".demo",
+   "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.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}