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 deq-runtime

See Install from source below if you want a development build or to hack on the Rust runtime.

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 black-box-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 (--decoder black-box-relay-bp, black-box-tesseract, ...). It 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 black-box-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 .