% !TeX spellcheck = en_US \documentclass{scrartcl} \title{yquant.sty package documentation} \subtitle{Typesetting quantum circuits in a human-readable language} \author{Benjamin Desef} % BEGIN_FOLD Packages \RequirePackage{fontspec} \setmainfont{XCharter}[Scale=.98] \RequirePackage[osf, semibold]{sourcesanspro} \RequirePackage[math-style=ISO, bold-style=ISO, sans-style=italic]{unicode-math} \usepackage{xcolor} \definecolor{darkblue}{RGB}{5, 10, 122} \usepackage[english]{babel} \usepackage[colorlinks, linkcolor=darkblue, bookmarksdepth=paragraph]{hyperref} \usepackage[compat=newest]{yquant} \usepackage{braket,hyphenat,microtype,hologo,minted,import,ragged2e} \usetikzlibrary{quotes,fit,shapes.symbols,backgrounds,quantikz} \useyquantlanguage{qasm,groups} \usepackage{amsmath,adjustbox,cleveref} \usepackage[framemethod=tikz]{mdframed} % END_FOLD \makeatletter \long\def\compat#1{\texorpdfstring{\leavevmode\makenote{#1}\penalty10000 }{}} % BEGIN_FOLD Minted configuration \begingroup \catcode`\&=11 % I use Intel Python, which requires using the `activate' command first \renewcommand{\MintedPygmentize}{activate && pygmentize} \endgroup \definecolor{boxGrayBody}{gray}{.94} \definecolor{boxRedHead} {RGB} {178, 34, 34} \definecolor{boxRedBody} {RGB} {255, 255, 192} \definecolor{boxBlueHead}{RGB} {118, 152, 199} \definecolor{boxBlueBody}{RGB} {242, 247, 255} \definecolor{mintgreen} {RGB} {11, 97, 11} \setminted{frame=none, linenos=false, fontsize=\footnotesize, breaklines, bgcolor=boxGrayBody} \setmintedinline{bgcolor={}, fontsize=} \newmintinline[yquant]{text}{} \newmintinline[tex]{tex}{} \newmintinline[ebnf]{ebnf}{} % END_FOLD % BEGIN_FOLD Block environments (options, code examples, ...) \def\unskipOpt{\vskip-5mm } \let\unpatched@minted@inline@iii=\minted@inline@iii% \def\patched@minted@inline@iii#1{% \unpatched@minted@inline@iii{#1}% \par% \endgroup\vskip-\parskip% \noindent\ignorespaces% } \newenvironment{option*}[3][]{\vskip5mm% \noindent\begin{minipage}[t]{\linewidth}% \begingroup% \let\minted@inline@iii=\patched@minted@inline@iii% \raggedleft% \hspace*{-1cm}% \phantomsection\label{style:/#2/#3}% \texttt{\ifstrempty{#1}\relax{\compat{#1}}\textcolor{gray}{/#2/}\textcolor{mintgreen}{#3}}\hfill default: % \tex}{% \end{minipage}} \newenvironment{option}[1][]{\csname option*\endcsname[{#1}]{yquant}}{\csname endoption*\endcsname} \newsavebox\codeexamplebox \newenvironment{codeexample}{% \VerbatimEnvironment% \let\FVB@VerbatimOut\minted@FVB@VerbatimOut \let\FVE@VerbatimOut\minted@FVE@VerbatimOut \minted@configlang{tex}% \minted@fvset \begin{VerbatimOut}[codes={\catcode`\^^I=12},firstline,lastline]{\minted@jobname.pyg}% }{ \end{VerbatimOut}% \minted@langlinenoson% \savebox\codeexamplebox{\input \minted@jobname.pyg}% \ifdim\wd\codeexamplebox>\dimexpr.5\linewidth-3mm\relax% \wd\codeexamplebox=.5\linewidth% squeeze if necessary \else% \wd\codeexamplebox=\dimexpr\wd\codeexamplebox+3mm\relax% else give some space \fi% \noindent\begin{minipage}{\wd\codeexamplebox}% \centering% \usebox\codeexamplebox% \end{minipage}% \begin{minipage}{\dimexpr\linewidth-\wd\codeexamplebox\relax}% \minted@pygmentize{\minted@lang}% \end{minipage}% \minted@langlinenosoff% \par% } \newenvironment{codeexample*}{% \VerbatimEnvironment% \let\FVB@VerbatimOut\minted@FVB@VerbatimOut \let\FVE@VerbatimOut\minted@FVE@VerbatimOut \minted@configlang{tex}% \minted@fvset \begin{VerbatimOut}[codes={\catcode`\^^I=12},firstline,lastline]{\minted@jobname.pyg}% }{ \end{VerbatimOut}% \minted@langlinenoson% \begin{adjustbox}{center} \input \minted@jobname.pyg % \end{adjustbox}\nopagebreak \minted@pygmentize{\minted@lang}% \minted@langlinenosoff% \par% } \def\bd@boxextra#1{% \node[anchor=north east, overlay] at (current bounding box.north west) {#1\hskip7pt};% } \newcommand*\bd@boxintro[5]{% \begingroup% \setlength{\parskip}{0pt}% \setlength{\parindent}{0pt}% \edef\tmp{#5}% \ifx\tmp\empty% \expandafter\@firstoftwo% \else% \expandafter\@secondoftwo% \fi{% \begin{mdframed}[style=bdBox, backgroundcolor=#4, linecolor=#2, firstextra=\bd@boxextra{#1}, singleextra=\bd@boxextra{#1}]% }{% \begin{mdframed}[style=bdBox, backgroundcolor=#4, frametitlefont=\bfseries\sffamily\color{#3}, frametitlebackgroundcolor=#2, frametitle={\strut\tmp}, linecolor=#2, firstextra=\bd@boxextra{#1}, singleextra=\bd@boxextra{#1}]% }% \ignorespaces% } \def\bd@boxoutro{% \end{mdframed}% \endgroup% } \iffalse% code folding breaks \end{mdframed} \fi \mdfdefinestyle{bdBox}{ skipabove=3pt, skipbelow=0pt, leftmargin=0pt, rightmargin=0pt, innerleftmargin=7pt, innerrightmargin=7pt, innertopmargin=5pt, innerbottommargin=5pt, splittopskip=17pt, frametitlealignment=\raggedright, frametitleaboveskip=3pt, frametitlebelowskip=1.5pt } \newenvironment*{warning}[1][]{% \bd@boxintro{\raisebox{\baselineskip-\height-6.5pt}{\includegraphics[width=1cm]{Warning.pdf}}}% {boxRedHead}{white}{boxRedBody}{\unexpanded{#1}}% \ignorespaces% }{% \bd@boxoutro% } \def\example{\@ifnextchar<\example@i{\example@i<>}} \def\example@i<#1>{\@ifnextchar[{\example@ii<{#1}>}{\example@ii<{#1}>[]}} \long\def\example@ii<#1>[#2]{% \bd@boxintro{\ifstrempty{#1}{}{\ifstrempty{#2}{\compat{#1}}{}}% \raisebox{\baselineskip-\height-6.5pt}{% \includegraphics[width=1cm]{Bulb.png}% }}{boxBlueHead}{white}{boxBlueBody}% {\ifstrempty{#1}{}{\ifstrempty{#2}{}{\unexpanded{\compat{#1}}}}\unexpanded{#2}}% \ignorespaces% } \let\endexample=\bd@boxoutro % END_FOLD \def\TikZ{\textcolor{brown}{Ti\textit kZ}} \def\pkg#1{\textcolor{brown}{\texttt{#1}}} \def\gate#1{\hyperref[gate:#1]{\texttt{#1}}} \def\style#1{\hyperref[style:#1]{\texttt{#1}}} \def\Yquant{\pkg{yquant}} \def\ii{{\symup i}} \def\ee{{\symup e}} \def\ketbra#1#2{\ket{#1}\!\bra{#2}} \frenchspacing \RequirePackage{scrlayer-scrpage,scrlayer-notecolumn} \setcounter{tocdepth}{\subsectiontocdepth} \KOMAoptions{DIV=8} \newcommand*{\the@orig@section}{} \let\the@orig@section=\section \renewcommand*{\section}{% \clearpage% \the@orig@section% } \addtokomafont{notecolumn.marginpar}{\footnotesize\RaggedRight} \recalctypearea \begin{document} \maketitle \begin{abstract} \noindent This manual introduces \Yquant, a \LaTeX\hyp only package that outputs quantum circuits. They are entered using a human\hyp readable language that, even from the source code, allows for a fluent understanding of the logic that underlies the circuit. \Yquant{} internally builds on \TikZ{} and can be easily combined with arbitrary \LaTeX{} code. More than fifty pages of examples complement the formal manual. \end{abstract} \tableofcontents \section{Introduction} This document outlines the scope and usage of the \Yquant{} package. It contains both a reference and a huge number of examples. \Yquant{} is a package that makes typesetting quantum circuits easy; the package is available on CTAN. This beta version~0.5 \emph{should} be stable and interfaces are not very likely to change in an incompatible way in the future. \compat{New in 0.4}Sometimes, backwards\hyp incompatible changes are required or advisable, in which case a compatibility setting will allow to revert back to the old behavior (rather, to maximize compatibility, this is an opt\hyp in setting: unless you choose the new behavior, you will get the old one). Please do report all issues and desirable additions on \href{https://github.com/projekter/yquant/issues}{GitHub}. \subsection{How to read the manual} The probably fastest way to start using \Yquant{} is by just scanning through the examples in \cref{sec:examples}. A more formal description of the \Yquant{} grammar and its fundamental concepts can be found in \cref{sec:grammar}. If your desire is to change the appearance of \Yquant{} elements, use the configuration reference in \cref{sec:config}. The full list of all available gates is provided in \cref{sec:gates}. Finally, you may find that \Yquant{} \emph{almost} does what you want, but there is some final tweak that you cannot achieve\dots. Then, have a look at \cref{sec:tikz} (or \cref{sec:alt}). \subsection{Installation} The recommended way of installation is through CTAN. A direct installation from the Git repository to obtain the latest additions and features is be possible by just cloning it to a path visible to your \TeX{} compiler. For example, you may put the source files in the same directory as your document (if you just want to give a try), or you may extract them to \texttt{tex/latex/yquant} in your local \texttt{texmf} (followed by an update of the file name database). While the repository may contain new additions, they are not thoroughly tested until they end up on CTAN; features that are not documented in this manual are entirely unreliable. \compat{New in 0.4}The CTAN repository reflects the most current version tag on Git; the \href{https://github.com/projekter/yquant/releases}{Releases} section on GitHub additionally provides a single\hyp file version of the main package, which can for example conveniently be included in arXiv submissions. Note that the arXiv currently provides \Yquant{}~0.3.2 out\hyp of\hyp the\hyp box. \subsection{Purpose of \Yquant, alternatives}\label{sec:alt} \Yquant{} is the acronym for ``yet another quantum circuit package.'' This highlights the fact that nothing that this package provides cannot be achieved by other means. In particular, there are at least the following methods to typeset quantum circuits in \TeX. \begin{itemize} \item Use some external program to draw them and include the output via \tex!\includegraphics!. \item Use either \TeX's own drawing capabilities (the \tex!picture! environment) or other drawing packages such as \TikZ{} or \pkg{pstricks}. \item Use a package specifically designed to draw quantum circuits (if you feel some other package should be mentioned here, please file an issue): \begin{itemize} \item \pkg{qasm} is probably the first of them (in terms of age). It was developed to typeset the circuits found in Nielsen and Chuang's famous \emph{Quantum Computation and Quantum Information} book. \pkg{qasm} consists of a Python~2 script (\texttt{qasm2circ}) that reads a quantum circuit written in a very intuitive language: declare names for your qubits, perform gates on them in each line. \texttt{qasm2circ} converts those circuits into \TeX{} files that internally make use of the \pkg{xy} package to display the output. Consequently, the user is restricted to the set of features that \pkg{qasm} directly offers (which is small). Changes to the output, while possible, will be overwritten if \texttt{qasm2circ} is run again. \pkg{qasm} output often looks sub\hyp optimal do to the fact that, e.g., rectangles are made up of four lines that do not properly connect and give a crumbly general feeling. Note that since version~0.3, \Yquant{} understands \pkg{qasm} syntax, see \cref{sec:foreign:qasm}. Maintenance status: last update of \pkg{qasm} in 2005. Also, \pkg{xy} was last updated in 2013, and the script is not compatible out\hyp of\hyp the\hyp box with Python~3, though an automatic conversion should work. \item \pkg{qcircuit} is probably the most\hyp widely used package. It provides commands that make it much easier to create quantum circuits using the \pkg{xy} package. Its syntax therefore is grid\hyp oriented; inferring what a circuit does or locating a gate in the code can be tough. This is particularly true for multi\hyp qubit gates. Additionally, the \tex!\xymatrix! syntax is also somewhat cryptic. \pkg{qcircuit} provides some flexibility within the limits of \pkg{xy} as to configuring the output. Maintenance status: last update in 2018; and remember this is \pkg{xy} based, with last update in 2013. \item \pkg{quantikz} is a relatively recent package that, following the same grid\hyp based approach as \pkg{qcircuit}, instead builds on \TikZ{} as a backend. As a consequence, it provides the full flexibility of customization that \TikZ{} offers, where hardly anything cannot be done. It also reduces burdens of the \pkg{xy} syntax. However, the disadvantages of the grid\hyp based syntax still remain. Maintenance status: last update in 2020; the underlying \TikZ{} is actively maintained again by now. \item \pkg{qpic} follows the approach of \pkg{qasm}: It makes use of an external Python program that reads the quantum circuits in an own language and converts them into \TikZ{} commands. The language \pkg{qpic} follows is much more powerful than \pkg{qasm}'s. The disadvantage that modifications in the output code will not remain after running the Python script again is mitigated by the possibility to define own \TeX{} macros. Being an external program, \pkg{qpic}'s intrinsic set of features (including, e.g., vertically set circuits) are huge. However, the language \pkg{qpic} uses cannot be understood without a detailed study of the manual, it appears to have been designed with the aim to minimize the length of command names. A disadvantage of external programs is that the amount of space gates need is not accessible by the script; hence, manual intervention may be required. Maintenance status: last update in 2020; the underlying \TikZ{} is actively maintained, and the script is compatible with Python~3. \end{itemize} \end{itemize} \subsection{License} This work may be distributed and/or modified under the conditions of the \LaTeX{} Project Public License, either version~1.3c of this license or (at your option) any later version. The latest version of this license is in \begin{center} \url{http://www.latex-project.org/lppl.txt} \end{center} and version~1.3c or later is part of all distributions of LaTeX version 2005/12/01 or later. \section{Basic elements of \Yquant}\label{sec:grammar} \Yquant, as some of the aforementioned packages, builds on \TikZ. Its basic syntax is similar to \pkg{pgfplots}: Start a \tex!tikzpicture! environment (perhaps passing some options); inside, start a \tex!yquant! environment. Inside the \tex!yquant! environment, \TeX{} will now understand the \Yquant{} language---so \Yquant{} falls into the same category as \pkg{qasm} and \pkg{qpic}, providing a human\hyp readable language for the specification of the circuit that is not fixed to the actual layout. However, \Yquant{} is a \TeX\hyp only package (actually, \hologo{LaTeX2e}, but not \hologo{LaTeX3}) that requires no external script to run---so it also falls into the same category as \pkg{qcircuit} and \pkg{quantikz}. Since it runs entirely within \TeX, you can at any time interject \Yquant{} code with arbitrary \TeX{} or \TikZ{} code (though if it is ``too arbitrary,'' you may need to restart the \Yquant{} interpreter). \subsection{General usage} \begin{minted}[escapeinside=||]{tex} % preamble: |\compat{Changed in 0.4}|\usepackage[compat=]{yquant} \begin{tikzpicture}% tikz options possible % tikz commands go here \begin{yquant}% yquant options possible. Watch the newlines! % yquant and tikz commands go here \end{yquant} % tikz commands go here \end{tikzpicture} \end{minted} Note that \Yquant{} depends on \pkg{etoolbox}, \TikZ, \pkg{trimspaces}, and \compat{Changed in 0.4}\pkg{xkeyval}. Additionally, it requires a moderately recent version of \hologo{LaTeX2e}, using either \hologo{LuaLaTeX}; or (untested) \hologo{pdfLaTeX} or \hologo{XeLaTeX}. \begin{warning}[Optional arguments] The optional arguments for the \tex!yquant! environment have to appear \emph{on the same line} as the environment itself. If you want to put the arguments into a new line, it is crucial to mask the line break by putting a comment symbol after the environment: \tex!\begin{yquant}%!. Without this comment, \Yquant{} will detect your line break (this is one of the few places in \TeX{} where line breaks and spaces are different) and assume that the expression in square brackets instead provides arguments for the following operation! \\ Finally note that in (non\hyp fragile) \pkg{beamer} frames, this discrimination between spaces and new lines does not work; the optional arguments will always be counted for the environment, not for the gate. In this case, you can either declare the frame as fragile or (recommended) introduce a blank line between the environment and the options for the first gate. \end{warning} \begin{warning}[\compat{New in 0.4}Compatibility mode] Sometimes, continued development shows that certain choices of interfaces, configuration, or behavior are less ideal than originally thought. In other cases, bugs are detected and fixed. Both may lead to a change in the look of circuits developed with a previous version of \Yquant{} or even---though this should rarely, if ever, happen, and should be filed as a bug---prevent compilation in the new version. For this reason, \Yquant{} offers a compatibility key that is highly recommended to be specified as a package option. This allows certain features that are expected to break old layout or functionality to revert to their previous behavior. Every feature affected by the \texttt{compat} key is documented in this manual. Once a compatibility version is selected in a document, it cannot be changed any more. Compatibility versions will include the major and minor, but not the patch level version number (though not every major or minor version will necessarily introduce new compatibility versions). Bugs that clearly violated behavior described in this manual will be fixed without a possibility to revert back. Changes that are not supposed to result in a (more than marginally) different result will not be included in the compatibility layer. If you find this to be wrong in a particular case, please file a bug report. When starting a new document, it is recommended to leave out the compatibility key at first compilation. \Yquant{} will then issue a warning from which you can infer the recommended setting, corresponding to the current version. You should then pass the appropriate version to the \tex!\usepackage! command. For example, this manual corresponds to \tex!\usepackage[compat=0.4]{yquant}!. Allowed values for \texttt{compat} are \texttt{newest} (discouraged), which equals \texttt{0.4}, and \texttt{0.3} (default). \end{warning} \subsection{Starred vs. unstarred environment} You may choose to use either the \tex!yquant! or the \tex!yquant*! environment. The former one requires you to define all your registers before you use them (though you may decide to define a register after some operations on \emph{different} registers, but before its first usage). The starred form additionally supports the use of undeclared registers: it basically declares a registers upon its first usage. This will always be a \texttt{qubit} register; but if you use the corresponding attribute and the first usage is an \gate{init} command, you may overwrite this. \compat{New in 0.2}Subcircuits always use the unstarred form. \compat{New in 0.1.1}Additionally, if you refer to the index $i$ of a vector register of length $L < i$, this register will automatically be enlarged to $i \coloneq L$. It is also possible to convert a scalar register into a vector register in this manner. To enlarge a register in the unstarred environment, you must precede the number of registers to be added in the second declaration by a plus sign. Note that in this manner, you may even create discontiguous vectors. \emph{This might be a good point to proceed to the examples \cref{sec:examples}.} \subsection[Formal syntax]{\compat{Enhanced in 0.1.2, 0.1.1}Formal syntax} Every \Yquant{} command has the same structure (described here in EBNF syntax): \begin{minted}{ebnf} Command = { Arguments }, ?command?, [ Value ], [ RegisterList ], Controls, ";"; Arguments = "[", ?pgfkeys?, "]"; Value = "{", ?TeX code?, "}"; Controls = [ "|", [ RegisterSingleList ] ], [ "~", [ RegisterSingleList ] ]; RegisterList = (RegisterSingle | RegisterMulti), [ ",", RegisterList ]; RegisterSingleList = RegisterSingle, [ ",", RegisterSingleList ]; RegisterSingle = RegisterSingleNoRange | RegisterRange; RegisterSingleNoRange = ?name?, [ "[", IndexMultiList, "]" ]; RegisterMulti = "(", ( RegisterMultiNoRange | [ "*" ], RegisterRange ), ")"; RegisterMultiNoRange = [ "*" ], ?name?, [ "[", IndexSingleMainList, "]" ]; RegisterRange = [ RegisterUnique ], "-", [ RegisterUnique ]; RegisterUnique = ?name?, [ "[", ?number?, "]" ]; IndexMultiList = IndexMulti, [ ",", IndexMultiList ]; IndexSingleList = IndexSingle, [ ",", IndexSingleList ]; IndexSingleMainList = [ "*" ], IndexSingle, [ ",", IndexSingleMainList ]; IndexMulti = IndexSingle | ( "(", IndexSingle, ")" ); IndexSingle = ?number? | ( [ ?number? ], "-", [ ?number? ] ); \end{minted} Note that \Yquant{} is quite tolerant with respect to whitespaces. Virtually every comma in the EBNF notation may consist of an arbitrary (including zero) number of whitespaces. Not all combinations that can be constructed by this grammar are actually allowed semantically; but it would make the grammar too verbose to spell this out in detail. Deviations are noted in this manual. Valid values for \begin{BVerbatim}[commandchars=\\\{\}] \PYG{n+ni}{?command?} \end{BVerbatim} \space (case\hyp insensitive) are documented in a \cref{sec:gates}. We use \begin{BVerbatim}[commandchars=\\\{\}] \PYG{n+ni}{?pgfkeys?} \end{BVerbatim} \space to describe any valid content passed to the \tex!\pgfkeys! macro (rather, \tex!\yquantset! is invoked with some subtleties); and by \begin{BVerbatim}[commandchars=\\\{\}] \PYG{n+ni}{?name?} \end{BVerbatim} \space we denote any valid register name. Register names must not contain any of the control literals used before (semicolon, comma, parentheses, square brackets, dash, pipe, tilde, beginning star); and you should avoid using special \TeX{} characters. Note that for performance reasons, \Yquant{} does not check whether a register name is valid or not, but expect to either see unintended output or not\hyp so\hyp helpful error messages if you choose an invalid name. \begin{BVerbatim}[commandchars=\\\{\}] \PYG{n+ni}{?number?} \end{BVerbatim} \space is a decimal integer larger or equal to zero (in the context of register creation, strictly larger; in this context, it may also contain a leading \begin{BVerbatim}[commandchars=\\\{\}] \PYG{l+s+s2}{\PYGZdq{}+\PYGZdq{}} \end{BVerbatim} ). \subsection{Registers}\label{sec:registers} Every quantum circuit is structured by means of \emph{registers}. A register has a \emph{type} that specifies how its wire is drawn, and that may even change during its lifetime. At the moment, \Yquant{} supports four types: \begin{enumerate} \item \gate{qubit} is the most common type, used for a quantum register. It corresponds to a single line. \item \gate{cbit} is a classical register, which can be either declared from the beginning or arises by using measurements. It corresponds to a double line. \item \gate{qubits} is a ``quantum bundle,'' i.e., a bunch of quantum registers that are always addressed in a group as a single register. Operations between bundles of the same length should be interpreted as transversal. It corresponds to a triple line. An alternative (and more common) representation is to use the \gate{qubit} type and a \gate{slash} gate at its very beginning. \item \gate{nobit} is the most obscure type, corresponding to a non\hyp existing wire. Mostly, this register type arises by using the \gate{discard} command. However, it can also be directly declared, which on rare occasions might be necessary (its type can then be changed by means of an \gate{init} or \gate{setwire} pseudo\hyp gate). If you want to declare a register only at a certain horizontal position in the circuit, consider using the \texttt{after} argument instead. \end{enumerate} Registers must be declared before they can be used (though in the \tex!yquant*! environment, this declaration may be implicit, creating a \gate{qubit} register). Registers can have a vector character, i.e., not only a \emph{name}, but also an \emph{index} (or, in the declaration, a \emph{length}). The index (zero\hyp based) or length is specified in square brackets following the name, which closely mimics the OpenQASM language. \compat{New in 0.1.1}Vector registers may be non\hyp contiguous: Whenever you create a bunch of registers, it is put at the bottom of the circuit. If you later on again create registers of the same name---either implicitly in the \tex!yquant*! environment, or explicitly by preceding the length of the vectors entries to be added by a plus, as in \yquant!qubit a[+3];!---they will be put to what is \emph{now} the bottom of the circuit, even if some other registers are interspersed. Registers are referenced---i.e., used in operations---by their name and index. If the latter is omitted, all indices of the register are targeted. Multiple registers can be referenced by joining their names in a comma\hyp separated list, or by means of a range specifier: give the name of the first (topmost), a dash, and the last (bottom\hyp most) register. Both are inclusive. In a range specifier, omitting the start name means that the range begins at the first known register; omitting the end name means that the range ends at the last known (at the moment of its use) register. Omitting both indicates a range over all known registers. \compat{New in 0.1.1}It is also possible to use comma\hyp separated lists and ranges within the indices themselves, so that, e.g., \yquant!a[0, 2, 5-], b[-2]! will target the zeroth and second index of \yquant!a!; the remaining indices of \yquant!a! starting from five; and the first three indices of \yquant!b!. However, if you use an \emph{outer} range (i.e., a range between indices of registers with different names), the initial and final register of the range must be unique, i.e., either you omit the index (targeting the first or last register with the given name) or specify a single one. \begin{warning}[Ranges and discontiguous registers] Assume a configuration in which the vector register \yquant!a! begins with one qubit, then the single register \yquant!b! follows, and after that \yquant!a! is continued with another qubit. The range \yquant!a-b! will target \yquant!a[0]! and \yquant!b[0]!, but not \yquant!a[1]!. As \yquant!a! is used as the initial register in the range without an explicit index specification, \Yquant{} automatically translates this into \yquant!a[0]!, while \yquant!b!, being used as the final register, is automatically translated into the last register of name \yquant!b! (which here happens to be \yquant!b[0]!). Ranges between different register names (outer ranges) are \emph{visual} ranges, i.e., they refer to the top\hyp to\hyp bottom order that is visible. Consequently, the register \yquant!a[1]! is left out since it is visually below the others. Likewise, the range \yquant!b-a! will target \yquant!b[0]! and \yquant!a[1]!. Ranges within indices are \emph{logical} ranges. Hence, \yquant!a!, \yquant!a[-]!, \yquant!a[0-]!, \yquant!a[-1]!, and \yquant!a[0-1]! are all equivalent: they all refer to the registers \yquant!a[0]! and \yquant!a[1]!, but never to \yquant!b!, regardless of any visual position. \end{warning} All that was said so far refers to the operation being carried out on each of the registers \emph{individually}, i.e., producing several copies of the operation. This is different from using the operation multiple times on the individual single registers only with regard to the horizontal positioning: if specified as a register list with one operation, all copies of the operation will be aligned at the same horizontal middle axis (for gates with the same width on each register, this is the same as issuing an \gate{align} command before performing the operations individually). \begin{warning} It is forbidden (in the sense of ``not useful and giving unexpected output,'' but \Yquant{} does not check for this) to list the same register multiple times (explicitly or via ranges) in one operation. \end{warning} Instead of copies of single\hyp register operations, one might want to carry out a multi\hyp register operation. In this case, the desired list of registers (comma separated, range, or both) must be surrounded by parentheses. It is possible to mix single- and multi\hyp register operations arbitrarily. In an index list, you may also choose to surround only certain indices with parenthesis, provided the whole register is not already a multi\hyp register. \begin{warning} Note that some gates, such as the \gate{swap} gate, always require (semantically, not grammatically) multi\hyp register operations. \compat{Changed in 0.1.2}The number of constituents is not stipulated; while a \gate{swap} gate with more than two targets is no longer well\hyp defined, other registers such as \gate{zz} may still be useful. \Yquant{} will prevent you from using a gate in a multi\hyp qubit setting when it may only be used for single registers. \end{warning} Typically, multi\hyp register operations should only be carried out on adjacent registers---but sometimes, one might want to carry out a multi\hyp qubit operation on a visually discontiguous set of registers (which, due to a particular quantum computer topology, might even be physically feasible). \compat{New in 0.1.2}\Yquant{} supports these discontiguous operations explicitly. It will draw a \emph{main} part of the gate at the first contiguous slice of registers in the target list---you may select another register for this part by preceding the name or index with a star (which, contrary to the simplified grammar, may only occur \emph{once} in a target specification). All other contiguous slices of target registers will be drawn in a \emph{subordinate style} for this gate. Finally, all slices will be connected by a single vertical line with the style \style{/yquant/every multi line}. \compat{New in 0.2}Subcircuits will always span the full region from the first to the last register specified in a multi\hyp qubit gate. This is due to the fact that they may contain arbitrary ancilla registers which may be positioned somewhere in between the parts that actually constitute the subcircuit---surrounding this with a scattered set of connected boxes would look quite unpleasant. \clearpage \begin{warning}[\compat{Improved in 0.1.2}Discontiguous targets and control lines] A control line extends from the very first to the very last affected register in an operation. A sub\hyp gate line that is used for discontiguous registers will only span the range of a multi\hyp register. This distinction becomes crucial if you want to carry out a \emph{controlled} operation on more than one multi\hyp register, where at least one is discontiguous. Without the controls, the separate multi\hyp registers could be identified, since no connecting vertical line extends between them (unless, which you should strictly avoid, they are intertwined). However, with the controls, the control line will make it hard (for some gates, impossible) to visually distinguish the connected parts. \Yquant{} will kindly provide a warning in this case. You may choose to suppress this warning using the boolean key \style{/yquant/operator/multi warning}. \end{warning} \begin{warning} There is no established style for discontiguous gates. Note that at the moment, main and subordinate style coincide for all gates except for the \gate{measure} gate with a value. In order to still make it possible to visually distinguish discontiguous multi\hyp register gates operating on slices of a single register from just a bunch of single\hyp register gates that are executed in a parallel manner if controls are present, \Yquant's default vertical line style for the former case is a wavy line instead of a straight one. Still, the meaning of this should probably be explained. Please feel free to submit issues or pull requests with propositions of how default styles or alternative subordinate gate shapes may additionally help to mitigate the problem. \end{warning} \subsection{Arguments} Every command may take one or multiple arguments. Those are specified in square brackets that precede the command itself. The content of those square brackets is essentially fed to a \tex!\pgfkeys!-like macro. The default path is set appropriately such that the arguments of the command can be accessed without path specifiers. If the key is not a valid argument for the command or a global argument and it is not given by an absolute path, it is searched for in the \texttt{/yquant} namespace. If it cannot be found there, it is passed to \style{/yquant/operator style}. Note that commands may have required arguments. If a required argument is missing, an error will be issued. The \texttt{value} attribute can alternatively be given inside curly brackets after the command name and before the register specification. This has the advantage that special characters such as a closing square bracket need not be escaped. If both alternatives are present, the value inside curly brackets takes precedence and a warning is issued. \subsection{Controls} Lots of gates may have controls, i.e., they are only to be executed if some other gate is set or unset. The former case is called a \emph{positive control}, the latter one a \emph{negative control}. Those are indicated by filled and empty circles on the control registers and a vertical line that joins the registers that belong together. The gate specification is followed by the list of target registers. By then writing a pipe (``\yquant!|!''), the list of positive controls is introduced; this mimics the mathematical syntax ``conditioned on'' for probabilities or ``given'' for sets. If there are no positive controls, the list may be empty or, together with the pipe, omitted. Preceded by a tilde (``\yquant!~!''), the list of negative controls then follows; this mimics the syntax of many programming languages that denote logical negation by a tilde. If there are no negative controls, the list may be empty or, together with the tilde, omitted. \subsection[Importing circuit from files]{\compat{New in 0.2}Importing circuits from files}\label{sec:import} \Yquant{} provides a simple way to import circuits that are stored in external files. The macro \tex!\yquantimport! can be used in three different contexts: \begin{itemize} \item Outside of a \TikZ{} picture environment. \\ Here, \tex!\yquantimport[]{}! will be equivalent to \begin{minted}{tex} \begin{tikzpicture} \begin{yquant}[] % the content of goes here \end{yquant} \end{tikzpicture} \end{minted} The starred form, \tex!\yquantimport*[]{}!, instead inserts the starred \Yquant{} environment. Note that the options are always \Yquant{} options; if you want to pass \TikZ{} options, you will have to create the picture environment by yourself or change the option path to the correct one (\texttt{/tikz/.cd}). \item Inside a \TikZ{} picture environment, but outside of a \Yquant{} environment. \\ This is the same as before, just that no extra picture environment will be added. \item Inside both a \TikZ{} picture environment and a \Yquant{} environment. \\ The file will be inserted directly into the environment. \Yquant's parser is automatically restarted after this. The content will always be put in a \TeX{} group; if additional options are provided, \Yquant{} also inserts a \TikZ{} \tex!scope! and executes \tex!\yquantset{}! directly after the scope. If \tex!\yquantimport! is used, the content will be read as if the containing environment was an unstarred one; if \tex!\yquantimport*! is used, the content will be read as if the containing environment was a starred one. \end{itemize} Note that \Yquant{} internally uses plain \TeX's \tex!\import! command (i.e., \tex!\@@import! in \LaTeX). However, when the \pkg{import} package is loaded, it uses \\ \tex!\subimport{\yquantimportpath}{}!, where \tex!\yquantimportpath! defaults to \texttt{./}---so by changing this, files from other folders may be imported which by themselves again include other files, and the relative path resolution will work. Note that you may in particular import the content of a \gate{subcircuit}. \subsection{Defining own gates} \begin{warning}[Scope] All gate declarations are always global. \end{warning} \compat{New in 0.2.1}If you want to define a gate that corresponds to a single \gate{box} gate with a certain pre\hyp defined content, you may use the macro\\ \tex!\yquantdefinebox{}[