Notebooks

These notebooks demonstrate integration with relevant tools for design and simulation of superconducting quantum devices. Each notebook addresses a different stage of the design flow and uses a different simulation method, allowing users to choose the tools that best fit their needs.

Because each notebook pulls in a different simulation backend, qpdk keeps those backends behind optional dependencies rather than installing all of them by default. The summary table at the bottom lists which extras each notebook needs, and how to install them.

Why multiple simulation approaches?

Designing a superconducting quantum chip involves physics at many scales. No single simulation tool covers all of them efficiently, so a practical design flow combines several complementary methods [BGGW21, KKY+19].

The notebooks in this collection are organized around four simulation categories:

1. Scattering-parameter (S-parameter) circuit models — fast, analytical or semi-analytical models for passive microwave components.

2. FEM-based electromagnetic simulations — full-wave or quasi-static solvers that capture geometry-dependent effects beyond simple analytical formulas.

3. Hamiltonian analysis — numerical or perturbative diagonalization of the quantum Hamiltonian to extract qubit parameters such as frequency, anharmonicity, and dispersive shift.

4. Pulse-level simulations — time-domain simulation of control pulses acting on the quantum system, including gate fidelity, leakage, and decoherence.

Any of these methods can be wrapped in an automated optimization loop (e.g. with Optuna) for design-space exploration.

Where each method fits in the design flow

The typical workflow when creating a chip with qpdk / gdsfactory can be summarized as follows. Each stage may loop back to earlier stages as the design is refined.

        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

S-parameter circuit models treat microwave components as linear, frequency-dependent networks described by their scattering matrices. In qpdk these models are implemented with JAX and composed into circuits using 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.

Notebooks:

• QPDK Models — Comprehensive overview of all S-parameter models available in the qpdk model library (capacitors, inductors, waveguides, couplers, resonators).

• Circuit Simulation with QPDK — Builds and simulates composite circuits with SAX, starting from individual components and assembling a quarter-wave resonator.

• Resonator frequency estimation models — Compares analytical resonance-frequency estimates with SAX circuit simulations.

• Monte Carlo Fabrication Tolerance Analysis — Monte Carlo fabrication tolerance analysis that loads a multi-resonator test chip from a YAML netlist, simulates the full S₂₁ response with SAX, and varies CPW width and gap to quantify resonance frequency spread.

• Model Comparison to Qucs-S — Validates qpdk S-parameter models against Qucs-S reference data for various passive components.

• JAX Backend Comparison for Quantum Circuit Simulation — Benchmarks SAX circuit evaluation on CPU, GPU (CUDA), and NPU (OpenVINO) backends.

FEM-based electromagnetic simulations

Finite-element method (FEM) and full-wave solvers discretize Maxwell’s equations over the physical geometry of the device. They capture effects such as radiation, surface currents, and substrate modes that analytical models may 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).

Notebooks:

• Q2D Cross-Section Impedance of a Coplanar Waveguide — Uses the Ansys Q2D quasi-static solver to extract CPW impedance from the cross-section geometry and compares the result with analytical conformal-mapping estimates.

• HFSS Eigenmode Simulation of a CPW Resonator — Eigenmode analysis of a meandering CPW resonator in Ansys HFSS to find resonant frequencies and Q-factors.

• HFSS Driven Modal Simulation of an Interdigital Capacitor — Driven-modal S-parameter simulation of an interdigital capacitor in Ansys HFSS.

• Elmer Capacitance Extraction of an Interdigital Capacitor — Quasi-static capacitance extraction of an interdigital capacitor with the open-source Elmer FEM solver.

• COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator — COMSOL ported resonator layout, adaptive S-parameter sweep, and field map.

• COMSOL transmon capacitance and field — COMSOL electrostatic extraction of transmon pad capacitance and field map.

• Optuna Optimization of Interdigital Capacitor — Couples Optuna optimization with the Palace FEM solver to optimize an interdigital capacitor towards a target capacitance.

Note

gsim — additional FEM and FDTD simulation examples

The gsim project provides a collection of example notebooks that demonstrate FEM (finite-element method) and FDTD (finite-difference time-domain) electromagnetic simulations built on top of GDSFactory. These notebooks cover solvers such as Palace (FEM) and Meep (FDTD), showing how to go from a GDSFactory layout to a full 3-D electromagnetic simulation. They are a valuable complement to the Ansys-based notebooks above and are especially useful for users looking for open-source solver workflows.

Topics covered in the gsim notebooks include:

