Quantum Simulation Suite

PyPI: https://pypi.org/project/vqe-pennylane/

Docs: https://sidrichardsquantum.github.io/Variational_Quantum_Eigensolver/

PennyLane-based workflows for:

• ground-state VQE
• excited-state methods
• quantum phase estimation
• variational imaginary-time evolution
• variational real-time evolution

Implemented packages:

• vqe for ground-state and excited-state solvers
• qpe for phase-estimation workflows
• qite for projected variational dynamics (VarQITE, VarQRTE)
• common for shared chemistry, Hamiltonians, caching, and plotting

Table of Contents

• What This Repo Is Good For
• Choose A Method
• Install
• Quickstart
• Typical Workflow
• Package Overview
  • vqe
  • qpe
  • qite
• Shared Infrastructure
• Supported Molecule Inputs
• Non-Molecule Mode
• Outputs And Reproducibility
• Notebooks
• Documentation
• Project Roadmap
• Repository Layout
• Testing
• Support Development
• Author
• License

What This Repo Is Good For

Use this repo if you want:

• one Hamiltonian pipeline shared across VQE, QPE, and QITE/QRTE
• one shared problem-resolution layer for molecule, explicit-geometry, and expert-mode inputs
• reproducible runs with stable cache keys and JSON outputs
• both Python APIs and CLI workflows
• notebooks that separate demos from benchmarks

It is optimized for small-molecule algorithm development and comparison, not large-scale production chemistry.

Choose A Method

Use VQE when you want a ground-state energy or a good reference state.

Use ADAPT-VQE when you want an adaptive ansatz rather than a fixed one.

Use QSE, EOM-QSE, LR-VQE, or EOM-VQE when you already have a converged VQE reference and want excited-state information.

Use SSVQE or VQD when you want variational excited-state solvers directly.

Use QPE when you want spectral / phase information rather than a compact variational state.

Use VarQITE when you want imaginary-time relaxation toward a low-energy state.

Use VarQRTE when you already have a relevant state and want to evolve it in real time and analyze observables.

Use expert-mode Hamiltonian inputs when you want to benchmark algorithms on non-chemistry qubit models without going through the molecule / geometry pipeline.

Install

Supported Python versions are 3.10–3.12, with numpy>=1.23,<2.0 and pennylane>=0.42,<0.45. Python 3.13 support is deferred until the NumPy 2 compatibility migration is complete.

From PyPI:

pip install vqe-pennylane

From source:

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

Verify:

python -c "import vqe, qpe, qite, common; print('Quantum stacks imported successfully')"

Quickstart

Python:

import pennylane as qml

from vqe import run_vqe
from qite import run_qite, run_qrte

vqe_res = run_vqe(molecule="H2")
print("VQE:", vqe_res["energy"])

qite_res = run_qite(molecule="H2", steps=75, dtau=0.2)
print("VarQITE:", qite_res["energy"])

qrte_res = run_qrte(molecule="H2", steps=20, dt=0.05)
print("VarQRTE final energy:", qrte_res["energy"])

H_model = qml.Hamiltonian([1.0, 0.5], [qml.PauliZ(0), qml.PauliX(0)])
model_res = run_vqe(
    hamiltonian=H_model,
    num_qubits=1,
    reference_state=[1],
    ansatz_name="RY-CZ",
    steps=10,
    plot=False,
)
print("Model VQE:", model_res["energy"])

run_vqe() uses the calibrated default stepsize for the selected optimizer when stepsize is omitted. The vqe CLI does the same when --stepsize is omitted.

CLI:

python -m vqe -m H2
python -m qpe --molecule H2 --ancillas 4 --shots 1000 --trotter-steps 2
python -m qite run --molecule H2 --steps 75 --dtau 0.2
python -m qite run-qrte --molecule H2 --steps 20 --dt 0.05

Typical Workflow

For stationary-state work:

1. run VQE to get a ground-state reference
2. run post-VQE or excited-state solvers if needed
3. compare against exact small-system references where possible

For dynamics:

1. prepare a state with VQE, VarQITE, or an excited-state workflow
2. use VarQRTE for real-time dynamics
3. benchmark against exact evolution on small systems when possible

Package Overview

vqe

Includes:

• run_vqe
• run_vqe_low_qubit_benchmark
• run_adapt_vqe
• run_lr_vqe
• run_eom_vqe
• run_qse
• run_eom_qse
• run_ssvqe
• run_vqd

