Qubi Reference Manual

Overview

Programs are plain text, one instruction per line (after trimming leading and trailing whitespace). Execution builds the circuit left-to-right: each parsed line becomes one column in the grid. Qubit indices are integers 0, 1, …; in Qubibyte’s algorithm library, index 0 is the least significant qubit in ket labels such as |q₁q₀⟩.

Recognized gate names in the simulator editor are H, X, Y, Z, S, T, RX, RY, RZ, CX, CY, CZ, SWAP, and MEASURE. Use those spellings so live validation and highlighting stay green.

Lexical rules

Whitespace

Each line is trim()’d before parsing. Indentation is allowed and ignored for matching; it is preserved only as part of the raw line for display.

Comments

Line comments start with // and run to the end of that physical line. A new comment starts only when both slash characters are at bracket depth zero (not nested inside unclosed ( ) or [ ] on that same line), so you can write H 0 // Bell prep and CX [0,1] // entangle. Text after that // is ignored by the parser.

Block comments use /* … */. They may appear anywhere a token can start (including between tokens on one line) and may span multiple lines. The first */ closes the nearest open block. Unclosed blocks are reported as an error in the simulator gutter.

After comments are removed, the remaining executable text on each line is trimmed and parsed. A line that contains only comments or whitespace is skipped.

Blank lines

Empty lines are skipped.

Numbers

Qubit indices are non-negative integers. For RX/RY/RZ, omitting the angle uses the default π/2. When you supply a bare decimal (with optional scientific notation), it is interpreted as a multiple of π. You may instead give an explicit unit: append rad or radians for radians, or deg / degrees for degrees (e.g. RX 0 1rad, RY 1 90deg).

Identifiers

Gate keywords are written in uppercase (MEASURE, SWAP, RX, …). Stick to the supported names so the editor’s gate list, validation, and execution path all agree.

Preprocessor: #import, #include, #define

Before the circuit is parsed, the simulator runs a small preprocessor (same behavior as qubi.js). Directive lines are trimmed; block comments are respected the same way as elsewhere.

#import and #include

Both forms are equivalent. They splice another Qubi file into the compilation unit at this point:

// utils.qubi must exist as another tab in the simulator (same basename)
#import utils.qubi
#include helpers.qubi

Filename tokens allow letters, digits, dot, underscore, and hyphen; the name must end with .qubi. Cycles or excessive nesting depth are rejected with an error. When no import resolver is configured, imports fail at execution time.

#define (named unitary)

Registers a custom gate backed by a literal complex matrix. The gate name (the token you use on circuit lines) must be 1–4 uppercase letters A–Z only (normalized to uppercase). Invalid names are rejected in the preprocessor and in the live editor validator.

Syntax:

#define U [1 0; 0 i] "Phase gadget" "purple"

The matrix is written in square brackets. Rows are separated by semicolons (;); entries in a row are separated by spaces or commas (comma is optional). The matrix must be square, size 2^k×2^k with k ≥ 1, and at most 16×16. It must be unitary (U†U = I) within numerical tolerance.

Matrix entry expressions

Inside #define each cell is parsed as a complex expression (whitespace ignored). Supported features match the simulator’s matrix helpers:

• Numbers (decimal and scientific notation), imaginary unit i, constant pi, constant e when not followed by ^.
• Euler style: e^(i*pi/4) (also works with complex exponents).
• Functions (real or complex argument where implemented): sqrt(…), sin(…), cos(…), tan(…), exp(…).
• Arithmetic + − * /, parentheses, unary +/−, and implicit multiplication (e.g. 2pi, 3i).

Using a #defined gate on wires

A 2×2 matrix is a one-qubit gate: use shorthand U 0 or parallel U (0,1) for two independent one-qubit Us in one column.

For a 2^k×2^k matrix with k > 1, list exactly k qubit indices in square brackets — one joint gate on that register, e.g. a 4×4 gate on qubits 0 and 1:

#define P [0 1 0 0; 1 0 0 0; 0 0 1 0; 0 0 0 1]
P [0,1]

CX, CY, CZ, and SWAP also use […] only (never bare (0,1), which is reserved for parallel single-qubit gates). You may wrap one or more bracket registers in parentheses: CX ([0,1]) or CX ([0,1], [2,3]) for two CNOTs in the same timestep.

Dragging from the palette: for multi-qubit custom gates, dropping the tile on wire q places the gate on the consecutive wires q, q+1, … if there is room and the column is free on all of them.

Line grammar

Lines are classified in this order (same order as qubi.js): rotation lines (angle optional; default π/2), REPEAT, END, single-qubit shorthand, then bracket registers or parenthesized parallel lists. Anything that does not match is silently omitted from the instruction list, so a typo can silently drop operations. Rely on the simulator’s red underline and gutter tooltips.

Rotation

RX|RY|RZ + qubit list + optional angle: either GATE q [θ], GATE (q0,q1,…) [θ], or GATE [q0,q1,…] [θ] for the same rotation on every listed wire. If θ is omitted, the rotation is π/2. When present, θ may be a multiple of π, or an explicit …rad / …deg literal (see Rotations).

REPEAT

Exact form REPEAT + one or more spaces + a positive integer count. Lines like REPEAT alone do not match and are skipped.

END

Executable text is exactly END (after comment removal and trim). Optional trailing line comments are allowed, e.g. END // loop.

Shorthand

GATE q: one gate token, whitespace, a single integer qubit. No commas. Example: H 0.

