Notebooks#
Worked, executable examples that take a qpdk component from requirements to a simulated result. Each notebook covers one stage of the design flow with one simulation method, so pick the one that fits your question and tooling.
Fast JAX/SAX circuit models for resonators, capacitors, and couplers.
Full-wave and quasi-static solvers: HFSS, Q2D, COMSOL, Elmer, Palace.
Qubit frequency, anharmonicity, and dispersive shift from the circuit Hamiltonian.
Gate fidelity, leakage, and decoherence under realistic control pulses.
Harmonic-balance and transient solvers with gradients through jax.grad.
Drive qpdk from MATLAB and its RF Toolbox.
Tip
Each backend sits behind an optional extra, so pip install qpdk stays light.
See Installing optional extras for how to install them and Summary table for
every notebook’s full dependency list.
On the cards, outlined badges are the main tools a notebook uses and filled
badges are what you need to install (qpdk extras, plus anything outside
them).
Where each method fits in the design flow#
No single tool covers every physical scale of a superconducting chip, so a practical flow combines complementary methods [BGGW21, KKY+19]. Each stage may loop back as the design is refined, and any of them can sit inside an optimization loop (e.g. with Optuna).
flowchart TB
A["Physical requirements<br>(qubit frequency, coupling, T₁, …)"]
B["Hamiltonian / perturbation analysis<br>(map requirements → circuit parameters)"]
C["Circuit / S-parameter models<br>(design passive components)"]
D["Layout with gdsfactory<br>(draw the chip in qpdk)"]
E["FEM verification<br>(validate geometry with a full-wave solver)"]
F["Pulse-level simulation<br>(predict gate performance)"]
G["Fabrication & measurement"]
A --> B --> C --> D --> E --> F --> G
F -.-> A
E -.-> C
S-parameter circuit models#
Microwave components as linear, frequency-dependent scattering matrices, implemented in JAX and composed into circuits with SAX [BGGW21, GFB+08].
Typical use cases
Choosing coplanar-waveguide (CPW) resonator, capacitor, and coupling structure geometries to meet target parameters.
Predicting resonance frequencies and quality factors of passive components.
Simulating complete test chips with many resonators from a gdsfactory netlist.
Every S-parameter model in qpdk.models: capacitors, inductors, waveguides,
couplers, resonators.
From single components to an assembled quarter-wave resonator.
Analytical resonance-frequency estimates against SAX circuit simulation.
Vary CPW width and gap on a YAML-netlist test chip and measure the spread in S₂₁ resonances.
qpdk models checked against Qucs-S reference data for passive components.
SAX circuit evaluation on CPU, CUDA, and Apple Silicon (MPS), with matching precision baselines and accuracy checks. Recorded runs from both machines share a scaling plot rendered from Parquet records in CI. Recording requires the corresponding hardware.
FEM-based electromagnetic simulations#
Finite-element and full-wave solvers discretize Maxwell’s equations over the real geometry, capturing radiation, surface currents, and substrate modes that analytical models miss [CSD+23, GFB+08].
Typical use cases
Extracting characteristic impedance and effective permittivity of CPW cross-sections.
Computing eigenmode frequencies and quality factors of resonators from their physical geometry.
Running driven-modal (port-based) S-parameter simulations of capacitors and other structures.
Optimizing component geometry against a target specification (e.g. a desired capacitance value).
CPW impedance from the cross-section, against conformal-mapping estimates.
Resonant frequencies and Q-factors of a meandering CPW resonator.
Driven-modal S-parameters of an interdigital capacitor.
Quasi-static capacitance of an interdigital capacitor with the open-source Elmer solver.
Ported resonator layout, adaptive S-parameter sweep, and field map.
Electrostatic extraction of transmon pad capacitance, with field map.
Optuna drives the Palace FEM solver towards a target capacitance.
Palace plate-capacitor and CPW datasets, lazy queries, multidimensional interpolation and SAX models.
The gsim notebooks take a GDSFactory layout to a 3-D simulation with open-source solvers: Palace eigenmode and driven-port runs, Meep FDTD with S-parameter extraction, meshing, and field post-processing.
Why the licensed-solver notebooks show a recorded run
COMSOL and Ansys AEDT are not pip-installable and do not run without a license, so Q2D Cross-Section Impedance of a Coplanar Waveguide, HFSS Eigenmode Simulation of a CPW Resonator, HFSS Driven Modal Simulation of an Interdigital Capacitor, COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator, and COMSOL transmon capacitance and field are published with the outputs of a real solver run stored in the notebook. Those stored figures and numbers are the artifact: the pages are not re-executed here, so what you see is the recorded run. The two COMSOL notebooks additionally run without a license, skipping the solver cells and reporting how to supply exported results, so their code can be read and executed up to the point where a license is needed.
Hamiltonian analysis#
Diagonalizing the circuit Hamiltonian yields qubit frequencies, anharmonicities, and coupling strengths that feed back into the layout [BGGW21, KYG+07].
Typical use cases
Computing transmon qubit frequency (\(\omega_{01}\)) and anharmonicity (\(\alpha\)) from Josephson energy \(E_\text{J}\) and charging energy \(E_\text{C}\).
Calculating the dispersive shift \(\chi\) of a transmon–resonator system for readout design.
Translating Hamiltonian-level parameters into physical layout dimensions.
Full numerical diagonalization of the transmon–resonator Hamiltonian [GK21], against perturbation theory.
Symbolic block-diagonalization [ADMK+25] mapped to layout parameters.
Exact diagonalization and variational methods, converted to layout dimensions.
Pulse-level simulations#
With qubit parameters in hand, time-domain simulation under microwave control pulses predicts gate fidelity, leakage to non-computational states, and the impact of decoherence [LCM22, MGRW09].
Single-qubit (X, Y) and two-qubit (Bell-state) gates with realistic pulse shapes: population dynamics, leakage to higher levels, and \(T_1\)/\(T_2\) effects on fidelity.
Differentiable circuit simulation#
The circuit as a system of differential-algebraic equations, solved with automatic differentiation: gradients of any simulated output with respect to physical parameters, without finite differences.
Harmonic-balance and transient solvers on a transmon: optimize junction
parameters with jax.grad and trace crosstalk sensitivity to the coupling
capacitance.
Harmonic-balance circuit simulation#
SPICE-class simulators with harmonic balance (HB) find the periodic steady state of a nonlinear circuit under a strong drive and, with a small-signal analysis around that state, the frequency conversion between sidebands. This is what parametric amplifiers need.
Typical use cases:
Gain, bandwidth and compression of Josephson parametric amplifiers.
Checking a resonator design for unwanted up-conversion into higher modes.
Notebooks:
Josephson traveling-wave parametric amplifiers with JosephsonCircuits.jl - A Julia notebook that compares loaded and uniform 2047-junction TWPAs with JosephsonCircuits.jl at the same incident pump. Cold dispersion and the pump Kerr shift explain resonant phase matching. Live harmonic-balance solves give the gain, the photon balance over all sidebands and the quantum efficiency, with a harmonic-basis check. Calls QPDK through PythonCall to show a junction layout and its critical-current targets.
Lumped Josephson parametric amplifiers with VACASK - Explains how VACASK analyses differ, then runs a current-pumped Kerr JPA and a lumped flux-pumped JPA in released VACASK. Compares gain and gain-bandwidth with single-mode theory, shows compression, and explains which layout values need calibration or extraction.
CPW parametric amplifiers: layout and circuit models - Builds a QPDK meander and uses its realized length and cross-section in the SAX and VACASK line models. Checks resonance, gain, higher-mode conversion and rational-fit error. A Manley-Rowe photon balance over all sidebands shows where the gain missing from single-mode theory goes.
The pages retain saved executions for documentation builds. The JPA companions need the external VACASK simulator, which runs as a separate program on the Verilog-A junction and SQUID models shipped with qpdk.
External integration#
Driving qpdk from outside Python, for teams whose primary tooling lives elsewhere.
GDS generation, parameter sweeps, inverse design with fzero, and Touchstone
round-trips through the RF Toolbox, via MATLAB’s built-in Python interface.
How the MATLAB notebook calls qpdk
The notebook calls qpdk directly from MATLAB via its built-in Python interface
(py.module.function(...)): GDS generation, parameter sweeps over
resonator_frequency, inverse design with fzero, and a parametric chip variant
grid summarised in a MATLAB table. It then exports SAX models as Touchstone files
with sax.write_sdict_touchstone and consumes them from MATLAB’s RF Toolbox as sparameters/nport boxes —
Smith charts, cascades in a circuit, rational fitting and transient response, and
back into SAX with sax.read_sdict_touchstone.
Those sections need the RF Toolbox and skip themselves when it is unavailable or when
QPDK_SKIP_RF_TOOLBOX is set; the rendered page shows a saved execution that had
the toolbox available. The notebook uses the MATLAB Jupyter kernel from
jupyter-matlab-proxy.
Installing optional extras#
pip install qpdk gives you the layout PDK and nothing else: the analytical models,
FEM drivers, and Hamiltonian/pulse solvers all live in extras, declared under
[project.optional-dependencies] in pyproject.toml. Extras compose, so install
them together in one command, and always quote the brackets — zsh and fish treat
them as globs.
# add qpdk with extras to the current project (writes pyproject.toml)
uv add "qpdk[models,netket]"
# install into the active environment without touching pyproject.toml
uv pip install "qpdk[models,netket]"
# run a notebook in a throwaway environment, no install step
uvx --with "qpdk[models,netket]" --from jupyterlab jupyter lab
pip install "qpdk[models]"
pip install "qpdk[models,netket]"
pip install "qpdk[circulax,comsol,graphics,hfss,models,netket,pymablock,qutip,ray,scqubits]"
# sync the locked environment with the extras you need
uv sync --extra models --extra netket
uv sync --all-extras
# or reproduce the rendered documentation, every backend included
uv sync --group docs
Extra |
Installs |
What it is for |
|---|---|---|
|
|
The analytical and S-parameter model library ( |
|
|
Ansys AEDT drivers (HFSS, Q2D, Q3D) from |
|
|
The MPh-based COMSOL geometry and study builders of |
|
|
Differentiable (JAX/DAE) circuit simulation: harmonic-balance and transient solvers with gradients. |
|
|
Exact-diagonalization and variational Hamiltonian analysis with NetKet. |
|
|
Symbolic perturbative block-diagonalization of the qubit–resonator Hamiltonian. |
|
|
Pulse-level, time-domain simulation of gates, leakage, and decoherence. |
|
|
Numerical diagonalization of transmon and transmon–resonator Hamiltonians. |
|
|
Parallel and distributed parameter sweeps, used for Monte Carlo tolerance runs. |
|
|
Interactive 3-D viewing of component meshes. Not needed by any notebook. |
|
|
The GDSFactory+ v2 SDK exercised by |
Note
These notebook dependencies are deliberately not extras:
A CUDA build of JAX or experimental
jax-mpsis needed only to record new measurements for JAX Backend Comparison for Quantum Circuit Simulation. The notebook itself renders saved Parquet records without a GPU. Installing a new MPS environment requires SAX to allow the JAX 0.11 version required by the plugin.MATLAB and jupyter-matlab-proxy, needed by Call qpdk from MATLAB, are not Python packages managed by
qpdk.The VACASK circuit simulator, needed by the lumped and CPW parametric-amplifier notebooks, is a separate program (AGPL-3.0) that qpdk runs as a subprocess; install it from its release page.
The Elmer notebook also needs gplugins[elmer] installed from Git until the next
gplugins release.
Summary table#
Every notebook at a glance; the Extras column links back to Installing optional extras.
Notebook |
Category |
Key tools |
Extras |
|---|---|---|---|
S-parameter models |
qpdk, JAX |
|
|
S-parameter models |
SAX, JAX |
|
|
S-parameter models |
SAX |
|
|
S-parameter models |
SAX, JAX, gdsfactory |
|
|
S-parameter models |
SAX, Qucs-S |
|
|
S-parameter models |
SAX, JAX |
|
|
FEM electromagnetics |
Ansys Q2D, PyAEDT |
|
|
FEM electromagnetics |
Ansys HFSS, PyAEDT |
|
|
FEM electromagnetics |
Ansys HFSS, PyAEDT |
|
|
FEM electromagnetics |
Elmer, meshwell |
|
|
COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator |
FEM electromagnetics |
COMSOL, MPh |
|
FEM electromagnetics |
COMSOL, MPh |
|
|
FEM optimization |
Optuna, Palace |
|
|
Dispersive Shift of a Transmon–Resonator System with scQubits |
Hamiltonian analysis |
scQubits |
|
Dispersive Shift of a Transmon–Resonator System with Pymablock |
Hamiltonian analysis |
Pymablock, SymPy |
|
Hamiltonian analysis |
NetKet, JAX |
|
|
Pulse-Level Simulation of Superconducting Qubits with QuTiP-QIP |
Pulse-level simulation |
QuTiP-QIP, JAX |
|
Differentiable circuit simulation |
Circulax, JAX, Optax |
|
|
Josephson traveling-wave parametric amplifiers with JosephsonCircuits.jl |
TWPA harmonic balance and quantum efficiency |
JosephsonCircuits.jl, PythonCall (Julia kernel) |
|
Lumped JPA harmonic balance |
VACASK (external program) |
|
|
CPW JPA model qualification |
VACASK (external program), SAX |
|
|
External integration |
MATLAB, RF Toolbox (optional), jupyter-matlab-proxy |
|
References#
Isidora Araya Day, Sebastian Miles, Hugo K. Kerstens, Daniel Varjas, and Anton R. Akhmerov. Pymablock: An algorithm and a package for quasi-degenerate perturbation theory. SciPost Physics Codebases, 2025. doi:10.21468/SciPostPhysCodeb.50.
Alexandre Blais, Arne L. Grimsmo, S. M. Girvin, and Andreas Wallraff. Circuit quantum electrodynamics. Reviews of Modern Physics, 93(2):025005, May 2021. doi:10.1103/RevModPhys.93.025005.
Qi-Ming Chen, Priyank Singh, Rostislav Duda, Giacomo Catto, Aarne Keränen, Arman Alizadeh, Timm Mörstedt, Aashish Sah, András Gunyhó, Wei Liu, and Mikko Möttönen. Compact inductor-capacitor resonators at sub-gigahertz frequencies. Physical Review Research, 5(4):043126, November 2023. doi:10.1103/PhysRevResearch.5.043126.
Peter Groszkowski and Jens Koch. Scqubits: a Python package for superconducting qubits. Quantum, 5:583, November 2021. doi:10.22331/q-2021-11-17-583.
M. Göppl, A. Fragner, M. Baur, R. Bianchetti, S. Filipp, J. M. Fink, P. J. Leek, G. Puebla, L. Steffen, and A. Wallraff. Coplanar waveguide resonators for circuit quantum electrodynamics. Journal of Applied Physics, 104(11):113904, December 2008. doi:10.1063/1.3010859.
Jens Koch, Terri M. Yu, Jay Gambetta, A. A. Houck, D. I. Schuster, J. Majer, Alexandre Blais, M. H. Devoret, S. M. Girvin, and R. J. Schoelkopf. Charge-insensitive qubit design derived from the Cooper pair box. Physical Review A, 76(4):042319, October 2007. doi:10.1103/PhysRevA.76.042319.
P. Krantz, M. Kjaergaard, F. Yan, T. P. Orlando, S. Gustavsson, and W. D. Oliver. A quantum engineer's guide to superconducting qubits. Applied Physics Reviews, 6(2):021318, June 2019. doi:10.1063/1.5089550.
Boxi Li, Tommaso Calarco, and Felix Motzoi. Pulse-level noisy quantum circuits with QuTiP. Quantum, 6:630, January 2022. doi:10.22331/q-2022-01-24-630.
F. Motzoi, J. M. Gambetta, P. Rebentrost, and F. K. Wilhelm. Simple pulses for elimination of leakage in weakly nonlinear qubits. Physical Review Letters, 103(11):110501, September 2009. doi:10.1103/PhysRevLett.103.110501.