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 — MPS 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 **mps** 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-mps", "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
+  `(5,3,3)` (the temporal bias for MPS prep's layered depth structure).
+- **Total params** — ~913K backbone + ~5K 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": "mps",
+  "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:c0accfca79d24f0f23becd2f4334c46b3007a7eba03fc87ca348253309844999
+size 3678914

d11/model.onnx

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

d11/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "mps",
+  "distance": 11,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.5914782265027364,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.6484808355990628,
+      "val_loss": 0.6087731907844544,
+      "val_acc": 0.64852
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.6031991806144045,
+      "val_loss": 0.6040539802296956,
+      "val_acc": 0.6555333333333333
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.5991920113218876,
+      "val_loss": 0.6001383352724711,
+      "val_acc": 0.6533333333333333
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.595755222846918,
+      "val_loss": 0.597707236328125,
+      "val_acc": 0.6544533333333333
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.5927219207773711,
+      "val_loss": 0.5949280035654704,
+      "val_acc": 0.65108
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.5904195594278971,
+      "val_loss": 0.5931575341796875,
+      "val_acc": 0.6528133333333334
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.5887521731048718,
+      "val_loss": 0.5921786656888326,
+      "val_acc": 0.6525066666666667
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.58778055483199,
+      "val_loss": 0.591686326789856,
+      "val_acc": 0.65304
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.5872493131316335,
+      "val_loss": 0.5915090257453919,
+      "val_acc": 0.6531066666666666
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.587051412791202,
+      "val_loss": 0.5914782265027364,
+      "val_acc": 0.6535066666666667
+    }
+  ],
+  "elapsed_s": 2171.176953315735
+}

d7/best.pt

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

d7/model.onnx

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

d7/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "mps",
+  "distance": 7,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.4831204416529338,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.5607715682975033,
+      "val_loss": 0.5172046812121074,
+      "val_acc": 0.72836
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.5119922722542076,
+      "val_loss": 0.5059984067726135,
+      "val_acc": 0.7311333333333333
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.5024265777868974,
+      "val_loss": 0.5000054170099895,
+      "val_acc": 0.73356
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.49566674374162106,
+      "val_loss": 0.4932661373837789,
+      "val_acc": 0.73652
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.4903293320657496,
+      "val_loss": 0.48893825971285504,
+      "val_acc": 0.7387333333333334
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.4865752147396824,
+      "val_loss": 0.4870646811612447,
+      "val_acc": 0.7389866666666667
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.48379588486286634,
+      "val_loss": 0.4845165158335368,
+      "val_acc": 0.7413733333333333
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.4821662684557731,
+      "val_loss": 0.4835508217271169,
+      "val_acc": 0.74152
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.48123680889230025,
+      "val_loss": 0.48317052680651346,
+      "val_acc": 0.74204
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.48091617532596254,
+      "val_loss": 0.4831204416529338,
+      "val_acc": 0.7419466666666666
+    }
+  ],
+  "elapsed_s": 898.6921174526215
+}

d9/best.pt

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

d9/model.onnx

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

d9/training_summary.json

@@ -0,0 +1,74 @@
+{
+  "family": "mps",
+  "distance": 9,
+  "p_errors": [
+    0.001,
+    0.003,
+    0.005
+  ],
+  "epochs": 10,
+  "best_val_loss": 0.5482157255172729,
+  "history": [
+    {
+      "epoch": 1,
+      "train_loss": 0.6155825373612789,
+      "val_loss": 0.5750814655431111,
+      "val_acc": 0.68864
+    },
+    {
+      "epoch": 2,
+      "train_loss": 0.5688975947440298,
+      "val_loss": 0.5643576537450155,
+      "val_acc": 0.6886266666666667
+    },
+    {
+      "epoch": 3,
+      "train_loss": 0.5614777644311336,
+      "val_loss": 0.5588828429603576,
+      "val_acc": 0.6888666666666666
+    },
+    {
+      "epoch": 4,
+      "train_loss": 0.5560373221681829,
+      "val_loss": 0.5546226082547505,
+      "val_acc": 0.68824
+    },
+    {
+      "epoch": 5,
+      "train_loss": 0.552139919251559,
+      "val_loss": 0.5518873160171509,
+      "val_acc": 0.6889466666666667
+    },
+    {
+      "epoch": 6,
+      "train_loss": 0.5495574191679035,
+      "val_loss": 0.5500225927098592,
+      "val_acc": 0.6896666666666667
+    },
+    {
+      "epoch": 7,
+      "train_loss": 0.5475853756727252,
+      "val_loss": 0.5492112227694194,
+      "val_acc": 0.6893333333333334
+    },
+    {
+      "epoch": 8,
+      "train_loss": 0.5464580642117952,
+      "val_loss": 0.5484689228375753,
+      "val_acc": 0.69088
+    },
+    {
+      "epoch": 9,
+      "train_loss": 0.5458091868042527,
+      "val_loss": 0.5482660090955098,
+      "val_acc": 0.69076
+    },
+    {
+      "epoch": 10,
+      "train_loss": 0.5455730257134689,
+      "val_loss": 0.5482157255172729,
+      "val_acc": 0.6909333333333333
+    }
+  ],
+  "elapsed_s": 1465.5698182582855
+}