Add quantum exact lanczos

[wsttiger]

Add Quantum Exact Lanczos (QEL) Algorithm to CUDA-Q Solvers

This PR introduces a complete implementation of the Quantum Exact Lanczos (QEL) algorithm for computing ground state energies of molecular Hamiltonians using hybrid quantum-classical methods.

Overview

QEL uses block encoding and amplitude amplification to build a Krylov subspace from quantum moment measurements, then solves a generalized eigenvalue problem classically to extract ground state energies. This implementation provides both C++ and Python interfaces with comprehensive testing on five molecular systems.

Key Components

Core Algorithm (quantum_exact_lanczos.cpp, 340 lines)

• PREPARE-SELECT-REFLECT circuits for quantum moment collection
• Observable construction for ancilla projectors (R̂ and Û operators)
• Krylov matrix construction (Hamiltonian H and overlap S matrices)
• Clean free-function API returning matrices for user-level eigenvalue solving

Block Encoding Support (block_encoding.cpp)

• Expanded PauliLCU preparation kernel from 10 to 20 ancilla qubits
• Now supports Hamiltonians with up to 2²⁰ (~1M) Pauli terms
• Essential for large molecular systems (e.g., LiH with 630 terms)

Python Bindings (py_block_encoding.cpp, 379 lines)

• BlockEncoding abstract base class
• PauliLCU with NumPy array accessors for debug/inspection
• QELResult container with get_hamiltonian_matrix(), get_overlap_matrix()
• quantum_exact_lanczos() function with krylov_dim, shots, verbose kwargs

Comprehensive Testing

• C++ unit tests: 3 test cases (operators, H2 molecule, metadata)
• Python unit tests: 7 test cases covering API, inheritance, and simple Hamiltonians
• Molecular tests: 5 molecular systems with CASCI reference energies

Molecular Test Coverage

Molecule	Qubits	Active Space	Pauli Terms	Error (mHa)	Runtime
H₂	4	(2e, 2o)	3	0.11	~30s
LiH	12	(4e, 6o)	630	0.66	~206s
N₂	8	(4e, 4o)	80	0.33	~45s
H₂O	8	(4e, 4o)	104	0.22	~50s
C₆H₆ (Benzene)	8	(4e, 4o)	160	0.76	~8.5s

All tests achieve sub-mHa accuracy (chemical accuracy is 2.5 mHa).

Design Highlights

1. Proper Constant Term Handling

• Critical fix: Constant terms kept separate from Hamiltonian to preserve 1-norm
• Adding constant to SpinOperator inflates normalization incorrectly
• Energy formula: E = eigenvalue * α + constant (constant added manually)

2. S-Matrix Filtering for Numerical Stability

• Krylov overlap matrix can become ill-conditioned
• Python tests filter S eigenvalues (threshold ~1e-4) before solving
• Ensures robust eigenvalue extraction

3. Pre-Extracted Hamiltonians

• All molecular data extracted via cudaq_solvers.create_molecule()
• Ensures reproducibility without PySCF/OpenFermion runtime dependency
• Data files include CASCI/CCSD reference energies for validation

4. Scalable Architecture

• Stateless quantum kernels compatible with CUDA-Q compiler
• No C++ linear algebra dependencies (user handles eigensolving in Python)
• Row-major matrix flattening for seamless NumPy integration

Example Usage

import numpy as np
from scipy import linalg
from cudaq import spin
import cudaq_solvers as solvers

# Define a simple Hamiltonian
h = 0.5 * spin.z(0) + 0.3 * spin.z(1) + 0.2 * spin.x(0) * spin.x(1)

# Run QEL
result = solvers.quantum_exact_lanczos(
    h, 
    num_qubits=2, 
    n_electrons=2,
    krylov_dim=4,
    shots=-1
)

# Extract Krylov matrices
H = result.get_hamiltonian_matrix()
S = result.get_overlap_matrix()

# Apply S-matrix filtering for numerical stability
threshold = 1e-4
evals_S, evecs_S = np.linalg.eigh(S)
keep = [i for i, e in enumerate(evals_S) if e > threshold]

# Solve in filtered subspace
V = evecs_S[:, keep]
H_proj = V.T @ H @ V
S_proj = np.diag(evals_S[keep])
S_inv_sqrt = np.diag(1.0 / np.sqrt(np.diag(S_proj)))
H_final = S_inv_sqrt @ H_proj @ S_inv_sqrt

eigenvalues = np.linalg.eigvalsh(H_final)

# Ground state energy (scaled by normalization + constant)
E_ground = eigenvalues[0] * result.normalization + result.constant_term
print(f"Ground state energy: {E_ground:.6f} Ha")For complete molecular examples, see `libs/solvers/python/cudaq_solvers/examples/qel_h2_example.py`.

Documentation

• README_QEL.md: Complete API reference, algorithm description, usage examples
• qel_h2_example.py: 5 working examples demonstrating QEL on H2 molecule
• qel_test_molecules.md: Catalog of current and proposed molecular test systems