TorchQuantum promises pulse simulation at the top and lists it as coming soon

Pulse simulation appears as shipped and as unfinished

The opening description says the framework supports statevector simulation and pulse simulation on GPUs, and that it scales to simulating 30 or more qubits across multiple GPUs.

The feature list, further down the same page, ends with a line reading (coming soon) pulse-level simulation.

Both statements are in the current text of the project's own front page. One of them is out of date, and the front page gives no date on either claim, so a reader arriving today cannot tell which one reflects the code. The statevector path is corroborated elsewhere, since the device class stores a statevector and the file table describes devices.py as the class holding it. The pulse path has no such corroboration in the visible material.

The qubit number deserves the same scepticism. Thirty-plus qubits with multiple GPUs is a headline figure with no processor named, no batch size, no gate count and no runtime attached to it. Statevector simulation cost scales exponentially in qubit count, so a claim about the ceiling is only meaningful next to the workload it was measured on, and none is given.

The Qiskit comparison is built on top of Qiskit

One section sets out what distinguishes this framework from Qiskit and PennyLane: a dynamic computation graph, automatic gradient computation, fast GPU support, and batch model tensorized processing. All four are reasonable differentiators.

Then look at what gets installed:

qiskit>=2.5,<3
recommonmark
qiskit-ibm-runtime>=0.40
qiskit-aer>=0.17

Qiskit itself, the Aer simulator and the IBM runtime client are all direct requirements. So is anyone who installs this. The comparison is not that the framework replaces Qiskit in your environment, it is that it gives you a different programming model for the circuit while routing execution and hardware access through Qiskit's stack.

That is a coherent design, and it is also worth being explicit about when choosing: the escape hatch to real hardware is a Qiskit path, not an independent one. The examples reflect this too, with a dedicated directory for converting circuits to Qiskit alongside a plugin package described as holding converters and processors for IBMQ deployment.

The version floors span five years in one file

The requirements file mixes minimums from opposite ends of the ecosystem. These five lines sit together:

torch>=1.8.0
torchdiffeq>=0.2.3
torchpack>=0.3.0
torchvision>=0.9.0.dev20210130
tqdm>=4.56.0

The torchvision floor is a nightly build from January 2021. Written as a lower bound it does not require an old version, but it permits one, and a resolver that finds a compatible 2021 nightly will stop there rather than reaching for a current release. The same lines set a floor on torch from early 2021, on an ODE solver package, and on a PyTorch extension library.

Meanwhile the upper half of the same file asks for numpy 2.0 or newer and Qiskit 2.5 with an upper bound below 3. Those are current-generation requirements. One file therefore declares a floor set in 2021 and a floor set in the present, and nothing in it reconciles the two or records which combination was last tested.

The one exact pin is dill at 0.3.4, held to a single version while everything else floats. Whether that is deliberate or historical is not stated.

Documentation tooling is installed as a runtime requirement

The install path is three commands, a clone, a directory change, and an editable install:

git clone https://github.com/mit-han-lab/torchquantum.git
cd torchquantum
pip install --editable .

What that editable install resolves comes from the same requirements file the documentation tooling uses, and the documentation tooling is in it. nbsphinx builds the notebooks, recommonmark processes markdown, pylatexenc handles LaTeX, matplotlib draws the figures. A user who wants to run one circuit pays for a documentation toolchain.

The first line of the file makes the origin obvious. It is a theme override pointing at a git URL under an individual's fork, and it is commented out:

# furo @ git+https://github.com/frogcjn/torchquantum-doc-furo-theme.git

So the documentation theme is currently falling back to whatever the build defaults to, and the pinned version of dill is the only dependency held exactly, which suggests these lines accumulated rather than being curated as one policy.

The clone step also brings in a repository that contains a .gitmodules file. A plain clone without submodule initialisation leaves those directories empty, and nothing in the three command install guide mentions it.

Four blocks in the usage guide do not run as printed

