RustQEC 0.3 · Development

Enable the optional qasm feature for semantic OpenQASM 2.0 import and export. The frontend parses a syntax tree, checks scopes and types, resolves gate definitions, and constructs ordered operations before choosing an execution target. It does not replace gate names in source strings.

This feature is available in the development checkout with qasm enabled. Build from this repository as shown below; the published native release and crates.io package may expose a different feature set. Use rstim capabilities --format json to inspect an installed executable.

Choose a conversion path

TaskCommand or APIWhat to keep
Import QASM and export it again with the same register layoutcircuit import-qasm, then circuit export-qasm --in-format qasm2-jsonThe semantic program.qasm2.json document
Sample a QASM programcircuit sample --in-format qasm2-json with an explicit backend and result viewThe document and the chosen result-view convention
Export an existing native circuitcircuit export-qasm --in native.stimThe QASM output and any omission report
Produce native instructions for another toolcircuit import-qasm --out-format stimThe original document too, if register names and classical destinations matter

Import checks declarations, operand types, indices, gate definitions, expressions and resource limits before lowering ordered operations to an execution backend. A successful conversion preserves quantum behavior, measurement positions and classical feedback within the supported profile. Source spelling and gate names are not a round-trip guarantee.

First QASM round trip

Build a small CLI with QASM support from the repository root, then use a scratch directory for the example files:

cargo build --locked -p rstim --no-default-features --features qasm,unified-cli
RSTIM="$(pwd)/target/debug/rstim"
qasm_demo_dir="$(mktemp -d)"
cd "$qasm_demo_dir"

This one-qubit program uses a T gate, measures before feedback, and writes the same classical bit twice:

cat > feedback.qasm <<'QASM'
OPENQASM 2.0;
include "qelib1.inc";
qreg q[1];
creg c[1];
h q[0];
t q[0];
h q[0];
measure q[0] -> c[0];
if(c==1) x q[0];
measure q[0] -> c[0];
QASM

"$RSTIM" circuit import-qasm --in feedback.qasm --out program.qasm2.json \
  --backend near-clifford
"$RSTIM" circuit sample --in program.qasm2.json --in-format qasm2-json \
  --backend near-clifford --result-view measurement-record \
  --shots 64 --seed 7 --out records.01
"$RSTIM" circuit sample --in program.qasm2.json --in-format qasm2-json \
  --backend near-clifford --result-view classical \
  --shots 64 --seed 7 --out classical.01
"$RSTIM" circuit export-qasm --in program.qasm2.json --in-format qasm2-json \
  --out roundtrip.qasm

Each row of records.01 has two bits: 00 or 10. Feedback maps the first measurement's state to zero before the second measurement. Each row of classical.01 therefore has one bit, 0: the final value of c[0]. The first measurement remains in the record even though its classical destination was overwritten. Export retains both measurements and the feedback between them.

The T gate requires --backend near-clifford; the default stabilizer backend rejects this program. For a Clifford-only circuit, choose --backend stabilizer. The near-Clifford rank limit still applies; see Supported profile.

To export a native circuit in the same directory:

printf 'H 0\nMX 0\nMR 1\n' > native.stim
"$RSTIM" circuit export-qasm --in native.stim --out native.qasm

Native export creates classical registers in measurement-record order. It checks the supported instruction subset and rejects noise and loss. Annotation omission requires the explicit policy described under Export checked and native circuits.

Rust feature setup

[dependencies]
rstim = { path = "../rstim/rstim", default-features = false, features = ["qasm"] }
rand = "0.8"

Import and execute

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use rand::{SeedableRng, rngs::StdRng};
    use rstim::qasm::{Backend, QasmLimits, from_qasm};

    let program = from_qasm(r#"
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    creg c[2];
    h q[0];
    cx q[0],q[1];
    measure q -> c;
    "#)?;
    let plan = program.lower(Backend::Stabilizer, &QasmLimits::default())?;
    let mut rng = StdRng::seed_from_u64(7);
    let shots = rstim::sampler::sample_batch(&plan.instructions, 16, &mut rng)?;
    for shot in 0..16 {
        let record = (0..plan.measurement_events.len())
            .map(|i| shots.measurements.get(i, shot)).collect::<Vec<_>>();
        let classical = plan.project_classical(&record)?;
        assert_eq!(classical[0], classical[1]);
    }
    Ok(())
}

Classical registers start at zero. A measurement executes at its original position and overwrites its destination bit. The native measurement record retains every measurement, including overwritten results; project_classical selects the latest assigned value for each declared bit and supplies unwritten zeros. Output bits use register declaration order, then increasing bit index. For integer comparisons, bit 0 is the least significant bit. These are separate ordering rules; do not reverse output bits to evaluate a condition.

The conversion document preserves declared register widths, including idle qubits. A plain .stim execution projection does not retain register names or classical destination assignments. Keep the conversion document when these are needed for subsequent export or result interpretation.

Supported profile

