shanto268 commited on
Commit
87bceec
·
verified ·
1 Parent(s): bb9d0ce

Add the Balanced tier (balanced/), README: short card in the paper's language with links

Browse files
README.md CHANGED
@@ -2,95 +2,101 @@
2
  license: mit
3
  library_name: pytorch
4
  tags: [superconducting-qubits, capacitance, electrostatics, gds, graph-neural-network, squadds]
 
 
5
  ---
6
 
7
- # Planar capacitance: flagship models (SQuADDS)
 
 
8
 
9
- GDS layout -> full Maxwell capacitance matrix of superconducting-circuit components. Networks trained on all 45,771 on-stack Q3D layouts, the paper's test split included, so these models have no held-out score of their own. Each tier lists its own in-sample fit (a fit to data it was trained on, not a generalisation score), one fresh check (B5: 39 new layouts of one generated family, 3-4 conductors, never seen by any component) and, labelled "paper's version", the held-out numbers of the paper's model of that tier, trained on the 35,354 TRAIN layouts only. Those numbers belong to the paper's versions, not to these models. For benchmarks use the paper model (`SQuADDS/PlanarCapacitance-paper`).
 
 
 
 
 
 
 
 
 
 
 
 
10
 
11
  ```python
12
  from squadds.ml.capacitance import CapacitancePredictor, load_model
13
- res = CapacitancePredictor(load_model("flagship", tier="accurate")).predict("chip.gds")
 
 
14
  res.names, res.matrix_fF, res.to_sim_results()
15
  ```
16
 
