File size: 7,726 Bytes
ff01de7
 
 
 
87bceec
 
ff01de7
 
87bceec
b2217a5
 
 
87bceec
ff01de7
25bdbb1
87bceec
3f5dbec
87bceec
d768a06
19980dd
87bceec
19980dd
25bdbb1
19980dd
87bceec
 
 
ff01de7
 
 
87bceec
25bdbb1
 
ff01de7
 
 
a5aa5b8
 
e408746
a5aa5b8
25bdbb1
 
 
a5aa5b8
 
25bdbb1
a5aa5b8
 
 
 
 
 
25bdbb1
a5aa5b8
 
 
 
 
 
 
25bdbb1
a5aa5b8
 
 
 
 
 
 
 
 
 
 
19b551b
ff01de7
25bdbb1
ff01de7
19b551b
87bceec
25bdbb1
 
 
ff01de7
19b551b
ff01de7
25bdbb1
ff01de7
87bceec
ff01de7
87bceec
25bdbb1
87bceec
ff01de7
87bceec
ff01de7
87bceec
 
 
19980dd
3f5dbec
87bceec
 
19980dd
87bceec
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ff01de7
 
 
87bceec
 
ff01de7
 
25bdbb1
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
---
license: mit
library_name: pytorch
tags: [superconducting-qubits, capacitance, electrostatics, gds, graph-neural-network, squadds]
datasets:
- SQuADDS/SQuADDS_PlanarCapacitance
---

<center>
  <img class="block dark:hidden" src="https://huggingface.co/SQuADDS/QCap/resolve/main/assets/qcap_horizontal_light.png" width="360" alt="QCap" />
  <img class="hidden dark:block" src="https://huggingface.co/SQuADDS/QCap/resolve/main/assets/qcap_horizontal_dark.png" width="360" alt="QCap" />
  <p>Part of <a href="https://github.com/LFL-Lab/SQuADDS">SQuADDS</a></p>
</center>

# QCap: our model trained on all of our Q3D data

The model of our paper *QCap: a physics-corrected graph neural network for the capacitance matrix of any planar superconducting device 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. Its held-out accuracy, from the same model trained without the test designs, is in the paper.

