| --- |
| library_name: pytorch |
| tags: |
| - quantum-error-correction |
| - surface-code |
| - cuda-q |
| - circuit-family-specialized |
| license: other |
| license_name: nvidia-open-model-license-derivative |
| base_model: nvidia/Ising-Decoder-SurfaceCode-1-Fast |
| --- |
| |
| # QFabric Shield — TEBD family decoder |
|
|
| Circuit-family-specialized neural QEC decoder, fine-tuned from |
| [`nvidia/Ising-Decoder-SurfaceCode-1-Fast`](https://huggingface.co/nvidia/Ising-Decoder-SurfaceCode-1-Fast) |
| on Stim-generated surface-code syndromes specific to the **tebd** circuit family |
| used by [QFabric](https://quantabull.com). |
|
|
| ## 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: |
|
|
| ```python |
| 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`](https://huggingface.co/datasets/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). |
|
|