Use it for:

• ground-state optimization
• low-qubit multi-molecule benchmarking
• excited-state studies
• ansatz / optimizer / mapping comparisons
• geometry scans
• noisy VQE experiments

qpe

Includes:

• run_qpe

Use it for:

• phase-to-energy estimation
• ancilla / shot studies
• controlled time-evolution experiments

Default QPE settings are H2-calibrated baseline defaults:

• n_ancilla=4
• t=1.0
• trotter_steps=2
• shots=1000

They are intended as good small-molecule starting values, not globally optimized settings for every molecule.

qite

Includes:

• run_qite
• run_qrte

Use it for:

• imaginary-time relaxation with VarQITE
• real-time dynamics with VarQRTE
• prepared-state quench workflows

Important:

• VarQITE is a state-finding / relaxation method
• VarQRTE is a dynamics method, not an eigensolver
• for time-independent Hamiltonians, VarQRTE should usually conserve energy up to numerical error

Shared Infrastructure

All solver packages use the same chemistry layer in common/.

That gives you:

• consistent Hamiltonians across algorithms
• comparable outputs across methods
• shared run signatures and cache reuse
• standardized result and image paths

Main shared modules:

• common/molecules.py
• common/geometry.py
• common/hamiltonian.py
• common/problem.py
• common/persist.py
• common/plotting.py
• common/paths.py

Useful shared helpers:

• build_hamiltonian(...)
• get_exact_spectrum(...)
• summarize_registry_coverage(...)

Supported Molecule Inputs

For standard chemistry workflows, prefer the shared molecule pipeline over expert-mode Hamiltonian inputs.

Built-in registry molecules currently include:

• H, H-, H2, H2+, H2-, H3, H3+, H4, H4+, H5+, H6
• He, He+, He2, HeH+
• Li, Li+, LiH
• Be, Be+, BeH2
• B, B+, C, C+, N, N+, O, O+, F, F+, Ne
• H2O

If a target system is not in the registry, use explicit geometry inputs such as symbols=..., coordinates=..., charge=..., multiplicity=..., and basis=.... That keeps the run on the standard chemistry path and avoids expert mode unless you already have a prebuilt qubit Hamiltonian.

For a ready-made inventory of the built-in registry, use:

from common import summarize_registry_coverage

rows = summarize_registry_coverage()

Non-Molecule Mode

The Python APIs also support a direct qubit-Hamiltonian mode for algorithm benchmarking outside chemistry.

Currently supported:

• run_vqe(..., hamiltonian=H, num_qubits=..., reference_state=...)
• run_qite(..., hamiltonian=H, num_qubits=..., reference_state=...)
• run_qrte(..., hamiltonian=H, num_qubits=..., reference_state=...)
• run_qpe(..., hamiltonian=H, hf_state=..., system_qubits=...)

Notes:

• this is a Python expert-mode API, not a CLI feature
• integer wire labels that fit the resolved register are preserved; otherwise labels are normalized in first-appearance order, which defines the reference bitstring order
• run_qpe(...) expert mode requires both hamiltonian and hf_state
• ansatz_name="auto" can select a conservative model ansatz for recognized Pauli structures such as TFIM, XXZ/Heisenberg, and SSH-like hopping chains
• chemistry-specific ansatzes like UCCSD still require chemistry metadata; for generic or unclassified model Hamiltonians use ansatz_name="auto" or explicit non-chemistry ansatzes such as RY-CZ, Minimal, or StronglyEntanglingLayers

Outputs And Reproducibility

Generated outputs are written under the user data directory:

• Linux: ${XDG_DATA_HOME:-~/.local/share}/vqe-pennylane
• macOS: ~/Library/Application Support/vqe-pennylane
• Windows: %LOCALAPPDATA%/vqe-pennylane

Set VQE_PENNYLANE_DATA_DIR to choose a different root. For repository-local output, run export VQE_PENNYLANE_DATA_DIR="$PWD" from the checkout. The override is read when artifacts are accessed, including after Python imports.

Paths beneath that root are:

results/vqe/
results/qpe/
results/qite/
images/vqe/
images/qpe/
images/qite/

General behavior:

