# qiskit-community/qiskit-metal architecture

> Architecture diagram of the GitHub repository qiskit-community/qiskit-metal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qiskit-community/qiskit-metal
- Repository: https://github.com/qiskit-community/qiskit-metal

## Overview

##### Project type and purpose
- Qiskit Metal is an open-source Python framework for designing superconducting quantum devices.
- It provides a core “Design” engine for chip layouts and quantum components (QComponents), a GUI front end, a suite of rendering back-ends (GDS, Ansys, Elmer, Gmsh, Matplotlib), and analysis modules (EM solvers, Hamiltonian models, quantization, sweeps).

##### File structure
- Top-level directories:
– qiskit_metal/           ← main Python package
– docs/, tutorials/      ← static documentation and Jupyter tutorials
– qiskit_metal/tests/    ← unit and integration tests
– .github/, CI configs  ← GitHub Actions, linting, release workflows
- Inside qiskit_metal/:
– designs/                ← base Design class plus planar, flip-chip, multilayer variants
– analyses/               ← modules for EM calculations, quantization, Hamiltonian analysis, sweep & optimization
– renderers/              ← exporter plug-in layers for GDS, Ansys (HFSS/Q3D via pyaedt), Elmer, Gmsh, Matplotlib
– config.py, setup.py      ← configuration and packaging
- Patterns:
– Plugin/Factory: renderers and analysis back-ends are discovered via setup_default or entry points.
– MVC-ish: GUI acts as View/Controller, Design object is Model.
– Separation of concerns: core engine, UI, libraries, external interfaces.

##### README for additional insights
- Emphasizes the “DesignPlanar” core, MetalGUI, and a workflow: define design → instantiate QComponents → launch GUI → render/export → analyze.
- Lists supported back-ends (GDS, HFSS, Q3D, Elmer, Gmsh) and primary dependencies (PySide2/6, geopandas, numpy, matplotlib, pyaedt).
- Points to tutorials showcasing rendering, analysis, and component creation.

##### Detail
- How Toolbox modules feed into both Core and Rendering layers
- Default config and entry points (setup_default.py) as part of the plugin discovery mechanism
- Do not hesitate to break into as many components as needed to convey separation of concerns and extension points

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        User["User"]:::external
    end

    subgraph "GUI Layer"
        GUI["MetalGUI"]:::gui
    end
    click GUI "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/_gui/"

    subgraph "Core Engine"
        DM["Design Manager"]:::core
        QCF["QComponent Factory"]:::core
        GH["Geometry Handler"]:::core
        Config["Config & Defaults"]:::core
    end
    click DM "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/designs/"
    click QCF "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/qlibrary/"
    click GH "https://github.com/qiskit-community/qiskit-metal/blob/main/qiskit_metal/qgeometries/qgeometries_handler.py"
    click Config "https://github.com/qiskit-community/qiskit-metal/blob/main/qiskit_metal/config.py"

    subgraph "Rendering Layer"
        GDS["GDS Renderer"]:::renderer
        ANS["Ansys Renderer"]:::renderer
        ELM["Elmer Renderer"]:::renderer
        GMSH["Gmsh Renderer"]:::renderer
        MPL["Matplotlib Renderer"]:::renderer
    end
    click GDS "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/renderers/renderer_gds/"
    click ANS "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/renderers/renderer_ansys/"
    click ELM "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/renderers/renderer_elmer/"
    click GMSH "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/renderers/renderer_gmsh/"
    click MPL "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/renderers/renderer_mpl/"

    subgraph "Analysis Layer"
        EM["EM Calculations"]:::analysis
        QUANT["Quantization"]:::analysis
        HAM["Hamiltonian Analysis"]:::analysis
        SIM["Simulations"]:::analysis
        SWEEP["Sweep & Optimization"]:::analysis
    end
    click EM "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/analyses/em/"
    click QUANT "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/analyses/quantization/"
    click HAM "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/analyses/hamiltonian/"
    click SIM "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/analyses/simulation/"
    click SWEEP "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/analyses/sweep_and_optimize/"

    subgraph "Utilities"
        DRAW["Draw Utilities"]:::util
        TMB["Toolbox Metal"]:::util
        TBP["Toolbox Python"]:::util
    end
    click DRAW "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/draw/"
    click TMB "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/toolbox_metal/"
    click TBP "https://github.com/qiskit-community/qiskit-metal/tree/main/qiskit_metal/toolbox_python/"

    subgraph "External Services"
        AnsysExt["Ansys"]:::external
        GmshExt["Gmsh"]:::external
        ElmerExt["Elmer"]:::external
        FileOut[(File Outputs)]:::persistent
    end

    User -->|"interact"| GUI
    GUI -->|"commands"| DM
    DM -->|"instantiate"| QCF
    DM -->|"handle geometry"| GH
    DRAW --> DM
    TMB --> DM
    TBP --> DM

    GH -->|"layout data"| GDS
    GH -->|"layout data"| ANS
    GH -->|"layout data"| ELM
    GH -->|"layout data"| GMSH
    GH -->|"layout data"| MPL

    GDS --> FileOut
    ANS --> AnsysExt
    ELM --> ElmerExt
    GMSH --> GmshExt
    MPL --> FileOut

    AnsysExt -->|"simulation results"| EM
    ElmerExt -->|"simulation results"| EM
    GmshExt -->|"mesh results"| EM
    FileOut -->|"file inputs"| EM

    EM --> QUANT
    EM --> HAM
    EM --> SWEEP
    QUANT --> SIM
    HAM --> SIM
    SIM --> SWEEP

    SWEEP -->|"analysis metrics"| GUI

    classDef core fill:#AED6F1,stroke:#2980B9
    classDef gui fill:#A9DFBF,stroke:#27AE60
    classDef renderer fill:#F9E79F,stroke:#B7950B
    classDef analysis fill:#D2B4DE,stroke:#8E44AD
    classDef util fill:#F5CBA7,stroke:#D35400
    classDef external fill:#BDC3C7,stroke:#7F8C8D
    classDef persistent fill:#D5DBDB,stroke:#566573
```
