

Quantum Metal is an open-source framework for engineers and scientists to design superconducting quantum devices with ease.
Regenerate this GIF · Full tutorial: 2.21
Quick start ·
How do I...? ·
Component catalog ·
Tutorials ·
Scripting and agent use
What’s new (v0.9.0 to v0.10.1, see the release notes):
- Open-source simulation: a gmsh + scikit-fem Maxwell solver (
qiskit_metal.analyses.fem) and tutorials 4.41–4.46 on package modes and qubit couplings, with no Ansys license.
- Design-rule checks:
validate(design) with shape rules and waivers; a GDS layer-properties file and starter rule deck for KLayout.
- Scripting:
python -m qiskit_metal.watch my_design.py re-runs a script on save and renders the chip; repeatable GDS export with SOURCE_DATE_EPOCH.
- Docs: a component catalog with default options and pins for every component, a task-organized How do I…? page, and a simulation pathways guide.
- Python 3.11 to 3.14 and numpy 2; many fixes to the analytic formulas, GDS export and routing (see Behavior changes in the changelog).
🚀 Try it now — zero install

One click → working Quantum Metal in your browser in 60 seconds (lite install, no Qt required).
📍 Where we’re heading: see ROADMAP.md for the open FEM
stack (ElmerFEM eigenmodes, a scikit-fem renderer, AWS Palace), solver
backends, more design-rule checks, and the planned import-path rename.
Install
pip install quantum-metal # lite: no Qt, no Ansys, no gmsh
pip install "quantum-metal[gui]" # + the desktop GUI
| Install |
What you get |
When |
pip install quantum-metal |
Core API, qm.view(design) headless viewer, GDS export, design-rule checks, pure-Python analyses |
Scripts, AI orchestration, Colab / Binder, CI |
"quantum-metal[gui]" |
+ MetalGUI desktop app (PySide6) |
Interactive design |
"quantum-metal[ansys]" |
+ HFSS / Q3D renderers, EPR (pyaedt, pyEPR-quantum) |
Ansys simulation (Ansys Electronics Desktop license) |
"quantum-metal[mesh]" |
+ gmsh meshing for ElmerFEM ([fem] is an alias) |
Open-source capacitance simulation |
"quantum-metal[skfem]" |
[mesh] + the scikit-fem solver (add pymetis for tutorial 4.46) |
Open-source eigenmodes and couplings, tutorials 4.41–4.46 |
"quantum-metal[full]" |
GUI, Ansys and mesh together |
Everything |
Extras compose: pip install "quantum-metal[gui,ansys]" works. Which extra to
choose is explained on the
simulation pathways
page.
Source install, conda, the full feature matrix and troubleshooting:
docs/installation.rst and the
FAQ.
CI runs on Python 3.11 / 3.12 / 3.13 / 3.14 across Linux, macOS, and Windows.
Quick Start
Create your first quantum design in a notebook or script — no Qt required:
import qiskit_metal as qm
from qiskit_metal import designs
from qiskit_metal.qlibrary.qubits.transmon_pocket import TransmonPocket
# Start a planar-chip quantum device design
design = designs.DesignPlanar()
design.chips.main.size.size_x = '11mm'
design.chips.main.size.size_y = '9mm'
# Add a transmon qubit with a connector pad "a"
q1 = TransmonPocket(design, 'Q1', options=dict(
pos_x='0.5 mm', pos_y='0.25 mm',
pad_height='90um', pad_width='455um', pad_gap='30um',
connection_pads=dict(a=dict()),
))
# Render to an inline matplotlib figure — works in Colab, CI, any notebook
fig = qm.view(design)
fig.savefig("my_first_chip.png")

