Add quil-plotting module

.gitignore

@@ -22,3 +22,11 @@ quil-rs/pyrightconfig.json
 
 # unversioned developer notes
 scratch/
+
+# images written by the quil-plotting example notebook
+quil-plotting/examples/plots/
+.ipynb_checkpoints/
+
+# plots written by the quil-plotting tests, for visual inspection of a run
+quil-plotting/tests/test_plots/
+quil-plotting/tests/test_plots_altair/

quil-plotting/.ipynb_checkpoints/pyproject-checkpoint.toml

@@ -0,0 +1,120 @@
+[project]
+name = "quil-plotting"
+version = "0.1.0"
+requires-python = ">=3.8"
+description = "A Python package for visualizing Quil programs."
+documentation = "https://rigetti.github.io/quil-rs/quil.html"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Rigetti Computing", email = "softapps@rigetti.com" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.2.1",
+    "plotly>=5.11",
+    "kaleido==0.2.1",
+    "pandas>=2.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.3.7",
+    "maturin>=1.2.3",
+    "mypy>=1.1.1",
+    "pytest>=7.2.2",
+    "pdoc>=14.1.0",
+    "syrupy>=3.0.6"
+]
+
+# [build-system]
+# requires = ["setuptools>=61.0"]
+# build-backend = "setuptools.build_meta"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+line-length = 120
+indent-width = 4
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["D", "E4", "E7", "E9", "F", "I", "B", "S", "W"]
+ignore = [
+    "E741" # "Ambiguous" variable names like "I" aren't ambiguous in this contex.
+]
+fixable = ["ALL"]
+unfixable = []
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.per-file-ignores]
+"quil/**/*.py" = [
+    "F403", # * imports allowed in extension module glue.
+    "D100", # docstrings belong in type stubs
+    "D104",
+]
+"test/**/*.py" = [
+    "D",    # docstrings are not enforced in tests
+    "S101", # asserts are allowed in tests
+    "S301", # we need to test pickling
+]
+"make_docs.py" = [ "D" ]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pyright]
+# This diagnostic is raised when a type stub is found without a corresponding source file. This is
+# necessarily the case for a pure Rust pyo3 module, so disabling it.
+reportMissingModuleSource = false
+
+[tool.mypy]
+plugins = "numpy.typing.mypy_plugin"
+
+[[tool.mypy.overrides]]
+module = [
+    "quil.quil",
+]
+ignore_missing_imports = true

quil-plotting/examples/schedule_plotting.ipynb

