Quantum Simulation Suite — VQE + QPE (PennyLane)

A modern, modular, and fully reproducible quantum-chemistry simulation suite built on
PennyLane, featuring:

• Variational Quantum Eigensolver (VQE)
• State-Specific VQE (SSVQE)
• Quantum Phase Estimation (QPE)
• Unified molecule registry, geometry generators, and plotting tools
• Consistent caching and reproducibility across all solvers

This project refactors all previous notebooks into a clean Python package with
a shared vqe_qpe_common/ layer for Hamiltonians, molecules, geometry, and plotting.

How to get started

• For the full background on VQE and QPE: see THEORY.md
• For CLI usage and automation: see USAGE.md
• For conceptual understanding: see H2_VQE_vs_QPE_From_Scratch.ipynb

These documents complement this 'README.md' and provide the theoretical foundation and hands-on execution details of the VQE/QPE suite.

---

Project Structure

Variational_Quantum_Eigensolver/
├── README.md
├── THEORY.md
├── USAGE.md
├── LICENSE
├── pyproject.toml
│
├── vqe/                     # VQE package
│   ├── __main__.py          # CLI: python -m vqe
│   ├── core.py              # VQE orchestration (runs, scans, sweeps)
│   ├── engine.py            # Devices, noise, ansatz/optimizer plumbing
│   ├── ansatz.py            # UCCSD, RY-CZ, HEA, minimal ansätze
│   ├── optimizer.py         # Adam, GD, Momentum, SPSA, etc.
│   ├── hamiltonian.py       # VQE-specific wrapper → uses vqe_qpe_common.hamiltonian
│   ├── io_utils.py          # JSON caching, run signatures
│   ├── visualize.py         # Convergence, scans, noise plots
│   └── ssvqe.py             # Subspace-search VQE (excited states)
│
├── qpe/                     # QPE package
│   ├── __main__.py          # CLI: python -m qpe
│   ├── core.py              # Controlled-U, trotterized dynamics, iQFT
│   ├── hamiltonian.py       # QPE-specific wrapper → uses vqe_qpe_common.hamiltonian
│   ├── io_utils.py          # JSON caching, run signatures
│   ├── noise.py             # Depolarizing + amplitude damping channels
│   └── visualize.py         # Phase histograms + sweep plots
│
├── vqe_qpe_common/          # Shared logic for VQE + QPE
│   ├── molecules.py         # Unified molecule registry
│   ├── geometry.py          # Bond/angle geometry generators
│   ├── hamiltonian.py       # Unified Hamiltonian builder (PennyLane/OpenFermion)
│   └── plotting.py          # Shared plotting + filename builders
│
├── images/                  # Saved png files
│   ├── vqe/
│   └── qpe/
│
├── results/                 # JSON outputs
│   ├── vqe/
│   └── qpe/
│
└── notebooks/
    ├── getting_started/     # Intro notebook implementing VQE and QPE from scratch
    ├── vqe/                 # Importing from the vqe/ package
    └── qpe/                 # Importing from the qpe/ package

This structure ensures:

• VQE and QPE share the same chemistry (vqe_qpe_common/)
• All results are cached consistently (results/)
• All plots use one naming system (vqe_qpe_common/plotting.py)
• CLI tools are production-ready (python -m vqe, python -m qpe)

---

⚙️ Installation

Install from PyPI

pip install vqe-pennylane

Install from source (development mode)

git clone https://github.com/SidRichardsQuantum/Variational_Quantum_Eigensolver.git
cd Variational_Quantum_Eigensolver
pip install -e .

Confirm installation

python -c "import vqe, qpe; print('VQE+QPE imported successfully!')"

---

Common Core (Shared by VQE & QPE)

The following modules ensure full consistency between solvers:

Module	Purpose
vqe_qpe_common/molecules.py	Canonical molecule definitions
vqe_qpe_common/geometry.py	Bond/angle/coordinate generators
vqe_qpe_common/hamiltonian.py	Hamiltonian construction + OpenFermion fallback
vqe_qpe_common/plotting.py	Unified filename builder + PNG export

---

🔹 VQE Package

Features:

• Ground-state VQE
• Excited-state SSVQE
• Geometry scans
• Noise sweeps
• Mapping comparisons
• Optimizer registry
• Result caching

Run example:

from vqe.core import run_vqe
result = run_vqe("H2", ansatz_name="UCCSD", optimizer_name="Adam", n_steps=50)
print(result["energy"])

---

🔹 QPE Package

Features:

• Noiseless & noisy QPE
• Trotterized exp(-iHt)
• Inverse QFT
• Noise channels
• Cached results

Example:

from pennylane import qchem
from vqe_qpe_common.hamiltonian import build_hamiltonian
from qpe.core import run_qpe

symbols = ["H", "H"]
coords = [[0.0, 0.0, 0.0], [0.0, 0.0, 0.7414]]

H, n_qubits = build_hamiltonian(symbols, coords, 0, "STO-3G")
hf_state = qchem.hf_state(2, n_qubits)

result = run_qpe(hamiltonian=H, hf_state=hf_state, n_ancilla=4)

---

CLI Usage

VQE

python -m vqe -m H2 -a UCCSD -o Adam --steps 50

QPE

python -m qpe --molecule H2 --ancillas 4 --shots 2000

---

🧪 Tests

pytest -v

---

📘 Author: Sid Richards (SidRichardsQuantum)

LinkedIn: https://www.linkedin.com/in/sid-richards-21374b30b/

This project is licensed under the MIT License - see the LICENSE file for details.