atomgptlab · knc6 · Jun 18, 2026 · Jun 18, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# MkDocs
+site/
diff --git a/README.md b/README.md
@@ -150,6 +150,22 @@ push.
 
 ---
 
+## Documentation
+
+Full documentation is built with [MkDocs](https://www.mkdocs.org/) (Material theme). The
+sources live under `docs/` and the site config is `mkdocs.yml`.
+
+```bash
+pip install mkdocs-material
+mkdocs serve     # live preview at http://127.0.0.1:8000
+mkdocs build     # render static site into ./site
+```
+
+Pages: Installation, Quick start, Methods (VQE / ADAPT-VQE / VQD), Example scripts,
+Testing, Web app, and Citation.
+
+---
+
 ## Repository layout
 
 ```

diff --git a/docs/citation.md b/docs/citation.md
@@ -0,0 +1,31 @@
+# Citation
+
+If you use AtomQC in your research, please cite:
+
+```bibtex
+@article{choudhary2021quantum,
+  title   = {Quantum computation for predicting electron and phonon properties of solids},
+  author  = {Choudhary, Kamal},
+  journal = {Journal of Physics: Condensed Matter},
+  volume  = {33},
+  number  = {38},
+  pages   = {385501},
+  year    = {2021},
+  doi     = {10.1088/1361-648X/ac1154}
+}
+```
+
+## References & links
+
+- 📄 Paper: [J. Phys.: Condens. Matter 33, 385501 (2021)](https://iopscience.iop.org/article/10.1088/1361-648X/ac1154/meta)
+- 📄 Related: [AtomGPT and generative materials design, *J. Comput. Chem.* (2025), doi:10.1002/jcc.70202](https://onlinelibrary.wiley.com/doi/full/10.1002/jcc.70202)
+- 🌐 Web app: [atomgpt.org/quantum](https://atomgpt.org/quantum)
+- 📓 Colab notebook: [Qiskit-based electronic bandstructure](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Qiskit_based_electronic_bandstructure_.ipynb)
+- 🧰 JARVIS-Tools: [github.com/usnistgov/jarvis](https://github.com/usnistgov/jarvis)
+- ⚛️ Qiskit: [qiskit.org](https://www.qiskit.org/)
+
+## License
+
+Distributed under the terms of the
+[LICENSE](https://github.com/atomgptlab/atomqc/blob/master/LICENSE.md) included in the
+repository.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,60 @@
+# AtomQC
+
+**Atomistic Calculations on Quantum Computers**
+
+AtomQC is a toolkit for running materials-science electronic-structure and
+lattice-dynamics calculations on quantum computers and quantum simulators. It maps the
+*Wannier tight-binding Hamiltonians* (WTBH) of real materials — taken from the
+[JARVIS-DFT](https://jarvis.nist.gov/jarvisdft/) database — onto qubits and solves for
+their eigenvalues using variational quantum algorithms such as the **Variational Quantum
+Eigensolver (VQE)**, **ADAPT-VQE**, and the **Variational Quantum Deflation (VQD)** method.
+From these eigenvalues it reconstructs electronic and phonon **bandstructures** that can be
+compared directly against classical (NumPy) diagonalization.
+
+The approach is described in:
+
+> **K. Choudhary, "Quantum computation for predicting electron and phonon properties of solids",**
+> *J. Phys.: Condens. Matter* **33**, 385501 (2021).
+> [doi:10.1088/1361-648X/ac1154](https://iopscience.iop.org/article/10.1088/1361-648X/ac1154/meta)
+
+!!! note
+    This project was originally developed under the
+    [github.com/usnistgov](https://github.com/usnistgov) organization. New updates and
+    developments are now carried out at
+    [github.com/atomgptlab/atomqc](https://github.com/atomgptlab/atomqc).
+
+## Why quantum computing for materials?
+
+Predicting the electronic and vibrational properties of solids reduces to finding the
+eigenvalues of a Hamiltonian matrix $H(k)$ at each point $k$ in the Brillouin zone. For a
+compact basis such as maximally-localized Wannier functions, these matrices are small
+enough that their **qubit-mapped** versions can be diagonalized on today's noisy quantum
+hardware and simulators, making materials a practical testbed for near-term quantum
+algorithms.
+
+AtomQC provides the glue between:
+
+- **JARVIS-DFT** WTBHs (`get_wann_electron`, `get_wann_phonon`, `get_hk_tb`) — the physics inputs,
+- **Qiskit** quantum algorithms and simulators — the quantum back end, and
+- **jarvis-tools** `HermitianSolver` / `get_bandstruct` — the solver layer that maps $H(k)$
+  to Pauli operators, runs the variational circuits, and assembles bandstructures.
+
+## Features
+
+- 🔬 **Electronic & phonon eigenvalues** of real materials from JARVIS-DFT WTBHs.
+- ⚛️ **VQE** with a library of hardware-efficient ansätze (`QuantumCircuitLibrary`).
+- ⚙️ **ADAPT-VQE** — iteratively grows a compact ansatz from a Pauli excitation pool.
+- 📈 **VQD bandstructures** along high-symmetry $k$-paths via `get_bandstruct`.
+- 🧮 **Classical cross-check** against exact NumPy diagonalization for every run.
+- 🖥️ **Multiple back ends** — exact statevector, Qiskit Aer simulators, and real IBM
+  Quantum hardware (with an API token).
+- 🌐 **Live web app** — interactive VQE / ADAPT-VQE / VQD explorer at
+  [atomgpt.org/quantum](https://atomgpt.org/quantum).
+
+## Where to next?
+
+- [Installation](installation.md) — set up the environment.
+- [Quick start](quickstart.md) — run your first VQE and bandstructure.
+- [Methods](methods.md) — the physics and algorithms behind AtomQC.
+- [Example scripts](scripts.md) — the batch/benchmark scripts shipped with the package.
+- [Web app](web-app.md) — the hosted AtomGPT Quantum Explorer.
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,49 @@
+# Installation
+
+AtomQC targets Python ≥ 3.8 and builds on `jarvis-tools` and `qiskit`.
+
+## From PyPI
+
+```bash
+pip install atomqc
+```
+
+## From source
+
+```bash
+git clone https://github.com/atomgptlab/atomqc.git
+cd atomqc
+pip install -e .
+```
+
+## With conda (reproducible environment)
+
+A pinned environment is provided in `environment.yml`:
+
+```bash
+conda env create -f environment.yml
+conda activate my_atomqc
+```
+
+## Core dependencies
+
+`jarvis-tools`, `qiskit`, `qiskit-aer`, `qiskit-algorithms`, `numpy`, `scipy`, `pandas`,
+`scikit-learn`, `matplotlib`. For real IBM hardware also install `qiskit-ibm-runtime`.
+
+!!! warning "Match the Qiskit version to the entry point"
+    The Qiskit API has changed substantially over time. The example scripts in
+    `atomqc/scripts/` were written against the older `qiskit.aqua` API, while the modern
+    solver path (`jarvis.io.qiskit.inputs`) and the AtomGPT web app use the
+    `qiskit>=2.0` / `qiskit-algorithms` primitives. Use a recent `jarvis-tools`
+    (≥ 2026.6.12) with `qiskit>=2.0` for the current code paths shown in the
+    [Quick start](quickstart.md).
+
+## Verify the install
+
+```bash
+python -c "import qiskit, jarvis; print(qiskit.__version__, jarvis.__version__)"
+pip install pytest
+pytest atomqc/tests/
+```
+
+See [Testing](testing.md) for what the test suite covers.
diff --git a/docs/methods.md b/docs/methods.md
@@ -0,0 +1,64 @@
+# Methods
+
+This page summarizes the physics and algorithms behind AtomQC. For the full treatment see
+the reference paper, *J. Phys.: Condens. Matter* **33**, 385501 (2021),
+[doi:10.1088/1361-648X/ac1154](https://iopscience.iop.org/article/10.1088/1361-648X/ac1154/meta).
+
+## From a material to a qubit Hamiltonian
+
+For a crystalline solid, a **Wannier tight-binding Hamiltonian** (WTBH) gives a small
+Hermitian matrix $H(k)$ at every crystal momentum $k$. Diagonalizing $H(k)$ across the
+Brillouin zone produces the band structure $E_n(k)$.
+
+JARVIS ships pre-computed Wannier Hamiltonians indexed by material ID, e.g. FCC Aluminum
+`JVASP-816` and diamond Silicon `JVASP-1002`. The bridge to a quantum computer is the fact
+that *any* Hermitian matrix can be written as a weighted sum of **Pauli strings**,
+
+$$ H=\sum_k c_k\, P_k,\qquad P_k\in\{I,X,Y,Z\}^{\otimes n}, $$
+
+and Pauli strings are exactly what a quantum computer can measure. `HermitianSolver`
+handles padding $H(k)$ to a power-of-two dimension so it maps onto an integer number of
+qubits ($N \times N$ needs $\lceil\log_2 N\rceil$ qubits).
+
+## VQE — Variational Quantum Eigensolver
+
+VQE prepares a parameterized trial state $|\psi(\theta)\rangle$ (the **ansatz**), measures
+its energy, and lets a **classical optimizer** push that energy down. The *variational
+principle* guarantees
+
+$$\langle\psi(\theta)|H|\psi(\theta)\rangle \;\ge\; E_{\text{ground}},$$
+
+so "lower is always better" — VQE can never undershoot the true ground state. AtomQC uses
+hardware-efficient ansätze from `QuantumCircuitLibrary`; the number of layers (`reps`)
+trades expressiveness for circuit depth (and noise on real hardware).
+
+## ADAPT-VQE — adaptively grown ansatz
+
+Fixed-depth VQE guesses the circuit shape up front. **ADAPT-VQE** instead *builds* the
+ansatz one operator at a time:
+
+1. Start from a reference state (e.g. $|0\dots0\rangle$).
+2. From a **pool** of candidate operators $\{P_j\}$, compute the energy gradient of adding each.
+3. Append the operator with the **largest gradient** as $e^{i\theta_j P_j}$, then re-optimize all parameters with VQE.
+4. Repeat until the largest gradient falls below a threshold (converged).
+
+The payoff is a **compact, problem-tailored circuit** — often fewer gates than fixed VQE
+for the same accuracy, which matters on noisy hardware.
+
+## VQD — excited states and band structure
+
+VQE finds only the **lowest** eigenvalue. A band structure needs *all* eigenvalues of
+$H(k)$ at every $k$. **VQD (Variational Quantum Deflation)** finds excited states by
+re-running VQE while adding a penalty that pushes each new state to be **orthogonal** to
+the ones already found:
+
+$$ E_k(\theta)=\langle\psi|H|\psi\rangle+\sum_{j<k}\beta_j\,|\langle\psi|\psi_j\rangle|^2. $$
+
+`get_bandstruct` repeats the VQD eigenvalue solve along a standard $k$-path and overlays
+the exact NumPy bands for comparison.
+
+## Classical cross-check
+
+Every run can be compared against exact diagonalization via `HermitianSolver.run_numpy()`
+(`numpy.linalg.eigh`). This is how AtomQC validates the quantum results and how the
+benchmark CSVs under `atomqc/data/` were generated — see [Example scripts](scripts.md).
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,94 @@
+# Quick start
+
+These examples use the modern solver path in `jarvis.io.qiskit.inputs` with
+`qiskit>=2.0`. They download Wannier tight-binding Hamiltonians from JARVIS-DFT on first
+use.
+
+## Single-$k$-point VQE
+
+Run a single-$k$-point VQE on FCC aluminum (`JVASP-816`) and compare against classical
+diagonalization:
+
+```python
+from jarvis.db.figshare import get_wann_electron, get_hk_tb
+from jarvis.io.qiskit.inputs import HermitianSolver
+
+# 1. Fetch the Wannier tight-binding Hamiltonian for Al from JARVIS-DFT
+w, ef, atoms = get_wann_electron(jid="JVASP-816")
+
+# 2. Build H(k) at a chosen k-point
+hk = get_hk_tb(w=w, k=[0.5, 0.5, 0.0])
+
+# 3. Solve for eigenvalues with VQE and with exact NumPy diagonalization
+HS = HermitianSolver(hk)
+vqe_energy, vqe_result, vqe = HS.run_vqe()      # min eigenvalue via VQE
+classical_vals, classical_vecs = HS.run_numpy() # exact reference
+
+print("VQE ground state:", vqe_energy)
+print("Classical minimum:", min(classical_vals.real))
+```
+
+## Choosing an ansatz
+
+`QuantumCircuitLibrary` provides a set of hardware-efficient ansätze. Pass one to
+`run_vqe` via `var_form`:
+
+```python
+from jarvis.core.circuits import QuantumCircuitLibrary
+
+n_qubits = HS.n_qubits()
+circ = QuantumCircuitLibrary(n_qubits=n_qubits, reps=2).circuit6()
+en_vqe, _, _ = HS.run_vqe(var_form=circ, backend="statevector_simulator")
+```
+
+More `reps` makes the ansatz more expressive (lower energy) but deeper — and, on real
+hardware, noisier. See [Methods](methods.md) for the trade-offs.
+
+## Pauli decomposition of $H(k)$
+
+Any Hermitian matrix can be written as a weighted sum of Pauli strings — exactly what a
+quantum computer measures:
+
+```python
+from jarvis.io.qiskit.inputs import decompose_Hamiltonian
+
+op = decompose_Hamiltonian(hk)   # qiskit SparsePauliOp
+print("Number of Pauli terms:", len(op))
+```
+
+## Full bandstructure (VQD)
+
+VQE returns only the lowest eigenvalue. A bandstructure needs *all* eigenvalues of $H(k)$
+at every $k$; **VQD** finds excited states by re-running VQE with an orthogonality
+penalty. `get_bandstruct` does this along a high-symmetry $k$-path:
+
+```python
+from jarvis.db.figshare import get_wann_electron
+from jarvis.io.qiskit.inputs import get_bandstruct
+
+w, ef, atoms = get_wann_electron(jid="JVASP-816")
+out = get_bandstruct(w=w, atoms=atoms, line_density=1, savefig=True)
+# out["eigvals_q"]  -> quantum (VQD) eigenvalues along the k-path
+# out["eigvals_np"] -> classical reference eigenvalues
+```
+
+Use `line_density=1` for a quick, crude plot; raise it (and the ansatz `reps`) for a
+publication-quality figure.
+
+## Back ends
+
+`run_vqe` / `run_vqd` accept a `backend` argument:
+
+- `"statevector_simulator"` — exact, noiseless (default; best for learning).
+- `"aer_simulator*"` — Qiskit Aer shot-based simulators.
+- an IBM backend name (e.g. `"ibm_brisbane"`) — real hardware, requires
+  `qiskit-ibm-runtime` and a saved IBM Quantum token.
+
+## A couple of materials to try
+
+| Material            | JARVIS ID    |
+| ------------------- | ------------ |
+| Al (FCC metal)      | `JVASP-816`  |
+| Si (semiconductor)  | `JVASP-1002` |
+
+Swap the JID into `get_wann_electron(...)` and re-run.
diff --git a/docs/scripts.md b/docs/scripts.md
@@ -0,0 +1,48 @@
+# Example scripts
+
+The package ships a handful of batch/benchmark scripts under `atomqc/scripts/`.
+
+| Script | What it does |
+| --- | --- |
+| `aluminum_example.py` | Runs VQE on the Al Hamiltonian sweeping COBYLA, L-BFGS-B, SLSQP, CG, SPSA optimizers and plots convergence, alongside VQD electron and phonon bandstructures. |
+| `circuit_comparison.py` | Benchmarks the ansätze in `QuantumCircuitLibrary` at several $k$-points. |
+| `compare_elect_vqe.py` | Loops over JARVIS jids, computes min/max electronic eigenvalues with VQE and NumPy, and dumps JSON. |
+| `compare_phonons_vqe.py` | Same as above for phonon Hamiltonians. |
+
+!!! warning "Qiskit API version"
+    `aluminum_example.py` and the other scripts were written against the older
+    `qiskit.aqua` API (`from qiskit.aqua ... import VQE, QuantumInstance`, `EfficientSU2`,
+    `op_converter`). They are kept as historical references for the workflow used in the
+    paper. For current `qiskit>=2.0`, use the `HermitianSolver` / `get_bandstruct` paths
+    shown in the [Quick start](quickstart.md) and [Methods](methods.md) pages.
+
+## Benchmark data
+
+The CSV files under `atomqc/data/` hold pre-computed VQE-vs-classical benchmark results
+referenced in the paper:
+
+- `electron_vqe_np_jid.csv` — electron VQE vs classical eigenvalues per JARVIS id.
+- `phonon_vqe_np_jid.csv` — phonon VQE vs classical eigenvalues per JARVIS id.
+
+## Repository layout
+
+```
+atomqc/
+├── atomqc/
+│   ├── __init__.py                 # version
+│   ├── scripts/
+│   │   ├── aluminum_example.py     # VQE on Al with several classical optimizers
+│   │   ├── circuit_comparison.py   # compare ansätze from QuantumCircuitLibrary
+│   │   ├── compare_elect_vqe.py    # batch electron VQE vs NumPy over JARVIS jids
+│   │   └── compare_phonons_vqe.py  # batch phonon VQE vs NumPy over JARVIS jids
+│   ├── tests/
+│   │   └── test_qiskit.py          # fast offline tests: H(k) -> Pauli -> VQE
+│   └── data/
+│       ├── electron_vqe_np_jid.csv # benchmark: electron VQE vs classical
+│       └── phonon_vqe_np_jid.csv   # benchmark: phonon VQE vs classical
+├── environment.yml                 # pinned conda environment
+├── mkdocs.yml                      # documentation site config
+├── docs/                           # documentation sources
+├── setup.py
+└── README.md
+```