Quantum RF¶
Mirrored from the notebooks page of QPDK v0.4.3; the
QPDK documentation has the latest version. The examples
linked below include outputs from validated notebook snapshots executed with the
QPDK kernel; their source cells are checked against the downloadable templates
during every documentation build. Notebooks without a template here link to the
QPDK documentation.
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.
-
S-parameter models: Fast JAX/SAX circuit models for resonators, capacitors, and couplers.
-
FEM electromagnetics: Full-wave and quasi-static solvers: HFSS, Q2D, COMSOL, Elmer, Palace.
-
Hamiltonian analysis: Qubit frequency, anharmonicity, and dispersive shift from the circuit Hamiltonian.
-
Pulse-level simulation: Gate fidelity, leakage, and decoherence under realistic control pulses.
-
Differentiable circuits: Harmonic-balance and transient solvers with gradients through
jax.grad. -
External integration: 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. 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.
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.
-
Model library tour: Every S-parameter model in
qpdk.models: capacitors, inductors, waveguides, couplers, resonators.Tools: qpdk, JAX · Install:
models -
Circuit simulation with SAX: From single components to an assembled quarter-wave resonator.
Tools: SAX, JAX · Install:
models -
Resonator frequency model: Analytical resonance-frequency estimates against SAX circuit simulation.
Tools: SAX · Install:
models -
Monte Carlo fabrication tolerance: Vary CPW width and gap on a YAML-netlist test chip and measure the spread in S₂₁ resonances.
Tools: SAX, gdsfactory · Install:
models,ray -
Validation against Qucs-S: qpdk models checked against Qucs-S reference data for passive components.
Tools: SAX, Qucs-S · Install:
models -
JAX backend benchmark: 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.
Tools: JAX, CUDA, MPS · Install:
models
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.
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).
-
Q2D CPW impedance: CPW impedance from the cross-section, against conformal-mapping estimates.
Tools: Ansys Q2D · Install:
models,hfss· licensed solver -
HFSS eigenmode resonator: Resonant frequencies and Q-factors of a meandering CPW resonator.
Tools: Ansys HFSS · Install:
models,hfss· licensed solver -
HFSS driven capacitor: Driven-modal S-parameters of an interdigital capacitor.
Tools: Ansys HFSS · Install:
models,hfss· licensed solver -
Elmer capacitance extraction: Quasi-static capacitance of an interdigital capacitor with the open-source Elmer solver.
Tools: Elmer, meshwell · Install:
models,gplugins[elmer] from Git· open source -
COMSOL CPW resonator: Ported resonator layout, adaptive S-parameter sweep, and field map.
Tools: COMSOL, MPh · Install:
comsol· licensed solver -
COMSOL qubit capacitance: Electrostatic extraction of transmon pad capacitance, with field map.
Tools: COMSOL, MPh · Install:
comsol· licensed solver -
Capacitor optimization with Optuna: Optuna drives the Palace FEM solver towards a target capacitance.
Tools: Optuna, Palace · Install:
models· open source -
FEM dataset lookups: Palace plate-capacitor and CPW datasets, lazy queries, multidimensional interpolation and SAX models.
Tools: JAX, Polars · Install:
models -
Palace qubit and readout resonator: Double-pad transmon and quarter-wave readout eigenmodes, with analytical estimates and geometry tuning.
Tools: Palace, gsim · open source
-
Palace flip-chip flipmon: Flip-chip eigenmodes and vacuum-gap energy participation.
Tools: Palace, gsim · open source
-
Palace qubit optimization: Batched geometry studies with Slurm MPI and Ray workers.
Tools: Palace, Slurm · Install:
optimization -
Palace TSV transition: Through-silicon-via CPW transition with backside metal, a conductor-backed CPW seed, and optional Palace-driven taper optimization.
Tools: Palace, gsim · Install:
optimization -
More FEM and FDTD in gsim: 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.
Tools: Palace, Meep · open source
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 also 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.
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.
-
scQubits parameters: Full numerical diagonalization of the transmon–resonator Hamiltonian, against perturbation theory.
Tools: scQubits · Install:
models,scqubits -
Dispersive shift with Pymablock: Symbolic block-diagonalization mapped to layout parameters.
Tools: Pymablock, SymPy · Install:
models,pymablock -
Transmon design with NetKet: Exact diagonalization, VMC, TDVP and a custom Flax network for transmons, junction arrays, unimons and gatemons, fed back into the SAX models. Includes an optional TPU section.
Tools: NetKet, JAX, Flax · Install:
models,netket
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.
-
Transmon gates with QuTiP-QIP: 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.
Tools: QuTiP-QIP, JAX · Install:
models,qutip
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.
-
Transmon optimization with Circulax: Harmonic-balance and transient solvers on a transmon: optimize junction parameters with
jax.gradand trace crosstalk sensitivity to the coupling capacitance.Tools: Circulax, Optax · Install:
models,circulax
Harmonic-balance circuit simulation¶
SPICE-class simulators with harmonic balance 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. qpdk does not import or link VACASK, which keeps it outside the AGPL's combined work rule under the maintainer's reading in VACASK issue #161.
External integration¶
Driving qpdk from outside Python, for teams whose primary tooling lives elsewhere.
-
qpdk from MATLAB: GDS generation, parameter sweeps, inverse design with
fzero, and Touchstone round-trips through the RF Toolbox, via MATLAB's built-in Python interface.Tools: MATLAB, RF Toolbox · Install:
models
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.
Finally it reads the Touchstone files 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.
uv
# 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
pip install "qpdk[models]"
pip install "qpdk[models,netket]"
pip install "qpdk[circulax,comsol,graphics,hfss,models,netket,pymablock,qutip,ray,scqubits]"
From a checkout
# 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 |
|---|---|---|
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 |
gplugins[ansys], pyaedt[graphics] |
Ansys AEDT drivers (HFSS, Q2D, Q3D) from gplugins.ansys. Also requires a local Ansys installation and a license, which are not pip-installable. |
comsol |
gplugins[comsol] |
The MPh-based COMSOL geometry and study builders of gplugins.comsol, used with qpdk.simulation.comsol for the QPDK layout and materials. 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 |
gdsfactoryplus (Python 3.12 only), jaxellip, polars |
The GDSFactory+ v2 SDK exercised by just test-gfp. Not needed by any notebook. |
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. A new MPS environment needs a SAX release that allows the JAX 0.11 version the plugin requires. - 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 rather than importing or linking; install it from its release page. This separation follows the maintainer's reading of the AGPL in VACASK issue #161.
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 |
|---|---|---|---|
| All 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 | models (GPU plugins only for recording) |
| 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 |
| Josephson traveling-wave parametric amplifiers with JosephsonCircuits.jl | TWPA harmonic balance and quantum efficiency | JosephsonCircuits.jl, PythonCall (Julia kernel) | models |
| Lumped Josephson parametric amplifiers with VACASK | Lumped JPA harmonic balance | VACASK (external program) | models |
| CPW parametric amplifiers: layout and circuit models | CPW JPA model qualification | VACASK (external program), SAX | models |
| Call qpdk from MATLAB | External integration | MATLAB, RF Toolbox (optional), jupyter-matlab-proxy | models |