Add global rotations tutorial reproducing ideal Fig. 4a (issue #119).

.gitignore

@@ -6,6 +6,9 @@
 .vscode
 experiments/
 
+# Local reference material (papers, notes) — not part of the repo
+*.pdf
+
 # mkdocs
 site/
 docs/reference/

docs/demos/global_rotations.ipynb

@@ -0,0 +1,255 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "71569fb7",
+      "metadata": {},
+      "source": [
+        "# Global rotations on colour codes\n",
+        "\n",
+        "This tutorial reproduces the **ideal (noiseless) simulation** of Fig. 4a from\n",
+        "[Bluvstein et al., Nature (2026)](https://www.nature.com/articles/s41586-025-09848-5):\n",
+        "subjecting quantum error-correction codes of different dimensionality to a\n",
+        "**global $R_Z(\\varphi)$ rotation**, then measuring the logical $X$ projection\n",
+        "and X-stabilizer revival.\n",
+        "\n",
+        "We use **Tsim** to prepare $|+_L\\rangle$ (hypercube encoder for $[[7,1,3]]$, Stim\n",
+        "graph-state synthesis for $[[15,1,3]]$). The rotation sweep uses exact state\n",
+        "vectors, which is fast for $n \\le 15$ and matches the paper's noiseless logical\n",
+        "response. It is **not** the experimental lookup-table decoder or postselection\n",
+        "pipeline."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "75a69061",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import numpy as np\n",
+        "import matplotlib.pyplot as plt\n",
+        "from tsim import Circuit\n",
+        "\n",
+        "from utils.global_rotation import (\n",
+        "    CODE_7_PLUS_L,\n",
+        "    GATE_LABELS_DEG,\n",
+        "    build_systems,\n",
+        "    compute_curve,\n",
+        "    reed_muller_prep_circuit,\n",
+        "    verify_encoding_flows,\n",
+        "    verify_steane_plus_l_flows,\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "3a6179ad",
+      "metadata": {},
+      "source": [
+        "## Physical setup\n",
+        "\n",
+        "Fig. 4a studies\n",
+        "\n",
+        "$$|+_L\\rangle \\;\\xrightarrow{\\; R_Z(\\varphi)^{\\otimes n}\\;}\\; \\text{measure } X_L \\text{ and stabilizers}$$\n",
+        "\n",
+        "for four configurations:\n",
+        "\n",
+        "* **2D colour code** — $[[7,1,3]]$ Steane code\n",
+        "* **3D colour code** — $[[15,1,3]]$ quantum Reed–Muller code\n",
+        "* **Unentangled** — $|+\\rangle^{\\otimes 15}$ analysed with the same 3D observables\n",
+        "* **3D negative stabilizer** — Reed–Muller state with flipped Z-check signs\n",
+        "\n",
+        "Encoded 2D/3D codes show **X-stabilizer revivals** at Clifford angles ($0^\\circ,\n",
+        "\\pm 90^\\circ, \\ldots$). The 3D Reed–Muller code has an additional revival at\n",
+        "$\\pm 45^\\circ$ (transversal $T$), where $\\langle X_L\\rangle = 1/\\sqrt{2}$.\n",
+        "Unentangled qubits analysed with the same 15-body observables revive only near\n",
+        "$\\pm 180^\\circ$.\n",
+        "\n",
+        "This notebook is an **ideal noiseless** tutorial calculation. The experimental\n",
+        "Fig. 4a curves additionally use lookup-table decoding, postselection, and\n",
+        "purity normalization (Methods)."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c7c5d1e0",
+      "metadata": {},
+      "source": [
+        "## Hypercube encoding of $|+_L\\rangle$ for $[[7,1,3]]$\n",
+        "\n",
+        "The QuEra codes belong to the Reed–Muller family (Extended Data Fig. 10a). For\n",
+        "the 2D Steane code the **fourth CZ layer is turned off**. Qubit 6 starts in\n",
+        "$|+\\rangle$; qubits 0–5 in $|0\\rangle$."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "60e04d88",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "encoding = Circuit(CODE_7_PLUS_L)\n",
+        "encoding.diagram(\"timeline-svg\", height=320)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "85462598",
+      "metadata": {},
+      "source": [
+        "Verify stabilizers and logical operators with Stim's `flow_generators()`, as\n",
+        "suggested in [issue #119](https://github.com/QuEraComputing/tsim/issues/119):"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "3f088d17",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "encoding_flows = verify_encoding_flows(CODE_7_PLUS_L)\n",
+        "prep_flows = verify_steane_plus_l_flows()\n",
+        "rm_flows = reed_muller_prep_circuit().flow_generators()\n",
+        "\n",
+        "print(f\"{len(encoding_flows)} flows on the Clifford encoding circuit\")\n",
+        "print(f\"{len(prep_flows)} flows on the full $[[7,1,3]]$ $|+_L\\\\rangle$ preparation\")\n",
+        "print(f\"{len(rm_flows)} flows on the $[[15,1,3]]$ preparation\")\n",
+        "for flow in encoding_flows[:4]:\n",
+        "    print(flow)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "c5fed406",
+      "metadata": {},
+      "source": [
+        "## Global rotation sweep\n",
+        "\n",
+        "For each $\\varphi/\\pi \\in [-1, 1]$, we apply global $R_Z(\\varphi)$ and evaluate\n",
+        "\n",
+        "1. $\\langle X_L\\rangle$ (logical $X$ projection), and\n",
+        "2. mean $|\\langle S_j^X\\rangle|$ over X-type stabilizers (normalized to unit peak).\n",
+        "\n",
+        "Global $R_Z$ disturbs X-checks while leaving Z-checks invariant; the bottom panel\n",
+        "tracks X-stabilizer revivals, matching the Fig. 4a convention."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "7f351602",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "N_ANGLES = 37\n",
+        "angles_deg = np.linspace(-180, 180, N_ANGLES)\n",
+        "\n",
+        "systems = build_systems()\n",
+        "curves = {system.label: compute_curve(system, angles_deg) for system in systems}"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "214da9bd",
+      "metadata": {},
+      "source": [
+        "## Fig. 4a (ideal simulation)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "e923c263",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "plot_order = [\n",
+        "    \"2D colour ($[[7,1,3]]$)\",\n",
+        "    \"3D colour ($[[15,1,3]]$)\",\n",
+        "    \"Unentangled\",\n",
+        "    \"3D negative stabilizer\",\n",
+        "]\n",
+        "colors = [\"C0\", \"C3\", \"C2\", \"C1\"]\n",
+        "\n",
+        "fig, axes = plt.subplots(2, 1, figsize=(8, 5.5), sharex=True, constrained_layout=True)\n",
+        "\n",
+        "for label, color in zip(plot_order, colors):\n",
+        "    curve = curves[label]\n",
+        "    axes[0].plot(curve.angles_deg, curve.logical_x, \"-\", color=color, label=label)\n",
+        "    if label != \"Unentangled\":\n",
+        "        axes[1].plot(curve.angles_deg, curve.stabilizer_abs, \"-\", color=color, label=label)\n",
+        "\n",
+        "axes[0].set_ylabel(r\"Logical $X$ projection\")\n",
+        "axes[0].set_ylim(-1.05, 1.05)\n",
+        "axes[0].axhline(0, color=\"0.85\", lw=0.8)\n",
+        "axes[0].legend(loc=\"lower center\", ncol=2, fontsize=8, frameon=False)\n",
+        "\n",
+        "axes[1].set_ylabel(\"Normalized abs. stabilizer\")\n",
+        "axes[1].set_xlabel(r\"Global $\\varphi\\;(^{\\circ})$\")\n",
+        "axes[1].set_ylim(-0.05, 1.05)\n",
+        "axes[1].legend(loc=\"lower center\", ncol=2, fontsize=8, frameon=False)\n",
+        "\n",
+        "for ax in axes:\n",
+        "    ax.set_xlim(-185, 185)\n",
+        "    ax.set_xticks(list(GATE_LABELS_DEG.keys()))\n",
+        "    ax.set_xticklabels(list(GATE_LABELS_DEG.values()))\n",
+        "\n",
+        "fig.suptitle(\"Fig. 4a — global $R_Z$ rotation (noiseless simulation)\", y=1.02)\n",
+        "plt.show()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "b2938e84",
+      "metadata": {},
+      "source": [
+        "## What to notice\n",
+        "\n",
+        "* **2D colour** — X-stabilizers revive at $0^\\circ$ and $\\pm 90^\\circ$; logical\n",
+        "  $X$ is $+1$ at $0^\\circ$ and $\\approx 0$ at $\\pm 90^\\circ$.\n",
+        "* **3D colour** — same Clifford stabilizer revivals **plus** a logical-$X$ value\n",
+        "  $1/\\sqrt{2}$ at $\\pm 45^\\circ$ (transversal $T$).\n",
+        "* **Unentangled** — $\\langle X_L\\rangle = \\cos^{15}\\varphi$; revivals only near\n",
+        "  $\\pm 180^\\circ$, not at Clifford angles.\n",
+        "* **Negative stabilizer** — wrong Z-check signs remove the 45° T feature while\n",
+        "  Clifford stabilizer revivals remain.\n",
+        "\n",
+        "The $[[15,1,3]]$ state is prepared from verified stabilizer generators (Stim\n",
+        "graph-state synthesis). The paper's hypercube encoder (Extended Data Fig. 10a) is\n",
+        "shown and verified for $[[7,1,3]]$ above; the full 15-qubit hypercube circuit is\n",
+        "not in the supplementary Stim files."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "494eba68",
+      "metadata": {},
+      "source": [
+        "## Summary\n",
+        "\n",
+        "In this notebook we:\n",
+        "\n",
+        "* built and verified the QuEra hypercube encoder for $|+_L\\rangle$ on $[[7,1,3]]$,\n",
+        "* prepared $[[15,1,3]]$ $|+_L\\rangle$ from its stabilizer generators,\n",
+        "* swept a global $R_Z$ rotation and computed logical-$X$ and X-stabilizer observables, and\n",
+        "* reproduced the qualitative structure of Fig. 4a for all four curves."
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.13.0"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}