open-standards/wai/wai-quantum-py/notebooks/getting-started.ipynb
Transaction Science c4bda95cca wai-quantum 0.7.0 integrated: the generated material on the final tree, the pins it moves, and what replaying every job found
Generated on the final tree: the views page, rebuilt (802 495 bytes, under
1 MiB) from its sources; the notebooks' stored outputs; the agent docs. The
pins that move: wai-web's course check names its engine now, so its digest
moves (374b400e... to 969b2c1c..., and with every release from here), and the
page's wasm32 count is 18 (native 26, as pinned). wai-quantum-qpu's library
count is 34, as the cherry-picked pin says.

What replaying each workflow's jobs found, each fixed here:
- the views page's one line carried the estimate pane's English note, "no
  other beats on both", which the comparative-prose check reads across the
  line; the note says "none of the others beats on both";
- the docs runner's broken.qasm is broken on purpose, so the editors check
  requires it to fail to parse, as the intent set's broken programs;
- the command line's parse test named the service's submit and task in a
  build without the service; those checks are a test of their own, built
  with it;
- the set-only Merkle helpers warned in a build without receipts;
- a one-element loop in the service's strict test;
- the energy job looked for the live counter's line at the start of a line,
  where --nocapture puts it after the test's name;
- the Python test comparing a run on the service with one here now leaves out
  the provenance the service adds, and checks it is there.

The release heading's caller list is the final API check's: the frame text's
new fields and variant, and the request's compile passes and mitigation.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-28 08:43:06 -04:00

487 lines
34 KiB
Text

{
"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-10-28T08:01:08.252068Z",
"iopub.status.busy": "2026-10-28T08:01:08.251991Z",
"iopub.status.idle": "2026-10-28T08:01:08.262307Z",
"shell.execute_reply": "2026-10-28T08:01:08.262058Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"'0.1.0'"
]
},
"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-10-28T08:01:08.263274Z",
"iopub.status.busy": "2026-10-28T08:01:08.263203Z",
"iopub.status.idle": "2026-10-28T08:01:08.264838Z",
"shell.execute_reply": "2026-10-28T08:01:08.264640Z"
}
},
"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-10-28T08:01:08.265673Z",
"iopub.status.busy": "2026-10-28T08:01:08.265609Z",
"iopub.status.idle": "2026-10-28T08:01:08.267553Z",
"shell.execute_reply": "2026-10-28T08:01:08.267344Z"
}
},
"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-10-28T08:01:08.268230Z",
"iopub.status.busy": "2026-10-28T08:01:08.268142Z",
"iopub.status.idle": "2026-10-28T08:01:08.270293Z",
"shell.execute_reply": "2026-10-28T08:01:08.270115Z"
}
},
"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.7.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': '57b40878d70402c45a5d04cb2549ec2d3752317bacb9aea890add5069eb9b13a',\n",
" 'signature': '3be4c1a273e3e11c0a0203f06a3660245d397a998a104a1ae3eaffdb5aecfb6d5e336c3af429ab561de0e2ae349204b37e823f38214456ef2500b922acd34b08'}}}"
]
},
"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-10-28T08:01:08.271106Z",
"iopub.status.busy": "2026-10-28T08:01:08.271041Z",
"iopub.status.idle": "2026-10-28T08:01:08.272679Z",
"shell.execute_reply": "2026-10-28T08:01:08.272473Z"
}
},
"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-10-28T08:01:08.273369Z",
"iopub.status.busy": "2026-10-28T08:01:08.273300Z",
"iopub.status.idle": "2026-10-28T08:01:08.274741Z",
"shell.execute_reply": "2026-10-28T08:01:08.274539Z"
}
},
"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-10-28T08:01:08.275420Z",
"iopub.status.busy": "2026-10-28T08:01:08.275364Z",
"iopub.status.idle": "2026-10-28T08:01:08.313903Z",
"shell.execute_reply": "2026-10-28T08:01:08.313547Z"
}
},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "98c4cc1a28394e16862b3cfa5d240dac",
"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-10-28T08:01:08.315388Z",
"iopub.status.busy": "2026-10-28T08:01:08.315309Z",
"iopub.status.idle": "2026-10-28T08:01:08.317133Z",
"shell.execute_reply": "2026-10-28T08:01:08.316863Z"
}
},
"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-10-28T08:01:08.317804Z",
"iopub.status.busy": "2026-10-28T08:01:08.317745Z",
"iopub.status.idle": "2026-10-28T08:01:08.319238Z",
"shell.execute_reply": "2026-10-28T08:01:08.318955Z"
}
},
"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",
"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"
]
}
],
"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-10-28T08:01:08.319876Z",
"iopub.status.busy": "2026-10-28T08:01:08.319820Z",
"iopub.status.idle": "2026-10-28T08:01:08.321721Z",
"shell.execute_reply": "2026-10-28T08:01:08.321462Z"
}
},
"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-10-28T08:01:08.322331Z",
"iopub.status.busy": "2026-10-28T08:01:08.322276Z",
"iopub.status.idle": "2026-10-28T08:01:08.324933Z",
"shell.execute_reply": "2026-10-28T08:01:08.324626Z"
}
},
"outputs": [
{
"data": {
"application/vnd.jupyter.widget-view+json": {
"model_id": "71e7e316cf1c4d6993bd73c703188142",
"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
}