open-standards/wai/wai-quantum-py/notebooks/getting-started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "getting-started-0",
   "metadata": {},
   "source": [
    "# Getting started with WAI Quantum in Python\n",
    "\n",
    "The package runs the WAI Quantum job engine in this process. A job planned, run and sealed here gives the same plan, the same result and the same receipt as the command line, the job service, the MCP servers, the Studio and the desktop app.\n",
    "\n",
    "Install it from a wheel (it is not on a public package index yet):\n",
    "\n",
    "```sh\n",
    "pip install wai_quantum-<version>-cp39-abi3-<platform>.whl            # the engine and the service client\n",
    "pip install \"wai_quantum-<version>-cp39-abi3-<platform>.whl[widgets]\" # and the notebook widgets\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "getting-started-1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.338617Z",
     "iopub.status.busy": "2026-11-11T12:23:53.338472Z",
     "iopub.status.idle": "2026-11-11T12:23:53.351396Z",
     "shell.execute_reply": "2026-11-11T12:23:53.351029Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0.1.4'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import wai_quantum as wq\n",
    "wq.__version__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "getting-started-2",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.352558Z",
     "iopub.status.busy": "2026-11-11T12:23:53.352453Z",
     "iopub.status.idle": "2026-11-11T12:23:53.354652Z",
     "shell.execute_reply": "2026-11-11T12:23:53.354335Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Key(did:key:z6MkehRgf7yJbgaGfYsdoAsKdBPE3dj2CYhowQdcjqSJgvVd, in memory)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# A fixed key for this page, so that its receipts repeat byte for byte when it runs\n",
    "# again. Keep a key of your own: wq.Key.generate().save(\"my.key\"), then\n",
    "# wq.Key.from_file(\"my.key\"); with no key given, wq.run signs with this user's key,\n",
    "# the command line's.\n",
    "key = wq.Key(bytes(range(32)))\n",
    "key"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-3",
   "metadata": {},
   "source": [
    "## Run a job\n",
    "\n",
    "A program is OpenQASM 3 (or 2) text, a path to a file of it, or a job as the service reads it. `run` plans it onto the strongest method the circuit admits, runs it, and seals the result. The job comes back as a plain dict in the service's form, with helpers for what is read most."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "getting-started-4",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.355407Z",
     "iopub.status.busy": "2026-11-11T12:23:53.355326Z",
     "iopub.status.idle": "2026-11-11T12:23:53.357999Z",
     "shell.execute_reply": "2026-11-11T12:23:53.357640Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "stabilizer, accuracy exact, 1000 shots, 2 outcomes listed, sealed\n",
      "method   stabilizer - Clifford circuit: the stabilizer tableau of 2 qubits\n",
      "accuracy exact\n",
      "counts   {'11': 505, '00': 495}\n"
     ]
    }
   ],
   "source": [
    "bell = '''OPENQASM 3.0;\n",
    "qubit[2] q;\n",
    "bit[2] c;\n",
    "h q[0];\n",
    "cx q[0], q[1];\n",
    "c = measure q;\n",
    "'''\n",
    "job = wq.run(bell, shots=1000, seed=7, key=key)\n",
    "print(job.summary())\n",
    "print(\"method  \", job.method, \"-\", job[\"why\"])\n",
    "print(\"accuracy\", job.accuracy)\n",
    "print(\"counts  \", job.counts)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-5",
   "metadata": {},
   "source": [
    "The job displays as its result: the counts, the method, the accuracy class and the receipt, checked here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "getting-started-6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.358954Z",
     "iopub.status.busy": "2026-11-11T12:23:53.358841Z",
     "iopub.status.idle": "2026-11-11T12:23:53.362788Z",
     "shell.execute_reply": "2026-11-11T12:23:53.362249Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"wq-result\" style=\"font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;border:1px solid var(--jp-border-color2,rgba(127,127,127,.35));border-radius:8px;padding:10px 12px;margin:2px 0;max-width:100%;overflow-x:auto\"><div><b>stabilizer</b> · accuracy <b>exact</b></div><div style=\"opacity:.7\">Clifford circuit: the stabilizer tableau of 2 qubits</div><div style=\"margin-top:6px\">1000 shots, 2 distinct outcomes; the 2 most frequent:</div><svg xmlns=\"http://www.w3.org/2000/svg\" class=\"wq-histogram\" width=\"370\" height=\"40\" viewBox=\"0 0 370 40\" role=\"img\" aria-label=\"Counts of 2 outcomes\"><text x=\"34\" y=\"11\" text-anchor=\"end\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px\">11</text><rect x=\"40\" y=\"4\" width=\"260.0\" height=\"14\" rx=\"2\" fill=\"#7aa0ff\"><title>11: 505 of 1000</title></rect><text x=\"306.0\" y=\"11\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:11px\">505</text><text x=\"34\" y=\"29\" text-anchor=\"end\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px\">00</text><rect x=\"40\" y=\"22\" width=\"254.9\" height=\"14\" rx=\"2\" fill=\"#7aa0ff\"><title>00: 495 of 1000</title></rect><text x=\"300.9\" y=\"29\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:11px\">495</text></svg><div style=\"margin-top:6px\">receipt <span class=\"wq-badge\" style=\"display:inline-block;padding:0 7px;border-radius:9px;font-size:11px;font-weight:600;color:#fff;background:#10b981\">verified</span> signed by <span style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px\" title=\"did:key:z6MkehRgf7yJbgaGfYsdoAsKdBPE3dj2CYhowQdcjqSJgvVd\">did:key:z6Mkeh…howQdcjqSJgvVd</span></div></div>"
      ],
      "text/plain": [
       "{'status': 'done',\n",
       " 'method': 'stabilizer',\n",
       " 'why': 'Clifford circuit: the stabilizer tableau of 2 qubits',\n",
       " 'estimate': {'memory_bytes': 67172870, 'work': 2008},\n",
       " 'request': {'qasm': 'OPENQASM 3.0;\\nqubit[2] q;\\nbit[2] c;\\nh q[0];\\ncx q[0], q[1];\\nc = measure q;\\n',\n",
       "  'shots': 1000,\n",
       "  'seed': 7},\n",
       " 'result': {'method': 'stabilizer',\n",
       "  'qubits': 2,\n",
       "  'gates': 2,\n",
       "  'accuracy': {'class': 'exact'},\n",
       "  'counts': {'11': 505, '00': 495},\n",
       "  'distinct_outcomes': 2,\n",
       "  'omitted_shots': 0,\n",
       "  'outcome_dimension': 1,\n",
       "  'elapsed_ms': 0,\n",
       "  'engine': {'name': 'wai-quantum', 'version': '0.10.0'},\n",
       "  'schema': 'wai.quantum.job-result/1',\n",
       "  'energy': {'unmetered': \"the Python package does not meter a run's energy\"},\n",
       "  'receipt': {'alg': 'ed25519',\n",
       "   'canon': 'rfc8785',\n",
       "   'key': '03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8',\n",
       "   'digest': 'e8f758f8e55156bc9387d8eb18274d16fb649cdfe79ea7e96c53cc71f6d52319',\n",
       "   'signature': 'deaebc8050e84b04e24e9f1650ee0712afcff768de594c53b18183a3ad1b0db6c5f7b1fa560a4e17a4d004065f43990636924af0be721244e72b2eecd3bb5f03'}}}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "job"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-7",
   "metadata": {},
   "source": [
    "## Check the receipt\n",
    "\n",
    "`verify` checks that the receipt seals this request and this result, offline. Any change to either breaks it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "getting-started-8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.363966Z",
     "iopub.status.busy": "2026-11-11T12:23:53.363881Z",
     "iopub.status.idle": "2026-11-11T12:23:53.366309Z",
     "shell.execute_reply": "2026-11-11T12:23:53.365991Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "v = wq.verify(job)\n",
    "print(v.valid, v.signer == key.did)\n",
    "forged = dict(job, result=dict(job.result, counts={\"00\": 1000}))\n",
    "print(wq.verify(forged).valid)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-9",
   "metadata": {},
   "source": [
    "## Before running: plan, lint, draw, critique\n",
    "\n",
    "None of these runs the circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "getting-started-10",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.366971Z",
     "iopub.status.busy": "2026-11-11T12:23:53.366901Z",
     "iopub.status.idle": "2026-11-11T12:23:53.368500Z",
     "shell.execute_reply": "2026-11-11T12:23:53.368243Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'method': 'stabilizer', 'why': 'Clifford circuit: the stabilizer tableau of 2 qubits', 'memory_bytes': 67174406, 'work': 2056, 'qubits': 2}\n",
      "{'ok': True, 'qubits': 2, 'gates': 2, 'bits': 2, 'measured': 2, 'dynamic_steps': None}\n",
      "q0: ──H──●──M0──\n",
      "         │\n",
      "q1: ─────⊕──M1──\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(wq.plan(bell))\n",
    "print(wq.lint(bell))\n",
    "print(wq.draw(bell))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "getting-started-11",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.369158Z",
     "iopub.status.busy": "2026-11-11T12:23:53.369099Z",
     "iopub.status.idle": "2026-11-11T12:23:53.412647Z",
     "shell.execute_reply": "2026-11-11T12:23:53.412122Z"
    }
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "4ab9f571da9a4c5a86b023b1cbb23b95",
       "version_major": 2,
       "version_minor": 1
      },
      "image/svg+xml": [
       "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"188\" height=\"90\" viewBox=\"0 0 188 90\" class=\"qc wq-circuit\" role=\"img\" aria-label=\"The circuit: 2 qubits, 4 operations in 3 columns\"><style>.wq-circuit{font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif}.wq-circuit .qc-bg{fill:var(--jp-layout-color0,#fff)}.wq-circuit .qc-wire{stroke:currentColor;stroke-opacity:.45;stroke-width:1.5}.wq-circuit .qc-name{fill:currentColor;fill-opacity:.7;font-size:11px}.wq-circuit .qc-join{stroke:currentColor;stroke-opacity:.8;stroke-width:1.5}.wq-circuit .qc-box{fill:var(--jp-layout-color0,#fff);stroke:currentColor;stroke-width:1.3}.wq-circuit .qc-cond .qc-box{stroke-dasharray:3 2}.wq-circuit .qc-label{fill:currentColor;font-size:12px}.wq-circuit .qc-sub,.wq-circuit .qc-note{fill:currentColor;fill-opacity:.65;font-size:9px}.wq-circuit .qc-note{font-size:11px}.wq-circuit .qc-dot{fill:currentColor}.wq-circuit .qc-ring{fill:var(--jp-layout-color0,#fff);stroke:currentColor;stroke-width:1.5}.wq-circuit .qc-stroke{stroke:currentColor;stroke-width:1.5}.wq-circuit .qc-meter{fill:none;stroke:currentColor;stroke-width:1.4}.wq-circuit .qc-item:hover .qc-box,.wq-circuit .qc-item:hover .qc-ring{stroke-width:2.2}.wq-circuit .qc-by-person .qc-box,.wq-circuit .qc-by-person .qc-ring{stroke:#d4a574;stroke-width:2.2}.wq-circuit .qc-key-person{fill:#d4a574}.wq-circuit .qc-by-assistant .qc-box,.wq-circuit .qc-by-assistant .qc-ring{stroke:#7aa0ff;stroke-width:2.2}.wq-circuit .qc-key-assistant{fill:#7aa0ff}.wq-circuit .qc-by-agent .qc-box,.wq-circuit .qc-by-agent .qc-ring{stroke:#10b981;stroke-width:2.2}.wq-circuit .qc-key-agent{fill:#10b981}.wq-circuit .qc-by-engine .qc-box,.wq-circuit .qc-by-engine .qc-ring{stroke:#9aa0a6;stroke-width:2.2}.wq-circuit .qc-key-engine{fill:#9aa0a6}.wq-circuit .qc-by-origin .qc-box,.wq-circuit .qc-by-origin .qc-ring{stroke:#5a5f66;stroke-width:2.2}.wq-circuit .qc-key-origin{fill:#5a5f66}.wq-circuit .qc-by-assistant_then_person .qc-box,.wq-circuit .qc-by-assistant_then_person .qc-ring{stroke:#d4a574;stroke-width:2.2;stroke-dasharray:3 2}.wq-circuit .qc-key-assistant_then_person{fill:#d4a574}.wq-circuit .qc-by-agent_then_person .qc-box,.wq-circuit .qc-by-agent_then_person .qc-ring{stroke:#d4a574;stroke-width:2.2;stroke-dasharray:3 2}.wq-circuit .qc-key-agent_then_person{fill:#d4a574}</style><rect class=\"qc-bg\" fill=\"none\" x=\"0\" y=\"0\" width=\"188\" height=\"90\"/><text x=\"26\" y=\"25\" class=\"qc-name\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\" data-q=\"0\">q0</text><line x1=\"40\" y1=\"25\" x2=\"174\" y2=\"25\" class=\"qc-wire\" stroke=\"currentColor\" data-q=\"0\"/><text x=\"26\" y=\"65\" class=\"qc-name\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\" data-q=\"1\">q1</text><line x1=\"40\" y1=\"65\" x2=\"174\" y2=\"65\" class=\"qc-wire\" stroke=\"currentColor\" data-q=\"1\"/><g class=\"qc-item\" data-op=\"0\"><title>H on q0</title><g class=\"qc-gate\"><rect x=\"60\" y=\"12\" width=\"28\" height=\"26\" rx=\"5\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><text x=\"74\" y=\"25\" class=\"qc-label\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">H</text></g></g><g class=\"qc-item\" data-op=\"1\"><title>● on q0, ⊕ on q1</title><line x1=\"114\" y1=\"25\" x2=\"114\" y2=\"65\" class=\"qc-join\" stroke=\"currentColor\"/><g class=\"qc-control\"><circle cx=\"114\" cy=\"25\" r=\"5\" class=\"qc-dot\" fill=\"currentColor\"/></g><g class=\"qc-target\"><circle cx=\"114\" cy=\"65\" r=\"10\" class=\"qc-ring\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"104\" y1=\"65\" x2=\"124\" y2=\"65\" class=\"qc-stroke\" stroke=\"currentColor\"/><line x1=\"114\" y1=\"55\" x2=\"114\" y2=\"75\" class=\"qc-stroke\" stroke=\"currentColor\"/></g></g><g class=\"qc-item\"><title>M0 on q0</title><g class=\"qc-measure\"><rect x=\"140\" y=\"13\" width=\"28\" height=\"24\" rx=\"4\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><path d=\"M 146 30 A 9 9 0 0 1 162 30\" class=\"qc-meter\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"154\" y1=\"30\" x2=\"160\" y2=\"20\" class=\"qc-meter\" stroke=\"currentColor\"/><text x=\"167\" y=\"40\" class=\"qc-sub\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">0</text></g></g><g class=\"qc-item\"><title>M1 on q1</title><g class=\"qc-measure\"><rect x=\"140\" y=\"53\" width=\"28\" height=\"24\" rx=\"4\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><path d=\"M 146 70 A 9 9 0 0 1 162 70\" class=\"qc-meter\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"154\" y1=\"70\" x2=\"160\" y2=\"60\" class=\"qc-meter\" stroke=\"currentColor\"/><text x=\"167\" y=\"80\" class=\"qc-sub\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">1</text></g></g></svg>"
      ],
      "text/html": [
       "<div class=\"wq-circuit-card\" style=\"font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;border:1px solid var(--jp-border-color2,rgba(127,127,127,.35));border-radius:8px;padding:10px 12px;margin:2px 0;max-width:100%;overflow-x:auto\"><svg xmlns=\"http://www.w3.org/2000/svg\" width=\"188\" height=\"90\" viewBox=\"0 0 188 90\" class=\"qc wq-circuit\" role=\"img\" aria-label=\"The circuit: 2 qubits, 4 operations in 3 columns\"><style>.wq-circuit{font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif}.wq-circuit .qc-bg{fill:var(--jp-layout-color0,#fff)}.wq-circuit .qc-wire{stroke:currentColor;stroke-opacity:.45;stroke-width:1.5}.wq-circuit .qc-name{fill:currentColor;fill-opacity:.7;font-size:11px}.wq-circuit .qc-join{stroke:currentColor;stroke-opacity:.8;stroke-width:1.5}.wq-circuit .qc-box{fill:var(--jp-layout-color0,#fff);stroke:currentColor;stroke-width:1.3}.wq-circuit .qc-cond .qc-box{stroke-dasharray:3 2}.wq-circuit .qc-label{fill:currentColor;font-size:12px}.wq-circuit .qc-sub,.wq-circuit .qc-note{fill:currentColor;fill-opacity:.65;font-size:9px}.wq-circuit .qc-note{font-size:11px}.wq-circuit .qc-dot{fill:currentColor}.wq-circuit .qc-ring{fill:var(--jp-layout-color0,#fff);stroke:currentColor;stroke-width:1.5}.wq-circuit .qc-stroke{stroke:currentColor;stroke-width:1.5}.wq-circuit .qc-meter{fill:none;stroke:currentColor;stroke-width:1.4}.wq-circuit .qc-item:hover .qc-box,.wq-circuit .qc-item:hover .qc-ring{stroke-width:2.2}.wq-circuit .qc-by-person .qc-box,.wq-circuit .qc-by-person .qc-ring{stroke:#d4a574;stroke-width:2.2}.wq-circuit .qc-key-person{fill:#d4a574}.wq-circuit .qc-by-assistant .qc-box,.wq-circuit .qc-by-assistant .qc-ring{stroke:#7aa0ff;stroke-width:2.2}.wq-circuit .qc-key-assistant{fill:#7aa0ff}.wq-circuit .qc-by-agent .qc-box,.wq-circuit .qc-by-agent .qc-ring{stroke:#10b981;stroke-width:2.2}.wq-circuit .qc-key-agent{fill:#10b981}.wq-circuit .qc-by-engine .qc-box,.wq-circuit .qc-by-engine .qc-ring{stroke:#9aa0a6;stroke-width:2.2}.wq-circuit .qc-key-engine{fill:#9aa0a6}.wq-circuit .qc-by-origin .qc-box,.wq-circuit .qc-by-origin .qc-ring{stroke:#5a5f66;stroke-width:2.2}.wq-circuit .qc-key-origin{fill:#5a5f66}.wq-circuit .qc-by-assistant_then_person .qc-box,.wq-circuit .qc-by-assistant_then_person .qc-ring{stroke:#d4a574;stroke-width:2.2;stroke-dasharray:3 2}.wq-circuit .qc-key-assistant_then_person{fill:#d4a574}.wq-circuit .qc-by-agent_then_person .qc-box,.wq-circuit .qc-by-agent_then_person .qc-ring{stroke:#d4a574;stroke-width:2.2;stroke-dasharray:3 2}.wq-circuit .qc-key-agent_then_person{fill:#d4a574}</style><rect class=\"qc-bg\" fill=\"none\" x=\"0\" y=\"0\" width=\"188\" height=\"90\"/><text x=\"26\" y=\"25\" class=\"qc-name\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\" data-q=\"0\">q0</text><line x1=\"40\" y1=\"25\" x2=\"174\" y2=\"25\" class=\"qc-wire\" stroke=\"currentColor\" data-q=\"0\"/><text x=\"26\" y=\"65\" class=\"qc-name\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\" data-q=\"1\">q1</text><line x1=\"40\" y1=\"65\" x2=\"174\" y2=\"65\" class=\"qc-wire\" stroke=\"currentColor\" data-q=\"1\"/><g class=\"qc-item\" data-op=\"0\"><title>H on q0</title><g class=\"qc-gate\"><rect x=\"60\" y=\"12\" width=\"28\" height=\"26\" rx=\"5\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><text x=\"74\" y=\"25\" class=\"qc-label\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">H</text></g></g><g class=\"qc-item\" data-op=\"1\"><title>● on q0, ⊕ on q1</title><line x1=\"114\" y1=\"25\" x2=\"114\" y2=\"65\" class=\"qc-join\" stroke=\"currentColor\"/><g class=\"qc-control\"><circle cx=\"114\" cy=\"25\" r=\"5\" class=\"qc-dot\" fill=\"currentColor\"/></g><g class=\"qc-target\"><circle cx=\"114\" cy=\"65\" r=\"10\" class=\"qc-ring\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"104\" y1=\"65\" x2=\"124\" y2=\"65\" class=\"qc-stroke\" stroke=\"currentColor\"/><line x1=\"114\" y1=\"55\" x2=\"114\" y2=\"75\" class=\"qc-stroke\" stroke=\"currentColor\"/></g></g><g class=\"qc-item\"><title>M0 on q0</title><g class=\"qc-measure\"><rect x=\"140\" y=\"13\" width=\"28\" height=\"24\" rx=\"4\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><path d=\"M 146 30 A 9 9 0 0 1 162 30\" class=\"qc-meter\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"154\" y1=\"30\" x2=\"160\" y2=\"20\" class=\"qc-meter\" stroke=\"currentColor\"/><text x=\"167\" y=\"40\" class=\"qc-sub\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">0</text></g></g><g class=\"qc-item\"><title>M1 on q1</title><g class=\"qc-measure\"><rect x=\"140\" y=\"53\" width=\"28\" height=\"24\" rx=\"4\" class=\"qc-box\" fill=\"none\" stroke=\"currentColor\"/><path d=\"M 146 70 A 9 9 0 0 1 162 70\" class=\"qc-meter\" fill=\"none\" stroke=\"currentColor\"/><line x1=\"154\" y1=\"70\" x2=\"160\" y2=\"60\" class=\"qc-meter\" stroke=\"currentColor\"/><text x=\"167\" y=\"80\" class=\"qc-sub\" fill=\"currentColor\" text-anchor=\"middle\" dominant-baseline=\"central\">1</text></g></g></svg></div>"
      ],
      "text/plain": [
       "Circuit(2 qubits, 4 operations in 3 columns)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "wq.Circuit(bell)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "getting-started-12",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.413691Z",
     "iopub.status.busy": "2026-11-11T12:23:53.413610Z",
     "iopub.status.idle": "2026-11-11T12:23:53.415615Z",
     "shell.execute_reply": "2026-11-11T12:23:53.415285Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 gates, depth 3\n",
      "cancels [3, 4] h on qubit 0 twice in a row (lines 3 and 4): together they do nothing (a fix is offered)\n"
     ]
    }
   ],
   "source": [
    "c = wq.critique(\"OPENQASM 3.0;\\nqubit[1] q;\\nh q[0];\\nh q[0];\\nx q[0];\\n\")\n",
    "print(c[\"gates\"], \"gates, depth\", c[\"depth\"])\n",
    "for s in c[\"smells\"]:\n",
    "    print(s[\"kind\"], s[\"lines\"], s[\"message\"], \"(a fix is offered)\" if s[\"fixable\"] else \"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-13",
   "metadata": {},
   "source": [
    "## Methods and accuracy\n",
    "\n",
    "Every result names its accuracy class. A circuit at arbitrary angles goes to a double-precision method; the bit-exact method takes dyadic angles only and refuses the rest rather than round them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "getting-started-14",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.416410Z",
     "iopub.status.busy": "2026-11-11T12:23:53.416314Z",
     "iopub.status.idle": "2026-11-11T12:23:53.418181Z",
     "shell.execute_reply": "2026-11-11T12:23:53.417883Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "exact                bit-exact\n",
      "statevector          exact\n",
      "statevector_single   single\n",
      "stabilizer           exact; with Pauli noise, counts are noisy samples and expectations estimates\n",
      "pauli                bounded\n",
      "mps                  exact when nothing is truncated, otherwise heuristic\n",
      "stabilizer_rank      exact; with terms or epsilon, an estimate with its bound\n",
      "tensor_network       exact\n",
      "cutrank              exact; single when only a single-precision table fits\n",
      "cutrank_single       single\n",
      "density_matrix       exact\n",
      "trajectories         estimate\n",
      "pulse                bounded\n"
     ]
    }
   ],
   "source": [
    "for m in wq.methods():\n",
    "    print(f\"{m['method']:<20} {m['accuracy']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "getting-started-15",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.418928Z",
     "iopub.status.busy": "2026-11-11T12:23:53.418836Z",
     "iopub.status.idle": "2026-11-11T12:23:53.421453Z",
     "shell.execute_reply": "2026-11-11T12:23:53.421160Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'Z0': 0.9553364891256059, 'X0': 0.29552020666133955}\n",
      "refused: exact needs dyadic angles: the angle 0.3 is not a dyadic multiple of 2π (2πm/2^k, k ≤ 32) [Q500] [J011]\n"
     ]
    }
   ],
   "source": [
    "rot = \"OPENQASM 3.0; qubit[1] q; ry(0.3) q[0];\"\n",
    "print(wq.run(rot, observables=[\"Z0\", \"X0\"], key=key).expectations)\n",
    "try:\n",
    "    wq.run(rot, observables=[\"Z0\"], method=\"exact\", key=key)\n",
    "except wq.EngineError as e:\n",
    "    print(\"refused:\", e.message)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "getting-started-16",
   "metadata": {},
   "source": [
    "## Bloch vectors\n",
    "\n",
    "Each qubit's reduced state, from the engine's expectation values of X, Y and Z on it. In a Bell pair each qubit alone is maximally mixed, so its vector has length 0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "getting-started-17",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-11T12:23:53.422136Z",
     "iopub.status.busy": "2026-11-11T12:23:53.422071Z",
     "iopub.status.idle": "2026-11-11T12:23:53.425127Z",
     "shell.execute_reply": "2026-11-11T12:23:53.424855Z"
    }
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0074e7c1c285417c8f868d5f1019061f",
       "version_major": 2,
       "version_minor": 1
      },
      "text/html": [
       "<div class=\"wq-bloch-card\" style=\"font-family:ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif;font-size:13px;line-height:1.45;border:1px solid var(--jp-border-color2,rgba(127,127,127,.35));border-radius:8px;padding:10px 12px;margin:2px 0;max-width:100%;overflow-x:auto\"><div><b>Bloch vectors</b> · statevector · accuracy <b>exact</b></div><div style=\"margin-top:6px\"><div style=\"display:inline-block;text-align:center;margin:0 8px 6px 0;vertical-align:top\"><svg xmlns=\"http://www.w3.org/2000/svg\" class=\"wq-bloch\" width=\"150\" height=\"160\" viewBox=\"0 0 150 160\" role=\"img\" aria-label=\"Qubit 0: Bloch vector (0, 0, 2.08167e-17)\"><circle cx=\"75\" cy=\"79\" r=\"54.00\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".35\"/><polyline points=\"119.23,68.41 122.90,70.47 125.74,72.68 127.72,75.00 128.79,77.39 128.95,79.81 128.18,82.21 126.50,84.55 123.94,86.81 120.54,88.92 116.37,90.87 111.48,92.62 105.97,94.13 99.93,95.38 93.47,96.36 86.69,97.03 79.71,97.40 72.64,97.45 65.62,97.19 58.76,96.61 52.18,95.74 45.99,94.58 40.29,93.15 35.19,91.48 30.77,89.59 27.10,87.53 24.26,85.32 22.28,83.00 21.21,80.61 21.05,78.19 21.82,75.79 23.50,73.45 26.06,71.19 29.46,69.08 33.63,67.13 38.52,65.38 44.03,63.87 50.07,62.62 56.53,61.64 63.31,60.97 70.29,60.60 77.36,60.55 84.38,60.81 91.24,61.39 97.82,62.26 104.01,63.42 109.71,64.85 114.81,66.52 119.23,68.41\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".25\" stroke-dasharray=\"3 2\"/><line x1=\"75.00\" y1=\"129.74\" x2=\"75.00\" y2=\"28.26\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"17.09\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|0⟩</text><line x1=\"75.00\" y1=\"28.26\" x2=\"75.00\" y2=\"129.74\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"140.91\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|1⟩</text><line x1=\"30.77\" y1=\"89.59\" x2=\"119.23\" y2=\"68.41\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"128.97\" y=\"66.08\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+x</text><line x1=\"44.03\" y1=\"63.87\" x2=\"105.97\" y2=\"94.13\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"112.79\" y=\"97.46\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+y</text><line x1=\"75\" y1=\"79\" x2=\"75.00\" y2=\"79.00\" stroke=\"#7aa0ff\" stroke-width=\"2.4\" stroke-linecap=\"round\"/><circle cx=\"75.00\" cy=\"79.00\" r=\"3.6\" fill=\"#7aa0ff\"/><text x=\"75\" y=\"10\" text-anchor=\"middle\" fill=\"currentColor\" style=\"font-size:11px;font-weight:600\">q0</text></svg><div style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;font-size:11px\">x 0 · y 0 · z 2.08167e-17<br>length 2.08167e-17</div></div><div style=\"display:inline-block;text-align:center;margin:0 8px 6px 0;vertical-align:top\"><svg xmlns=\"http://www.w3.org/2000/svg\" class=\"wq-bloch\" width=\"150\" height=\"160\" viewBox=\"0 0 150 160\" role=\"img\" aria-label=\"Qubit 1: Bloch vector (0, 0, 2.08167e-17)\"><circle cx=\"75\" cy=\"79\" r=\"54.00\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".35\"/><polyline points=\"119.23,68.41 122.90,70.47 125.74,72.68 127.72,75.00 128.79,77.39 128.95,79.81 128.18,82.21 126.50,84.55 123.94,86.81 120.54,88.92 116.37,90.87 111.48,92.62 105.97,94.13 99.93,95.38 93.47,96.36 86.69,97.03 79.71,97.40 72.64,97.45 65.62,97.19 58.76,96.61 52.18,95.74 45.99,94.58 40.29,93.15 35.19,91.48 30.77,89.59 27.10,87.53 24.26,85.32 22.28,83.00 21.21,80.61 21.05,78.19 21.82,75.79 23.50,73.45 26.06,71.19 29.46,69.08 33.63,67.13 38.52,65.38 44.03,63.87 50.07,62.62 56.53,61.64 63.31,60.97 70.29,60.60 77.36,60.55 84.38,60.81 91.24,61.39 97.82,62.26 104.01,63.42 109.71,64.85 114.81,66.52 119.23,68.41\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".25\" stroke-dasharray=\"3 2\"/><line x1=\"75.00\" y1=\"129.74\" x2=\"75.00\" y2=\"28.26\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"17.09\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|0⟩</text><line x1=\"75.00\" y1=\"28.26\" x2=\"75.00\" y2=\"129.74\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"140.91\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|1⟩</text><line x1=\"30.77\" y1=\"89.59\" x2=\"119.23\" y2=\"68.41\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"128.97\" y=\"66.08\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+x</text><line x1=\"44.03\" y1=\"63.87\" x2=\"105.97\" y2=\"94.13\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"112.79\" y=\"97.46\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+y</text><line x1=\"75\" y1=\"79\" x2=\"75.00\" y2=\"79.00\" stroke=\"#7aa0ff\" stroke-width=\"2.4\" stroke-linecap=\"round\"/><circle cx=\"75.00\" cy=\"79.00\" r=\"3.6\" fill=\"#7aa0ff\"/><text x=\"75\" y=\"10\" text-anchor=\"middle\" fill=\"currentColor\" style=\"font-size:11px;font-weight:600\">q1</text></svg><div style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;font-size:11px\">x 0 · y 0 · z 2.08167e-17<br>length 2.08167e-17</div></div><div style=\"display:inline-block;text-align:center;margin:0 8px 6px 0;vertical-align:top\"><svg xmlns=\"http://www.w3.org/2000/svg\" class=\"wq-bloch\" width=\"150\" height=\"160\" viewBox=\"0 0 150 160\" role=\"img\" aria-label=\"Qubit 2: Bloch vector (0.564642, 0, 0.825336)\"><circle cx=\"75\" cy=\"79\" r=\"54.00\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".35\"/><polyline points=\"119.23,68.41 122.90,70.47 125.74,72.68 127.72,75.00 128.79,77.39 128.95,79.81 128.18,82.21 126.50,84.55 123.94,86.81 120.54,88.92 116.37,90.87 111.48,92.62 105.97,94.13 99.93,95.38 93.47,96.36 86.69,97.03 79.71,97.40 72.64,97.45 65.62,97.19 58.76,96.61 52.18,95.74 45.99,94.58 40.29,93.15 35.19,91.48 30.77,89.59 27.10,87.53 24.26,85.32 22.28,83.00 21.21,80.61 21.05,78.19 21.82,75.79 23.50,73.45 26.06,71.19 29.46,69.08 33.63,67.13 38.52,65.38 44.03,63.87 50.07,62.62 56.53,61.64 63.31,60.97 70.29,60.60 77.36,60.55 84.38,60.81 91.24,61.39 97.82,62.26 104.01,63.42 109.71,64.85 114.81,66.52 119.23,68.41\" fill=\"none\" stroke=\"currentColor\" stroke-opacity=\".25\" stroke-dasharray=\"3 2\"/><line x1=\"75.00\" y1=\"129.74\" x2=\"75.00\" y2=\"28.26\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"17.09\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|0⟩</text><line x1=\"75.00\" y1=\"28.26\" x2=\"75.00\" y2=\"129.74\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"75.00\" y=\"140.91\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">|1⟩</text><line x1=\"30.77\" y1=\"89.59\" x2=\"119.23\" y2=\"68.41\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"128.97\" y=\"66.08\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+x</text><line x1=\"44.03\" y1=\"63.87\" x2=\"105.97\" y2=\"94.13\" stroke=\"currentColor\" stroke-opacity=\".2\"/><text x=\"112.79\" y=\"97.46\" text-anchor=\"middle\" dominant-baseline=\"central\" fill=\"currentColor\" style=\"font-size:10px;opacity:.65\">+y</text><line x1=\"75\" y1=\"79\" x2=\"99.98\" y2=\"31.14\" stroke=\"#7aa0ff\" stroke-width=\"2.4\" stroke-linecap=\"round\"/><circle cx=\"99.98\" cy=\"31.14\" r=\"3.6\" fill=\"#7aa0ff\"/><text x=\"75\" y=\"10\" text-anchor=\"middle\" fill=\"currentColor\" style=\"font-size:11px;font-weight:600\">q2</text></svg><div style=\"font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;font-size:11px\">x 0.564642 · y 0 · z 0.825336<br>length 1</div></div></div><div style=\"opacity:.7\">Each qubit's reduced state: length 1 is pure, shorter is mixed (entangled with the others, or noisy).</div></div>"
      ],
      "text/plain": [
       "Bloch(3 qubits, statevector, accuracy exact)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "wq.Bloch(\"OPENQASM 3.0; qubit[3] q; h q[0]; cx q[0], q[1]; ry(0.6) q[2];\", key=key)"
   ]
  }
 ],
 "metadata": {
  "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.12.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}