Parallel

GATE (q1,q2,…): ASCII parentheses; comma-separated non-negative integers; optional spaces after commas. Applies the same single-qubit gate to each listed wire in one time step. For RX/RY/RZ, put an optional angle after the closing parenthesis: RX (0,1) 0.5 or RX (0,1) for the default π/2.

Brackets

GATE [q0,q1,…]: square brackets; comma-separated integers. Used for CX/CY/CZ, SWAP, joint #defined unitaries, and broadcasting any single-qubit gate to several wires (see next section). One timestep may list several registers as GATE ([q…],[q…]).

// Comment-only line
H 0 // same-line
/* multi-
line block */
H (0,1,2)
CX [0,1]
CX ([0,1], [2,3])
REPEAT 4
  RZ 0 0.25
  RX [0,1] 0.25
  RY 2 45deg
END

Gate set

Single-qubit unitaries include the Clifford set and T for π/8 phase. Multi-qubit primitives are Pauli-controlled rotations and swap. MEASURE collapses a wire in simulation.

Controlled and parallel operations

Square brackets (controlled)

For CX, CY, and CZ, the parser marks the line as controlled. The last index in the bracket list is the target; every earlier index is a control. So CX [0,1] is control 0, target 1; CX [0,1,2] is controls 0 and 1, target 2 (Toffoli-style multi-controlled X).

Parentheses (parallel)

Parentheses apply one single-qubit gate to several wires at the same time step, e.g. uniform superposition on a register:

H (0,1,2,3)

SWAP

Use bracket notation with the two wires to exchange:

SWAP [1,3]

Parameterized rotations

RX, RY, and RZ take a qubit (or parenthesized or bracket list for the same gate on multiple wires in one step), then an optional angle. If you omit the angle, the rotation is π/2 (same default as parallel RX (0) on one wire). A plain number (when you supply an angle) is always a multiple of π: RY 1 0.5 is π/2 about Y on qubit 1.

Optionally use units: rad / radians for radians, or deg / degrees for degrees — e.g. RX 0 1rad is a 1-radian rotation about X, and RZ 2 90deg is π/2 about Z. Optional spaces before the suffix are allowed (35 deg).

Parallel rotations: RX (0,1) 0.5 applies the same RX (here 0.5·π on each) to qubits 0 and 1 in one timestep, analogous to H (0,1).

The editor accepts the same default: RX 0, RY [0,1], or RZ (0,1) with no trailing token means π/2 on each listed wire. If you do write an angle, it must parse as a π-multiple, …rad, or …deg.

RX 0
// default π/2 about X on qubit 0
RX 0 1
// π rotation about X (1·π); same as 1π shorthand
RY 1 0.5
RX 0 1rad
RZ 2 90deg
RX (0,1) 0.25
// π/4 RX on both qubits 0 and 1
RZ 2 0.125

REPEAT and END

REPEAT n opens a block; every following line until the matching END belongs to that block. Blocks may nest: inner REPEAT pairs with the nearest following END at the correct depth. The visual editor renders these as control-flow regions around the enclosed columns.

Each gate line inside a block still consumes one column; REPEAT and END themselves occupy control-flow columns in the layout.

REPEAT 2
  H 0
  REPEAT 3
    T 1
  END
  CX [0,1]
END

Measurement

MEASURE q inserts a measurement on that wire. Use the same shorthand pattern as other unary operations. Semantics follow the simulator backend (collapse and sampled outcomes for shots).

H 0
MEASURE 0

Editor validation (what turns red)

The live highlighter shares rules with the error tooltips on the line gutter. Highlights use the same token colors as above; invalid tokens use the simulator’s error style (red with wavy underline).

• Unclosed /* block comment (missing */).
• Unknown gate name at the start of a gate line.
• REPEAT without a positive integer, or non-numeric count.
• END with no matching REPEAT (unbalanced block).
• Unclosed REPEAT at end of file (missing END).
• RX/RY/RZ with a supplied angle that is unparseable (including …deg / …rad), or bad qubit list in (q,…) / [q,…] for rotations.
• Malformed parenthesis or bracket lists (non-integers, bad commas, missing closing delimiter).
• Preprocessor: invalid #import / #include filename; invalid #define gate name (must be 1–4 uppercase letters), non-unitary matrix, non–power-of-two size, or size over 16×16.

Balanced END without REPEAT is flagged; fix structure before exporting or sharing snippets.

Patterns and recipes

Bell |Φ+⟩

// |Φ+⟩ = (|00⟩+|11⟩)/√2
H 0
CX [0,1]

Phase kickback with CZ

H 0
X 1
CZ [0,1]

Grover outer loop (placeholder body)

Fill oracle and diffusion from the simulator’s Algorithms menu for tuned counts; the skeleton below shows only control flow:

H (0,1,2)
REPEAT 5
  // oracle
  // diffusion
END

Algorithm examples

Same parameterized Qubi generators as the simulator’s Quantum Examples library. Use the buttons to switch algorithms; change qubits and other options to refresh the preview. Open in Simulator sends the current preview into the simulator editor; you can also copy the snippet. In the simulator, the examples modal can show Qubi preview before loading into the editor.

Tools and workflow

The Quantum Circuit Simulator keeps Qubi, the drag-and-drop canvas, and exports in sync. QubiAI generates Qubi that follows these same patterns. Review bracket ordering (target last) after any AI edit. The interactive tutorial explains the linear algebra and algorithms behind the snippets here.