The basic usage snippet builds a two wire device, applies gates through three different interfaces, and then stops mid-comment:

# obtain the qasm string
from torchquantum.plugin import op_history2qasm
print(op_history2qasm(qdev.n_wires, qdev.op_history))

# measure the

The measurement line the comment was introducing never appears. A second example is not merely incomplete but wrapped in an HTML comment block, so the measurement call it contains, with an explicit shot count, is invisible on the rendered page while remaining in the file.

The parameterized circuit example is cut inside the class body, ending on two characters of a method definition. And the two runnable scripts are labelled as Python while containing shell commands:

cd examples/vqe
python vqe.py

Neither block would execute under a Python interpreter. Both sets of instructions are also preceded by the phrase about deploying on the real IBM Quito quantum computer, a spelling that appears twice in the same form.

None of this makes the framework wrong. It makes the guide unreliable as a copy-and-paste source, which matters more here than usual because the notebooks it points at are the intended alternative reading path.

Deployment runs through a recorded operation history

Sending a circuit to real hardware does not happen by passing an object. The device is constructed with record_op turned on, gates applied through the device, the functional interface or an operator instance all accumulate into an operation history, and a plugin function converts that history into a QASM string.

That is the whole deployment mechanism, and it explains the design choice underneath. Because the framework builds a dynamic computation graph, the circuit at any moment is a record of what has been executed rather than a static description of what will be. Converting that record to QASM is a post-hoc translation of the history, not a compile step on a declared circuit.

The file table shows the other mode is still present. A graph module is described as the quantum gate graph used in static mode, alongside a device class that stores the statevector. So there are two execution paths, one dynamic and one static, and the visible documentation explains the dynamic one in detail.

For anyone building on this, the practical consequence is that the operation history is the thing you must get right. It is also the thing you can inspect, which is what makes the debugging story work.

A model checkpoint and retired examples sit at the root

The top level is not tidy. Alongside the source package, tests, docs and configuration files, it holds a committed PyTorch checkpoint named model_whole.pt, two notebooks named for paper sections, a logo image, a figures directory, and an old_examples directory kept next to the current examples.

The checkpoint is the notable one. A binary model file at the repository root is an artifact rather than source, and anyone cloning for the first time downloads it whether or not they want it. Its name suggests it is a full model rather than a checkpoint fragment, since the whole thing is bundled into one file.

The duplicated example directories are a smaller version of the same problem. Both exist, so anyone looking for the current MNIST implementation has two places to check and nothing at the top level telling them which is authoritative.

The published primary language for this repository is Jupyter Notebook rather than Python. That is consistent with a project whose teaching surface is notebooks and whose example index is a list of directories, and it also means the bulk of what a newcomer reads is tutorial code rather than library code.

setup.py starts with the licence and reads its version by exec

The packaging file opens with the MIT licence text, pasted above the imports and above the setuptools call. Only after the warranty disclaimer do the real statements begin.

The version is not declared. It is read by opening torchquantum/__version__.py and passing its contents to exec, then pulling the result out of a dict. That keeps a single source of truth for the version string, and it also means the version file is executed as Python at build time rather than parsed.

The author field is a single string listing nine names separated by commas, and the author email beside it is cut off mid-address. For a project with this many contributors the packaging metadata does not distinguish authors from maintainers, and a truncated email address in the published package metadata is not something a consumer would expect to find.

The install guide covers none of this. It assumes a clone and an editable install, which suits development against the source rather than consuming a released wheel.

Editorial conclusion

This suits someone writing a differentiable circuit whose gradients have to flow through PyTorch, and who can tolerate a framework whose last tagged release is from February 2024 while new work sits on another branch. Before building on it, check which branch you actually need, read the requirement floors rather than assuming recent versions, and confirm the qubit scale claim against your own hardware, since no processor or benchmark is named anywhere for it.

Frequently asked questions

Official sources

1. License: MIT
2. mit-han-lab/torchquantum on GitHub
3. Project website
4. README
5. Releases