MuqcsCraft

MuqcsCraft is a web-based graphical simulator and visualizer for quantum circuits, built on top of the muqcs library.

MuqcsCraft allows gates to be drag-and-dropped onto a circuit. Each gate can have an arbitrary number of control and anticontrol qubits. MuqcsCraft computes and can display the phase, probability, purity, linear entropy, and von Neumann entropy (to quantify mixedness) of individual qubits; and the concurrence (to quantify entanglement), correlation, purity, linear entropy, and von Neumann entropy of each pair of qubits. MuqcsCraft runs inside a web browser, and like Quirk, the structure of the circuit is encoded in the URL query string, making it easy to bookmark or share circuits just by copying the URL.

Below the circuit, MuqcsCraft can show the state vector layer-by-layer. For certain gates (namely, the Hadamard, Pauli $X$, $Y$, $Z$, $S = Z^{1/2}$, $S^{-1} = Z^{-1/2}$, $T = Z^{1/4}$, $T^{-1} = Z^{-1/4}$, Phase($\theta$) $= Z^{\theta/\pi}$, GlobalPhase($\theta$), and SWAP gates, with arbitrary control and anticontrol qubits) that appear alone in their layer, the state vector is shown with difference highlighting, which uses colors, arrows, and symbols to make it easier to see how the gate changes the state vector in that layer.

Gates whose effects on the state vector cannot be visualized directly with difference highlighting can be replaced with equivalent sequences of gates using an 'Expand Circuit' button. The toolbar in MuqcsCraft includes so-called generalized gates (generalized $Z$, generalized $Y$, and generalized Hadamard), which are not standard, but are well suited for visualization with difference highlighting, and whose use allows the 'Expand Circuit' button to produce shorter sequences. This is further explained in the companion video and paper.

The definitions of the matrices for all the gates, including the generalized gates, are available here.

Above: an example circuit showing off several features of MuqcsCraft. A: circuit diagram. B: toolbar from which gates can be dragged. C: reduced state of each qubit. D: state vectors with difference highlighting. E: bits of the base states. F: half-matrix showing information about each pair of qubits. G: tooltip.

Above: a circuit that generates a W-4 state. A: reduced state of each qubit, layer-by-layer. B: state vector, layer-by-layer, with difference highlighting.

Above: one iteration of Grover's algorithm.

MuqcsCraft also has features to export circuits to Quirk and to IBM Quantum Composer.

Companion Video

A video demonstrating MuqcsCraft's functionality:

View the video

Companion Paper

A companion paper at https://arxiv.org/abs/2510.00895 explains the design and features of MuqcsCraft. Please cite that paper if you would like to cite the MuqcsCraft software in your own academic work.

Building the code

The build process is simple but idiosyncratic, and is designed to produce a single .html file containing all icon images embedded in the file.

The util/ folder contains a Makefile to build two utilities: (1) a "quoter" written in C, which takes the contents of a file and outputs it as a quoted string, escaping characters as necessary, and (2) an "includer" written in perl, that can be used as a very simple text preprocessor to include the contents of one file in another, similar to #include statements in C code, by using SIMPLE_INCLUDE statements.

The icons/ folder contains image files in png format, and a Makefile that converts the png files to a base64 plain text encoding that is then quoted and saved into .txt files. The .txt files can be easily included in javascript source files. The generated .txt files are provided in the github repository for convenience, however developers who edit the png files will need to run the Makefile to regenerate the .txt files.

The root folder contains a Makefile that includes the muqcs.js and icons/*.txt files into the index.html.source file and outputs the final index.html file. Search for SIMPLE_INCLUDE inside the index.html.source file to find where these inclusions happen.

So the index.html.source file is the one that a programmer would normally edit to modify functionality before running 'make' to build the index.html file.

Search for "web analytics" inside the index.html.source file to see how visits are logged without tracking personal information.

The doc/ folder contains some diagrams that could be useful to understand the layout source code.