@@ -0,0 +1,243 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Plotting Quil pulse schedules\n",
+    "\n",
+    "This notebook plots a Quil program's pulse schedule with both of `quil_plotting`'s backends:\n",
+    "\n",
+    "- **plotly** (`plot_schedule`) \u2014 the original backend.\n",
+    "- **Altair / Vega-Lite** (`plot_schedule_altair`) \u2014 renders static images in process, so it does\n",
+    "  not need an installed copy of Chrome to write a png or svg.\n",
+    "\n",
+    "Both read the same schedule dataframe and take the same options, so you can compare them directly."
+   ],
+   "id": "cell-00"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "Locate the package and the bundled test programs. This works without installing `quil_plotting`,\n",
+    "as long as the notebook lives somewhere inside the package."
+   ],
+   "id": "cell-01"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "from pathlib import Path\n",
+    "\n",
+    "PACKAGE_ROOT = next(p for p in [Path.cwd(), *Path.cwd().parents] if (p / \"quil_plotting\").is_dir())\n",
+    "sys.path.insert(0, str(PACKAGE_ROOT))\n",
+    "\n",
+    "PROGRAM_DIR = PACKAGE_ROOT / \"tests\" / \"programs\"\n",
+    "\n",
+    "# Imported after the path is set up, hence the `noqa`.\n",
+    "from quil.program import Program  # noqa: E402\n",
+    "\n",
+    "from quil_plotting import (  # noqa: E402\n",
+    "    add_plot_metadata,\n",
+    "    plot_schedule,\n",
+    "    plot_schedule_altair,\n",
+    "    program_to_dataframe,\n",
+    ")\n",
+    "\n",
+    "sorted(path.stem for path in PROGRAM_DIR.glob(\"*.quil\"))"
+   ],
+   "id": "cell-02"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Choose a program\n",
+    "\n",
+    "Set `PROGRAM_NAME` to any of the names listed above and re-run the notebook. Some suggestions:\n",
+    "\n",
+    "| name | what it shows |\n",
+    "| --- | --- |\n",
+    "| `multiple_gates_with_measures` | small and quick \u2014 a good place to start |\n",
+    "| `single_gate_iswap` | one two-qubit gate, with the coupler frame alongside the qubits |\n",
+    "| `sequenced_hadamard_barrier` | how barriers serialize the schedule |\n",
+    "| `randomized_circuit_0` | a busier circuit, ~26 us long |\n",
+    "| `rotated-surface-code` | 41 frames over 8 rounds of syndrome extraction \u2014 the stress case |"
+   ],
+   "id": "cell-03"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "PROGRAM_NAME = \"multiple_gates_with_measures\"\n",
+    "\n",
+    "program = Program.parse((PROGRAM_DIR / f\"{PROGRAM_NAME}.quil\").read_text())\n",
+    "print(f\"{PROGRAM_NAME}: {len(program.body_instructions)} instructions, \"\n",
+    "      f\"{len(program.calibrations.calibrations)} calibrations, {len(program.frames)} frames\")"
+   ],
+   "id": "cell-04"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The schedule dataframe\n",
+    "\n",
+    "Both backends are built on this. Each row is one IQ sample of one pulse, carrying the metadata\n",
+    "needed to place, colour, and label it. `program_to_dataframe` expands the program's calibrations\n",
+    "and schedules the result; `add_plot_metadata` adds the plotting columns (`Offset`, `Color`,\n",
+    "`Normalized IQ`, `Label`, ...)."
+   ],
+   "id": "cell-05"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = add_plot_metadata(program_to_dataframe(program))\n",
+    "print(f\"{len(df)} rows, spanning {(df['Time (s)'].max() - df['Time (s)'].min()) * 1e6:.3f} us\")\n",
+    "df.head()"
+   ],
+   "id": "cell-06"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The plotly backend\n",
+    "\n",
+    "**Interacting:** drag to zoom into a time range, double-click to reset, and click a legend entry to\n",
+    "hide that operation (double-click one to isolate it). Hovering a pulse shows its I/Q value, frame, and\n",
+    "channel type."
+   ],
+   "id": "cell-07"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = plot_schedule(program)\n",
+    "fig.show()"
+   ],
+   "id": "cell-08"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The Altair backend\n",
+    "\n",
+    "The same schedule, rendered through Vega-Lite.\n",
+    "\n",
+    "**Interacting:** drag to pan and scroll to zoom (both axes), and click a legend entry to isolate\n",
+    "that operation \u2014 the others dim rather than disappear, so the shape of the schedule is preserved.\n",
+    "Shift-click to select several. Hovering a pulse shows its I/Q value, frame, and channel type.\n",
+    "\n",
+    "Altair's default renderer loads Vega from a CDN. On a machine without internet access, run\n",
+    "`alt.renderers.enable(\"mimetype\")` first and JupyterLab will render the chart itself."
+   ],
+   "id": "cell-09"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "chart = plot_schedule_altair(program)\n",
+    "chart"
+   ],
+   "id": "cell-10"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Static export\n",
+    "\n",
+    "Altair renders png and svg in process. Plotly's `write_image` goes through Kaleido, which needs a\n",
+    "copy of Chrome on the machine \u2014 if it is missing, install one with `plotly_get_chrome`."
+   ],
+   "id": "cell-11"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "output_dir = Path(\"plots\")\n",
+    "output_dir.mkdir(exist_ok=True)\n",
+    "\n",
+    "chart.save(output_dir / f\"{PROGRAM_NAME}-altair.svg\")\n",
+    "chart.save(output_dir / f\"{PROGRAM_NAME}-altair.png\", ppi=100)\n",
+    "\n",
+    "# Needs Chrome; comment out if it is not installed.\n",
+    "fig.write_image(output_dir / f\"{PROGRAM_NAME}-plotly.png\")\n",
+    "\n",
+    "sorted(path.name for path in output_dir.iterdir())"
+   ],
+   "id": "cell-12"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Options\n",
+    "\n",
+    "Both backends accept the same arguments, so the same call works against either. A few worth trying:\n",
+    "\n",
+    "- `runners` \u2014 what to stack up the y-axis (default `\"Qubit\"`).\n",
+    "- `color_by` / `label_by` \u2014 what drives the colours and the legend. Defaults to `\"Operation\"`,\n",
+    "  the gate (or, in future, reset) each pulse came from. `\"Channel Type\"` groups by\n",
+    "  hardware channel instead of by operation.\n",
+    "- `exclude_readout` \u2014 set `False` to include the readout pulses, which are long and flat and\n",
+    "  otherwise dominate the normalization.\n",
+    "- `normalize_by` \u2014 the grouping whose peak amplitude scales each pulse to fit its row."
+   ],
+   "id": "cell-13"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot_schedule_altair(\n",
+    "    program,\n",
+    "    color_by=\"Channel Type\",\n",
+    "    label_by=\"Channel Type\",\n",
+    "    exclude_readout=False,\n",
+    ")"
+   ],
+   "id": "cell-14"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}