Consider deprecating the `cirq-web` module

[mhucka]

Description of the issue

This is a proposal to deprecate the cirq-web module after the next Cirq release (1.7), with intention to remove it from the code base in a subsequent release.

Motivations

The cirq-web module is an experimental tool that offers an interactive 3D circuit visualization facility implemented in JavaScript. It can be run in a web browser to display circuit diagrams such as the static example shown below:

Unfortunately, despite the allure of interactive 3D visualization of quantum circuits, the cirq-web module has seen very little use since its introduction approximately five years ago. An internal survey has revealed that there are no known users of cirq-web in the Quantum AI team, and searches of GitHub and the web at large for cirq-web or cirq_web failed to turn up any signs of use of cirq-web in other projects or publications.

In addition:

• The many JavaScript package dependencies has been a maintenance burden for the Cirq maintainers, due to frequent security-related version updates to JavaScript libraries.

• The current implementation of cirq-web lacks some desirable features (e.g., cirq-web shows a blank window for circuits with no-target operations #5172, Improve support for circuit repeats in cirq-web #7540), hampering users who have tried to use it.

• Informal interviews with Quantum AI users who have attempted to use it revealed they find the complexity of the 3D diagrams grows too quickly with increasing circuit sizes, leading them to give up (and in some cases implement their own alternatives that use a different visualization approach).

• The module has only sparse API documentation.

Taken together, these points argue that we should deprecate cirq-web from Cirq, with the intention to remove it in a future release.

Proposed process

We would aim to do roughly the following steps:

1. After the upcoming Cirq 1.7 release is made, add deprecation messages to the main branch of Cirq version 1.8.0.dev in GitHub. This deprecation message will be included in the public release of Cirq 1.8. Also inform developers and users of the plan, and ask them to contact us if it causes a problem.

2. After the release of version 1.8, remove the cirq-web module from the main branch in GitHub (which at that point will be for development version 1.9.0.dev). When the version 1.9 release is made, the cirq-web module will be omitted.

Optionally, if there is interest by the developer and user community, the cirq-web module could be moved to ReCirq.

[smrutee20]

Hey @mhucka, I'm interested in helping with this.

I had a quick look at cirq-web and noticed cirq_web/init.py mainly exports three classes: Widget, BlochSphere, and Circuit3D.

What if we just throw the standard deprecated_class decorator (the one from cirq-core/cirq/_compat.py) onto those three? That way, users get a warning whenever they try to use them, which seems pretty consistent with how the rest of Cirq handles this stuff. Would that approach align with what you have in mind, or is there a different scope/PR structure you'd prefer? Happy to start with a small PR if so.

[seunomonije]

Some thoughts @mhucka

The maintenance burden is clear, especially since the JS dependency work has nothing to do with core Cirq functionality. If moving to ReCirq is an option, would it be permissible to use something like continue-on-error: true or a similar pattern for CI checks so that the same thing doesn't happen?

The BlochSphere and Circuit widgets were built with the intention to improve over time, with most of the problems reducing down to fixing rough edges on circuit serialization back and forth from the TS (just now finding the circuits here cirq-core/cirq/protocols/json_test_data/ would be a useful for smoke testing).

I also think the utility would be clearer if widgets were built to solve a specific problem rather than be general solutions. For example, could cirq-web be used to eventually hypothesize, construct, or replay meaningful fault-tolerant circuit constructions or costly primitives at the physical level? Or provide a mechanism to stitch together these primitives or lower-level subroutines like lattice surgery? Eg. the architecture diagrams in the verifiable DQI paper.

You can (very roughly, prototyped over a day, ~600 LOC) extend the existing infra to introduce a hybrid 2d/3d mode as an example (adapted from the 2024 magic state cultivation paper):

cirqweb2d_small.mp4

However, the above is all theoretical. As noted, the cirq-web module has had plenty of time to find utility and has not done so. I do think that there remains a lot of potential with circuit visualization and that the module could be useful in some experimental capacity, but the effort required to realize this potential may be out of scope. I will be working on visualizing quantum computation for a while and plan(ned) to use cirq-web, but can adapt.

Happy to chip in as needed to help move the issue forward.

[mhucka]

Discussed during Cirq Cynq 2026-07-08:

• Ask QAI UI team for additional input in whether we can build on this. If not, next consider moving this to ReCirq

• Will this be useful for QEC? Ask the QEC teams if they envision using some kind of 3D visualization like this.

[mhucka]

@seunomonije Thank you so much for your input and comments! As mentioned in the notes from the Cynq today, we want to consult with a couple of other teams. Depending on the outcome of that, it will most probably either be kept in Cirq, or moved to Recirq.