• Eigenmode and driven-port simulations with Palace.

• FDTD simulations with Meep, including S-parameter extraction.

• Geometry preparation and meshing pipelines starting from GDSFactory components.

• Post-processing and visualization of electromagnetic field results.

See the gsim documentation for the full list of available notebooks.

Note

Notebooks that need a licensed solver are published with saved outputs

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

Superconducting qubits are nonlinear quantum circuits whose behavior is governed by a Hamiltonian. Diagonalizing this Hamiltonian yields qubit frequencies, anharmonicities, and coupling strengths that feed back into the layout design [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.

Notebooks:

• Dispersive Shift of a Transmon–Resonator System with scQubits — Full numerical diagonalization of the transmon–resonator Hamiltonian with scQubits [GK21], compared against analytical perturbation theory.

• Dispersive Shift of a Transmon–Resonator System with Pymablock — Perturbative block-diagonalization with Pymablock [ADMK+25] to compute the dispersive shift symbolically and map the result to layout parameters.

• Transmon Qubit Design with NetKet — Transmon Hamiltonian analysis with NetKet (exact diagonalization and variational methods) including extraction of qubit parameters and conversion to layout dimensions.

Pulse-level simulations

Once the qubit parameters are known, pulse-level simulations model the time-domain evolution of the quantum state under microwave control pulses. These simulations predict gate fidelities, leakage to non-computational states, and the impact of decoherence [LCM22, MGRW09].

Typical use cases:

• Simulating single-qubit gates (e.g. X, Y) and two-qubit gates (e.g. Bell-state preparation) with realistic pulse shapes.

• Estimating leakage to higher transmon levels.

• Evaluating the effect of \(T_1\) and \(T_2\) decoherence on gate fidelity.

• Connecting physical layout parameters (frequency, anharmonicity) to gate performance.

Notebooks:

• Pulse-Level Simulation of Superconducting Qubits with QuTiP-QIP — Pulse-level simulation of transmon gates with QuTiP-QIP [LCM22], including population dynamics, leakage analysis, and decoherence effects.

Differentiable circuit simulation

Differentiable circuit simulators formulate the circuit as a system of Differential Algebraic Equations (DAEs) and solve them with automatic differentiation support. This enables gradient-based optimization of physical parameters directly from simulation outputs—without finite-difference approximations.

Typical use cases:

• Optimizing Josephson junction parameters (critical current, shunt capacitance) to meet target qubit frequency and anharmonicity.

• Simulating time-domain response of coupled qubit circuits to fast control pulses.

• Computing gradients of crosstalk metrics with respect to layout geometry for automated design refinement.

• Harmonic-balance analysis of nonlinear superconducting circuits under periodic microwave drives.

Notebooks:

• Differentiable Transmon Circuit Simulation with Circulax — Demonstrates Circulax’s harmonic balance and transient solvers applied to a transmon qubit circuit: optimizes junction parameters via jax.grad and simulates crosstalk between coupled qubits, analyzing its sensitivity to the coupling capacitance.

External integration

Notebooks that demonstrate driving qpdk from outside Python — useful for users whose primary tooling lives in another environment.

Notebooks:

• Call qpdk from MATLAB — Calls qpdk directly from MATLAB via MATLAB’s built-in Python interface (py.module.function(…)). Demonstrates 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.

Extra	Installs	What it is for
models	sax, jaxellip, optax, optuna, gplugins[meshwell], scikit-rf, sympy, polars, pandas[parquet]	The analytical and S-parameter model library (qpdk.models), SAX circuit simulation, meshing, and the DataFrame display helpers. This is the baseline extra — nearly every notebook needs it.
hfss	pyaedt[graphics], polars	Ansys AEDT drivers (HFSS, Q2D, Q3D) behind qpdk.simulation. Also requires a local Ansys installation and a license, which are not pip-installable.
comsol	MPh	MPh-based COMSOL geometry and study builders in qpdk.simulation. Building and solving require a COMSOL installation and license; RF solves also need the RF Module. MPh itself is only a client and installs no solver.
circulax	circulax, optax	Differentiable (JAX/DAE) circuit simulation: harmonic-balance and transient solvers with gradients.
netket	netket, flax, optax	Exact-diagonalization and variational Hamiltonian analysis with NetKet.
pymablock	pymablock	Symbolic perturbative block-diagonalization of the qubit–resonator Hamiltonian.
qutip	qutip-jax, qutip-qip	Pulse-level, time-domain simulation of gates, leakage, and decoherence.
scqubits	scqubits	Numerical diagonalization of transmon and transmon–resonator Hamiltonians.
ray	ray[default], tqdm	Parallel and distributed parameter sweeps, used for Monte Carlo tolerance runs.
graphics	trimesh, pyglet	Interactive 3-D viewing of component meshes. Not needed by any notebook.
gdsfactoryplus	doroutes, elvis-lvs, httpx, inspice, jaxellip, kfnetlist, sax	Dependencies of the GDSFactory+ v2 SDK exercised by just test-gfp. Not needed by any notebook.

Extras compose, so install them together in one command. Always quote the brackets — zsh and fish treat them as globs.

With uv:

# add qpdk with extras to the current project (writes pyproject.toml)
uv add "qpdk[models]"
uv add "qpdk[models,netket]"

# install into the active environment without touching pyproject.toml
uv pip install "qpdk[models,netket]"

# in a checkout of this repository, sync the locked environment
uv sync --extra models --extra netket
uv sync --all-extras

# run a notebook in a throwaway environment, no install step
uvx --with "qpdk[models,netket]" --from jupyterlab jupyter lab

With pip:

pip install "qpdk[models]"
pip install "qpdk[models,netket]"
pip install "qpdk[circulax,comsol,graphics,hfss,models,netket,pymablock,qutip,ray,scqubits]"

Note

Two notebook dependencies are deliberately not extras:

• openvino, used by JAX Backend Comparison for Quantum Circuit Simulation for the NPU benchmark, is optional and platform-specific — install it with pip install openvino. The notebook skips that section if it is missing.

• MATLAB and jupyter-matlab-proxy, needed by Call qpdk from MATLAB, are not Python packages managed by qpdk.

If you only want to reproduce the rendered documentation, uv sync --group docs installs the docs dependency group, which already pulls in every backend the notebooks execute with.

Summary table

The Extras column lists the qpdk extras required to run each notebook; see Installing optional extras for what each one installs.

Notebook	Category	Key tools	Extras
QPDK Models	S-parameter models	qpdk, JAX	models
Circuit Simulation with QPDK	S-parameter models	SAX, JAX	models
Resonator frequency estimation models	S-parameter models	SAX	models
Monte Carlo Fabrication Tolerance Analysis	S-parameter models	SAX, JAX, gdsfactory	models, ray
Model Comparison to Qucs-S	S-parameter models	SAX, Qucs-S	models
JAX Backend Comparison for Quantum Circuit Simulation	S-parameter models	SAX, JAX, OpenVINO	models (+ openvino)
Q2D Cross-Section Impedance of a Coplanar Waveguide	FEM electromagnetics	Ansys Q2D, PyAEDT	models, hfss
HFSS Eigenmode Simulation of a CPW Resonator	FEM electromagnetics	Ansys HFSS, PyAEDT	models, hfss
HFSS Driven Modal Simulation of an Interdigital Capacitor	FEM electromagnetics	Ansys HFSS, PyAEDT	models, hfss
Elmer Capacitance Extraction of an Interdigital Capacitor	FEM electromagnetics	Elmer, meshwell	models (+ gplugins[elmer] from Git until release)
COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator	FEM electromagnetics	COMSOL, MPh	comsol
COMSOL transmon capacitance and field	FEM electromagnetics	COMSOL, MPh	comsol
Optuna Optimization of Interdigital Capacitor	FEM optimization	Optuna, Palace	models
Dispersive Shift of a Transmon–Resonator System with scQubits	Hamiltonian analysis	scQubits	models, scqubits
Dispersive Shift of a Transmon–Resonator System with Pymablock	Hamiltonian analysis	Pymablock, SymPy	models, pymablock
Transmon Qubit Design with NetKet	Hamiltonian analysis	NetKet, JAX	models, netket
Pulse-Level Simulation of Superconducting Qubits with QuTiP-QIP	Pulse-level simulation	QuTiP-QIP, JAX	models, qutip
Differentiable Transmon Circuit Simulation with Circulax	Differentiable circuit simulation	Circulax, JAX, Optax	models, circulax
Call qpdk from MATLAB	External integration	MATLAB, RF Toolbox (optional), jupyter-matlab-proxy	models

References

[ADMK+25]

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.

[BGGW21] (1,2,3)

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.

[CSD+23]

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.

[GK21]

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.

[GFB+08] (1,2)

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.

[KYG+07]

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.

[KKY+19]

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.

[LCM22] (1,2)

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.

[MGRW09]

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.