---
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).