feat: Add crumpy Python package for visualizing Crumble timeline in Jupyter

[guenp]

This PR adds a new Python package called crumpy to the glue/ folder. CrumPy was built by @zzzappy as part of his summer 2025 internship at Riverlane. We'd like to contribute this back to Stim.

In order to make this work we had to make changes to the Crumble source code. The modified files are in glue/crumpy/src/js. There is one other file where the edit is just a few lines, so in this PR I've left that file in glue/crumble. A follow-up project could be to refactor the Crumble code and unify this code and make it configurable for use with CrumPy.

How it works

Please see glue/crumpy/README.md for the project overview and build instructions:

CrumPy makes use of the widget creation tool
AnyWidget. With AnyWidget, Python classes are able to
take JavaScript and display custom widgets in Jupyter environments. In order to
visualize Crumble within CrumPy, some modifications in the Crumble source code
were needed. CrumPy therefore includes both JavaScript and Python subparts:

glue/
├── crumpy/                       # Modified Crumble code
│   ├── src/
│   │   ├── crumpy/
│   │   │   └── __init__.py       # Python code for CircuitWidget
│   │   ├── js/
│   │   │   ├── draw/             # Modified JS source code
│   │   │   ├── main.js           # Main circuit visualization/setup
│   │   │   ├── bundle.js         # Bundled JavaScript will appear here
│   │   │   └── package.json      # Bundling setup and scripts
│   └── ...
│   ├── tests/                    # Python tests
│   ├── simple_example.ipynb      # Example notebook
│   └── getting_started.ipynb     # Getting started notebook

glue/crumpy contains the main Python package code.

glue/crumpy/src/crumpy/__init__.py contains the main class of the crumpy package,
CircuitWidget.

glue/crumpy/src/js/ contains the modified Crumble circuit visualization code that
will be rendered in the CircuitWidget widget. In the build step, we copy the Crumble
source code and modify it with the .js files in this folder.

glue/crumpy/src/js/main.js contains the main circuit visualization and setup logic
in the form of the render function
used by AnyWidget.

Bundling

To create a Jupyter widget, AnyWidget takes in JavaScript as an ECMAScript
Module (ESM). Any changes made to the JavaScript code that backs the circuit
visualization will require re-bundling into one optimized ESM file.

To bundle the JavaScript:

1. Navigate to glue/crumpy/src/js
2. If you haven't yet, run npm install (this will install the
   esbuild bundler)
3. Run npm run build (or npm run watch for watch mode)

A new bundle should appear at src/js/bundle.js.

Example

circuit_with_error = """
#!pragma MARKX(0) 0
TICK
CNOT 0 1
TICK
H 0
"""

CircuitWidget(stim=circuit_with_error)

Todo

This PR is still in draft mode for initial review comments.

• Add CI/CD build and PyPI release pipeline

You can find the current version of CrumPy here: https://github.com/Deltakit/crumpy and the latest PyPI release: https://pypi.org/project/crumpy/.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB