Hamiltonian VQE Kit (hvk)

Hamiltonian VQE Kit (hvk) is an open-source, scientifically validated toolkit designed to take any molecular or qubit Hamiltonian and synthesize a diagnosed VQE / ADAPT-VQE workflow capable of achieving chemical accuracy ($\le 1.6,\text{mHa}$ vs. Full Configuration Interaction / FCI) with strict, verifiable accounting of quantum simulation cost.

📌 Core Modules

⚖️ Non-Negotiable Honesty Rules

This repository operates under strict scientific reproducibility constraints:

1. Zero Hardcoded Numbers: Every metric, iteration count, and energy reported in documentation or tables must be generated by verifiable scripts in benchmarks/results/ recording random seed, commit hash, and dependency versions.
2. FCI/PySCF Parity: All molecular test systems ($H_2$, $\text{LiH}$, $\text{BeH}_2$, $H_4$ chain) must be validated directly against PySCF Hartree-Fock and FCI exact ground states. Tests fail if reference energies diverge.
3. Core is 100% Non-ML: The core toolkit operates with standard numerical computing dependencies (numpy, scipy). Machine learning models are strictly optional extras (pip install hvk[ml]).
4. Honest Baseline Comparisons: ML components must be compared head-to-head against exact non-ML and simple heuristic methods. If ML does not win, the null or negative result will be reported plainly.
5. Guarded Residual Initializer: The residual-ML initializer is explicitly guarded, not guaranteed: it evaluates energy at $\boldsymbol{\theta}{\text{HF}}$ and $\boldsymbol{\theta}{\text{HF}} + \Delta\boldsymbol{\theta}$, returns the lower energy, and falls back to PA-HF when an explicit out-of-distribution (OOD) criterion is triggered.
6. Physical Noise Metric: Noise benchmarks measure ENERGY ERROR under noise vs. the exact ground state with confidence intervals. State fidelity vs. ideal state is only reported if explicitly labeled as such.
7. Strict Measurement Accounting: ADAPT execution tracks every energy evaluation, commutator measurement, and appended operator using documented, deterministic counting conventions.
8. Code Quality Standards: 100% type annotations, comprehensive docstrings, clean ruff and mypy audits, unit tests for every public function, and test coverage $> 85%$.

⚡ Quickstart

Installation

# Core package (zero ML overhead)
pip install hamiltonian-vqe-kit

# With optional chemistry and dev dependencies
pip install "hamiltonian-vqe-kit[chemistry,dev]"

# With optional machine learning extensions
pip install "hamiltonian-vqe-kit[ml]"

Command-Line Interface (CLI)

# 1. Audit Hamiltonian locality and interaction graph
hvk audit H2

# 2. Run exact ADAPT-VQE toward chemical accuracy (<= 1.6 mHa)
hvk adapt LiH --accuracy 0.0016

# 3. Build a sparse ansatz from the interaction graph
hvk build BeH2

# 4. Run barren plateau diagnostic
hvk diagnose H4

# 5. Execute full reproducible multi-molecule benchmark suite
hvk benchmark --output-dir benchmarks/results

⚠️ Limitations and Known Failures

This section is continuously updated as empirical benchmarks are evaluated.

• Phase 0 Status: Initial repository scaffolding and packaging phase. Core chemistry validation (Phase 1) is currently queued.
• Qubit Active Space Boundaries: Phase 1 through Phase 4 focus on small-molecule STO-3G active spaces ($N \le 8$ qubits). Systems exceeding 8 qubits require frozen-core approximations or extended basis set loaders.
• Physical Noise Assumptions: Energy-error-under-noise simulation in Phase 4 models quantum channels via stochastic Kraus operators; cross-talk and drift are not modeled in initial releases.

📜 Prior Work & Citation

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

@software{khan2026hvk,
  author    = {Ashraf Khan},
  title     = {Hamiltonian VQE Kit: Validated, Honest VQE and ADAPT-VQE Toolkit},
  year      = {2026},
  publisher = {GitHub},
  version   = {0.1.0},
  url       = {https://github.com/aashiq-parinda/hamiltonian-vqe-kit}
}

This project builds upon foundational theoretical and architectural insights pre-registered in:

• Ashraf Khan (2026). Rigorous Generalization Study: Transformer-Accelerated VQE Warm-Starting Across Multi-Molecule Families. Zenodo Record #22013110.

📄 License

Licensed under the Apache License, Version 2.0 (the "License"). See LICENSE for details.