Architecture

Quantum Metal is organised around three load-bearing abstractions — QComponent (geometry pieces), QDesign (chip canvas), and QRenderer (export to GDS / HFSS / FEM). The viewers (MetalGUI and the new headless MetalGUIHeadless) share the same matplotlib renderer underneath; the qm.gui(design) factory auto-picks one based on the environment.

        flowchart TB
    user["User code<br/><i>script, notebook, MetalGUI</i>"]

    subgraph design_layer["QDesign — designs/"]
        comps[design.components<br/><i>dict of QComponent</i>]
        qg[design.qgeometry<br/><i>shapely tables</i>]
        chips[design.chips<br/><i>chip stack</i>]
        vars[design.variables]
    end

    subgraph component_layer["QComponent — qlibrary/"]
        base[QComponent<br/><b>core/base.py</b>]
        qubits[qubits/]
        couplers[couplers/]
        tlines[tlines/]
        terms[terminations/]
        res[resonators/]
        base -.-> qubits & couplers & tlines & terms & res
    end

    subgraph renderer_layer["QRenderer — renderers/"]
        rbase[QRenderer / QRendererAnalysis<br/><b>renderer_base/</b>]
        mpl[renderer_mpl<br/><i>qm.view, MetalGUI canvas</i>]
        gds[renderer_gds<br/><i>GDS export</i>]
        ansys[renderer_ansys + renderer_ansys_pyaedt<br/><i>HFSS / Q3D</i>]
        fem[renderer_gmsh + renderer_elmer<br/><i>open FEM</i>]
        rbase -.-> mpl & gds & ansys & fem
    end

    subgraph analyses_layer["Analyses — analyses/"]
        ham[Hamiltonian quantization]
        cap[Capacitance / LOM]
        epr[Eigenmode + EPR]
    end

    subgraph gui_layer["Viewers — _gui/ + viewer/"]
        factory["qm.gui(design)<br/><i>auto-pick by env</i>"]
        metalgui[MetalGUI<br/><i>Qt desktop</i>]
        headless[MetalGUIHeadless<br/><i>inline matplotlib</i>]
        factory --> metalgui & headless
    end

    user --> design_layer
    user --> factory
    component_layer -- "construction registers" --> comps
    comps -- "make() / rebuild()" --> qg
    qg --> renderer_layer
    renderer_layer --> analyses_layer
    qg --> metalgui & headless

    classDef pri fill:#6929C4,stroke:#3D1773,color:#fff
    classDef sec fill:#e8defc,stroke:#6929C4,color:#1a1a1a
    classDef user_box fill:#fff4e3,stroke:#E07A5F,color:#1a1a1a
    class user user_box
    class base,rbase,factory pri
    class qubits,couplers,tlines,terms,res,mpl,gds,ansys,fem,metalgui,headless,ham,cap,epr,comps,qg,chips,vars sec
    

For deeper contributor-side detail on each abstraction (lifecycle, options parsing, the lazy-Qt setup), read .claude/context/architecture.md in the repo root.