QREF is an open, language-independent format for describing quantum programs so their resource costs - qubits, gates, time - can be estimated and compared. It comes out of PsiQuantum's open tooling and powers compilers like Bartiq. This page is the plain-English reference: what it is, how SchemaV1 fits together, a worked example, and a free validator.
Fault-tolerant quantum algorithms are expensive, and "how expensive" is the question that decides what to build. Resource estimation needs programs described in a structured way: not as flat gate lists (too big), but as hierarchies of routines with repetition and data flow. QREF is that description. You write a program as nested routines with typed qubit ports, connections showing data flow, and repetition counts; estimation tools then aggregate the resources.
QREF is Apache-2.0, maintained by PsiQuantum at github.com/PsiQ/qref, and designed to be produced and consumed by any toolchain.
Programs are trees of routines. A routine can declare children, so a million-gate algorithm stays a small, readable document.
Sizes and costs can be expressions like precision * (precision - 1) / 2, so one document describes a whole family of problem sizes.
Resource declarations (additive, multiplicative, qubits) let tools roll costs up the tree, weighted by repetition.
A QREF document is JSON with "version": "v1" and a single top-level program routine. These are the building blocks, matching the canonical model in PsiQ/qref (schema_v1.py).
| Piece | What it is | Key fields |
|---|---|---|
| Routine | A node in the program tree: an operation, subroutine, or the whole program. | name, type, children, ports, connections, repetition, resources, input_params, local_variables, linked_params |
| Port | A typed, sized qubit register on a routine. Direction says whether qubits flow in, out, or through. | name, direction (input | output | through), size (number, expression, or null) |
| Connection | Data flow between ports of the routine and its children, written source -> target. | source, target (namespaced like child.port) |
| Repetition | How many times a routine repeats, with the pattern of the repetition. | count, sequence: constant | arithmetic | geometric | closed_form | custom |
| Resource | A declared cost of a routine: T-gates, measurements, qubits. | name, type (additive | multiplicative | qubits | other), value |
| Params | Free variables of the program (input_params), constants derived locally (local_variables), and links that bind a parent value into children (linked_params). | names matching [A-Za-z_][A-Za-z0-9_]*, optionally namespaced |
A minimal phase-estimation skeleton: state preparation, a controlled unitary repeated with geometric growth, and an inverse QFT. Note the namespaced connection targets and the symbolic T-gate counts.
{
"version": "v1",
"program": {
"name": "qpe",
"type": "phase_estimation",
"input_params": ["precision"],
"ports": [
{"name": "in_0", "direction": "input", "size": "precision"},
{"name": "out_0", "direction": "output", "size": "precision"}
],
"children": [
{"name": "state_prep", "type": "state_preparation",
"ports": [{"name": "out", "direction": "output", "size": "precision"}],
"resources": [{"name": "t_gates", "type": "additive", "value": "precision"}]},
{"name": "controlled_unitary", "type": "controlled",
"repetition": {"count": "precision", "sequence": {"type": "geometric", "ratio": 2}},
"ports": [{"name": "ctrl", "direction": "input", "size": 1},
{"name": "target", "direction": "through", "size": "n"}],
"resources": [{"name": "t_gates", "type": "additive", "value": "4 * n"}]},
{"name": "qft_inv", "type": "qft",
"ports": [{"name": "in", "direction": "input", "size": "precision"}],
"resources": [{"name": "t_gates", "type": "additive", "value": "precision * (precision - 1) / 2"}]}
],
"connections": [
{"source": "state_prep.out", "target": "controlled_unitary.target"},
{"source": "in_0", "target": "controlled_unitary.ctrl"},
{"source": "controlled_unitary.target", "target": "qft_inv.in"},
{"source": "qft_inv.in", "target": "out_0"}
],
"local_variables": {"n": "ceil(log2(1/precision))"}
}
}
Structural validation against SchemaV1, in your browser - nothing is uploaded. For the full tree rendering and resource breakdown, use QREF Render; for symbolic compilation, see Bartiq.