QuantaBull/qfabric-shield-tebd

QFabric Shield — TEBD family decoder

Circuit-family-specialized neural QEC decoder, fine-tuned from nvidia/Ising-Decoder-SurfaceCode-1-Fast on Stim-generated surface-code syndromes specific to the tebd circuit family used by QFabric.

Distance variants

This repo contains one decoder per code distance, each trained on the full sweep of physical error rates p in { 0.001, 0.003, 0.005 }:

• d7/ — code distance D=7
• d9/ — code distance D=9
• d11/ — code distance D=11

Loading a specific variant:

import torch
ckpt = torch.load(hf_hub_download("QuantaBull/qfabric-shield-tebd", "d9/best.pt", token=HF_TOKEN))

Architecture

• Backbone — 4-layer 3D CNN matching the Ising-Fast topology (channels 4 → 128 → 128 → 128 → 4, kernel 3×3×3, GELU, ~913K params).
• Family adapter — small residual 3D CNN with family-biased kernel shape (3,5,5) (the spatial bias for TEBD's nearest-neighbor 2-qubit pattern).
• Total params — ~913K backbone + ~9K adapter.

Training

• Base: nvidia/Ising-Decoder-SurfaceCode-1-Fast weights loaded by shape-match.
• Data: ~500K Stim shots per (distance, p_error) cell, family-specific noise.
• Optimizer: AdamW, lr=1e-4, cosine schedule, 20 epochs.
• Hardware: single RTX 4090 (Community Cloud spot), ~2 hours per (family, distance).

Performance — threshold curve

See QuantaBull/qfabric-shield-bench for the LER vs p threshold curve across all distances and decoders. The canonical figure of merit: as code distance increases, Shield's specialist drives LER below threshold faster than PyMatching does on the same family.

Runtime

• ONNX exports under d{N}/model.onnx, opset 18, FP32 storage.
• Designed for CUDA-Q QEC's trt_decoder for sub-µs real-time decoding.
• CPU inference latency under 10 ms / shot via onnxruntime — used by the public demo Space.

License & rights

Derivative of NVIDIA's Ising-Decoder-SurfaceCode-1-Fast under the NVIDIA Open Model License. Family-adapter architecture and fine-tuned weights are proprietary to QuantaBull and covered by US Provisional Patent Application "Circuit-Family-Specialized Neural Decoder for Financial Quantum Computing" (Q3 2026 filing, Jay Gopalan inventor).