Bring your own decoder: hierarchical QEC decoding with Backline, NVIDIA Ising, and PyMatching

Backline lets you bring your own quantum error correction decoders — whether they are neural networks, compiled libraries, or Python packages. To show it off, we ran NVIDIA's Ising AI pre-decoder on an AMD Instinct™ GPU, and paired it with PyMatching for online decoding — all from a single Python program.

Ask a room full of quantum error correction (QEC) researchers which decoder they use, and you'll likely get more answers than there are people in the room. Matching decoders, union-find, belief propagation, and — increasingly — neural networks all come with their own trade-offs between speed and accuracy, and their own preferred languages, libraries, and hardware.

This diversity is a good thing; decoding is one of the most active research areas on the road to fault-tolerant quantum computing (FTQC). And we can see this diversity in the current quantum software ecosystem — from libraries such as PyMatching, TQEC and qLDPC, to AI models such as NVIDIA Ising.

With this diversity, however, comes a logistical challenge. To explore the end-to-end impact of different QEC architectures and implementations, we need to integrate these software tools into quantum computing software stacks that include the application alongside logical and hardware compilation. Furthermore, to correct errors on a real device, the decoder has to run right beside the quantum hardware, on whatever classical hardware the control stack provides, and keep up with a stream of syndrome data that arrives roughly every microsecond.

Last month, we announced Backline, an open platform — co-designed with AMD — for compiling quantum programs and executing them alongside CPUs, GPUs, and FPGAs with low latency, entirely from Python. Out of the box, it came with built-in decoders, and the ability to write your own GPU kernels in Python using Triton. But the decoder you actually want to use probably already exists — and somebody else wrote it.

So, today, we're making it easy to bring your own decoder to Backline.

Contents

• Bring your own decoder
• Putting it to the test: NVIDIA Ising on AMD Instinct GPUs
• Try it out and get involved

Bring your own decoder

Whatever form your decoder takes, there is now a path to running it with Backline:

The most recent addition is qp.backline.onnx_decoder. ONNX is an open standard for machine learning models, and nearly every major framework (such as PyTorch, JAX, and TensorFlow) can export to it. Simply provide qp.backline.onnx_decoder an exported model, and it hands back a coprocessing function that's ready to drop straight into a backline:

import pennylane as qp

predecoder = qp.backline.onnx_decoder("predecoder.onnx")

dev = qp.Backline(
    controller=qp.Controller(device=qp.device("lightning.qubit", wires=1)),
    coprocessors=[qp.Coprocessor(hardware="gpu", coprocessor_fn=predecoder)],
    transport="memcpy",
)

That's it. There's no build step, and no need to tell Backline how much data to send back and forth — the message sizes are read straight from the model's input and output shapes.

Best of all, the model runs with ONNX Runtime, so the same program can target different hardware simply by installing a different package: onnxruntime-migraphx for AMD Instinct GPUs (using AMD's MIGraphX inference engine on ROCm™), onnxruntime-gpu for NVIDIA GPUs, or plain onnxruntime for the CPU. (So far, we've tested it on CPUs and AMD Instinct GPUs.) In other words, models from across the ecosystem — including those trained and released for other hardware — can run on AMD Instinct GPUs without modification.

Not every decoder is a neural network, of course. If your decoder lives in a Python package, pure_callback lets you call it from a local controller, directly within your compiled program — perfect for rapid R&D (albeit with the overhead of calling back into Python). And if it's a compiled library with a C interface, you can register it as a coprocessing function, or call it from the controller with qp.runtime_call.

Putting it to the test: NVIDIA Ising on AMD Instinct GPUs

To see how this works in practice, we built a two-stage hierarchical decoder out of two existing, openly available decoders.

The first stage is NVIDIA Ising, a family of AI pre-decoders for the surface code, released by NVIDIA earlier this year alongside its training recipes and trained models. These 3D convolutional neural networks (3DCNNs) look at several rounds of syndrome data at once, clear away most of the local detection events, and predict the logical correction that those detection events imply.

