deq 0.3.0

deq: quantum error correction decoding system.

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

Installation

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 .

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}'

Documentation

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