Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,95 @@
+---
+language: en
+license: mit
+tags:
+  - qec
+  - surface-code
+  - quantum
+  - pytorch
+  - quantum-error-correction
+  - neural-decoder
+pipeline_tag: other
+---
+
+# NTU Surface Code Decoder (AlphaQubit V2)
+
+Pre-trained neural decoder checkpoints for rotated surface codes, based on the
+**Neural Transfer Unification (NTU)** framework.
+
+📄 **Paper**: *Transfer Learning is All You Need for Scalable Neural Decoder*
+
+## Model Architecture
+
+**AlphaQubit V2** — A high-capacity neural decoder (~58M parameters) featuring:
+
+- **Interleaved RNN-Transformer backbone** (5 GRU + 6 self-attention layers)
+- **2D Rotary Position Embedding (RoPE)** based on physical detector coordinates
+- **Joint X+Z stabilizer processing** with spatial hint connections
+- **Cross-attention readout** with learnable logical query tokens
+- Trained with **progressive knowledge distillation** from MWPM pseudo-labels
+
+## Checkpoints
+
+| File | Distance | Size | Training Step |
+|------|----------|------|---------------|
+| `d7.pth`  | d=7  | ~121 MB | scratch |
+| `d11.pth` | d=11 | ~121 MB | transfer from d7 |
+| `d15.pth` | d=15 | ~121 MB | transfer from d11 |
+| `d19.pth` | d=19 | ~121 MB | transfer from d15 |
+| `d23.pth` | d=23 | ~121 MB | transfer from d19 |
+| `d25.pth` | d=25 | ~122 MB | transfer from d23 |
+
+Each checkpoint contains:
+- `model_state` — OrderedDict of model weights
+- `d` — code distance (int)
+- `rounds` — decoding rounds (int)
+- `step` — training step (int)
+
+## Usage
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+
+# Download checkpoint
+ckpt_path = hf_hub_download(
+    repo_id="Dreamworldsmile/ntu-surface-code-decoder",
+    filename="d7.pth",
+)
+
+# Load into AlphaQubit V2
+ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+model.load_state_dict(
+    {k.replace("_orig_mod.", "").replace("module.", ""): v
+     for k, v in ckpt["model_state"].items()},
+    strict=False,
+)
+```
+
+### With the official code
+
+```bash
+# Inference
+python inference.py --hf_repo Dreamworldsmile/ntu-surface-code-decoder --d 7 --shots 100000
+
+# Transfer learning
+python transformer.py --mode train --d 11 \
+    --hf_resume Dreamworldsmile/ntu-surface-code-decoder/d7.pth
+```
+
+## Authors
+
+Ge Yan, Shanchuan Li, **Shiyi Xiao**, Pengyue Ma, Hanyan Cao, Feng Pan, Yuxuan Du
+
+*Nanyang Technological University · TUAT · Shanghai Jiao Tong University · SUTD*
+
+## Citation
+
+```bibtex
+@article{ntu2024,
+  title={Transfer Learning is All You Need for Scalable Neural Decoder},
+  author={Yan, Ge and Li, Shanchuan and Xiao, Shiyi and Ma, Pengyue and
+          Cao, Hanyan and Pan, Feng and Du, Yuxuan},
+  year={2024},
+}
+```