The SQuADDS (Superconducting Qubit And Device Design and Simulation) Database Project is an open-source resource aimed at advancing research in superconducting quantum device designs. It provides a robust workflow for generating and simulating superconducting quantum device designs, facilitating the accurate prediction of Hamiltonian parameters across a wide range of design geometries.
SQuADDS also predicts the full Maxwell capacitance matrix of any planar superconducting circuit layout straight from its GDS file. The models behind this are physics-corrected graph neural networks trained on our Q3D dataset, and they run on your own machine in about a second per layout.
SQuADDS Paper Link: SQuADDS: A Database for Superconducting Quantum Device Design and Simulation
QCap Paper Link: QCap: a physics-corrected graph neural network for the capacitance matrix of any planar superconducting device layout
QCap Paper Page: https://lfl-lab.github.io/SQuADDS/qcap/, with the explainer videos and the tutorials
Docsite Link: https://lfl-lab.github.io/SQuADDS/
Hugging Face Links: SQuADDS database, planar capacitance dataset, planar capacitance models, all SQuADDS models
Browser Demo: https://huggingface.co/spaces/SQuADDS/planar-capacitance (upload a GDS, get its capacitance matrix)
Contribution Portal Link: https://squadds-portal.vercel.app
Chat with the Codebase: https://deepwiki.com/LFL-Lab/SQuADDS/1-overview
- Citation
- Installation
- Tutorials
- MCP Server (AI Agent Integration)
- ML Models
- Contributing
- License
- FAQs
- Contact
- Contributors
- Developers
If SQuADDS helps your research, please support its continued development and maintenance by citing the paper: Shanto et al., Quantum 8, 1465 (2024). If you use QCap (the planar capacitance models or their dataset), please also cite Shanto, Das and Levenson-Falk (2026).
@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}
}
@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},
eprint = {2611.22057},
archivePrefix = {arXiv},
primaryClass = {quant-ph},
url = {https://arxiv.org/abs/2611.22057}
}SQuADDS needs Python 3.11 or newer (we test 3.11, 3.12 and 3.13). It uses uv for fast, reliable Python package management.
Install uv (if you don't have it already):
curl -LsSf https://astral.sh/uv/install.sh | shgit clone https://github.com/LFL-Lab/SQuADDS.git
cd SQuADDS
uv syncVerify the installation:
uv run python -c "import squadds; print(squadds.__file__)"pip install SQuADDSInstall GDS processing tools:
uv sync --extra gdsInstall the planar capacitance models (PyTorch, gdstk and the physics prior):
uv sync --extra mlor, with pip:
pip install "squadds[ml]"Install documentation tools:
uv sync --extra docsInstall development tools:
uv sync --extra devInstall contribution tools (for contributing data to SQuADDS):
uv sync --extra contribInstall all optional dependencies:
uv sync --all-extrasTo use SQuADDS in Jupyter notebooks (including VS Code/Cursor), register the kernel:
uv sync --extra dev # Installs ipykernel
uv run python -m ipykernel install --user --name squadds --display-name "SQuADDS (uv)"Then select "SQuADDS (uv)" as your kernel in Jupyter/VS Code/Cursor.
Click to expand/hide Docker instructions
We provide a pre-built Docker image that contains all dependencies, including Qiskit-Metal and the latest SQuADDS release.
You can pull the latest image of SQuADDS from GitHub Packages:
docker pull ghcr.io/lfl-lab/squadds_env:latestIf you'd like to pull a specific version (support begins from v0.3.4 onwards), use the following command:
docker pull ghcr.io/lfl-lab/squadds_env:v0.3.4You can find all available versions and tags for the squadds_env Docker image on LFL-Lab Packages.
After pulling the image, you can run the container using:
docker run -it ghcr.io/lfl-lab/squadds_env:latest /bin/bashThis will give you access to a bash shell inside the container.
Inside the container, activate the squadds-env environment:
conda activate squadds-envOnce the environment is active, you can run SQuADDS by executing your Python scripts or starting an interactive Python session.
The following tutorials are available to help you get started with SQuADDS:
- Tutorial 0: Using the SQuADDS WebUI
- Tutorial 1: Getting Started with SQuADDS
- Tutorial 2: Simulating Interpolated Designs
- Tutorial 3: Contributing Experimentally-Validated Simulation Data to the SQuADDS Database
- Tutorial 4: Contributing Measured Devices' Data to the SQuADDS Database
- Tutorial 5: Designing a "fab-ready" chip with SQuADDS
- Tutorial 6: Adding Airbridges
- Tutorial 7: Simulate designs with palace
- Tutorial 8: ML Interpolation in SQuADDS
- Tutorial 9: HFSS Driven-Modal Capacitance Extraction
- Tutorial 10: Unified Driven-Modal Hamiltonian Extraction
- Tutorial 11: Predicting Capacitance Matrices from a GDS
- Tutorial 12: Planar Capacitance Families in SQuADDS
- Tutorial 13: From Layout to Hamiltonian with ML
- Tutorial 14: Training on Your Own Designs
- Tutorial 15: Contributing Capacitance Data and Models
- Tutorial 16: Inverse Design by ML Screening
SQuADDS includes a built-in Model Context Protocol (MCP) server that lets AI coding agents interact with the entire database — searching designs, interpolating parameters, and exploring components — through a standardized protocol.
If you're using an AI coding assistant, just paste this prompt to have it set up SQuADDS MCP for you:
Click to copy the agent setup prompt
I need you to set up the SQuADDS MCP server so I can access the superconducting
qubit design database through you. Here's what to do:
1. Clone the repo and install:
git clone https://github.com/LFL-Lab/SQuADDS.git
cd SQuADDS
uv sync --extra mcp --extra ml
(drop `--extra ml` if you don't need the planar capacitance models)
2. Add the MCP server to your config. The command to run the server is:
uv run --directory /path/to/SQuADDS squadds-mcp
3. Once connected, read the `squadds://guide` resource for a quick overview
of available tools.
The server exposes these key tools:
- `list_components` / `list_datasets` — explore the database
- `find_closest_designs` — find designs matching target Hamiltonian parameters
- `interpolate_design` — get physics-interpolated designs
- `get_hamiltonian_param_keys` — discover valid search parameters
- `predict_capacitance_from_gds` — full Maxwell capacitance matrix of a GDS layout
(read `squadds://planar-capacitance-guide` first)
- `capacitance_to_hamiltonian` — E_C, qubit frequency, anharmonicity and g from a matrix
- `query_planar_capacitance` / `nearest_planar_capacitance_designs` — the planar
capacitance dataset
- `list_hosted_ml_models` / `predict_with_hosted_ml_model` — models on the hosted API
Typical target parameter ranges:
- qubit_frequency_GHz: 3–8
- anharmonicity_MHz: −500 to −50
- cavity_frequency_GHz: 5–12
- kappa_kHz: 10–1000
- g_MHz: 10–200
Please set this up and confirm you can access the SQuADDS tools.
git clone https://github.com/LFL-Lab/SQuADDS.git
cd SQuADDS
uv sync --extra mcp# stdio mode (for local AI assistants)
uv run squadds-mcp
# HTTP mode (for networked/remote usage)
SQUADDS_MCP_TRANSPORT=streamable-http uv run squadds-mcpClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}Claude Code
claude mcp add squadds -- uv run --directory /path/to/SQuADDS squadds-mcpCursor
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}VS Code (Copilot)
Add to .vscode/settings.json:
{
"mcp": {
"servers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}
}Antigravity (Gemini)
Add to ~/.gemini/settings.json (or project-level .gemini/settings.json):
{
"mcpServers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}OpenAI Codex CLI
codex --mcp-config mcp.jsonWith mcp.json:
{
"mcpServers": {
"squadds": {
"command": "uv",
"args": ["run", "--directory", "/path/to/SQuADDS", "squadds-mcp"]
}
}
}Full MCP documentation: MCP_README.md | Developer guide: MCP_DEVELOPER_GUIDE.md
SQuADDS has two groups of machine-learning models today: the planar capacitance models and the TransmonCross Hamiltonian-to-geometry model. Each is described below in the same order: what it does, how to run it locally and on our hosted API, its accuracy and time, and where to read more. The hosted API they share comes after both.
Given a GDS layout, the model predicts the full N x N Maxwell capacitance matrix (fF, ground first) of every conductor in it. We infer the conductors from the layout and never merge nets, so N can be anything. A thin-film physics solve gives a first estimate, and graph neural networks trained on our Q3D dataset correct it. There are two models: QCap (the default) for accuracy and QCap-Fast, which skips the physics solve, for quick screening. They were built by Sadman Ahmed Shanto, Saikat Das and Eli Levenson-Falk.
pip install "squadds[ml]"from squadds.ml.capacitance import CapacitancePredictor, load_model
res = CapacitancePredictor(load_model("QCap")).predict("chip.gds") # or "QCap-Fast"
res.names, res.matrix_fF, res.checks, res.timing_s # also res.to_sim_results() for squadds.calcssquadds-ml predict chip.gds # CSV matrix; --model QCap-Fast, --format json, --threads N
squadds-ml train --data shards/ --out runs/ --seeds 0,1,2 # retrain (paper recipe); --slurm job.sh writes an array scriptIt runs on a CPU and uses all your cores by default (threads= or --threads to limit), about a second per layout on a laptop. The package also gives you:
- the physics priors on their own:
physics_priorandoptimized_physics_prior - the dataset:
PlanarCapacitanceDB, also part ofSQuADDS_DB()as theplanar_capacitancesource (SQuADDS_DB(sources=("default",))gives the original database alone) - Q3D-shaped results inside the usual workflows:
MLSimulatorandAnalyzer.predict_capacitance, from which the TransmonPocket and Xmon Hamiltonians follow - retraining on your own designs:
fit_in_familyandretrain_collective - contributing data and models:
validate_capacitance_contribution,contribute_capacitanceandcontribute_model
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"}'from squadds.ml import client
res = client.predict("qcap", file="chip.gds") # or "qcap-fast"
res["outputs"]["names"], res["outputs"]["matrix_fF"]Or upload a GDS to the browser demo.
Inputs, outputs and limits
- Input: the GDS file as the multipart field
file, or base64 encoded ininputs.file_base64of a JSON body. The optional inputs areground_layerandconductor_layer(1/0and1/10by default), the substrate'seps_randthickness_um(11.45 and 350 µm), andground_pieceswhen ground and conductors share a layer. - Outputs:
names(G first, then C1..Cn in file order),matrix_fF(the N x N Maxwell matrix in fF, ground first) andsim_results(the shapeSQuADDS_DBuses). - Limits: up to 70 conductors plus ground and 20 MB per file. The API runs on free, shared Hugging Face compute (two shared vCPUs, one prediction at a time), so large layouts take minutes. On your own machine the same models use all your cores and have no conductor limit, which is what we recommend.
| model | median error on a family it has never seen (MAE / RMSE) | time per layout (median, x86, 2 CPUs) |
|---|---|---|
QCap (default) |
1.05 % (0.132 / 0.188 fF) | 0.845 s |
QCap-Fast |
3.175 % (0.583 / 0.824 fF) | 0.091 s |
Both models are trained on all of our data. The error is the median relative error of the mutual capacitances on 39 layouts of a family that no part of either model saw in training (rings with a neighbour, 3 or 4 conductors). On that family QCap-Fast does worse than the physics prior alone, 1.765 % (0.275 / 0.376 fF), so use it only to screen the families it was trained on. The scores per family are in the ML Models guide and the paper.
- Models: SQuADDS/QCap
- Dataset: SQuADDS/SQuADDS_PlanarCapacitance
- Browser demo: SQuADDS/planar-capacitance
- Guide: ML Models, and Tutorials 11-16 above
- Paper: QCap: a physics-corrected graph neural network for the capacitance matrix of any planar superconducting device layout, with explainer videos on the paper page
Given a target qubit frequency and anharmonicity, the model returns the TransmonCross (qubit-claw) geometry that gives them: the claw length, the claw's ground spacing and the cross length, in meters. Feed those straight into SQuADDS / Qiskit Metal downstream flows. It was developed in collaboration with Taylor Patti, Nicola Pancotti, Enectali Figueroa-Feliciano, Sara Sussman, Abhishek Chakraborty, Olivia Seidel, Firas Abouzahr, Eli Levenson-Falk and Sadman Ahmed Shanto, with Olivia Seidel and Firas Abouzahr as the primary trainers.
The Keras checkpoint, its scalers and inference_manifest.json (input and output order, units) are in the model repo:
huggingface-cli download SQuADDS/transmon-cross-hamiltonian-inverse --local-dir transmon-cross-hamiltonian-inversecurl -X POST \
https://squadds-squadds-ml-inference-api.hf.space/v1/models/transmon_cross_hamiltonian_inverse/predict \
-H 'Content-Type: application/json' \
-d '{"inputs":{"qubit_frequency_GHz":4.85,"anharmonicity_MHz":-205.0}}'from squadds.ml import client
res = client.predict("transmon_cross_hamiltonian_inverse",
inputs={"qubit_frequency_GHz": 4.85, "anharmonicity_MHz": -205.0})
res["outputs"]["predictions"][0] # claw_length, ground_spacing, cross_length in metersInputs, outputs and limits
- Inputs:
qubit_frequency_GHz,anharmonicity_MHz. - Outputs (SI units, meters):
design_options.connection_pads.readout.claw_length,design_options.connection_pads.readout.ground_spacing,design_options.cross_length. - Full contract, sample response and manifest: the model repo README and the Space README.
Its accuracy is reported in the paper.
- Paper: Component-Level Inverse Design of Transmon Qubits Using Neural Networks (Seidel et al., 2026)
- Model: SQuADDS/transmon-cross-hamiltonian-inverse
- Training data: the
qubit-TransmonCross-cap_matrixconfiguration of SQuADDS_DB - Guide: ML Models
The SQuADDS ML inference API serves the models we host on our Hugging Face org over HTTP. It runs in the SQuADDS ML Inference API Space at https://squadds-squadds-ml-inference-api.hf.space. Every model sits behind the same routes:
| route | what it returns |
|---|---|
GET /v1/models |
the models you can call (id, family, input_kind, revision, status). This list is the source of truth for what is available |
GET /v1/models/{model_id} |
the model's contract: input and output names, units, limits, an example request |
GET /v1/models/{model_id}/schema |
the JSON schema of the request. ?format=tool returns a tool definition for an AI agent (name, description, input_schema) |
POST /v1/models/{model_id}/predict |
the prediction: JSON {"inputs": {...}, "options": {...}}, or multipart (file + inputs) for models that take a file |
GET /v1/health, GET /docs, GET /openapi.json |
status, interactive docs, OpenAPI spec |
An AI agent uses the same routes. It lists the models, fetches /v1/models/{model_id}/schema?format=tool, registers the result as a tool and POSTs its arguments to /v1/models/{model_id}/predict. The MCP server does this for you with list_hosted_ml_models and predict_with_hosted_ml_model. The legacy routes GET /health, GET /models and POST /predict (body {"model_id", "inputs"}) still work, with their original shapes.
We will add more models. To add your own, push its weights to a Hugging Face model repository and open an issue or pull request on SQuADDS/squadds-ml-inference-api. A model of an existing family needs only one registry entry (pinned weights and an example request). A new kind of model needs one adapter class, as described in Contributing a model.
We welcome contributions from the community! Here is what you can contribute and how:
- Simulation data for the SQuADDS database: follow Tutorial 3, or upload your files on our web portal.
- Measured device data: follow Tutorial 4.
- Capacitance data: Maxwell matrices from Q3D or any other solver, with the GDS of each layout.
validate_capacitance_contributionchecks them, andcontribute_capacitanceopens a pull request on the planar capacitance dataset. Tutorial 15 walks through it. - Capacitance models:
contribute_modelvalidates your model and opens a pull request that adds it to our model registry, also in Tutorial 15. To serve a model on the hosted API, see Adding a model. - Code, documentation and bug reports: see our Contributing Guidelines and our work wish list, or open an issue.
- Compute: we also ask for compute (simulation licences, CPU and GPU time) to grow the datasets and retrain the models. If you can offer some, please contact elevenso@usc.edu.
Absolutely feel free to reach out to us if you have any questions.
This project is licensed under the MIT License - see the LICENSE file for details.
Check out our FAQs for common questions and answers. The ones we hear most:
- Which Python do I need? Python 3.11 or newer (we test 3.11, 3.12 and 3.13).
- Do the capacitance models need a GPU? No.
pip install "squadds[ml]"and they run on a CPU, about a second per layout on a laptop. QCaporQCap-Fast?QCapfor anything that matters.QCap-Fastis only for screening the families it was trained on.- How large a chip can I predict? Locally there is no conductor limit, and SQuADDS uses all your cores by default (
threads=or--threadsto limit). The browser demo and hosted API run on free, shared Hugging Face compute, so they take up to 70 conductors plus ground (API, 20 MB per file) and fewer than 70 conductors with the ground (demo). - How do I get the original database without the planar capacitance data?
SQuADDS_DB(sources=("default",)).
For inquiries or support, please contact Sadman Ahmed Shanto.
| Name | Institution | Contribution |
|---|---|---|
| Clark Miyamoto | New York University | Code contributor |
| Madison Howard | California Institute of Technology | Bug Hunter |
| Evangelos Vlachos | University of Southern California | Code contributor |
| Kaveh Pezeshki | Stanford University | Documentation contributor |
| Anne Whelan | US Navy | Documentation contributor |
| Jenny Huang | Columbia University | Documentation contributor |
| Connie Miao | Stanford University | Data Contributor |
| Malida Hecht | University of Southern California | Data contributor |
| Daria Kowsari, PhD | University of Southern California | Data contributor |
| Vivek Maurya | University of Southern California | Data contributor |
| Haimeng Zhang, PhD | IBM | Data contributor |
| Elizabeth Kunz | University of Southern California | Documentation and Code contributor |
| Adhish Chakravorty | University of Southern California | Documentation and Code contributor |
| Ethan Zheng | University of Southern California | Data contributor and Bug Hunter |
| Sara Sussman, PhD | Fermilab | Bug Hunter |
| Priyangshu Chatterjee | IIT Kharagpur | Documentation contributor |
| Abhishek Chakraborty | Rigetti Computing | Code contributor |
| Saikat Das | University of Southern California | Data contributor and Reviewer |
| Firas Abouzahr | Northwestern | Bug Hunter |
- shanto268 - 475 contributions
- elizabethkunz - 17 contributions
- LFL-Lab - 9 contributions
- NxtGenLegend - 1 contributions
- ethanzhen7 - 1 contributions
- PCodeShark25 - 1 contributions
