Quantum Metal (formerly: Qiskit Metal)

Quantum Metal is an open-source framework for engineers and scientists to design superconducting quantum devices with ease.

New in v0.8.1: the desktop GUI canvas is now directly editable — click a component to select it, move and rotate it with the keyboard, rebuild to re-route connected CPWs (selection survives). See the GUI Navigation & Shortcuts docs page.

🚀 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 lite-by-default install (v0.7.0, shipped), the AI-orchestration profile, the open FEM stack (gmsh + Elmer + AWS Palace), and the upcoming import-path rename.

---

Install

pip install quantum-metal             # lite (v0.7.0+ default)
pip install "quantum-metal[full]"     # everything (v0.6.x compatibility)

Pick the install command that matches your workflow:

	What you get	When
🪶 Lite pip install quantum-metal	Core API, qm.view(design) headless viewer, GDS export, pure-Python analyses	AI orchestration, Colab / Binder, cloud Jupyter, CI, any non-interactive workflow
🖥️ GUI pip install "quantum-metal[gui]"	+ MetalGUI desktop app (PySide6, qdarkstyle)	Interactive design work
🧲 Ansys pip install "quantum-metal[ansys]"	+ HFSS / Q3D renderers, EPR analyses (pyaedt, pyEPR-quantum)	HFSS / Q3D simulation (Windows + Ansys AEDT license)
🔺 Open FEM mesher pip install "quantum-metal[mesh]"	+ gmsh meshing (foundation for Elmer / Palace)	Open-source FEM (no Ansys license). [fem] is a backward-compat alias.
📦 Full pip install "quantum-metal[full]"	All of the above	Migrating from v0.6.x, want zero behavior change

Extras compose: pip install "quantum-metal[gui,ansys]" works.

	lite	[gui]	[ansys]	[mesh]	[full]
import qiskit_metal	✅	✅	✅	✅	✅
qm.view(design) (headless matplotlib)	✅	✅	✅	✅	✅
Build designs + components from qlibrary	✅	✅	✅	✅	✅
GDS export	✅	✅	✅	✅	✅
LOManalysis, LOM math, capacitance reductions	✅	✅	✅	✅	✅
MetalGUI desktop app	—	✅	—	—	✅
HFSS / Q3D renderers	—	—	✅	—	✅
EPR analyses (EigenmodeSim, LumpedElementsSim)	—	—	✅	—	✅
gmsh mesher (for Elmer / Palace)	—	—	—	✅	✅

[fem] is a backward-compatible alias of [mesh] — both install gmsh.

Source install, conda, troubleshooting, and per-persona migration recipes: docs/installation.rst · docs/migration-to-v0.7.0.rst.

CI runs on Python 3.10 / 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")

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: browse the tutorial notebooks (40+ Jupyter notebooks covering the full API) or the online documentation.

---

Transition notices

• ✅ 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 emits a FutureWarning today.

---

🌐 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.

Built on Quantum Metal

• 🔬 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.

Solvers Quantum Metal integrates with

AWS Palace (roadmap) · Ansys HFSS/Q3D (via [ansys]) · Elmer FEM (via [mesh]) · gmsh (via [mesh]).

Quantization & analysis

pyEPR · scqubits · QuTiP.

Community organization & events

• Quantum Device Workshop (QDW) — annual workshop at UCLA/USC with invited leaders in the field. Recent speakers: Michel Devoret, Andreas Wallraff, Zlatko Minev, Eli Levenson-Falk. Video recordings · Sign for 2026.
• Quantum Device Consortium (QDC) — the community organization stewarding Quantum Metal alongside the tools above. Join the QDC Discord.

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

• 💬 Discord — fastest way to reach maintainers and the broader community. Primary community channel.
• 📺 YouTube video tutorials
• 💻 GitHub Issues — bugs and feature requests
• 🟪 Qiskit Slack #metal — legacy channel, being phased out in favor of Discord

---

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 · 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