What is a `.circuit` file?

A .circuit file is a JSON document that describes a circuit diagram in a way that’s easy for tools to generate and modify. It contains:

Global metadata (what the file is, title, default styles)
A single top-level list of operations that define registers and draw operations on those registers (gates, routines, labels, groups, etc.)
Optional hierarchy via children to express layout and nesting (columns, groups, routines)

Top-level structure

Typical top-level keys:

record_type: identifies the format (e.g. psiquantum.circuit)
title: display title
style: optional global defaults (often for registers/operations)
operations: the main list of nodes that make up the diagram

Operations

Each entry in operations is an object describing one element of the circuit. Every operation has at least:

type: what kind of element this is
id: a unique identifier within the file

Common optional fields

Many operations also support the following fields:

input_registers: specifies which registers the operation applies to
children: nested operations, used for layout and grouping
style: visual overrides for appearance and layout

Common operation types

register: defines a wire or set of wires (rails)
gate: places a gate on one or more registers
routine: a named, reusable block that contains child operations
label: textual annotations tied to registers
group: a visual grouping container
column: a layout container for vertical organization
separator: visual spacing or separators

Register selection (`input_registers`)

input_registers specifies which registers an operation targets. It is usually a string supporting several selection patterns:

"r1" — single register
"r1,r2" — multiple registers
"*" — all registers
"reg[0]" — single index
"reg[1:3]" — range selection
"reg[-2:]" — negative indexing
"reg[0,2,4]" — explicit index list

Controlled operations

Some operations—most notably gate and routine—support control conditions via the controlled_by field.

"controlled_by": "a0,c0"

Example 1: Minimal circuit (registers + gate + label)

{
  "record_type": "psiquantum.circuit",
  "title": "Minimal Example",
  "operations": [
    { "type": "register", "id": "r1", "label": "q", "size": 2 },
    { "type": "register", "id": "r2", "label": "anc" },

    { "type": "label", "id": "label1", "label_type": "register-start", "label": "init", "input_registers": "r1,r2" },

    { "type": "gate", "id": "g1", "gate_type": "hadamard", "input_registers": "r1[0]" },
    { "type": "gate", "id": "g2", "gate_type": "hadamard", "input_registers": "r1[1]", "controlled_by": "r2" }
  ]
}

What this shows:

A multi-rail register (size: 2)
A label attached to multiple registers
A controlled gate (controlled_by)

Example 2: Hierarchy (column → group → routine → gates)

{
  "record_type": "psiquantum.circuit",
  "title": "Structured Example",
  "operations": [
    { "type": "register", "id": "a0", "label": "a" },
    { "type": "register", "id": "b0", "label": "b" },
    { "type": "register", "id": "c0", "label": "c" },

    {
      "type": "column",
      "id": "col1",
      "input_registers": "*",
      "children": [
        {
          "type": "group",
          "id": "grp1",
          "name": "demo group",
          "input_registers": "a0,b0,c0",
          "style": { "box_el": { "border": "1 solid black", "padding": { "r": "20" } } },
          "children": [
            {
              "type": "routine",
              "id": "rt1",
              "name": "controlled block",
              "label": "\\text{controlled}",
              "input_registers": "a0,b0,c0",
              "style": { "expanded": true },
              "children": [
                { "type": "gate", "id": "g1", "gate_type": "hadamard", "input_registers": "b0", "controlled_by": "!a0,c0" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

What this shows:

Layout and nesting via children
A routine used as a block container
A gate controlled by multiple registers, including a negative control (!a0)

Example `.circuit` files

The following example circuits demonstrate a range of supported features and serve as reference patterns for both humans and LLMs generating .circuit files. All examples are located in the /example_circuits/ directory.

RegisterRangeTest.circuit
Demonstrates register range selection, slicing, and index-based addressing using input_registers.
GateStyles.circuit
Shows how different gate styles and visual overrides are expressed using the style field.
RoutineStyles.circuit
Illustrates routines as reusable, named blocks, including styling, expansion behavior, and nested children.
sample-actions.circuit
Provides examples of higher-level actions and structured operations that go beyond simple gates.
Testing.circuit
Contains testing-oriented constructs and patterns used for validation and experimentation.
labels.circuit
Focuses on label usage, including register-attached annotations and layout placement.

What is a .circuit file?