- **Paper page:** [lfl-lab.github.io/SQuADDS/ml-paper](https://lfl-lab.github.io/SQuADDS/ml-paper/), with the explainer videos and the [tutorials](https://lfl-lab.github.io/SQuADDS/ml-paper/#tutorials)
- **Paper:** [lfl-lab.github.io/SQuADDS/ml-paper/paper](https://lfl-lab.github.io/SQuADDS/ml-paper/paper/)
- **Code:** [github.com/LFL-Lab/SQuADDS](https://github.com/LFL-Lab/SQuADDS)
- **Data:** [Q3D dataset](https://huggingface.co/datasets/SQuADDS/SQuADDS_PlanarCapacitance) and [synthetic dataset](https://huggingface.co/datasets/SQuADDS/SQuADDS_PlanarCapacitance-Synthetic), part of the [SQuADDS datasets](https://huggingface.co/collections/SQuADDS/squadds-datasets-6a65152b857f8efa5620880a)
- **Models:** [QCap models](https://huggingface.co/SQuADDS/QCap) (QCap, QCap-Lite and QCap-Fast), part of the [SQuADDS models](https://huggingface.co/collections/SQuADDS/squadds-models-6af8b7da67a22df62af374c6)
- **API:** [SQuADDS ML inference API](https://huggingface.co/spaces/SQuADDS/squadds-ml-inference-api)
- **Point of contact:** [Sadman Ahmed Shanto](mailto:shanto@usc.edu)

## Usage

```python
from squadds.ml.capacitance import CapacitancePredictor, load_model

res = CapacitancePredictor(load_model("QCap")).predict("chip.gds")        # QCap
fast = CapacitancePredictor(load_model("QCap-Fast")).predict("chip.gds")  # QCap-Fast
res.names, res.matrix_fF, res.to_sim_results()
```

## Hosted API

The [SQuADDS ML inference API](https://huggingface.co/spaces/SQuADDS/squadds-ml-inference-api) serves these models over HTTP as `qcap` (QCap) and `qcap-fast` (QCap-Fast).

- `GET /v1/models/qcap` describes the model, with its inputs, limits and an example.
- `GET /v1/models/qcap/schema?format=tool` gives a ready tool definition for AI agents.
- `POST /v1/models/qcap/predict` takes the GDS file as the multipart field `file`, or base64 encoded in `inputs.file_base64` of a JSON body. The optional inputs are `ground_layer` and `conductor_layer` (`1/0` and `1/10` by default), `eps_r` and `thickness_um` (11.45 and 350 µm), and `ground_pieces` when ground and conductors share a layer.

```bash
curl -X POST https://squadds-squadds-ml-inference-api.hf.space/v1/models/qcap/predict \
  -F file=@chip.gds -F 'inputs={"ground_layer": "1/0", "conductor_layer": "1/10"}'
```

```python
from squadds.ml import client

r = client.predict("qcap", file="chip.gds")
r["outputs"]["names"], r["outputs"]["matrix_fF"]
```

The response for the interdigital example layout:

```json
{
  "model_id": "qcap",
  "outputs": {
    "names": ["G", "C1", "C2"],
    "matrix_fF": [[31.727, -4.264, -5.711], [-4.264, 6.598, -2.285], [-5.711, -2.285, 8.045]],
    "units": "fF",
    "convention": "Maxwell matrix, ground first (row and column 0), nets never merged"
  }
}
```

The API takes up to 70 conductors plus ground and 20 MB per file. It runs one prediction at a time on two shared vCPUs, so large layouts take minutes. The full list of hosted models is at `GET /v1/models`.

## Models

This repository holds all three models in `qcap/`, `qcap-lite/` and `qcap-fast/`. SQuADDS loads QCap and QCap-Fast.

| model | how it works | error on 39 new layouts, % (MAE / RMSE, fF) | median time |
|---|---|---|---|
| QCap (default) | the extrapolated prior from two coarse method-of-moments solves, corrected by the networks | 1.05 (0.132 / 0.188) | 1.1 s |
| QCap-Lite | the same recipe on two coarser solves | 2.044 (0.258 / 0.348) | 0.56 s |
| QCap-Fast | a learned prior replaces the solves, then the networks correct it | 3.175 (0.583 / 0.824) | 0.24 s |

The 39 layouts are generated rings with a neighbour (3 or 4 conductors) that no part of any model 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.

QCap-Fast is for quick screening of the component families it was trained on. Use QCap otherwise.

## Conventions

- Capacitance is in fF. Ground is row and column 0, and nets are never merged.
- Trained on a 350 µm silicon substrate (eps_r 11.45) with zero-thickness metal. QCap takes other substrates with `predict(..., eps_r=..., thickness_um=...)`, as in Sec. IV C of the paper. QCap-Fast only rescales by permittivity there and warns.
- 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.

## Citation

If you use these data or models, please cite our paper and SQuADDS.

```bibtex
@misc{Shanto2026planarcapacitance,
  title   = {{QCap}: a physics-corrected graph neural network for the capacitance matrix of any planar superconducting device layout},
  author  = {Shanto, Sadman Ahmed and Das, Saikat and Levenson-Falk, Eli},
  year    = {2026},
  url     = {https://lfl-lab.github.io/SQuADDS/ml-paper/paper/}
}

@article{Shanto2024squaddsvalidated,
  doi = {10.22331/q-2024-09-09-1465},
  url = {https://doi.org/10.22331/q-2024-09-09-1465},
  title = {{SQ}u{ADDS}: {A} validated design database and simulation workflow for superconducting qubit design},
  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},
  journal = {{Quantum}},
  issn = {2521-327X},
  publisher = {{Verein zur F{\"{o}}rderung des Open Access Publizierens in den Quantenwissenschaften}},
  volume = {8},
  pages = {1465},
  month = sep,
  year = {2024}
}
```

## Licence

MIT.

## Files

SQuADDS checks every file against the manifest in the package (`squadds/ml/capacitance/manifest.json`).

| file | sha256 |
|---|---|
| `qcap/acc_v2m_sf_s0.pt` | `cc69c5818f5028c26177159b88239116520abbb290743d6a6c091657e8dbf1c5` |
| `qcap/acc_v2m_sf_s1.pt` | `2f88606dbec5c599550d088213a4c37af3b3ad5134ebad2e60519fb534553a57` |
| `qcap/acc_v2m_sf_s2.pt` | `d13bafc6b2eb7cadcd97a387d791c0210976db1a9d618f9acc1b614e3701daed` |
| `qcap-lite/bal_v2m_sf_s0.pt` | `aa742ab93b1e3ffcd86a753bda5cc4a68812acbe8140a6b0e311c11d1f36b4b2` |
| `qcap-lite/bal_v2m_sf_s1.pt` | `486466473eba61c090f4e3fa7988bf880fc183570c5d02bd78f4c1356691f926` |
| `qcap-lite/bal_v2m_sf_s2.pt` | `1b55ded04fd624585eeeccf2ab6e4a8e9354a9b96694131e1737dde43ad3ff58` |
| `qcap-fast/acc_v1_s0.pt` | `9dff20ade26619e7713c2d145dada65e4554a623780290673cfe9452cf9b64ba` |
| `qcap-fast/acc_v1_s1.pt` | `f1ad2ca065dd650ccabcad73a3c6ad2ac1042f4f68bb828893bbdecc47411ffe` |
| `qcap-fast/acc_v1_s2.pt` | `8cbada211724df5cc05a7b4fdd232607de047b248a43993d3844bd68ff8060c4` |
| `qcap-fast/sall_all_s0.pt` | `132d6f389eda798d31bd5654a96e24cce18fa750134a9fb2a9725eafed339dac` |