Shield sweep upload

README.md

@@ -0,0 +1,71 @@
+---
+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).

config.json

@@ -0,0 +1,14 @@
+{
+  "family": "tebd",
+  "base_model": "nvidia/Ising-Decoder-SurfaceCode-1-Fast",
+  "distances": [
+    7,
+    9,
+    11
+  ],
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ]
+}

d11/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fef344f8df00144b9f77c0ac6a606c35977550b1c1168075387e09a515b99f73
+size 3694274

d11/model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:72f4c6cf7465aa2becfcb44f074552c96044c9f3d9089e70aca32eb7173632af
+size 3695831

d11/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "tebd",
+  "distance": 11,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.5893307039197286,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.6496606458968447,
+      "val_loss": 0.6067798583475749,
+      "val_acc": 0.6567733333333333
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.6043295821357192,
+      "val_loss": 0.6026874630037944,
+      "val_acc": 0.6579733333333333
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.6001519353535301,
+      "val_loss": 0.5988685774167378,
+      "val_acc": 0.6554933333333334
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.5964663791014019,
+      "val_loss": 0.5957653186162313,
+      "val_acc": 0.6543866666666667
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.5933235687433209,
+      "val_loss": 0.5926446552848816,
+      "val_acc": 0.6568933333333333
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.5908793199609456,
+      "val_loss": 0.5918899087270101,
+      "val_acc": 0.6588
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.5891345897999144,
+      "val_loss": 0.590268524500529,
+      "val_acc": 0.6554133333333333
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.5881762293079443,
+      "val_loss": 0.5895180296770731,
+      "val_acc": 0.6578533333333333
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.5876082948406955,
+      "val_loss": 0.5893909070714315,
+      "val_acc": 0.65712
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.5874070725343938,
+      "val_loss": 0.5893307039197286,
+      "val_acc": 0.6580133333333333
+    }
+  ],
+  "elapsed_s": 2155.1507194042206
+}

d7/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a21befdb68bdd4544629d40b0f072c00cea306b511672d2c51e3b0cd7fc14ed
+size 3694274

d7/model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d3877d1975e462c9e4492a3938103ee2a6065f06e848c85773f2231d25e762c4
+size 3695831

d7/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "tebd",
+  "distance": 7,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.4850299895922343,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.560978079570971,
+      "val_loss": 0.5189036681556701,
+      "val_acc": 0.72708
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.5125583040240773,
+      "val_loss": 0.507024670607249,
+      "val_acc": 0.7310266666666667
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.503054410458615,
+      "val_loss": 0.5004609227244059,
+      "val_acc": 0.7327866666666667
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.4961215019574082,
+      "val_loss": 0.4956115154202779,
+      "val_acc": 0.73564
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.4910303274914256,
+      "val_loss": 0.4917865618801117,
+      "val_acc": 0.7368266666666666
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.4871813299694396,
+      "val_loss": 0.48907088412920635,
+      "val_acc": 0.7391066666666667
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.48446081741751285,
+      "val_loss": 0.48709864040056866,
+      "val_acc": 0.7389066666666667
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.4827537358407807,
+      "val_loss": 0.4854605124632517,
+      "val_acc": 0.7402933333333334
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.4818504030906945,
+      "val_loss": 0.48508225439389546,
+      "val_acc": 0.7400533333333333
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.48151920323321695,
+      "val_loss": 0.4850299895922343,
+      "val_acc": 0.7400933333333334
+    }
+  ],
+  "elapsed_s": 896.5598595142365
+}

d9/best.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:97e1d8dac6c2383e997ff8e987149c6fd01bb40f89cce837712a16b18ea505b9
+size 3694274

d9/model.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:842fe6ab3973bcfb02a010f9d0321190da620d85eb49e89d4ec6485ffcad8dca
+size 3695831

d9/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "tebd",
+  "distance": 9,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.5463277807617187,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.6150136535925614,
+      "val_loss": 0.572360772151947,
+      "val_acc": 0.68836
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.5687772997969912,
+      "val_loss": 0.5633413609313965,
+      "val_acc": 0.6896133333333333
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.5610227698660734,
+      "val_loss": 0.5573002897135416,
+      "val_acc": 0.6895733333333334
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.5554959305334928,
+      "val_loss": 0.553101398340861,
+      "val_acc": 0.6912266666666667
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.5515863727666621,
+      "val_loss": 0.5506294211959839,
+      "val_acc": 0.69332
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.5488491834352728,
+      "val_loss": 0.548536518535614,
+      "val_acc": 0.6940533333333333
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.5469643701908045,
+      "val_loss": 0.5472446662012737,
+      "val_acc": 0.69452
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.545853731637252,
+      "val_loss": 0.5465782469367981,
+      "val_acc": 0.6949333333333333
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.5452096749275609,
+      "val_loss": 0.5463539229011536,
+      "val_acc": 0.6952666666666667
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.5449687300953112,
+      "val_loss": 0.5463277807617187,
+      "val_acc": 0.6951333333333334
+    }
+  ],
+  "elapsed_s": 1421.626991033554
+}