Prefer the interactive desktop GUI?
Install with pip install "quantum-metal[gui]", then replace the qm.view(...)
line with the GUI flow:
from qiskit_metal import MetalGUI
gui = MetalGUI(design) # launch the interactive editor
gui.rebuild() # re-render after edits
gui.edit_component('Q1') # select for editing
gui.autoscale()
# ... later
gui.main_window.close()
See docs/headless-usage.rst for the full
no-Qt workflow and what to use when.
Stability: the GUI self-heals after a crashed launch (startup journal),
and window layout is no longer auto-restored by default — the historical
source of the “kernel appears to have died” crashes
(#1048).
See the FAQ
for the related environment switches.
Next: pick a goal on Choose your path, browse the tutorial notebooks (about 95 Jupyter notebooks
from first steps to solver tutorials) or the
online documentation.
Transition notices
Qiskit Metal → Quantum Metal rebrand (in progress)
- ✅ New project name: Quantum Metal
- ✅ PyPI package:
quantum-metal (current; the old qiskit-metal package
stays archived at its pre-v0.5 state)
- ✅ Lite-by-default install (v0.7.0)
- 🔜 Repository rename to
quantum-metal — will keep redirects so existing
clones and links continue to work
- 🔜 Python import path rename (
qiskit_metal → quantum_metal) — planned,
no release set. import qiskit_metal stays valid until then.
🌐 Ecosystem
Quantum Metal is the open-source chip-design layer for superconducting
quantum hardware. A growing community of tools builds on it, extends it
with new simulation backends, and plugs into it for quantization and
discovery. Full map: docs…/ecosystem.
- 🔬 SQuADDS (LFL-Lab @ USC) —
validated qubit-design database + parameter interpolation. Published
in Quantum journal (Sept 2024).
- 🧲 SQDMetal (SQDLab @ UQ) —
simulation wrapper for
QDesign → AWS Palace / COMSOL.
- 🤖 ML_qubit_design
(Fermilab + Northwestern) — ML-based inverse design predicting Quantum
Metal parameters from target qubit properties.
- ⚗️ Qiskit-Metal-to-Litho
(Onri Jay Benally) — end-to-end design → lithography workflow with
headless Colab install scripts, GDS post-processing (PHIDL / GDSTK),
EBPG / BEAMER fab prep, and 3D Blender viz. Real fabricated chip examples.
- 🌐 pypalace (Northwestern) —
Python toolkit for AWS Palace with Quantum Metal gmsh export.
AWS Palace (roadmap) ·
Ansys HFSS/Q3D
(via [ansys]) · Elmer FEM (via [mesh]) ·
gmsh (via [mesh]).
Quantization & analysis
pyEPR ·
scqubits ·
QuTiP.
Building something on Quantum Metal? Open an issue
or ping us on Discord — we’d love to add you to the list.
🌱 From IBM to a Community-Maintained Project
Originally developed at IBM, conceived and led by Dr. Zlatko K. Minev,
Quantum Metal has transitioned into a community-driven project supported by
universities, research groups, labs, and individual contributors worldwide.
Development continues through the Quantum Device Consortium (QDC), the
broader community, and active maintainers — in close collaboration with Zlatko
Minev and contributors across QDW/QDC shaping this next chapter.
Acknowledgements for the v0.5+ community release effort and ongoing
contributors are tracked in the changelog and the
contributors graph.
Community and Support
Contributing
If you’d like to contribute, please read the
contribution guidelines
and the contributor guide in the docs.
This project adheres to the code of conduct.
We use GitHub issues
for bugs and feature requests.
Architecture
For a high-level walkthrough of the codebase — Core, Renderers, Analyses, GUI,
Utilities — and how they interact, see
docs/architecture.rst.
Module-level deep dive:
docs/overview.rst (API summary and package map) ·
docs/workflow.rst.
Authors and Citation
Quantum Metal is the work of many people
who contribute to the project at different levels. The project was conceived
and developed by Zlatko Minev at IBM, then
co-led with Thomas McConkey, and has since transitioned to community maintenance
through the QDC.
If you use Quantum Metal in your research, please cite it — see the
BibTeX entry.
Changelog and Release Notes
Release notes for each version are published on the
GitHub releases page.
Developer notes for in-flight releases live in changelog.md.
License
Apache License 2.0
评论