AWR Qubit Simulation

A Python toolchain for designing superconducting-qubit chips and pulling their circuit-QED parameters straight out of EM simulation. You lay out the geometry with phidl, export it to GDS, and drive AWR Microwave Office (AXIEM) to solve the structure and extract the numbers that matter — resonator frequency and linewidth κ, qubit charging energy E_C, and the qubit–resonator coupling g and dispersive shift χ — so a design can be tuned against its targets before fabrication.

This main branch is a trimmed, general-purpose example: one qubit–resonator pair, end to end. The full body of work — every chip design, fabrication mask, wafer GDS, and simulation result — lives on the jsun-awr-design branch.

📖 New to this workflow? Start with the introductory guide by Basil Smitham (Princeton, Houck Lab): AWR qubit-simulation guide.

What's here

Design/
  lib/                          Reusable design + simulation modules
    cpw_modules.py              CPW backbone, meanders, GSG launch pads, airbridges (gap-only architecture)
    design_generator.py         Filter / coupler / resonator generators (layer-scheme-agnostic)
    junction_modules.py         Josephson-junction / SQUID geometry
    transmon_module.py          Floating-transmon pad geometry
    prepare_gds.py              Boolean-merge a design GDS into simulation / fabrication layouts
    awr_stackup.py              Configure the AWR Microwave Office global STACKUP
    awr_ports.py                Import GDS into an AWR EM structure and place ports
                                (interior PinPad probe or edge-of-frame CPW launch)
    awr_analysis.py             Wire AWR schematics; extract f_r / C / kappa / Q / g / chi from sweeps
    awr_mesh.py                 Programmatic per-shape AXIEM mesh-density override (.eml round trip)
  qubit_resonator_pair_design_and_simulation.ipynb   End-to-end demo notebook
  building_blocks_example.py    Gallery of every geometry primitive (exports building_blocks_example.gds)
  docs/                         Reference docs, guide + vendor PDFs, EM-settings study, mesh-API repro
    awr_simulation_workflow.md          Port scheme + extraction recipes (R1-R7)
    awr_em_settings_comparison.md       AXIEM mesh/solver accuracy-vs-runtime study
    awrPythonApiReference25.1.pdf       Vendor: AWR Python API reference
    awrPythonScript25.1.pdf             Vendor: AWR Python scripting guide
    awr_shape_mesh_api_issue/           Forum post + repro for the per-shape mesh COM-API gap
    figures/                            PNGs embedded in the EM-settings study
    Cadence_AWR_Microwave_Office_Guide_For_SC_Qubits_Smitham_Princeton_230915.pdf
                                        Smitham AWR-for-SC-qubits guide (offline copy of the Google Doc)

GDS/
  QubitResonatorPair/
    qubit_resonator_pair_p1_v1.gds        Example design output
    qubit_resonator_pair_p1_v1_sim.gds    Same design after prepare_gds() sim prep
  building_blocks_example.gds             Output of building_blocks_example.py

SimResult/QubitResonatorPair/
  qubit_resonator_pair_p1_v1_summary.csv      Example extracted-parameters output
  qubit_resonator_pair_p1_v191_summary.csv    Extracted parameters, design variant v191
  qubit_resonator_pair_p1_v1comparison.csv    Simulated-vs-target comparison table

The demo notebook

qubit_resonator_pair_design_and_simulation.ipynb builds one floating-transmon + λ/4 readout-resonator pair coupled to a readout feedline (transmission line), then drives AWR Microwave Office (AXIEM) end-to-end:

1. Geometry — transmon pads, a meander resonator (with airbridges over its turns), and a chip-spanning feedline with edge-launch ports (also airbridged). prepare_gds() then boolean-merges the design into the simulation layout.
2. EM setup — configure the STACKUP, import the geometry, place ports, and give the ground / flood fill a Low per-shape mesh density (via awr_mesh) so the big metal sheet doesn't dominate the AXIEM mesh.
3. Extraction — from the S/Y sweeps: resonator f_r and C, qubit C_q and E_C, qubit–resonator C_qr / g / chi, and the readout kappa / Q computed two independent ways — Re(Y) with a 50 Ω series-R feedline (R2) and an S21-notch Lorentzian fit.

The building blocks gallery

building_blocks_example.py is a standalone catalog of the geometry the toolchain can generate. It draws one labeled row of variants for every component class — launch pads, CPW segments and bends, λ/4 resonators, airbridges/wirebonds, Josephson junctions and SQUIDs (Manhattan, Dolan, DC- and side-SQUID), flux-bias lines, complete floating-transmon objects, MWO simulation-port square patterns, and fabrication probe structures — assembles them into one master layout, and exports it to GDS/building_blocks_example.gds for inspection in a GDS viewer (e.g. KLayout). It doubles as a live usage reference for the lib/ modules: each section has an editable parameter block at the top, so you can tweak a value and re-run to watch the geometry change. It uses the same 100s-band process layers and 1000s-band simulation-port convention as the real design scripts, so the port-square patterns in its Section 8 are exactly what awr_ports.py recognizes.

How it works

The design modules use the gap-only CPW architecture: lay one chip-wide ground plane on layer 0, then have every CPW (feedline, filter, resonator) contribute only gap stripes on the gap layer. The signal center pin and ground rails form for free during a later boolean op (chip_ground − all_gaps) in the simulation-prep step.