The second stage is PyMatching, the widely used minimum-weight perfect matching decoder. It decodes the residual syndomes output from the pre-decoder, and the two corrections are combined to give the final answer.

Why split the work? Matching decoders bottleneck as the number of detection events grow, while 3DCNNs excel at analyzing dense local syndrome patterns in parallel on a GPU. Letting the predecoder reduce the density of syndromes leaves a sparser problem for the matcher, while allowing each stage to run on hardware that suits it best (exactly what Backline was built for!).

We exported NVIDIA's model from PyTorch to ONNX, ran it on an AMD Instinct™ MI210 GPU coprocessor, and called PyMatching from the CPU controller. This is online decoding: each shot is decoded, and its correction applied, inside the running program — rather than collected and decoded offline after the fact. Schematically, an error-corrected QNode using this hierarchical decoder looks like this:

qdev = qp.device("null.qubit", wires=50)
predecoder_fn = qp.backline.onnx_decoder("predecoder.onnx")

CPU = qp.Controller(device=qdev)
GPU = qp.Coprocessor(hardware="gpu", coprocessor_fn=predecoder_fn)
dev = qp.Backline(controller=CPU, coprocessors=[GPU], transport="memcpy")

@qp.qnode(dev)
def error_corrected_circuit():
    # explicit error encoded circuit
    surface_code_encoded_circuit()

    # perform syndrome measurements
    syndromes = extract_syndromes()

    # Stage 1: the Ising pre-decoder, on the GPU coprocessor
    predecoded = qp.backline.decode(syndromes, bitpack=False)
    pre_flip, residual = predecoded[0], predecoded[1:]

    # Stage 2: PyMatching, on the controller
    flip = pre_flip.astype(jnp.int64) ^ match(residual)

    if flip == 1:
        qp.X(0)

    return qp.expval(qp.Z(0))

Here, match is a thin pure_callback wrapper around PyMatching:

import numpy as np
import pymatching
import stim
from catalyst import pure_callback

error_model = stim.DetectorErrorModel.from_file("circuit.dem")  # detector error model
matcher = pymatching.Matching.from_detector_error_model(error_model)

@pure_callback
def match(residual) -> int:
    """PyMatching's predicted logical correction for one shot's residual detectors."""
    return np.asarray(matcher.decode(np.asarray(residual))[0], dtype=np.int64)

Wrap a loop over shots in @qp.qjit, and the whole pipeline — quantum device, GPU inference, Python callback, and the corrective feedforward — is compiled into a single program.

In the demo, we sample the syndromes of a distance-5 surface code memory experiment from NVIDIA's Stim-based simulation, rather than simulating the full encoded circuit. Check it out for more details, and to reproduce this result using Backline.

So what just happened? An AI pre-decoder from NVIDIA, exported through an open standard, running on an AMD Instinct GPU, and combined with a community-developed Python decoder — all orchestrated from a few lines of PennyLane. No custom C++ bindings, and no rewriting the decoder to fit the platform.

Try it out and get involved

Ready to bring your own decoder? Here's where to start:

• Run the demo: Follow along step by step in our demo — export NVIDIA's model to ONNX, build the backline, and decode on AMD GPUs.

• Read the docs: Check out the documentation for qp.backline.onnx_decoder, and the wider Backline documentation.

• New to Backline? Read the announcement, and see how to go from local CPU prototyping to low-latency FPGA-GPU communication in our original demo.

• Explore the technology: Read the Backline paper for a technical overview of the infrastructure and its performance.

Have a decoder you'd love to see running on Backline? Let us know! Head over to our GitHub repository to check out the ongoing work and join in on the development, or pop over to the PennyLane discussion forum to tell us how you are using PennyLane, Backline, and Catalyst in your workflows.

And if you are as excited as we are, make sure to sign up for the PennyLane newsletter for the latest PennyLane features and updates!