quantum-metal 0.7.0

Quantum Metal (formerly Qiskit Metal) | for quantum device design & analysis

Quantum Metal (formerly: Qiskit Metal)

Discord

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

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 pip install "quantum-metal[fem]"	+ gmsh meshing, Elmer FEM	Open-source FEM (no Ansys license needed)
📦 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.

Feature matrix — what each install gives you

	lite	[gui]	[ansys]	[fem]	[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 / Elmer mesher	—	—	—	✅	✅

Full migration recipes (per persona) live in docs/migration-to-v0.7.0.rst.

⚠️ Transition notices

v0.5 → v0.7 (in progress, mostly complete). The project is mid-rebrand from Qiskit Metal to Quantum Metal:

• ✅ New project name: Quantum Metal
• ✅ PyPI package: quantum-metal (the new canonical wheel; the old qiskit-metal package stays archived at its pre-0.5 state)
• ✅ GitHub continuity: same repo, issues, stars, forks, history
• 🔜 Repository rename to quantum-metal: scheduled — will keep redirects so existing clones / links continue to work
• 🔜 Python import path rename (qiskit_metal → quantum_metal): scheduled for a future major release (target v0.8 or v1.0). Plan to update your imports ahead of that release. A FutureWarning fires on import qiskit_metal advertising this.

Suppress the rename warning with QISKIT_METAL_SUPPRESS_RENAME_WARNING=1 until you're ready to migrate.

🌐 Part of the Quantum Device Design Ecosystem

Quantum Metal has graduated from being an IBM maintained project and is now one of the core tools in a growing community ecosystem for superconducting quantum device design and education, including:

• Quantum Device Workspace (QDW) – https://qdw-ucla.squarespace.com/ Hosted annually at UCLA/USC with invited leaders in the field. Recent speakers include: Michel Devoret, Andreas Wallraff, Zlatko Minev, Eli Levenson-Falk. Video recordings

  Sign for 2026 to meet the community, learn from experts, and participate directly.*

• Quantum Device Consortium (QDC) — an upcoming community organization that will maintain and evolve Quantum Metal as part of a shared ecosystem of tools (including SQUADDS, SQDMetal, scqubits, pyEPR, and many others). (Website and governance page) Discord Channel here

🌱 From IBM to a Community-Maintained Project

Originally developed at IBM, originated by Dr. Zlatko K. Minev, Qiskit Metal has, over the last two years, naturally transitioned into a community-driven project supported by multiple universities, research groups, labs, and individual contributors.

This v0.5 release marks the formal graduation into that next phase of the project’s life.

Development continues through the QDC, the community, and active maintainers, working in close collaboration with Zlatko Minev and contributors across QDW/QDC who are shaping this next chapter.

---

🙏 BIG THANK YOU to Community Contributors (PR #1002)

This release is the result of a substantial collective effort. Our deepest thanks go to:

Sadman Ahmed Shanto, Abhishek Chakraborty, PositroniumJS, SamWolski, Nicolas Dirnegger, Eli Levenson-Falk, and Murat Can Sarıhan

for their extensive testing, debugging, patching, platform validation, and contributions to the massive PySide6 transition in PR #1002.

We are grateful to all users, contributors, and maintainers who continue to move the project forward.

Installation

During the transition to Quantum Metal, the package is still published on PyPI under the legacy name qiskit-metal until the import path is updated in a follow-up release. The instructions below ensure users can install the new v0.5 release while keeping compatibility.

If you prefer installing from source or contributing, please follow the developer installation guide in the documentation and/or the developer README.

Installing the Current Release (v0.5)

Quantum Metal is now available on PyPI:
pip install quantum-metal
Project page: https://pypi.org/project/quantum-metal/

If you prefer installing from source, clone and install locally (steps below). Continuous integration runs on Python 3.10, 3.11 and 3.12 across Linux (Ubuntu 24.04), macOS 15, and Windows, plus separate jobs for lint and docs. Sticking to those versions mirrors the CI-tested setup; on Ubuntu you may need extra system libs for Gmsh (see CI script).

Key notes to keep in mind:

• Python 3.10/3.11/3.12 mirror the CI matrix.
• macOS ARM users should avoid Python 3.12+ to prevent C/C++ toolchain errors.
• uv is the preferred and fastest method and avoids most scientific‑stack headaches.

Preferred: uv (fast, modern, reliable)

First install uv, then clone the repository, use Python 3.11, set up the virtual environment, then install requirements and Quantum Metal.

• macOS / Linux (bash):

  # Install uv on linux/macOS
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # Clone the repository
  git clone https://github.com/qiskit-community/qiskit-metal.git quantum-metal
  # Change to the repository directory
  cd quantum-metal
  # Create a new virtual environment
  uv venv --python 3.11  # could also be 3.10 or 3.12
  # Install the package in editable mode
  uv pip install -e .
  # Activate the virtual environment
  source .venv/bin/activate
  

• Windows (PowerShell):

  # install uv on Windows 
  iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex
  # Clone the repository
  git clone https://github.com/qiskit-community/qiskit-metal.git quantum-metal
  # Change to the repository directory
  cd quantum-metal
  # Create a new virtual environment
  uv venv --python 3.11  # could also be 3.10 or 3.12
  # Install the package in editable mode
  uv pip install -e .
  # Activate the virtual environment
  .\.venv\Scripts\Activate.ps1
  

On Ubuntu you may need system packages for Gmsh/Qt (see CI: libglu1-mesa, libegl1-mesa-dev), and on Windows/macOS ensure build tools/CLT are present if you add native extensions.

Option 2: Conda (best for binary-heavy scientific stacks)

  # Clone the repository
  git clone https://github.com/qiskit-community/qiskit-metal.git quantum-metal
  # Change to the repository directory
  cd quantum-metal
  # Create a new conda environment
  conda create -n quantum-metal -f environment.yml python=3.11 
  # activate the conda environment
  conda activate quantum-metal
  # Install the package in editable mode 
  python -m pip install --no-deps -e .

Option 3: Standard venv (simple, lightweight)

First, ensure that Python 3.11 is installed on your system. You may also use Python 3.10 or 3.12.

# Create a new virtual environment
python3.11 -m venv qm_env
# Activate the virtual environment
source qm_env/bin/activate
# Upgrade pip to the latest version
pip install --upgrade pip
# Install the package in editable mode (with its dependencies)
pip install -e .

Using Jupyter Notebook

We recommend using Jupyter Notebook/Lab to access the full GUI and interactive features. If Jupyter is not installed in your environment, install it with:

pip install jupyterlab

If needed, add your environment as a Jupyter kernel:

python -m ipykernel install --user --name quantum-metal

Quick Start: Creating Your First Quantum Component in Quantum Metal:

Now that Quantum Metal is installed, it's time to begin working with it. We are ready to try out a quantum chip example, which is simulated locally using the Quantum Metal GUI element. This is a simple example that makes a qubit.

Install note: the example below uses MetalGUI, which requires PySide6. Install with:

pip install "quantum-metal[gui]"

Prefer no-Qt? Replace gui = MetalGUI(design) and the gui.rebuild() / gui.autoscale() calls with fig = qm.view(design) — see docs/headless-usage.rst. The headless path also covers AI-orchestration / Colab / Binder / cloud-Jupyter use cases.

from qiskit_metal import designs, MetalGUI, open_docs, draw

# Start a planar-chip quantum device design
design = designs.DesignPlanar()
design.chips.main.size.size_x = '11mm'
design.chips.main.size.size_y = '9mm'
print(design.chips.main)

# Launch the Qiskit Metal GUI to interactively view, edit, and simulate the design
gui = MetalGUI(design)

# Create a new qubit form the library, a transmon, by creating an object of this class.
from qiskit_metal.qlibrary.qubits.transmon_pocket import TransmonPocket
# Let's also add a connector pad, called "a" with default options, you can overwrite them as dictionary keys
q1 = TransmonPocket(design, 'Q1', options=dict(connection_pads=dict(a=dict())))

# To see qubit, rebuild the design with this new qubit in place
gui.rebuild()
# Select for editing, highlight, and autoscale gui view
gui.edit_component('Q1')
gui.autoscale()

# Change options.
q1.options.pos_x      = '0.5 mm'
q1.options.pos_y      = '0.25 mm'
q1.options.pad_height = '90um'
q1.options.pad_width  = '455um'
q1.options.pad_gap    = '30 um'

# Update the component geometry after changing the options.
gui.rebuild()
gui.autoscale()

Get a list of all the qcomponents in QDesign and then zoom on them.

all_component_names = design.components.keys()
gui.zoom_on_components(all_component_names)

Closing the Qiskit Metal GUI.

>>> gui.main_window.close()

A script is available here, where we also show the overview of Qiskit Metal.

Community and Support

Watch the recorded tutorials

The streaming will also be recorded and made available here for offline review.

Take part in the live tutorials and discussion

Through June 2021 we are offering live tutorials and Q&A. Sign up to receive an invite to the upcoming sessions. The streaming will also be recorded and made available for offline review. Find here more details on schedule and use the Slack channel to give us feedback and to request the most relevant content to you.

Get help: Slack

Use the slack channel. Join qiskit slack and then join the #metal channel to communicate with the developers and other participants. You may also use this channel to inquire about collaborations.

Contribution Guidelines

If you'd like to contribute to Qiskit Metal, please take a look at our contribution guidelines. This project adheres to Qiskit's code of conduct. By participating, you are expected to uphold this code. We use GitHub issues for tracking requests and bugs. Please join the Qiskit Slack community and use our Qiskit Slack channel for discussion and simple questions. For questions that are more suited for a forum we use the Qiskit tag in the Stack Exchange.

Next Steps

Now you're set up and ready to check out some of the other examples from our Qiskit Metal Tutorials repository or Qiskit Metal Documentation.

---

Big Picture Architecutre Overview

Diagram

The Qiskit Metal codebase is organized into several key modules, each with a distinct role in enabling the design, analysis, and visualization of quantum circuits. Below is an overview of the primary components and their interactions, discussed deeper in the Architecture Readme and the docs:

   %%{init: {"flowchart": {"htmlLabels": true}, 'theme':'forest'} }%%
    graph TB
        classDef core fill:#87cefa,stroke:#000000;
        classDef gui fill:#FFDDC1,stroke:#000000;
        classDef renderer fill:#DBB9FF,stroke:#000000;
        classDef utility fill:#FFD700,stroke:#000000;
        classDef design fill:#90EE90,stroke:#000000;
        classDef analysis fill:#FFB6C1,stroke:#000000;

        subgraph Qiskit_Metal
            subgraph Core
                QLibraryComponents["QLibrary Components"]
                QDesign["QDesign"]
                QComponent["QComponent"]
                QRoute["QRoute"]
                BaseQubit["BaseQubit"]
            end

            subgraph GUI
                MetalGUI["MetalGUI"]
            end

            subgraph Renderers
                QRenderer["QRenderer"]
                QRendererGui["QRendererGui"]
                QGDSRenderer["QGDSRenderer"]
                QAnsysRenderer["QAnsysRenderer"]
                QHFSSRenderer["QHFSSRenderer"]
                QQ3DRenderer["QQ3DRenderer"]
                QPyaedt["QPyaedt"]
                QGmshRenderer["QGmshRenderer"]
                QElmerRenderer["QElmerRenderer"]
            end

            subgraph Analyses
                Hamiltonian["Hamiltonian"]
                Sweep_Options["Sweep_Options"]
            end

            subgraph Utilities
                Parsing["Parsing"]
                Exceptions["Exceptions"]
                Logging["Logging"]
                Toolbox["Toolbox"]
            end
        end

        QLibraryComponents --> QDesign
        QRenderer --> QDesign
        QRendererGui --> QRenderer
        MetalGUI --> QRendererGui
        MetalGUI --> QLibraryComponents
        MetalGUI --> QDesign
        QGDSRenderer --> QRenderer
        QAnsysRenderer --> QRenderer
        QHFSSRenderer --> QRenderer
        QQ3DRenderer --> QRenderer
        QPyaedt --> QRenderer
        QGmshRenderer --> QRenderer
        QElmerRenderer --> QRenderer
        Parsing --> QDesign
        Exceptions --> QDesign
        Logging --> QDesign
        Toolbox --> QDesign
        QDesign --> QComponent
        QDesign --> QRoute
        QDesign --> BaseQubit
        Hamiltonian --> QDesign
        Sweep_Options --> QDesign

        class QLibraryComponents,QDesign,QComponent,QRoute,BaseQubit core;
        class MetalGUI gui;
        class QRenderer,QRendererGui,QGDSRenderer,QAnsysRenderer,QHFSSRenderer,QQ3DRenderer,QPyaedt,QGmshRenderer,QElmerRenderer renderer;
        class Parsing,Exceptions,Logging,Toolbox utility;
        class Hamiltonian,Sweep_Options analysis;

Core

The Core module serves as the backbone of Qiskit Metal, housing essential elements for design and component creation:

• QLibrary Components: Predefined library of quantum circuit elements, such as qubits and resonators, that can be used in designs.
• QDesign: The central design framework that integrates all components and handles design rules.
• QComponent: Base class for all components in the design.
• QRoute: Specialized class for managing connections between components.
• BaseQubit: Represents foundational qubit structures used in circuit designs.

Renderers

The Renderers module facilitates exporting designs to external tools for electromagnetic simulation and layout rendering:

• QRenderer: Base class for all renderers.
• QRendererGui: GUI interface for managing renderers.
• Specialized renderers like:
  • QGDSRenderer
  • QAnsysRenderer
  • QHFSSRenderer
  • QQ3DRenderer
  • QPyaedt
  • QGmshRenderer
  • QElmerRenderer

These renderers enable integration with industry-standard tools for detailed simulation and fabrication.

Analyses

The Analyses module includes tools for performing simulations and extracting insights from designs:

• Hamiltonian: Supports calculations of Hamiltonian parameters.
• Sweep Options: Provides tools for parametric sweeps and optimizations.

GUI

The GUI module provides tools for user-friendly interaction with Qiskit Metal. The MetalGUI clas is the primary graphical interface for managing designs and visualizations. It is discussed in more depth in the Architecture Readme.

Utilities

The Utilities module supports the overall functionality of Qiskit Metal by offering supplementary tools.

Key Interactions

• The Core modules form the foundation and integrate tightly with the Renderers, GUI, and Analyses modules.
• The GUI depends on the Core and Renderers to provide visualization and interactivity.
• The Renderers serve as bridges between Qiskit Metal and external tools, interacting with the Core to export designs.
• The Analyses modules leverage the Core to extract meaningful data for optimization and validation.
• The Utilities modules provide essential supporting functionalities across the entire codebase.

This modular structure ensures scalability, flexibility, and ease of use for designing, analyzing, and fabricating quantum circuits.

---

Backmatter

Authors and Citation

Qiskit Metal is the work of many people who contribute to the project at different levels. Metal was conceived and developed by Zlatko Minev at IBM; then co-led with Thomas McConkey. If you use Qiskit Metal, please cite as per the included BibTeX file. For icon attributions, see here.

Changelog and Release Notes

The changelog provides a quick overview of notable changes for a given release.

The changelog for a particular release can be found in the correspondent Github release page. For example, you can find the changelog for the 0.0.4 release here

The changelog for all releases can be found in the release page:

Additionally, as part of each release detailed release notes are written to document in detail what has changed as part of a release. This includes any documentation on potential breaking changes on upgrade and new features.

License

Apache License 2.0