Each notebook defines its own (layer, datatype) tuples and wires them onto the modules in a glue cell (the modules are layer-scheme-agnostic and read those attributes at call time), e.g.:

import sys, os
sys.path.insert(0, os.path.join(os.getcwd(), 'lib'))

import cpw_modules as cm
import transmon_module as tm
import design_generator as dg
import prepare_gds
import awr_stackup, awr_ports, awr_analysis, awr_mesh

dg.gap_layer   = gap_layer
dg.metal_layer = metal_layer
dg.X_CPW       = X_CPW

Ports are inferred from the port-square geometry on each port layer: two squares → a differential port, three interior squares → a PinPad probe, and three squares flush with the chip edge → an edge-of-frame CPW launch (used for the feedline).

Method and validation

The extraction methods here follow the black-box / lumped-element approach to superconducting-circuit design [1]–[4]. The core idea is to use the EM solver to characterize the linear part of the circuit — every capacitance, inductance, and loss channel of the metal structure — and distill it into an effective lumped-element model (equivalently, the multiport admittance/impedance seen at the nonlinear elements). That reduced model can then be handed to a circuit-quantization tool such as scqubits, with the Josephson junctions reinstated as the nonlinear elements, to obtain the quantized spectrum, couplings, and dispersive shifts. (This example carries out the final transmon step with the closed-form expressions in awr_analysis.py.)

The best check that a simulation is correct is self-consistency of the lumped model: reconstruct the admittance/impedance of the extracted lumped-element model and compare it against the admittance extracted directly from the AWR simulation across the band of interest. If the two agree, the lumped model is a faithful reduction of the EM structure. If they disagree, the lumped-element model is not a good approximation — either something is wrong with the simulation, the ports, or the mesh, or the structure has additional modes that must be included to capture its full response [1], [2].

Documentation

Design/docs/ collects the reference material behind the toolchain:

• awr_simulation_workflow.md — the deepest technical reference: the full pipeline (geometry → prepare_gds → stackup/ports → analysis), the port-square scheme and its layer-band convention, and extraction recipes R1–R7 (which ports to drive/short/open, Y vs Z, at what frequency, and the closed-form formula for f_r, C, κ/Q, C_q/E_C, C_qr/g/χ, the capacitance matrix, and mutual inductance).
• awr_em_settings_comparison.md — a benchmarking study of AXIEM solver settings (mesh density, mesh parameters, solver type, accuracy presets) trading solve time against extracted-parameter accuracy, with recommendations; the plots it embeds live in figures/.
• Cadence_AWR_Microwave_Office_Guide_For_SC_Qubits_Smitham_Princeton_230915.pdf — the introductory AWR-for-superconducting-qubits guide by Basil Smitham (Princeton, Houck Lab); the offline copy of the Google-Doc guide linked at the top of this README.
• awrPythonApiReference25.1.pdf and awrPythonScript25.1.pdf — the vendor AWR Design Environment Python API reference and scripting guide (v25.1), the reference for the pyawr COM calls used throughout lib/awr_*.py.
• awr_shape_mesh_api_issue/ — a self-contained forum post and minimal reproducer for the AWR COM-API limitation (it cannot create per-shape mesh records) that awr_mesh.py works around via its .eml splice.

Note: some paths cited inside these .md docs (e.g. awr_measure.py, transmon_params.py, awr_port_registry.py, Design/tests/, SimResult/Spring2026/) refer to the full jsun-awr-design branch and are not present on this trimmed main.

Requirements

See requirements.txt. The geometry stack (numpy, matplotlib, scipy, phidl, gdspy, gdstk) is open source and runs anywhere. The awr_*.py modules additionally require a licensed AWR Microwave Office install on Windows (via pyawr + pywin32); the geometry generation and GDS export work without them.

pip install -r requirements.txt

References

• Introductory guide: B. Smitham, Cadence AWR Microwave Office Guide for Superconducting Circuits (Princeton, Houck Lab, 2023) — Google Doc · local copy in Design/docs/.
• [1] B. M. Smitham and A. A. Houck, "Reciprocal lumped-element superconducting circuits: quantization, decomposition, and model extraction," arXiv:2412.06880 (2024). doi:10.48550/arXiv.2412.06880.
• [2] F. Solgun, D. W. Abraham, and D. P. DiVincenzo, "Blackbox quantization of superconducting circuits using exact impedance synthesis," Phys. Rev. B 90, 134504 (2014). doi:10.1103/PhysRevB.90.134504.
• [3] D. S. Wisbey, A. Martin, A. Reinisch, and J. Gao, "New Method for Determining the Quality Factor and Resonance Frequency of Superconducting Micro-Resonators from Sonnet Simulations," J. Low Temp. Phys. 176, 538 (2014). doi:10.1007/s10909-014-1099-3.
• [4] S. E. Nigg et al., "Black-box superconducting circuit quantization," Phys. Rev. Lett. 108, 240502 (2012). doi:10.1103/PhysRevLett.108.240502.

Contributors

• Jiayi Sun — project lead and main orchestrator of the toolchain.
• Paul Varosy — first additional user; contributed additional documentation and building-blocks work.
• Claude (Opus / Fable) — primary code author.