VQE Baseline

Variational Quantum Eigensolver (VQE) baseline implementation for quantum chemistry benchmarks using CUDA-Q.

TLDR

# Install dependencies
uv sync

# Run VQE on H2 molecule
uv run python main.py

# Run on different molecule
uv run python main.py --molecule LiH

# List available molecules
uv run python main.py --list-molecules

Overview

This project provides a modular VQE implementation using:

• CUDA-Q: NVIDIA quantum circuit simulation framework
• PyTorch: Neural quantum state (NQS) for initial state preparation
• PySCF + OpenFermion: Molecular Hamiltonian construction via Jordan-Wigner transformation

Features

• Pre-defined molecular geometries (H2, LiH, BeH2, H2O, NH3, CH4, N2, O2, F2, etc.)
• Hardware-efficient ansatz circuits (RY-RZ rotations with configurable entangling patterns)
• Adaptive parallelization (automatic GPU/CPU detection and strategy selection)
• Classical benchmarks (HF, FCI, CCSD, CCSD(T) energy comparison)

Project Structure

vqe_baseline/
├── main.py              # Main entry point
├── config.yaml          # Configuration file
├── pyproject.toml       # Project metadata and dependencies (uv)
├── models.py            # Neural network models (FFNN)
├── moleculars.py        # Molecular data and PySCF interface
├── vqe_ansatz.py        # VQE circuit definitions
├── vqe_optimizer.py     # VQE optimization logic (L-BFGS-B)
├── vqe_parallel.py      # Parallelization strategies
├── vqe_utils.py         # Utility functions
├── requirements.txt     # Python dependencies (legacy pip)
└── tests/               # Test suite

Installation

Prerequisites

• Python 3.10-3.13
• CUDA-Q (see https://nvidia.github.io/cuda-quantum/latest/install.html)
• NVIDIA GPU (optional, but recommended)

Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and create virtual environment
uv sync

# Run with uv
uv run python main.py

Using pip (Legacy)

pip install -r requirements.txt
python main.py

CUDA-Q

CUDA-Q is now included in the dependencies and will be installed automatically via uv sync.

System requirements:

• Linux x86_64 (Ubuntu 22.04+ recommended)
• NVIDIA GPU with CUDA 12.x support (optional, for GPU acceleration)
• Python 3.10-3.13

For CPU-only mode, CUDA-Q will use the qpp-cpu backend automatically.

Usage

Basic Commands

# Run with default configuration (H2)
uv run python main.py

# Specify molecule
uv run python main.py --molecule LiH

# Use custom configuration file
uv run python main.py --config my_config.yaml

# List available molecules
uv run python main.py --list-molecules

# Force CPU device
uv run python main.py --device cpu

Configuration

Edit config.yaml:

# Target molecule
molecule_name: 'H2'

# VQE parameters
vqe_params:
  n_layers: 2              # Ansatz depth
  max_iterations: 500      # Optimization iterations
  ansatz: 'hardware_efficient'

# NQS pre-training
nqs_params:
  alpha: 3                 # Hidden layer size factor
  n_layers: 3              # Neural network depth
  pretrain_epochs: 100     # VMC pre-training epochs

Workflow

1. Molecular Setup: Load geometry and construct qubit Hamiltonian
2. NQS Pre-training: Train neural quantum state using VMC (optional)
3. VQE Optimization: Optimize variational parameters using L-BFGS-B
4. Benchmarking: Compare VQE energy with classical methods

Ansatz Options

Ansatz	Description	Parameters
hardware_efficient	RY-RZ + fully-connected CNOT	2n(L+1)
ring	RY-RZ + ring CZ	2n(L+1)
expressive	RY-RZ-RY + fully-connected CNOT	3nL + 2n

Where n = number of qubits, L = number of layers.

Parallelization Strategies

Automatic selection based on hardware:

Hardware	Strategy	Description
Multi-GPU	multi_gpu	Distribute gradient computation across GPUs
Single GPU	single_gpu	GPU-accelerated sequential execution
CPU (small systems)	cpu_multiprocess	Python multiprocessing
CPU (large systems)	cpu_openmp	OpenMP internal parallelization

Available Molecules

Molecule	Basis	Spin	Qubits
H2	sto-3g	0	4
LiH	sto-3g	0	12
BeH2	sto-3g	0	14
H2O	sto-3g	0	14
NH3	sto-3g	0	16
CH4	sto-3g	0	18
N2	sto-3g	0	20
O2	sto-3g	2	20
F2	sto-3g	0	20

Example Output

============================================================
VQE Benchmark: H2
============================================================

Classical Reference Energies:
  Hartree-Fock: -1.11675930 Ha
  FCI:          -1.13727618 Ha
  CCSD:         -1.13727618 Ha
  CCSD(T):      -1.13727618 Ha

[VQE Init] Initial energy (from NQS) = -1.10234567 Ha
[VQE Init] Parameter count = 16
[VQE Parallel] Single GPU mode, sequential parameter-shift
...
[VQE Complete] Final Energy: -1.13725432 Ha

============================================================
Results Summary
============================================================
  VQE Energy:    -1.13725432 Ha
  Error vs FCI:  0.00002186 Ha (0.0219 mHa)

Testing

# Run all tests
uv run python tests/run_all_tests.py

# Run quick tests (skip CUDA-Q dependent tests)
uv run python tests/run_all_tests.py --quick

# Run specific test module
uv run python tests/test_moleculars.py

Dependencies

Package	Version	Purpose
torch	>= 2.0.0	Neural network backend
numpy	>= 1.21.0, < 2.0.0	Numerical operations
scipy	>= 1.7.0	Optimization (L-BFGS-B)
pyscf	>= 2.0.0	Quantum chemistry integrals
openfermion	>= 1.5.0	Fermionic operators
openfermionpyscf	>= 0.5	PySCF-OpenFermion interface
cudaq	>= 0.13.0	CUDA-Q quantum circuit simulation

License

MIT License