Gate Creator
Build custom gates without typing a full gate { } block by hand. Every form field maps to a Qubi gate-block property; the preview textarea stays in sync both ways. When you are happy, Create Gate registers the gate for the current session and adds it to the palette.
Quick start
- Open the Gate Creator tab (center tab row).
- Optionally drag a palette gate into the drop zone at the top to clone its matrix, colors, and labels.
- Set gate (identifier), label (tile text), and type (unitary, controlled, or sequence).
- Fill matrix or sequence fields; watch the Qubi definition preview update.
- Click Create Gate. The gate appears under Custom in the left palette.
For the raw syntax reference, see Gate Blocks. Gate Creator generates the same structure.
Drop zone (load from palette)
Drag any loadable gate from the left palette into the drop zone labeled “Drag a gate from the palette to load its settings.” The form fills from:
- Built-in gates (H, X, CX, SWAP, …)
- Custom gates already registered this session
gate { }blocks parsed from any open.qubifile in the editor
Control-flow tiles (MEASURE, LOOP, REPEAT, END) cannot be loaded as templates. After loading, change the gate name before Create Gate if you are cloning a built-in (built-in names are rejected).
Identity and documentation fields
| Field | Description |
|---|---|
| gate | Header name (gate MYGATE or gate MYGATE(a,b)). Required. Letters, digits, underscore only; normalized to uppercase. Must not collide with a built-in or an existing custom gate. |
| parameters | Comma-separated parameter names (e.g. theta, phi). When non-empty, a defaults row appears so you can set default values used for unitarity checks and Bloch preview. Reference params in matrix cells as {0}, {1}, … or by name where the parser allows. |
| name | Palette display name (name: in the block). Optional human-readable title (e.g. “Pauli-X”). Falls back to the gate identifier. |
| label | Circuit tile symbol (label:). Required. 1–4 uppercase letters (e.g. MG, RX). Shown on the gate icon in the builder. |
| sidelabel | Longer wire-side text (sidelabel:). Up to 20 characters. Checkbox same as label keeps sidelabel locked to label; uncheck to edit independently. |
| desc | Short description stored in gate docs (desc:). Shown in tooltips / reference where available. |
| examples | Example invocation lines (examples:), e.g. MYGATE 0, MYGATE (0,1) theta. Helps future you remember argument order. |
Structure: type, category, qubits
| Field | Description |
|---|---|
type (unitary | controlled | sequence) | Chooses which fields are visible. Controlled and sequence types force category: Multi. |
category (Single | Multi) | Palette grouping for unitary gates. Controlled and sequence gates always register as Multi. |
| qubits (unitary only) | Matrix order: 1 qubit (2×2), 2 (4×4), 3 (8×8), or 4 (16×16). Resizes the matrix grid. |
| controls (controlled only) | Control qubit count 1–6. Checkbox 1..max writes controls: N..max so the gate accepts N through max controls at runtime. |
| targets (controlled) | Target qubit count 1 or 2. Sets target matrix size (2×2 or 4×4). Label on the matrix block reads targetmatrix instead of matrix. |
| sequence (sequence only) | Comma-separated gate lines inside the composite, e.g. CX [a,b], H a, RX a theta. Parsed with the same rules as inline sequence gates in Qubi. |
| targets (sequence) | How many qubit parameters the sequence expects (1 or 2). For 2+, header becomes gate NAME [a,b] style. |
| encapsulate (sequence) | When checked (default), the palette shows one composite tile; when off, expanding behavior follows sequence gate rules in the builder. Writes encapsulate: true when on. |
Matrix, u spec, and cell syntax
For unitary gates you can enable matrix, u, or both (at least one required):
- matrix checkbox includes a
matrix: [ … ]block. Grid cells accept complex literals and expressions:i,pi,sqrt(2),sin(theta),e^(i*pi/4), parameter refs, and implicit multiply (2i). - u checkbox (1-qubit unitary only) includes
u: theta, phi, lambdain ZYZ Euler form. Matrix and u stay synced when both are enabled on a 2×2 gate: editing one updates the other.
For controlled gates, only targetmatrix is used (the full controlled unitary is built from control count + target matrix). Target matrix must be 2×2 (one target) or 4×4 (two targets).
On create, the tool checks unitarity (U†U = I) at default parameter values. Non-unitary matrices show an error and block registration.
Appearance
| Field | Description |
|---|---|
| color | Gate tile background (color:). Color picker supports named swatches and custom values like the code editor. |
| font | Label typeface (font:). Dropdown lists Qubi gate font options; default uses the standard gate font. |
| fontsize | Label scale (fontsize:), e.g. 1.0 or 1.2. |
| size | Tile scale (size:), e.g. 1.0 or 1.25. |
| fontcolor | Label color (fontcolor:). Separate picker from gate color. |
The right-hand Gate preview card shows a palette mock and a mini circuit strip so you can see label, color, and sidelabel before saving.
Qubi definition preview
The large textarea labeled Qubi definition mirrors the form in real time. You can also edit it directly:
- Paste or type a full
gate NAME { … }block; on blur the form fields and matrix grid rehydrate from the parse result. - Legacy
#define NAME [ … ]one-liners still apply for simple unitary matrices. - While the textarea is focused, the form does not overwrite your typing until you blur.
Invalid blocks show a status message when blur parsing fails.
Bloch preview
For single-qubit unitary templates, the aside shows Effect on |0⟩ and |1⟩: two Bloch spheres tracing where |0⟩ and |1⟩ map under the current matrix (evaluated at default parameters when parametric). Multi-qubit, controlled-only, and sequence types hide or de-emphasize this panel when a Bloch view is not meaningful.
Create Gate and validation
Create Gate runs full validation, then writes to CustomGateTemplates, CustomGateSequences, and session metadata. Success adds the gate to the palette immediately; a short OK status appears and fades.
Common errors:
- Missing or invalid gate name (empty, bad characters, built-in collision, duplicate custom name)
- Label not 1–4 uppercase letters
- Neither matrix nor u enabled for unitary type
- Empty or invalid sequence
- Non-unitary matrix at default parameters
- Empty u spec when u is enabled without matrix
Updating an existing custom gate name in-place is not supported through this form; load it, change the name to a new identifier, and create again. To persist across reloads, paste the preview block into a .qubi library file and #import it.
Example workflow: parametric Rx
gate RX(theta) {
label: RX
matrix: [cos(theta/2) -i*sin(theta/2); -i*sin(theta/2) cos(theta/2)]
category: Single
color: green
}
In the form: set gate to RX, parameters to theta, default theta to pi/2, enable matrix, enter the cells (or type the block in the preview). Create Gate, then use RX 0 pi/4 in the main layer.