17
- | tier | folder | what |
18
- |---|---|---|
19
- | **Accurate** (default) | `accurate/` | Two thin-film method-of-moments solves (corrected prior with substrate far field, 1.5 and 3 panels per gap), Richardson-extrapolated, corrected by a 3-seed ensemble of the paper model's networks (89,858 parameters per seed, bounded residual) with a learned row-sum closure: the complete Maxwell matrix, self terms included. Networks retrained on all 45,771 on-stack Q3D layouts (2026-10-20, on the corrected prior with substrate far field). |
20
- | Fast | `fast/` | An improved release of the paper's fast model, same architecture: a learned surrogate (1.02M parameters) predicts the two uncorrected-prior solves at 1.5 and 3 panels per gap and residual networks correct them. The surrogate is trained on more generated layouts (the prior of every on-stack layout plus 432,697 generated layouts labelled by the prior alone, against 385,593 for the paper's) and the networks are retrained on every labelled design (all 45,771 on-stack layouts, the paper's test split included). No field solve: the time is the geometric embedding. |
21
 
22
- > **Warning (Fast).** Use Fast only for quick screening of the component families it was trained on (interdigital, paddle, concentric, star, multipad star, Xmon, TransmonPocket, shielded concentric, two-net, random, procedurally generated and synthetic campaign layouts). On new designs of a trained family (B5) it was worse than the physics alone, 3.175 % (MAE 0.583 / RMSE 0.824 fF) against 1.765 % (0.275 / 0.376 fF), and the paper's version of it was worse than the physics alone on a held-out family too, 3.11 % (0.533 / 0.633 fF) against 1.55 % (0.166 / 0.205 fF). Use Accurate for anything that matters. Every result carries its physical checks (symmetry, off-diagonal signs, positive-definite signal block); when one fails, the result says so in its warnings (and SQuADDS raises a `UserWarning`): do not use that matrix.
23
 
24
- ## Accurate
 
 
 
 
25
 
26
- Paper's version: the paper's model (same architecture and prior stack at inference; its networks were trained on the 35,354 TRAIN layouts only, on the uncorrected prior; retrained on the corrected prior, as here, they score validation 0.218 % (0.0774 / 0.0888 fF)). Its held-out numbers below belong to that version, not to this release.
27
 
28
- | set | median % (MAE / RMSE) |
29
- |---|---|
30
- | this model, in-sample (all 45,771 training layouts; it was trained on them) | 0.207 % (MAE 0.0679 fF / RMSE 0.077 fF) |
31
- | this model, B5 fresh check (39 layouts, never seen) | 1.05 % (MAE 0.132 fF / RMSE 0.188 fF) |
32
- | B5: physics alone C^R = R(1.5, 3) | 1.765 % (MAE 0.275 fF / RMSE 0.376 fF) |
33
- | paper's version, validation (4,608 layouts) | 0.229 % (MAE 0.0674 fF / RMSE 0.0792 fF) |
34
- | paper's version, test in family (4,009) | 0.177 % (MAE 0.0203 fF / RMSE 0.025 fF) |
35
- | paper's version, test zero-shot macro (1,878) | 0.587 % (MAE 1.092 fF / RMSE 1.152 fF) |
36
- | paper's version, held-out family (4,071) | 0.408 % (MAE 0.049 fF / RMSE 0.059 fF) |
37
 
38
- Time: x86 cluster node, 2 CPUs: 0.845 / 5.96 s in family, 1.75 / 18.1 s zero-shot (median / p90; x86 cluster, 2 CPUs); B5 0.99 s median (1.14 s on the 2026-10-20 re-run, Xeon E5-2640 v4). HF Space (2 vCPU): interdigital 0.47 s, xmon 0.91 s, 1-qubit lattice (N 15) 19.0 s, 16-conductor layout 9.9 s, 9-qubit lattice (N 67) 154 s (server time, one request, Docker build 2026-10-20; a repeated request is answered from the cache in ~0.01 s). SQuADDS package (median per layout, cold caches, warm numba; 2 / 8 threads): GH200 (aarch64) N<=4 1.88 / 0.98 s, N 5-9 6.41 / 3.42 s, N 10-20 23.0 / 10.5 s, N 35 22.0 / 9.5 s; x86 Xeon Silver 4116 N<=4 3.76 / 3.10 s, N 5-9 13.35 / 9.60 s, N 10-20 46.2 / 29.2 s, N 35 44.6 / 24.9 s. The first call of a session also loads the model and compiles the solver (about 40 s once); a repeated layout is answered from the cache in milliseconds.
39
 
40
- ## Fast
 
 
41
 
42
- This is an improved release of the paper's fast model: the same architecture, a surrogate trained on more generated layouts and networks retrained on every labelled design, the paper's test split included. Paper's version: the surrogate t100_norm (385,593 generated layouts + the TRAIN geometry) with networks trained on the 35,354 TRAIN layouts only. Its held-out numbers below belong to that version, not to this release.
43
 
44
- | set | median % (MAE / RMSE) |
45
- |---|---|
46
- | this model, in-sample (all 45,771 training layouts; it was trained on them) | 0.671 % (MAE 0.353 fF / RMSE 0.395 fF) |
47
- | this model, B5 fresh check (39 layouts, never seen) | 3.175 % (MAE 0.583 fF / RMSE 0.824 fF) |
48
- | B5: physics alone C^R = R(1.5, 3) (Fast is behind the physics here) | 1.765 % (MAE 0.275 fF / RMSE 0.376 fF) |
49
- | this surrogate recipe trained without the validation layouts, with the paper's TRAIN-only networks, validation (4,608, held out) | 0.722 % (MAE 0.387 fF / RMSE 0.436 fF) |
50
- | paper's version, validation (4,608 layouts) | 0.846 % (MAE 0.491 fF / RMSE 0.549 fF) |
51
- | paper's version, test in family (4,009) | 0.63 % (MAE 0.113 fF / RMSE 0.1414 fF) |
52
- | paper's version, test zero-shot macro (1,878) | 3.576 % (MAE 4.608 fF / RMSE 5.058 fF) |
53
- | paper's version, held-out family (4,071) | 3.113 % (MAE 0.533 fF / RMSE 0.633 fF) |
54
- | paper's version, held-out family: physics alone | 1.554 % (MAE 0.166 fF / RMSE 0.205 fF) |
55
-
56
- Time: x86 cluster node, 2 CPUs: 0.091 / 0.274 s in family, 0.30 / 2.45 s zero-shot (median / p90; x86 cluster, 2 CPUs); B5 0.24 s median. HF Space (2 vCPU): interdigital 0.036 s, xmon 0.11 s, 1-qubit lattice (N 15) 0.82 s, 16-conductor layout 0.49 s, 9-qubit lattice (N 67) 3.9 s (server time, one request, Docker build 2026-10-20; a repeated request is answered from the cache in ~0.01 s). SQuADDS package (median per layout, cold caches, warm numba; 2 / 8 threads): GH200 (aarch64) N<=4 0.093 / 0.084 s, N 5-9 0.25 / 0.20 s, N 10-20 0.32 / 0.34 s, N 35 0.82 / 0.59 s; x86 Xeon Silver 4116 N<=4 0.17 / 0.22 s, N 5-9 0.33 / 0.30 s, N 10-20 0.53 / 0.56 s, N 35 2.21 / 1.96 s. The first call of a session also loads the model (and the embedding code compiles once).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
57
 
58
  ## Files
59
 
 
 
60
  | file | sha256 |
61
  |---|---|
62
  | `accurate/acc_v2m_sf_s0.pt` | `cc69c5818f5028c26177159b88239116520abbb290743d6a6c091657e8dbf1c5` |
63
  | `accurate/acc_v2m_sf_s1.pt` | `2f88606dbec5c599550d088213a4c37af3b3ad5134ebad2e60519fb534553a57` |
64
  | `accurate/acc_v2m_sf_s2.pt` | `d13bafc6b2eb7cadcd97a387d791c0210976db1a9d618f9acc1b614e3701daed` |
 
 
 
65
  | `fast/acc_v1_s0.pt` | `9dff20ade26619e7713c2d145dada65e4554a623780290673cfe9452cf9b64ba` |
66
  | `fast/acc_v1_s1.pt` | `f1ad2ca065dd650ccabcad73a3c6ad2ac1042f4f68bb828893bbdecc47411ffe` |
67
  | `fast/acc_v1_s2.pt` | `8cbada211724df5cc05a7b4fdd232607de047b248a43993d3844bd68ff8060c4` |
68
  | `fast/sall_all_s0.pt` | `132d6f389eda798d31bd5654a96e24cce18fa750134a9fb2a9725eafed339dac` |
69
-
70
- Units and conventions: fF; the full N x N Maxwell matrix of every conductor the layout has (nets are never merged), ground
71
- first (row/column 0), diagonal = self, off-diagonal = -mutual. Trained on Si (eps_r 11.45), 350 µm substrates, zero-thickness
72
- metal; ground on GDS layer 1/0, conductors on 1/10 (configurable).
73
-
74
- Other substrates (`predict(..., eps_r=, thickness_um=)`; the route is recorded in `result.substrate`): Accurate and the paper
75
- model solve the physics prior at the requested stack and the unchanged networks correct it (embedding at the training stack).
76
- On the 15 held-out designs of the stack study (paper model, Q3D at each stack) this gave 0.21-1.02 % (MAE 0.07-0.33 fF,
77
- RMSE 0.09-0.45 fF) on every tested stack: Si 10 µm 0.69 % (0.115 / 0.164 fF), fused silica 0.64 % (0.071 / 0.093 fF),
78
- sapphire (eps_r 10.34) 0.26 % (0.076 / 0.106 fF), GaAs (eps_r 12.9) 0.22 % (0.086 / 0.120 fF), LaAlO3 (eps_r 24)
79
- 0.23 % (0.161 / 0.219 fF); the fixed-stack prediction was 76.6 % (13.7 / 18.8 fF) at 10 µm Si and 162.9 %
80
- (23.4 / 30.5 fF) on fused silica. A bounded error, not training-stack accuracy (0.23 % (0.080 / 0.111 fF)): worse than
81
- permittivity rescaling for small capacitors (interdigital, paddle) at 50-200 µm (interdigital 50 µm 1.39 % (0.098 / 0.114 fF) vs
82
- 0.53 % (0.043 / 0.045 fF)), on
83
- thick Si (1000 µm 0.65 % (0.325 / 0.451 fF) vs 0.50 % (0.187 / 0.245 fF)) and for self terms (0.96-1.22 %, MAE 0.48-0.79,
84
- RMSE 0.52-0.86 fF at 10-50 µm Si, vs 0.24 % (0.18 / 0.22 fF)). Tested: Si at 10-1000 µm, or eps_r 3.8-24 at 350 µm; other
85
- combinations warn. Cost: one prior pair per stack (median 1.33 s, max 37 s) + 0.1 s network (HPC x86, AMD EPYC, 2 threads).
86
- Fast cannot solve a prior: off the stack it rescales its training-stack prediction by (1 + eps_r) / (1 + 11.45) (thickness not
87
- modelled) and warns on every call; Fast itself was not scored off the stack (rescaling alone, with the paper model's networks:
88
- ties the training stack for eps_r 9.7-12.9 at 350 µm (sapphire 0.32 % (0.091 / 0.126 fF), GaAs 0.21 % (0.085 / 0.117 fF)), 1.41 % (0.223 / 0.309 fF) on fused silica, 76.6 % (13.7 / 18.8 fF) at
89
- 10 µm Si).
90
-
91
- Metric: layout-mean median relative error over mutual entries against Q3D (0.1 fF floor), with MAE / RMSE in fF.
92
-
93
- Integrity: SQuADDS pins a revision of this repository and checks the sha256 of every file against the manifest shipped in the
94
- package (`squadds/ml/capacitance/manifest.json`); see `SHA256SUMS`.
95
-
96
- Prior stack (Accurate): `v2m_sf_fc_dipfill_margin_slabfar` (corrected prior with substrate far field, compiled exact solver). Physics priors computed on macOS differ from the HPC x86 ones by up to ~2.4e-3 relative.
 
2
  license: mit
3
  library_name: pytorch
4
  tags: [superconducting-qubits, capacitance, electrostatics, gds, graph-neural-network, squadds]
5
+ datasets:
6
+ - SQuADDS/SQuADDS_PlanarCapacitance
7
  ---
8
 
9
+ <center>
10
+ <img src="https://github.com/LFL-Lab/SQuADDS/blob/master/docs/_static/images/squadds_logo_dark_name.png?raw=true" width="80%" alt="SQuADDS logo" />
11
+ </center>
12
 
13
+ # PlanarCapacitance-flagship: our model trained on all of our Q3D data
14
+
15
+ The model of our paper *A physics-corrected graph neural network for the capacitance matrix of any planar superconducting circuit layout*, trained on all 45,771 designs of our Q3D dataset, the test designs included. It reads a GDS layout and returns the full Maxwell capacitance matrix of every conductor in it. Because it has seen the test designs, it has no held-out score of its own. For held-out numbers see the [paper model](https://huggingface.co/SQuADDS/PlanarCapacitance-paper).
16
+
17
+ - **Paper page** (videos and tutorials): [lfl-lab.github.io/SQuADDS/paper](https://lfl-lab.github.io/SQuADDS/paper/)
18
+ - **Paper:** arXiv link added at publication
19
+ - **Code:** [github.com/LFL-Lab/SQuADDS](https://github.com/LFL-Lab/SQuADDS)
20
+ - **Data:** [Q3D dataset](https://huggingface.co/datasets/SQuADDS/SQuADDS_PlanarCapacitance) and [synthetic dataset](https://huggingface.co/datasets/SQuADDS/SQuADDS_PlanarCapacitance-Synthetic)
21
+ - **Models:** [paper model](https://huggingface.co/SQuADDS/PlanarCapacitance-paper) and [flagship models](https://huggingface.co/SQuADDS/PlanarCapacitance-flagship)
22
+ - **Try it:** [Planar Capacitance Model Space](https://huggingface.co/spaces/shanto268/PlanarCapacitanceModel)
23
+ - **Point of contact:** [Sadman Ahmed Shanto](mailto:shanto@usc.edu)
24
+
25
+ ## Usage
26
 
27
  ```python
28
  from squadds.ml.capacitance import CapacitancePredictor, load_model
29
+
30
+ res = CapacitancePredictor(load_model("flagship")).predict("chip.gds") # Accurate
31
+ fast = CapacitancePredictor(load_model("fast")).predict("chip.gds") # Fast
32
  res.names, res.matrix_fF, res.to_sim_results()
33
  ```
34
 
35
+ ## Tiers
 
 
 
36
 
37
+ This repository holds all three tiers in `accurate/`, `balanced/` and `fast/`. SQuADDS loads Accurate and Fast, and the [Space](https://huggingface.co/spaces/shanto268/PlanarCapacitanceModel) serves all three.
38
 
39
+ | tier | how it works | error on 39 new layouts, % (MAE / RMSE, fF) | median time |
40
+ |---|---|---|---|
41
+ | Accurate (default) | the extrapolated prior from two coarse method-of-moments solves, corrected by the networks | 1.05 (0.132 / 0.188) | 1.1 s |
42
+ | Balanced | the same recipe on two coarser solves | 2.044 (0.258 / 0.348) | 0.56 s |
43
+ | Fast | a learned prior replaces the solves, then the networks correct it | 3.175 (0.583 / 0.824) | 0.24 s |
44
 
45
+ The 39 layouts are generated rings with a neighbour (3 or 4 conductors) that no part of any tier saw in training. On them the extrapolated prior alone scores 1.765 % (MAE 0.275 / RMSE 0.376 fF). Times are on two CPUs of an Intel Xeon E5-2640 v4 cluster node.
46
 
47
+ Fast is for quick screening of the component families it was trained on. Use Accurate otherwise.
 
 
 
 
 
 
 
 
48
 
49
+ ## Conventions
50
 
51
+ - Capacitance is in fF. Ground is row and column 0, and nets are never merged.
52
+ - Trained on a 350 µm silicon substrate (eps_r 11.45) with zero-thickness metal. Accurate takes other substrates with `predict(..., eps_r=..., thickness_um=...)`, as in Sec. IV C of the paper. Fast only rescales by permittivity there and warns.
53
+ - Ground on GDS layer 1/0 and conductors on 1/10 by default. Every result carries its physical checks, and a failed check is raised as a warning.
54
 
55
+ ## Citation
56
 
57
+ If you use these data or models, please cite our paper and SQuADDS.
58
+
59
+ ```bibtex
60
+ @article{Shanto2026planarcapacitance,
61
+ title = {A physics-corrected graph neural network for the capacitance matrix of any planar superconducting circuit layout},
62
+ author = {Shanto, Sadman Ahmed and Das, Saikat and Levenson-Falk, Eli},
63
+ journal = {arXiv preprint},
64
+ year = {2026},
65
+ note = {arXiv identifier added at publication}
66
+ }
67
+
68
+ @article{Shanto2024squaddsvalidated,
69
+ doi = {10.22331/q-2024-09-09-1465},
70
+ url = {https://doi.org/10.22331/q-2024-09-09-1465},
71
+ title = {{SQ}u{ADDS}: {A} validated design database and simulation workflow for superconducting qubit design},
72
+ author = {Shanto, Sadman and Kuo, Andre and Miyamoto, Clark and Zhang, Haimeng and Maurya, Vivek and Vlachos, Evangelos and Hecht, Malida and Shum, Chung Wa and Levenson-Falk, Eli},
73
+ journal = {{Quantum}},
74
+ issn = {2521-327X},
75
+ publisher = {{Verein zur F{\"{o}}rderung des Open Access Publizierens in den Quantenwissenschaften}},
76
+ volume = {8},
77
+ pages = {1465},
78
+ month = sep,
79
+ year = {2024}
80
+ }
81
+ ```
82
+
83
+ ## Licence
84
+
85
+ MIT.
86
 
87
  ## Files
88
 
89
+ SQuADDS checks every file against the manifest in the package (`squadds/ml/capacitance/manifest.json`).
90
+
91
  | file | sha256 |
92
  |---|---|
93
  | `accurate/acc_v2m_sf_s0.pt` | `cc69c5818f5028c26177159b88239116520abbb290743d6a6c091657e8dbf1c5` |
94
  | `accurate/acc_v2m_sf_s1.pt` | `2f88606dbec5c599550d088213a4c37af3b3ad5134ebad2e60519fb534553a57` |
95
  | `accurate/acc_v2m_sf_s2.pt` | `d13bafc6b2eb7cadcd97a387d791c0210976db1a9d618f9acc1b614e3701daed` |
96
+ | `balanced/bal_v2m_sf_s0.pt` | `aa742ab93b1e3ffcd86a753bda5cc4a68812acbe8140a6b0e311c11d1f36b4b2` |
97
+ | `balanced/bal_v2m_sf_s1.pt` | `486466473eba61c090f4e3fa7988bf880fc183570c5d02bd78f4c1356691f926` |
98
+ | `balanced/bal_v2m_sf_s2.pt` | `1b55ded04fd624585eeeccf2ab6e4a8e9354a9b96694131e1737dde43ad3ff58` |
99
  | `fast/acc_v1_s0.pt` | `9dff20ade26619e7713c2d145dada65e4554a623780290673cfe9452cf9b64ba` |
100
  | `fast/acc_v1_s1.pt` | `f1ad2ca065dd650ccabcad73a3c6ad2ac1042f4f68bb828893bbdecc47411ffe` |
101
  | `fast/acc_v1_s2.pt` | `8cbada211724df5cc05a7b4fdd232607de047b248a43993d3844bd68ff8060c4` |
102
  | `fast/sall_all_s0.pt` | `132d6f389eda798d31bd5654a96e24cce18fa750134a9fb2a9725eafed339dac` |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
SHA256SUMS CHANGED
@@ -5,3 +5,6 @@ d13bafc6b2eb7cadcd97a387d791c0210976db1a9d618f9acc1b614e3701daed accurate/acc_v
5
  f1ad2ca065dd650ccabcad73a3c6ad2ac1042f4f68bb828893bbdecc47411ffe fast/acc_v1_s1.pt
6
  8cbada211724df5cc05a7b4fdd232607de047b248a43993d3844bd68ff8060c4 fast/acc_v1_s2.pt
7
  132d6f389eda798d31bd5654a96e24cce18fa750134a9fb2a9725eafed339dac fast/sall_all_s0.pt
 
 
 
 
5
  f1ad2ca065dd650ccabcad73a3c6ad2ac1042f4f68bb828893bbdecc47411ffe fast/acc_v1_s1.pt
6
  8cbada211724df5cc05a7b4fdd232607de047b248a43993d3844bd68ff8060c4 fast/acc_v1_s2.pt
7
  132d6f389eda798d31bd5654a96e24cce18fa750134a9fb2a9725eafed339dac fast/sall_all_s0.pt
8
+ aa742ab93b1e3ffcd86a753bda5cc4a68812acbe8140a6b0e311c11d1f36b4b2 balanced/bal_v2m_sf_s0.pt
9
+ 486466473eba61c090f4e3fa7988bf880fc183570c5d02bd78f4c1356691f926 balanced/bal_v2m_sf_s1.pt
10
+ 1b55ded04fd624585eeeccf2ab6e4a8e9354a9b96694131e1737dde43ad3ff58 balanced/bal_v2m_sf_s2.pt
balanced/bal_v2m_sf_s0.pt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:aa742ab93b1e3ffcd86a753bda5cc4a68812acbe8140a6b0e311c11d1f36b4b2
3
+ size 8410606
balanced/bal_v2m_sf_s1.pt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:486466473eba61c090f4e3fa7988bf880fc183570c5d02bd78f4c1356691f926
3
+ size 8410606
balanced/bal_v2m_sf_s2.pt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:1b55ded04fd624585eeeccf2ab6e4a8e9354a9b96694131e1737dde43ad3ff58
3
+ size 8410606