ConstructBehavior
QASM 2 declarations and multiple registersChecked names, types, sizes, offsets and indices
Built-in U/CX, original qelib1.incChecked primitive or named-gate lowering
Custom unitary definitionsParameter binding and bounded expansion; bodies validated even if unused
Register operandsChecked width expansion and quantum operand aliasing
Measurement/resetOrdered quantum operations; measurement destinations retained
BarriersScoped in the document; a conservative global TICK in the execution projection
One-bit register conditions on X/Y/ZNative Pauli feedback; equality to zero and one supported
General multi-bit or non-Pauli conditionsExplicitly rejected as outside the supported profile
Executed opaque gatesExplicitly rejected; unused declarations can be retained during checking
QASM 3, noise and pulse syntaxNot supported by this profile

The stabilizer target accepts operations whose lowering consists of Clifford gates. Exact symbolic multiples of pi/2 can be recognized without a numerical threshold. Nearby decimal angles are not snapped to Cliffords. Gate sequences that happen to cancel to a Clifford are not generally optimized.

T gates and general rotations require an explicit Backend::NearClifford selection. Lowered rotations use native half-turns, not radians. R_Z is a rotation; RZ without an underscore is a reset. Execute the lowered plan with CompiledNearCliffordExecutor::compile_with_limit(plan.instructions.clone(), 16) and its sampler; ordinary stabilizer sampling never switches backends. Active rank and memory limits still apply. program.analyze(&limits) reports each backend's support independently of execution cost.

Header and phase conventions

The bundled header is the original qelib1.inc. Gate bodies are authoritative. A user-defined gate named x does not acquire Pauli semantics solely from its name. Modern names such as swap and sx must have definitions; they are not implicit extensions to the original header.

Primitive U(theta,phi,lambda) uses the usual matrix with top-left entry cos(theta/2), top-right -exp(i*lambda)*sin(theta/2), bottom-left exp(i*phi)*sin(theta/2) and bottom-right exp(i*(phi+lambda))*cos(theta/2). One common global phase of a complete unitary is immaterial. Relative phases across control branches are preserved.

The original header aliases rz to u1. Its original cu3 definition also differs from a conventionally controlled U by a control-dependent phase. Import uses the literal original body rather than silently substituting a differently defined tool-specific gate. This matters when comparing with other importers; see Qiskit's phase convention notes.

Export checked and native circuits

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use rstim::qasm::{from_qasm, to_qasm, export_stim, ExportOptions, QasmLimits};

    let limits = QasmLimits::default();
    let options = ExportOptions::default();
    let program = from_qasm("OPENQASM 2.0; qreg h[1]; creg c[1]; measure h -> c;")?;
    let output = to_qasm(&program, &options, &limits)?;
    assert!(output.text.contains("qreg h[1]"));

    let native = rstim::parser::parse_lines("H 0\nCX 0 1\nMX 0\nMR 1\n")?;
    let output = export_stim(&native, &options, &limits)?;
    assert_eq!(output.classical_registers.len(), 2);
    Ok(())
}

Checked-document export preserves declared registers and each measurement's destination. Native Stim export has no original classical layout; it creates one-bit m0, m1, ... registers in record order. This allows record feedback to use legal QASM 2 register-equality conditions. Basis measurements restore the post-measurement quantum state; inverted measurements complement their output without changing that state. Reset does not add a visible measurement result.

The writer emits portable primitive U/CX operations, without a header or helper names that might collide with a source register. This also avoids relying on tool-specific gates such as sx or swap. Gate names and original source formatting are not reconstructed. Exact expression literals use the signed 64-bit integer range, including an arithmetic spelling for its minimum value. A checked angle can have an exact unsigned 64-bit denominator produced by several divisions; export rejects a denominator above i64::MAX with qasm_unrepresentable_export instead of silently replacing it with a floating-point parameter.

Native instruction familyExport behavior
I/H/Paulis/S and inverse, SQRT_X/Y/Z and inverse, CX/CY/CZ/SWAP aliasesChecked primitive decompositions
T/T_DAG and R_X/R_Y/R_ZCoherent rotations; exact binary half-turn periods retained
M/MZ/MX/MY, MR/MRZ/MRX/MRY, inverted measurement targetsBasis-preserving projective instruments
R/RZ/RX/RYUnobserved reset in the corresponding basis
Record-controlled X/Y/ZSingleton-register equality feedback
Positive REPEATBounded expansion, including empty-body work accounting
TICKBarrier; empty ticks have an explicit omission report
Detector/observable/coordinate annotations and tagsStrict rejection by default
Noise, loss, sweep, MPP/MXX/MYY/MZZ, SPP, MPAD and unknown gatesRejected, including zero-probability noise

ExportOptions { omit_annotations: true } explicitly requests a projection that omits QEC and layout annotations. Every removed item appears in omitted_annotations with its instruction/repeat path. This option never permits discarding quantum noise, reset, measurement, feedback, or unknown operations. Export performs validation without compiling or simulating a near-Clifford plan.

Includes, diagnostics and limits

from_qasm supplies the bundled standard header and otherwise has no implicit filesystem or network access. parse_and_check accepts an explicit IncludeResolver. For files, from_qasm_file(path, &FileResolver::default(), &limits) searches the including file's directory and configured include paths. The reserved bundled standard header wins over unrelated working-directory files.

