From 79c88e97cbfb17bf80119aa7737a13592a7907f3 Mon Sep 17 00:00:00 2001 From: Ayush Asthana Date: Sun, 16 Aug 2026 15:28:34 -0500 Subject: [PATCH 1/2] Polish README documentation --- README.md | 199 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 117 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 2bbade0..463e9ec 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,43 @@ # Benchmark-QC -[![CI](https://github.com/AsthanaLab/BenchmarkQC/actions/workflows/python-package.yml/badge.svg)](https://github.com/AsthanaLab/BenchmarkQC/actions/workflows/python-package.yml) -[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) -[![License](https://img.shields.io/badge/license-BSD--3--Clause-0A7BBB.svg)](LICENSE) -[![Datasets](https://img.shields.io/badge/datasets-78-6E56CF.svg)](datasets/catalog.json) +

+ Portable, checksum-pinned molecular benchmark Hamiltonians for quantum chemistry.
+ Reproducible active-space datasets, normalized integral archives, and Python loaders for quantum-computing research. +

+ +

+ CI + Python 3.10+ + BSD 3-Clause license + 78 dataset entries +

-

+

Documentation · Dataset catalog · Python API · + Contributing · Report an issue

-Benchmark-QC is a versioned collection of molecular quantum-computing -benchmark Hamiltonians and portable active-space integral archives. It puts -the original BenchmarkQC systems and the corrected MolVQE-21 reference cases -in one consistent, checksum-pinned repository. - -## What is included - -The repository contains 78 benchmark catalog entries: 51 BenchmarkQC point -systems and 27 corrected MolVQE-21 point systems. Each bond distance and each -active-space/orbital variant is represented as its own catalog entry: - -- `datasets/benchmarkQC/`: the C2, C2H4, CH2, Fe2S2, FeH, FeS, N2, O2, and U2 - benchmark families, including historical compatibility archives and newer - numeric source archives. -- `datasets/molvqe21/`: 27 MolVQE-21 cases imported from Mushir’s corrected - caches in `asthanaa/benchmarkkrylov`. The two source records without - corrected benchmark caches are intentionally excluded. -- `src/benchmark_qc/`: importable loaders, integral conversion utilities, and - physics-aware validation helpers. -- `datasets/catalog.json`: the machine-readable inventory with SHA-256 values, - model metadata, and relative paths. -- `datasets/benchmarkQC/reference/reference_results.json`: common scalar CASCI, CISD, - CCSD, Rényi-0.25, and cumulant records for all 51 BenchmarkQC points. -- `docs/SI_TABLE_I_AUDIT.md` and - `datasets/benchmarkQC/reference/inventory.json`: the complete audit of all - 26 SI Table I geometry rows and their reconstruction provenance. -- `docs/ACTIVE_SPACE_AND_METHOD_AUDIT.md`: active-space evidence, limitations, - literature checks, and scalar-method data coverage for all 51 BenchmarkQC - records. -- `applications/`: a documented, ignored workspace for local experiments. - Application calculations and their outputs are not part of this repository. - -The checked-in dataset archives are reference artifacts, not a record of a -particular local environment. Dataset builders preserve their input hashes, -orbital selections, numerical conventions, and validation metadata so that a -future rebuild can be audited. +Benchmark-QC is a versioned collection of molecular quantum-computing benchmark Hamiltonians and portable active-space integral archives. It brings the original BenchmarkQC systems and the corrected MolVQE-21 reference cases into one consistent, checksum-pinned repository. + +## At a glance + +| Collection | Entries | What it contains | +| --- | ---: | --- | +| **BenchmarkQC** | 51 | C2, C2H4, CH2, Fe2S2, FeH, FeS, N2, O2, and U2 benchmark systems | +| **Corrected MolVQE-21** | 27 | Corrected MolVQE-21 reference cases with Hamiltonians, integral archives, and shared metadata | +| **Total catalog** | **78** | Point-level entries with paths, metadata, and SHA-256 checksums | + +Each catalog entry has a runnable Hamiltonian archive, a normalized spatial integral archive, per-system metadata, and provenance links. The catalog is the authoritative index for the checked-in data. ## Quick start ```sh git clone https://github.com/AsthanaLab/BenchmarkQC.git cd BenchmarkQC + python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip @@ -61,7 +45,7 @@ python -m pip install -e . python -m pytest -q ``` -The package can then load the corrected MolVQE-21 cases directly: +Load a corrected MolVQE-21 case directly from the package: ```python from benchmark_qc.molvqe21 import list_cases, load_hamiltonian, load_source_integrals @@ -69,47 +53,98 @@ from benchmark_qc.molvqe21 import list_cases, load_hamiltonian, load_source_inte case = list_cases()[0] hamiltonian = load_hamiltonian(case.case_id) integrals = load_source_integrals(case.case_id) -print(case.case_id, integrals.n_qubits, hamiltonian.ref_energies[0]) + +print(case.case_id) +print(integrals.n_qubits, hamiltonian.ref_energies[0]) ``` -For the complete set of loaders, file contracts, validation commands, and -dataset-specific caveats, start with [the documentation index](docs/README.md). - -## Scientific scope and caveats - -- The historical `.npz` Hamiltonian contract stores PennyLane operators in an - object array. Load those files only from a trusted checkout and verify the - catalog checksum first. -- Numeric integral archives use `allow_pickle=False` and are the preferred - input for reproducible Hamiltonian reconstruction. -- Every catalog entry has a normalized spatial one-/two-electron integral - archive. The 27 historical BenchmarkQC point archives that originally retained - only JW operators now include a minimum-norm, real, chemist-symmetry - reconstruction that regenerates the checked-in JW Hamiltonian. Those files - are explicitly labeled as operator-equivalent frames; they do not claim to - recover the unavailable original AO/MO coefficient frame. -- The accepted Fe2S2 historical records deliberately preserve their qualified - nonstationary default-RHF/CASCI orbital frame. They are not natural-orbital - or Active Space Finder selections; the constructed nested CAS(8e,8o) record - is clearly labeled as a present-work control. -- MolVQE-21 contains only the 27 corrected-cache systems. `Ferrocene_ceo` and - `feo4_2minus_ceo` are excluded because corrected benchmark caches were not - available. -- Scalar CASCI, CISD, CCSD, Rényi-0.25, and two-body-cumulant records are - available under `reference_results` for all 51 BenchmarkQC point systems. - SI values are preserved as published; missing historical controls are computed - from the checked-in normalized archives and marked with their provenance. - Application calculations remain ignored under `applications/`. - -## Contributing and citation - -Please read [CONTRIBUTING.md](CONTRIBUTING.md) before adding a dataset. New -systems must include a portable source archive, provenance, validation tests, -catalog metadata, and checksums. See [Adding a molecular dataset](docs/ADDING_DATASETS.md) -for the acceptance checklist. - -If this repository supports published work, please use the metadata in -[CITATION.cff](CITATION.cff) and preserve the dataset commit in your methods -section. +For installation from PyPI, use: + +```sh +python -m pip install benchmark-qc +``` + +## Repository map + +```text +BenchmarkQC/ +├── src/benchmark_qc/ # Importable loaders and validation utilities +├── datasets/ +│ ├── catalog.json # Authoritative 78-entry dataset index +│ ├── benchmarkQC/ +│ │ ├── systems/ # 51 runnable BenchmarkQC point systems +│ │ ├── reference/ # Scalar reference results and inventories +│ │ └── source/ # Shared manifest, provenance, and builders +│ └── molvqe21/ +│ ├── systems/ # 27 corrected MolVQE-21 point systems +│ ├── reference/ # Reference results and inventories +│ └── source/ # Manifests, overrides, and dataset builders +├── docs/ # Usage, API, formats, audits, and validation +├── applications/ # Ignored workspace for local experiments +├── tests/ # Schema, physics, and reproducibility tests +├── tools/ # Dataset maintenance and audit utilities +├── CITATION.cff # Machine-readable citation metadata +└── pyproject.toml # Package metadata and dependencies +``` + +## Documentation + +Start with the [documentation index](docs/README.md) for the complete guide: + +- [Repository layout](docs/REPOSITORY_LAYOUT.md) +- [Usage examples](docs/USAGE.md) +- [Dataset catalog](docs/DATASETS.md) +- [Package API](docs/API.md) +- [Integral archives and reconstruction](docs/INTEGRAL_ARCHIVES.md) +- [Saved NPZ format](docs/NPZ_FORMAT.md) +- [Validation and release checks](docs/VALIDATION.md) +- [Adding a molecular dataset](docs/ADDING_DATASETS.md) +- [Active-space and method-data audit](docs/ACTIVE_SPACE_AND_METHOD_AUDIT.md) + +## Validation + +Run the complete local validation gate from the repository root: + +```sh +python -m pip install -e . +python -m pytest -q +python -m build +``` + +The GitHub Actions workflow runs the test suite on Python 3.11 and 3.12, checks for syntax and undefined-name errors, and builds the source distribution and wheel. + +## Citation + +If you use the BenchmarkQC collection, cite [*Chemically decisive benchmarks on the path to quantum utility*](https://ui.adsabs.harvard.edu/abs/2026arXiv260110813P/abstract). If you use the corrected MolVQE-21 collection, cite [*Exponential Scaling Barriers for Variational Quantum Eigensolvers*](https://arxiv.org/abs/2603.13073), which introduces the MolVQE-21 benchmark set. + +```bibtex +@misc{Sundar2026ChemicallyDecisiveBenchmarks, + title = {Chemically decisive benchmarks on the path to quantum utility}, + author = {Sundar, Srivathsan Poyyapakkam and Abraham, Vibin and Peng, Bo and Asthana, Ayush}, + year = {2026}, + eprint = {2601.10813}, + archivePrefix = {arXiv}, + primaryClass = {physics.chem-ph}, + doi = {10.48550/arXiv.2601.10813} +} + +@misc{Hagelueken2026ExponentialScalingBarriers, + title = {Exponential Scaling Barriers for Variational Quantum Eigensolvers}, + author = {Hagelueken, Manuel and Kreplin, David A. and Wieland, Florian and Huber, Marco F. and Roth, Marco}, + year = {2026}, + eprint = {2603.13073}, + archivePrefix = {arXiv}, + primaryClass = {quant-ph}, + doi = {10.48550/arXiv.2603.13073} +} +``` + +Please also see [CITATION.cff](CITATION.cff) for machine-readable repository metadata. When reporting results, preserve the dataset commit or release used in the methods section. + +## Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) before adding or changing a dataset. New systems should include portable source data, provenance, validation tests, catalog metadata, and checksums. The [dataset acceptance checklist](docs/ADDING_DATASETS.md) describes the required files and review steps. + +## License Released under the [BSD 3-Clause license](LICENSE). From 95854977428d2defd78c4519662d25028bf9e8ce Mon Sep 17 00:00:00 2001 From: Ayush Asthana Date: Sun, 16 Aug 2026 19:00:55 -0500 Subject: [PATCH 2/2] List corrected MolVQE-21 molecules --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 463e9ec..0743ca9 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Benchmark-QC is a versioned collection of molecular quantum-computing benchmark | Collection | Entries | What it contains | | --- | ---: | --- | | **BenchmarkQC** | 51 | C2, C2H4, CH2, Fe2S2, FeH, FeS, N2, O2, and U2 benchmark systems | -| **Corrected MolVQE-21** | 27 | Corrected MolVQE-21 reference cases with Hamiltonians, integral archives, and shared metadata | +| **Corrected MolVQE-21** | 27 | Al₃⁻, BeH₂, CH₂O, CO, cyclobutadiene, FeNO²⁺, Fe(NO)(CO)₃⁻, FeO, H₄–H₁₀ chains, hexatriene, m-benzyne, magnesium porphyrin, and N₂ | | **Total catalog** | **78** | Point-level entries with paths, metadata, and SHA-256 checksums | Each catalog entry has a runnable Hamiltonian archive, a normalized spatial integral archive, per-system metadata, and provenance links. The catalog is the authoritative index for the checked-in data.