Metadata-Version: 2.4
Name: hamiltonian-vqe-kit
Version: 0.1.0
Summary: Validated, honest VQE and ADAPT-VQE toolkit for chemical accuracy and honest cost accounting
Author-email: Ashraf Khan <research@appliedquantum.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/aashiq-parinda/hamiltonian-vqe-kit
Project-URL: Repository, https://github.com/aashiq-parinda/hamiltonian-vqe-kit
Project-URL: Issues, https://github.com/aashiq-parinda/hamiltonian-vqe-kit/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Provides-Extra: chemistry
Requires-Dist: pyscf>=2.4.0; platform_system != "Windows" and extra == "chemistry"
Requires-Dist: openfermion>=1.6.0; extra == "chemistry"
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Provides-Extra: exporters
Requires-Dist: qiskit>=1.0.0; extra == "exporters"
Requires-Dist: pennylane>=0.35.0; extra == "exporters"
Requires-Dist: cirq-core>=1.3.0; extra == "exporters"
Provides-Extra: all
Requires-Dist: hamiltonian-vqe-kit[chemistry,dev,exporters,ml]; extra == "all"
Dynamic: license-file

# Hamiltonian VQE Kit (`hvk`)

[![CI](https://github.com/aashiq-parinda/hamiltonian-vqe-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/aashiq-parinda/hamiltonian-vqe-kit/actions)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![Prior Work DOI](https://img.shields.io/badge/Prior%20Work-10.5281%2Fzenodo.22013110-blue.svg)](https://doi.org/10.5281/zenodo.22013110)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type Checked: Mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)

**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

| Module | Purpose |
| :--- | :--- |
| **`hvk.chemistry`** | PySCF & OpenFermion Hamiltonian loaders, Jordan-Wigner transformation, Pauli parsing, FCI & HF reference solutions |
| **`hvk.audit`** | Hamiltonian 2-body interaction graph analysis and wasted CNOT audit vs. rigid hardware-efficient ansätze (HEA) |
| **`hvk.adapt`** | Exact ADAPT-VQE engine with fermionic/qubit operator pools, commutator gradients, and strict measurement tracking |
| **`hvk.ansatz`** | Deterministic, connected sparse ansatz generator derived directly from Hamiltonian interaction topology |
| **`hvk.init`** | Principled statevector initializers (Random, Hartree-Fock, Perturbation-Adjusted HF, Guarded Residual ML) |
| **`hvk.diagnostics`** | Barren plateau gradient variance analyzers and realistic NISQ energy-error-under-noise benchmarks |
| **`hvk.exporters`** | Zero-overhead circuit and operator export to Qiskit, PennyLane, and Cirq |
| **`hvk.cli`** | Unified command-line interface (`hvk audit | adapt | build | init | diagnose | benchmark`) |

---

## ⚖️ 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

```bash
# 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)

```bash
# 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:

```bibtex
@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](https://doi.org/10.5281/zenodo.22013110).

---

## 📄 License

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