deqagram
deqagram provides a pest-based parser and a typed AST for
the deq quantum error correction file
format:
.deq— declarative QEC code, gadget, compose, and program definitions.
Files are parsed into a typed AST via FromStr and serialized back via
Display, with roundtrip fidelity as a core invariant: parsing a file and
displaying it produces output that re-parses to the same AST.
Architecture
The crate (src/) has three layers:
- PEG grammar (
src/deq.pest) — the concrete syntax, and the definition of DEQ syntax. It began as a port of the Lark grammar deq used before this parser replaced it. - Parser struct (
src/lib.rs) — a thin#[derive(Parser)]wrapper around the grammar (DeqParser). Parser-level tests live insrc/parser_tests.rs. - AST (
src/ast.rs) — a typed representation built from pest pairs viaFromStr, serialized back viaDisplay, and mirroring deqagram's Python dataclasses. Source spans live insrc/span.rsand the error type insrc/error.rs.
The grammar is whitespace- and newline-insensitive, so roundtrip fidelity is at
the AST level (parse → display → re-parse), not byte-for-byte; comments are not
retained. The CHECK/DETECTOR and READOUT/OBSERVABLE_INCLUDE aliases are
conflated into single node kinds. Mako-templated .deq files are out of scope:
deq renders Mako before parsing.
Installation
Add it from crates.io:
[]
= "0.1"
Within the qdk-ec workspace it is a path dependency
(deqagram = { path = "../deqagram" }).
Usage
Parse a .deq file, inspect the AST, and serialize it back:
use DeqFile;
let input = "\
CODE RepetitionCode [[3,1,1]] {
LOGICAL X0*X1*X2 Z0*Z1*Z2
STABILIZER Z0*Z1 Z1*Z2
}
";
let file: DeqFile = input.parse.unwrap;
// Round-trips: displaying and re-parsing yields the same AST.
let serialized = file.to_string;
assert_eq!;
Runnable example
Parse and roundtrip-check one or more .deq files:
Development
deqagram is developed as part of the qdk-ec
workspace; build and test it with the usual workspace commands:
The Python bindings live under bindings/python and build
with maturin develop --release. In Python, deqagram.parse(text) returns
pure-Python dataclasses exported by deqagram. See the repository root README.md for
contributor setup and the CI pipelines.
This project uses Rust edition 2024.