Qcircuit
A macro package that simplifies the construction of quantum circuit diagrams in LaTeX, making it as easy as constructing an array.
What is it?
A High-Level LaTeX Package for Quantum Circuits
Typesetting quantum circuit diagrams using standard LaTeX graphics packages is a difficult and time-consuming business. Qcircuit is a high-level macro package designed to change that.
With Qcircuit, drawing quantum circuit diagrams is as easy as constructing an array. In a matter of minutes you can learn the basic syntax and start producing circuits of your own. The package is built on top of the Xy-pic and ifpdf packages.
Qcircuit was originally created by Bryan Eastin and Steve Flammia while working at the University of New Mexico. The project has since been maintained on GitHub with contributions from the CQuIC community and the broader quantum information science community.
The package has been adopted widely across the quantum information community and is available through the Comprehensive TeX Archive Network (CTAN).
Getting Started
Installation
Three ways to install Qcircuit — pick whichever suits your workflow.
Via TeX Package Manager Recommended
The easiest and most reliable method.
Qcircuit is on CTAN, so you can install it via your TeX distribution's package manager. The package name is qcircuit.
tlmgr install qcircuit
mpm --install qcircuit
Simple Install
Works on any TeX distribution, no admin rights needed.
- Download
qcircuit.styfrom GitHub or CTAN. - Place
qcircuit.styin the same folder as your.texdocument. - Add
\usepackage{qcircuit}to your preamble.
TeX Tree Install
Makes Qcircuit available system-wide.
Place qcircuit.sty in your TeX tree and update the database:
Place the file in:
~/Library/texmf/tex/latex/Qcircuit/
Place the file in:
C:\Program Files\texmf\tex\latex\Qcircuit\
Then update the tree:
initexmf --update-fndb
Find your texmf root:
locate texmf
Place the file there, then run:
texhash
How to use it
Usage
After installation, call the package in your document preamble.
Preamble
\usepackage[options]{qcircuit}
Qcircuit loads the amsmath and xy packages automatically. No need to load them separately.
Available Options
Both options are off by default, letting you define your own commands without clashes. Enable them explicitly:
\usepackage[braket, qm]{qcircuit}
The \Qcircuit Command
Qcircuit defines the \Qcircuit command as an \xymatrix with entries of default size 0em:
\Qcircuit @C=1em @R=1em { ... }
The @C parameter controls column spacing and @R controls row spacing. Circuit elements are placed in an array-like structure using & column separators and \\ row separators.
Qtutorial.tex file to verify your installation. By inspecting the figures produced and comparing with the source code, you'll quickly learn the syntax.
Code Samples
Circuit Examples
Copy any of these into your LaTeX document to get started.
Single-Qubit NOT Gate
Beginner\Qcircuit @C=1em @R=1em {
\lstick{\ket{0}} & \gate{X} & \rstick{\ket{1}} \qw
}
The simplest possible circuit — a Pauli-X gate applied to a qubit initialised in |0⟩.
Bell State Preparation
Beginner\Qcircuit @C=1em @R=1em {
\lstick{\ket{0}} & \gate{H} & \ctrl{1} & \qw \\
\lstick{\ket{0}} & \qw & \targ & \qw
}
Hadamard gate followed by a CNOT gate to create a maximally entangled Bell state.
Quantum Teleportation
Intermediate\Qcircuit @C=1em @R=1em {
\lstick{\ket{\psi}} & \ctrl{1} & \gate{H} & \meter & \cw \\
\lstick{\ket{0}} & \targ & \qw & \meter & \cw \\
\lstick{\ket{0}} & \qw & \qw & \gate{X}\cwx[-1] & \gate{Z}\cwx[-2] & \rstick{\ket{\psi}} \qw
}
Standard quantum teleportation protocol with measurements and classical feed-forward.
Multi-Qubit Gate
Intermediate\Qcircuit @C=1em @R=1em {
& \multigate{2}{U} & \qw \\
& \ghost{U} & \qw \\
& \ghost{U} & \qw
}
Three-qubit unitary gate spanning multiple rows using \multigate and \ghost.
Centered in a Figure
Usage tip\begin{figure}[h]
\mbox{
\Qcircuit @C=1em @R=1em {
& \gate{X} & \qw
}
}
\caption{NOT Gate}
\end{figure}
Use \mbox{} to center a circuit inside a figure environment.
Vertical Centering in Text
Usage tip$\begin{array}{c}
\Qcircuit @C=1em @R=1em {
& \gate{X} & \qw
}
\end{array}$
Vertically center an entire circuit within a line of inline text.
Troubleshooting
Frequently Asked Questions
Why is Qcircuit suddenly generating lots of errors?
If Qcircuit was previously working and suddenly stopped, the most likely cause is that you are using Xy-pic version 3.8 or later with Qcircuit version 1.2 or earlier. You should switch to version 2 or later of the package. Use the qcircuit.sty file (not the old Qcircuit.tex).
Can I put a label and a gate in the same entry?
No. A label is treated as a kind of gate command, so you can't put a label and a gate in the same entry — just like you can't put two gates in the same entry. Each circuit entry holds exactly one element.
Why isn't my circuit centered? / Why do my labels stick out?
Labels are treated as having zero size, which prevents them from affecting the circuit layout but also means they are not considered when calculating the circuit's bounding box. Use this hack for labels that stick out:
\Qcircuit @C=1em @R=1em {
\push{\rule{0em}{1em}} & & \dstick{label} \\
\push{\rule{2em}{0em}} & \lstick{label} & \gate{A}
}
How can I place a label between rows?
For rough positioning, use \dstick or \ustick. For precise vertical placement, use \raisebox:
\Qcircuit @C=1em @R=1em {
& \gate{A} & \qw & & &\gate{B} & \qw \\
& \gate{C} & \qw & \raisebox{2em}{=} & &\gate{D} & \qw
}
Why can't I center circuits inside figures?
Place the \Qcircuit command inside a \mbox{}, an equation environment, or a \centerline{}. If all else fails, try \centering followed by \leavevmode inside the figure environment.
\begin{figure}[h]
\mbox{
\Qcircuit @C=1em @R=1em { & \gate{X} & \qw }
}
\caption{NOT Gate}
\end{figure}
How can I vertically center a circuit in a line of text?
Using $...$ centers the top row. For full vertical centering, use the array environment:
$\begin{array}{c}
\Qcircuit @C=1em @R=1em {
& \gate{X} & \qw
}
\end{array}$
How do I color parts of my circuit?
LaTeX views the wires and gate outlines as a single object, so you cannot color them separately. You can color the entire circuit or any text argument in the normal manner using the xcolor package.
More questions? See the full FAQ on GitHub Wiki or submit an issue.
The Team
Authors & Contributors
dev branch, and help improve Qcircuit for the whole community. See the open issues for ideas.
Get It
Downloads & Resources
Download ZIP
Full repository including source, tutorial, and examples
qcircuit.sty
Just the style file — all you need for most use cases
Tutorial PDF
Compiled Qtutorial.pdf — comprehensive reference guide
Qtutorial.tex
Tutorial source — compile it to verify your installation
GitHub Repository
Source code, issues, pull requests, and GitHub wiki
CTAN Package Page
Official CTAN listing with package documentation and downloads