deq: dynamic and generic QEC decoding system

deq is a quantum error correction (QEC) decoding system that provides an automated workflow from declarative definitions of QEC codes and logical instructions to a runtime decoder for arbitrary dynamic logical circuits.

Key features:

• Declarative .deq language — define QEC codes and their physical gate realizations using a stim-compatible DSL; deq automatically discovers checks (detectors) from the Clifford circuit
• Dynamic circuit decoding — decode logical circuits whose instructions stream in at runtime, not just static offline-known circuits
• Simulation & deployment — run logical error rate simulations, latency benchmarks, and deploy on real hardware with the same compiled library
• Pluggable decoders — use a built-in decoder, or load any decoder from a binary-only shared library at runtime via a stable C ABI (see Decoder plugins)

See the Tutorial for a full introduction, language reference, and worked examples.

Installation

pip install deq

See Install from source below if you want a development build or to hack on the Rust runtime. For vs code user, it's recommended to install the QDK extension, which provides syntax highlight to deq files.

Quick start

Here is an example deq program:

# define a QEC code of [[n,k,d]] (d is optional)
CODE RepetitionCode [[3,1,3]] {
    LOGICAL X0*X1*X2 Z0*Z1*Z2
    STABILIZER Z0*Z1 Z1*Z2
}

GADGET PrepareZ {
    R 0 1 2
    X_ERROR(0.03) 0 1 2
    OUTPUT RepetitionCode 0 1 2
}

GADGET Idle {
    INPUT RepetitionCode 0 2 4
    X_ERROR(0.03) 0 2 4  # data qubit error
    R 1 3
    CX 0 1 2 3
    CX 2 1 4 3
    M(0.03) 1 3  # measurement error
    OUTPUT RepetitionCode 0 2 4
}

GADGET MeasureZ {
    INPUT RepetitionCode 0 1 2
    M(0.03) 0 1 2  # measurement error
    READOUT rec[-1] rec[-2] rec[-3]
}

# a logical circuit with criteria of logical error
PROGRAM Simulation {
    PrepareZ 0
    Idle 0
    MeasureZ 0
    ASSERT_EQ rec[-1] 0
}

# Transpile a .deq definition into a JIT library
deq transpile example.deq --out example.deq.jit --program Simulation

# Run a logical error rate simulation
deq server --decoder relay-bp --coordinator window \
    --controller jit --controller-config '{"filepath":"example.deq.jit"}' \
    --simulator jit-static --simulator-config '{"filepath":"example.stim","jit_library_filepath":"example.deq.jit","shots":100000}'

Decoder plugins

deq ships several built-in decoders, including native graph MWPM (--decoder mwpm), native hypergraph MWPF (--decoder mwpf), graph union-find (--decoder uf), hypergraph union-find (--decoder huf), Relay-BP (--decoder relay-bp), and Tesseract (--decoder tesseract). The legacy black-box-* names remain accepted. deq can also load a decoder from a binary-only shared library at runtime — no recompilation of deq — as long as the library implements deq's stable C ABI. This lets you plug in a decoder written in any language (Rust, C, C++) and distributed as a .so/.dylib/.dll.

Build the runtime with the dylib feature (off by default), then select the plugin by path:

# build deq_runtime with plugin loading enabled
cd deq_runtime && maturin develop --release --features dylib && cd ..

# decode with a plugin. `library` is the path to the shared object and
# `parallel` is deq's worker count; plugin-specific parameters go in the
# nested `decoder_config` object, the only part forwarded to the plugin.
deq server --decoder dyn-lib \
    --decoder-config '{"library":"/path/to/libmy_decoder.so","parallel":0,"decoder_config":{}}' \
    --coordinator window ...

The plugin is loaded once (dlopen), then serves every decode in-process at native speed; there is no per-shot serialization. To write a plugin, implement the DeqDecoder trait and the declare_decoder! macro from the deq-decoder-abi crate (Rust), or export the C ABI directly using its header deq_decoder.h (C/C++). See that crate's documentation for the full contract.

Install from source

Prerequisites

• Python ≥ 3.10
• Rust toolchain (for building deq_runtime)
• maturin (pip install maturin)
• protobuf compiler (apt install protobuf-compiler on Ubuntu, brew install protobuf on macOS)

Steps

# 1. Build and install the Rust runtime (deq_runtime)
cd deq_runtime
maturin develop --release
cd ..

# 2. Generate protobuf Python bindings
python deq/proto/compile.py

# 3. Install the deq Python package
pip install -e .