Upload README.md with huggingface_hub

README.md

@@ -28,16 +28,20 @@ Pre-trained neural decoder checkpoints for rotated surface codes, based on the
 - **Cross-attention readout** with learnable logical query tokens
 - Trained with **progressive knowledge distillation** from MWPM pseudo-labels
 
-## Checkpoints
+## Repository Structure
 
-| 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 |
+```
+ntu-surface-code-decoder/
+├── README.md
+├── surface/           ← Surface code checkpoints (AlphaQubit V2)
+│   ├── d7.pth         (~121 MB, scratch)
+│   ├── d11.pth        (~121 MB, transfer from d7)
+│   ├── d15.pth        (~121 MB, transfer from d11)
+│   ├── d19.pth        (~121 MB, transfer from d15)
+│   ├── d23.pth        (~121 MB, transfer from d19)
+│   └── d25.pth        (~122 MB, transfer from d23)
+└── bb/                ← BB code checkpoints (coming soon)
+```
 
 Each checkpoint contains:
 - `model_state` — OrderedDict of model weights
@@ -51,10 +55,10 @@ Each checkpoint contains:
 import torch
 from huggingface_hub import hf_hub_download
 
-# Download checkpoint
+# Download a surface code checkpoint
 ckpt_path = hf_hub_download(
     repo_id="Dreamworldsmile/ntu-surface-code-decoder",
-    filename="d7.pth",
+    filename="surface/d7.pth",
 )
 
 # Load into AlphaQubit V2
@@ -69,12 +73,12 @@ model.load_state_dict(
 ### With the official code
 
 ```bash
-# Inference
+# Inference — auto-downloads surface/d{d}.pth
 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
+# Transfer learning — specify full path within the repo
+bash train.sh --mode transfer \
+    --hf_ckpt Dreamworldsmile/ntu-surface-code-decoder/surface/d7.pth --d 11 ...
 ```
 
 ## Authors