# 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](#notebook-extras) for how to install them and [Summary table](#notebook-summary) 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](#id16), [KKY+19](#id44)]. Each
stage may loop back as the design is refined, and any of them can sit inside an
optimization loop (e.g. with [Optuna](https://optuna.org/)).

<a id="notebooks-sparameter"></a>

## S-parameter circuit models

Microwave components as linear, frequency-dependent scattering matrices, implemented in
[JAX](https://jax.readthedocs.io/) and composed into circuits with [SAX](https://gdsfactory.github.io/sax/)
[[BGGW21](#id16), [GFB+08](#id30)].

### 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.

qpdk JAX models

From single components to an assembled quarter-wave resonator.

SAX JAX models

Analytical resonance-frequency estimates against SAX circuit simulation.

SAX models

Vary CPW width and gap on a YAML-netlist test chip and measure the spread in
S₂₁ resonances.

SAX gdsfactory models
ray

qpdk models checked against Qucs-S reference data for passive components.

SAX Qucs-S models

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.

JAX CUDA MPS models

<a id="notebooks-fem"></a>

## 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](#id19), [GFB+08](#id30)].

### 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.

Ansys Q2D models hfss
licensed solver

Resonant frequencies and Q-factors of a meandering CPW resonator.

Ansys HFSS models hfss
licensed solver

Driven-modal S-parameters of an interdigital capacitor.

Ansys HFSS models hfss
licensed solver

Quasi-static capacitance of an interdigital capacitor with the open-source Elmer
solver.

Elmer meshwell models
gplugins[elmer] from Git
open source

Ported resonator layout, adaptive S-parameter sweep, and field map.

COMSOL MPh comsol
licensed solver

Electrostatic extraction of transmon pad capacitance, with field map.

COMSOL MPh comsol
licensed solver

Optuna drives the Palace FEM solver towards a target capacitance.

Optuna Palace models
open source

Palace plate-capacitor and CPW datasets, lazy queries, multidimensional
interpolation and SAX models.

JAX Polars 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.

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](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_q2d_cpw_impedance.html.md), [HFSS Eigenmode Simulation of a CPW Resonator](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_eigenmode_resonator.html.md),
[HFSS Driven Modal Simulation of an Interdigital Capacitor](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_driven_capacitor.html.md), [COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/comsol_cpw_resonator.html.md), and
[COMSOL transmon capacitance and field](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/comsol_qubit_capacitance.html.md) 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.

<a id="notebooks-hamiltonian"></a>

## Hamiltonian analysis

Diagonalizing the circuit Hamiltonian yields qubit frequencies, anharmonicities, and
coupling strengths that feed back into the layout
[[BGGW21](#id16), [KYG+07](#id43)].

### 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](#id31)], against perturbation theory.

scQubits models scqubits

Symbolic block-diagonalization [[ADMK+25](#id13)]
mapped to layout parameters.

Pymablock SymPy
models pymablock

Exact diagonalization and variational methods, converted to layout dimensions.

NetKet JAX models
netket

<a id="notebooks-pulse"></a>

## 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](#id47), [MGRW09](#id57)].

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.

QuTiP-QIP JAX models
qutip

<a id="notebooks-differentiable"></a>

## 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.

Circulax Optax
models circulax

<a id="notebooks-external"></a>

## 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](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/josephsoncircuits_twpa.html.md) - 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](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/vacask_lumped_parametric_amplifier.html.md) - 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](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/vacask_cpw_parametric_amplifier.html.md) - 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](https://codeberg.org/arpadbuermen/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.

MATLAB RF Toolbox
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](https://se.mathworks.com/help/rf/index.html) 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](https://github.com/mathworks/jupyter-matlab-proxy).

<a id="notebook-extras"></a>

## 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

```bash
# 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

```bash
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

```bash
# 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]`,<br/>`scikit-rf`, `sympy`, `polars`, `pandas[parquet]` | The analytical and S-parameter model library (`qpdk.models`), SAX circuit<br/>simulation, meshing, and the DataFrame display helpers. **This is the baseline<br/>extra — nearly every notebook needs it.**                                                                                                      |
| `hfss`           | `gplugins[ansys]`, `pyaedt[graphics]`                                                                             | Ansys AEDT drivers (HFSS, Q2D, Q3D) from `gplugins.ansys`. Also requires a<br/>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<br/>with `qpdk.simulation.comsol` for the QPDK layout and materials. Building and<br/>solving require a COMSOL installation and license; RF solves also need the RF<br/>Module. MPh itself is only a client and installs no solver. |
| `circulax`       | `circulax`, `optax`                                                                                               | Differentiable (JAX/DAE) circuit simulation: harmonic-balance and transient<br/>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<br/>notebook.                                                                                                                                                                                                                            |

#### NOTE
These notebook dependencies are deliberately *not* extras:

- A CUDA build of JAX or experimental `jax-mps` is needed only to record new
  measurements for [JAX Backend Comparison for Quantum Circuit Simulation](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/jax_backend_comparison.html.md). 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](https://github.com/mathworks/jupyter-matlab-proxy), needed by
  [Call qpdk from MATLAB](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/matlab_integration.html.md), are not Python packages managed by `qpdk`.
- The [VACASK](https://codeberg.org/arpadbuermen/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.

<a id="notebook-summary"></a>

## Summary table

Every notebook at a glance; the **Extras** column links back to [Installing optional extras](#notebook-extras).

| Notebook                                                                                                                | Category                                     | Key tools                                           | Extras                                                |
|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|-----------------------------------------------------|-------------------------------------------------------|
| [QPDK Models](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/all_models.html.md)                                                              | S-parameter models                           | qpdk, JAX                                           | `models`                                              |
| [Circuit Simulation with QPDK](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/circuit_simulation_demo.html.md)                                             | S-parameter models                           | SAX, JAX                                            | `models`                                              |
| [Resonator frequency estimation models](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/resonator_frequency_model.html.md)                                    | S-parameter models                           | SAX                                                 | `models`                                              |
| [Monte Carlo Fabrication Tolerance Analysis](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/monte_carlo_fabrication_tolerance.html.md)                               | S-parameter models                           | SAX, JAX, gdsfactory                                | `models`, `ray`                                       |
| [Model Comparison to Qucs-S](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/model_comparison_to_qucs.html.md)                                               | S-parameter models                           | SAX, Qucs-S                                         | `models`                                              |
| [JAX Backend Comparison for Quantum Circuit Simulation](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/jax_backend_comparison.html.md)                    | S-parameter models                           | SAX, JAX                                            | `models` (GPU plugins only for recording)             |
| [Q2D Cross-Section Impedance of a Coplanar Waveguide](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_q2d_cpw_impedance.html.md)                      | FEM electromagnetics                         | Ansys Q2D, PyAEDT                                   | `models`, `hfss`                                      |
| [HFSS Eigenmode Simulation of a CPW Resonator](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_eigenmode_resonator.html.md)                             | FEM electromagnetics                         | Ansys HFSS, PyAEDT                                  | `models`, `hfss`                                      |
| [HFSS Driven Modal Simulation of an Interdigital Capacitor](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/hfss_driven_capacitor.html.md)                | FEM electromagnetics                         | Ansys HFSS, PyAEDT                                  | `models`, `hfss`                                      |
| [Elmer Capacitance Extraction of an Interdigital Capacitor](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/elmer_capacitance_interdigital.html.md)                | FEM electromagnetics                         | Elmer, meshwell                                     | `models` (+ `gplugins[elmer]` from Git until release) |
| [COMSOL Full-Wave Simulation of a Coupled Quarter-Wave Resonator](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/comsol_cpw_resonator.html.md)          | FEM electromagnetics                         | COMSOL, MPh                                         | `comsol`                                              |
| [COMSOL transmon capacitance and field](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/comsol_qubit_capacitance.html.md)                                    | FEM electromagnetics                         | COMSOL, MPh                                         | `comsol`                                              |
| [Optuna Optimization of Interdigital Capacitor](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/optimize_capacitor_optuna.html.md)                            | FEM optimization                             | Optuna, Palace                                      | `models`                                              |
| [Dispersive Shift of a Transmon–Resonator System with scQubits](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/scqubits_parameter_calculation.html.md)            | Hamiltonian analysis                         | scQubits                                            | `models`, `scqubits`                                  |
| [Dispersive Shift of a Transmon–Resonator System with Pymablock](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/pymablock_dispersive_shift.html.md)           | Hamiltonian analysis                         | Pymablock, SymPy                                    | `models`, `pymablock`                                 |
| [Transmon Qubit Design with NetKet](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/netket_transmon_design.html.md)                                        | Hamiltonian analysis                         | NetKet, JAX                                         | `models`, `netket`                                    |
| [Pulse-Level Simulation of Superconducting Qubits with QuTiP-QIP](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/qutip_qip_pulse_simulation.html.md)          | Pulse-level simulation                       | QuTiP-QIP, JAX                                      | `models`, `qutip`                                     |
| [Differentiable Transmon Circuit Simulation with Circulax](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/circulax_transmon_optimization.html.md)                 | Differentiable circuit simulation            | Circulax, JAX, Optax                                | `models`, `circulax`                                  |
| [Josephson traveling-wave parametric amplifiers with JosephsonCircuits.jl](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/josephsoncircuits_twpa.html.md) | TWPA harmonic balance and quantum efficiency | JosephsonCircuits.jl, PythonCall (Julia kernel)     | `models`                                              |
| [Lumped Josephson parametric amplifiers with VACASK](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/vacask_lumped_parametric_amplifier.html.md)                       | Lumped JPA harmonic balance                  | VACASK (external program)                           | `models`                                              |
| [CPW parametric amplifiers: layout and circuit models](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/vacask_cpw_parametric_amplifier.html.md)                     | CPW JPA model qualification                  | VACASK (external program), SAX                      | `models`                                              |
| [Call qpdk from MATLAB](https://gdsfactory.github.io/quantum-rf-pdk/notebooks/matlab_integration.html.md)                                                    | External integration                         | MATLAB, RF Toolbox (optional), jupyter-matlab-proxy | `models`                                              |

## References