Quantum VQE Waveguide Solver

Variational Quantum Eigensolver for computing electromagnetic modes of vacuum and cold-plasma-filled rectangular waveguides.

Overview

This repository implements a Variational Quantum Algorithm (VQA) to solve eigenvalue problems arising in rectangular waveguide theory:

Regime	Equation	Eigenvalue
Vacuum	$(-\partial_{xx} - \partial_{yy}) \Psi = \lambda\Psi$	$\lambda = \omega_{\text{cutoff}}^2 / c^2$
Cold Plasma (O-mode)	$(-\partial_{xx} - \partial_{yy} + \omega_p^2/c^2) E_3 = (\omega^2/c^2) E_3$	$\lambda = \omega^2 / c^2$

The spatial domain is discretised on a $2^{n_x} \times 2^{n_y}$ grid and encoded into $n_x + n_y$ qubits. A hardware-efficient ansatz (HEA) with Ry gates and CNOT entanglers is optimised with L-BFGS-B.

This is the physical representation of our system.

ML Warm-Start

An MLP neural network is trained to predict good initial circuit parameters $\theta_0$ from the problem configuration (grid size, mode index, plasma density), replacing random initialisation.

Repository Structure

├── src/
│   ├── __init__.py
│   ├── coldplasma_vqe_waveguide.py   # Core VQE solver
│   └── ml_warmstart_vqe.py           # ML warm-start extension
│
├── notebooks/
│   ├── 01_vacuum_waveguide.ipynb      # Vacuum TM/TE modes
│   ├── 02_cold_plasma_waveguide.ipynb # Plasma modes (no ML)
│   ├── 03_train_ml_warmstart.ipynb    # Train the ML predictor
│   └── 04_cold_plasma_with_ml.ipynb   # Plasma modes with ML warm-start
│
├── warmstart_models/                  # Trained MLP models (joblib)
├── data/                              # Training data for ML warm-start
├── figures/                           # Generated plots
├── .github/workflows/ci.yml           # Test workflow
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── README.md

Installation

Editable install (recommended — this also wires up from src import ...):

pip install -e .

To additionally run the notebooks and the test suite:

pip install -e ".[notebooks,dev]"

Or, for a plain runtime environment:

pip install -r requirements.txt

Quick Start

1. Run a vacuum waveguide simulation

from src import WaveguideModeVQA

solver = WaveguideModeVQA(
    nx=2, ny=2, n_layers=2,
    mode_type='TM',
    Lx=0.015, Ly=0.010,
)

eigenvalue, params, history = solver.optimize_mode(k=0)
solver.print_plot_parameters(0, eigenvalue, params)

2. Add a plasma fill

solver = WaveguideModeVQA(
    nx=2, ny=2, n_layers=2,
    mode_type='TM',
    Lx=0.015, Ly=0.010,
    plasma_density=1e17,   # Uniform Ne = 10^17 m^-3
)

eigenvalue, params, history = solver.optimize_mode(k=0)
solver.print_plasma_info(eigenvalue)

3. Use ML warm-start

from src import WarmStartPredictor, WarmStartVQA

# Load pre-trained predictor
predictor = WarmStartPredictor(
    data_path='data/warmstart_data.json',
    model_dir='warmstart_models',
)

# Solve with warm-start
solver = WarmStartVQA(
    nx=2, ny=2, n_layers=2,
    mode_type='TM',
    plasma_density=1e17,
    predictor=predictor,
)

eigenvalue, params, history = solver.optimize_mode(k=0)

Notebooks

Notebook	Description
01_vacuum_waveguide.ipynb	Compute TM and TE cutoff modes of a vacuum waveguide. Compares VQE results against classical diagonalisation.
02_cold_plasma_waveguide.ipynb	Solve O-mode eigenvalues with uniform and Gaussian plasma profiles. Includes a density sweep.
03_train_ml_warmstart.ipynb	Full ML training pipeline: data collection → MLP training → diagnostics → benchmarking.
04_cold_plasma_with_ml.ipynb	Side-by-side comparison of ML warm-start vs random initialisation convergence.

Results

Reference cutoff frequencies for a 15 mm × 10 mm vacuum waveguide on a 16 × 8 grid (classical diagonalisation of the finite-difference operator):

Mode	TM $\lambda$ (m⁻²)	TM $f$ (GHz)	TE $\lambda$ (m⁻²)	TE $f$ (GHz)
0	141 158	17.93	43 724	9.98
1	270 651	24.82	97 434	14.89
2	418 627	30.87	141 158	17.93
3	480 934	33.09	173 216	19.86

The VQE reproduces these to high accuracy. For a uniform-plasma O-mode example, the VQE eigenvalue agrees with the dense numerical eigenvalue to a relative error of about 0.015%. See the notebooks for full convergence plots.

Tests

pip install -e ".[dev]"
pytest

The suite checks operator symmetry, that adding plasma shifts the spectrum upward, and that the VQE ground mode matches classical diagonalisation within tolerance.

Dependencies

• Python ≥ 3.10
• Qiskit ≥ 1.0
• qiskit-algorithms
• NumPy, SciPy, Matplotlib
• scikit-learn, joblib (for ML warm-start)

See requirements.txt for exact versions.

Physics Background

Vacuum Waveguide

For a rectangular waveguide of dimensions $L_x \times L_y$ with perfectly conducting walls, the transverse eigenvalue problem reduces to the 2D Helmholtz equation. The analytical cutoff frequencies for TM modes are:

$$f_{mn} = \frac{c}{2}\sqrt{\left(\frac{m}{L_x}\right)^2 + \left(\frac{n}{L_y}\right)^2}$$

Cold Plasma O-Mode

When the waveguide is filled with a cold magnetised plasma, the O-mode (ordinary mode) propagation is governed by a modified Helmholtz equation where the plasma frequency $\omega_p$ shifts the eigenvalue spectrum upward. The plasma frequency depends on the local electron density:

$$\omega_p^2(x,y) = \frac{q_e^2, N_e(x,y)}{m_e, \varepsilon_0}$$

Citation

If you use this code in your research, please cite:

@software{quantum_vqe_waveguide,
  title  = {Quantum VQE Waveguide Solver with ML Warm-Start},
  author = {Juan Manuel},
  year   = {2026},
  url    = {https://github.com/JuanManuelsm95/quantum-vqe-waveguide}
}

License

MIT License — see LICENSE for details.