|
Download README.md from SQuADDS/QCap: direct link, hf CLI and curl.
- Browser
- Download file 7.73 kB
-
https://huggingface.co/SQuADDS/QCap/resolve/main/README.md
- Command line
-
hf download hf://SQuADDS/QCap/README.md
-
curl -L -o README.md https://huggingface.co/SQuADDS/QCap/resolve/main/README.md
7.73 kB
| 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` | | |