• run configurations are hashed deterministically
• matching runs reuse cached JSON records
• expert-mode Hamiltonian runs cache by canonical Pauli-term fingerprint, reference bitstring, resolved ansatz, and solver settings
• cached records missing runtime metadata are treated as stale and recomputed automatically
• v0.3.27 versions cache signatures to recompute results affected by numerical fixes, including spin references and QPE term order; old files are retained
• --force recomputes instead of loading cache

For sampled QPE runs with finite shots, seed still matters because the measured bitstring distribution is stochastic. In analytic mode (shots=None), the seed is effectively irrelevant.

Notebooks

Notebook guide:

• notebooks/README_notebooks.md

Layout:

• notebooks/getting_started/ for usage-oriented demos
• notebooks/benchmarks/ for exact-reference, comparison, and scan workflows

Recommended starting points:

• notebooks/getting_started/01_vqe_vs_qpe_from_scratch_h2.ipynb
• notebooks/getting_started/07_getting_started_qite_h2.ipynb
• notebooks/getting_started/11_getting_started_qrte_h2.ipynb
• notebooks/benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb

Documentation

Introduced in v0.3.28, an optional VQE Experiment Studio provides a browser composer, VQE and ADAPT-VQE execution, live energy observations, experiment comparisons, artifact-backed history, JSON export, and re-run configuration restoration. Run it from a source checkout with python -m studio; the Studio is excluded from the wheel and source distribution. It calls the existing Python solvers and adds no dependencies to the scientific package. See the guide for fresh Codespaces setup commands.

The repository documentation can be built as a navigable Sphinx site:

pip install -e ".[docs]"
python -m sphinx -W -b html docs docs/_build/html

Use these in order:

1. README.md for orientation and quickstart
2. USAGE.md for CLI and Python entrypoints
3. THEORY.md for algorithmic background
4. RESEARCH.md for benchmark evidence standards
5. notebooks/README_notebooks.md for notebook navigation

Deeper implementation notes:

• more_docs/architecture.md
• more_docs/vqe/
• more_docs/qpe/
• more_docs/qite/

Project Roadmap

• ROADMAP.md tracks package engineering work for installation, numerical API correctness, CI, and distribution quality.
• notebooks/BENCHMARK_ROADMAP.md remains the focused backlog for research-validation notebooks.

Repository Layout

Variational_Quantum_Eigensolver/
├── vqe/
├── qpe/
├── qite/
├── common/
├── notebooks/
│   ├── getting_started/
│   └── benchmarks/
├── results/
├── images/
├── README.md
├── ROADMAP.md
├── USAGE.md
├── THEORY.md
└── pyproject.toml

Testing

The default pytest target is the fast development suite. Slow chemistry checks and selected subprocess CLI integration tests are marked separately.

pytest -q

Run the full suite, including slow integration coverage, with:

pytest -q -o addopts=''

Run only the additional slow tests, or inspect test durations, with:

python -m pytest -q -m slow --durations=15

CI runs the fast suite on Python 3.10/3.11/3.12 and the additional slow tests on Python 3.12, without repeating the fast suite in the integration job. Scientific test jobs use OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1; use the same environment settings locally to avoid thread oversubscription.

Release tags must match the project version and reference a commit reachable from main. Publishing waits for validation and uploads the validated package artifacts. There are no scheduled workflows; the advisory NumPy 2 probe is manual-only. See the release guide for the terminal sequence and complete release checks.

Run a registered benchmark suite and write reproducible artifacts with:

python -m common.benchmarks run --suite expert-z-cross-method --out benchmark_runs

List available suites with:

python -m common.benchmarks list

Compare two benchmark runs with:

python -m common.benchmarks compare --base old_run/h2-cross-method --head new_run/h2-cross-method

Support development

If this repository is useful for research, learning, or experimentation, you can support continued development via GitHub Sponsors:

https://github.com/sponsors/SidRichardsQuantum

Sponsorship helps support ongoing work on open-source implementations of quantum algorithms, including improvements to documentation, reproducible workflows, and example notebooks.

Support helps maintain and expand practical tooling for variational quantum methods, quantum simulation workflows, and related experimentation.

Citation

Sid Richards (2026)

Unified Variational and Phase-Estimation Quantum Simulation Suite

Author

Sid Richards

• LinkedIn: sid-richards-21374b30b
• GitHub: SidRichardsQuantum

License

MIT. See LICENSE.