QasmLimits bounds source bytes, tokens, include files/depth, gate and expression depth, expanded operations, qubits and classical bits. max_operations separately bounds the number of retained operations and their cumulative expanded operand work: each gate/condition target or barrier qubit counts once, and each measurement/reset counts once. Wide barriers therefore share one cumulative budget instead of allocating an unbounded target list per source statement. Declared idle register width remains governed by the qubit/classical-bit limits. Gate expansion also charges broadcast-lane operand visits against max_operations * max_gate_depth, including calls to empty gate bodies. max_output_bytes is used by QASM export and semantic JSON input/output; QASM parsing/lowering do not consume that budget. File reads are bounded separately by FileResolver::max_file_bytes. Expressions use checked bounded rational arithmetic where possible, otherwise finite FP64 values. Invalid domains, non-finite results and excessive expansion fail explicitly.

QasmError includes a stable category, message, source location and expansion context. Syntax/type errors, valid unsupported constructs and backend limitations are distinct. Conversion failures never remove unsupported operations and continue with a different circuit.

Persistent semantic documents

QasmCircuit::to_json(&limits) produces schema rstim.qasm2-program.v1. QasmCircuit::from_json(text, &limits) checks the schema, every nested field, register layout, operation arity, angle domain, provenance, and all resource limits before returning a usable document. Unknown fields and malformed operations fail rather than changing meaning. Floating-point angles retain their FP64 values through serialization; exact rational multiples of pi retain their integer representation.

The document stores expanded typed operations, declared quantum/classical registers, and optional source spans. It does not store a second executable plan or a cached classical-output map that could disagree with those operations. Lowering recomputes measurement events and final classical bindings. Keeping the document is the normal workflow for a semantic round trip; .stim is an explicit execution projection with a warning about lost layout information.

Command-line workflows

Build conversion commands with both optional features:

cargo build --locked -p rstim --no-default-features --features qasm,unified-cli
RSTIM=target/debug/rstim
"$RSTIM" circuit import-qasm --in input.qasm --out program.qasm2.json --backend near-clifford
"$RSTIM" circuit export-qasm --in program.qasm2.json --in-format qasm2-json --out output.qasm
"$RSTIM" circuit sample --in program.qasm2.json --in-format qasm2-json \
  --backend near-clifford --result-view classical \
  --shots 1024 --seed 7 --out shots.01
"$RSTIM" circuit export-qasm --in native.stim --out native.qasm

For a Clifford-only program, choose --backend stabilizer (the default). Near-Clifford sampling requires an explicit selection and accepts --max-active-rank (default 16). Exceeding that limit fails with an actionable error; rank limits are never automatically raised. Conversion itself does not sample or compile the potentially expensive near-Clifford execution state.

Import defaults to --out-format qasm2-json; --out-format stim requests the execution projection and reports layout loss. Export defaults to --in-format stim; use --in-format qasm2-json to retain the original layout. --omit-annotations reports every omitted native annotation and never removes noise or unsupported quantum operations.

Omitting --in, or passing --in -, reads stdin. File imports resolve relative includes beside the including file. Stdin imports require explicit --include-dir PATH for external includes; nested includes then resolve beside the included file. The bundled standard header remains available in either case. Circuit artifacts go to the required --out file; JSON/human reports go to stdout and diagnostics go to stderr. Failed validation or sampling leaves an existing output file intact.

Sampling defaults to --result-view measurement-record. The classical view uses declared register order, preserves unwritten zeros, and selects the latest measurement assigned to each bit. It requires a semantic document; a plain Stim file has no classical layout. Supported shot encodings are 01, b8, r8, hits, and ptb64. Existing Stim-only sampling defaults are unchanged. QASM documents are not direct input to detection-event, DEM, or decoder commands. rstim capabilities --format json advertises the conversion commands only when the feature is enabled.

Verification and reference implementations

Ordinary Rust tests use an independent full-matrix and labelled-instrument interpreter for small circuits. Comparisons use one common unitary phase, or outcome-labelled Choi matrices for measurement/reset/feedback. Generated properties cover source/document/export and native/export/import round trips; they check quantum state changes as well as final classical results. Focused CLI tests cover both backends, result views, file/stdin handling, atomic output, and disabled-feature behavior.

The dedicated QASM workflow runs an independent strict Qiskit parser and pinned upstream Stim differential checks. Run its external check locally with the exact pinned dependencies in that workflow and python3 tools/qasm2_conformance.py --binary target/debug/rstim. The same workflow smoke-tests the bounded qasm2_parse and qasm2_document fuzz targets. The general CI suite also exercises feature combinations. Repository coverage runs on master pushes, scheduled runs and manual runs include the optional conversion code; PRs run the workspace and focused QASM test gates.

Stim's exporter informed basis/inverted-measurement decompositions and explicit failure behavior. The yao-rs converter informed the AST/type-check/expansion architecture. Its measurement treatment is not an execution oracle. rstim uses its own bounded frontend because the examined openqasm 0.1.2 parser stores real literals as FP32 and lacks scientific notation. These references guide interoperability; they do not replace semantic tests.