Inputs, Installation, and Conventions

File	Purpose
README.md	overview and quickstart
USAGE.md	workflows and APIs (this file)
THEORY.md	algorithms and derivations
more_docs/architecture.md	system design
more_docs/vqe/	VQE internals
more_docs/qpe/	QPE details
more_docs/qite/	QITE details

---

Core Execution Model

All stacks share the same pipeline:

problem spec → resolved problem → algorithm → results + cache

Lower-level chemistry contract:

H, n_qubits, hf_state = build_hamiltonian(...)

Registry-inventory helper:

rows = summarize_registry_coverage(...)

High-level shared resolver:

problem = resolve_problem(...)

from:

from common.problem import resolve_problem
from common import summarize_registry_coverage

Implications:

• identical physics across all methods

• one normalization path for molecule, explicit-geometry, and expert-mode inputs

• reproducible cross-algorithm comparisons

• unified caching and output structure

There is also an expert-mode path for prebuilt qubit Hamiltonians when you do not want molecule or geometry inputs.

Supported Molecule Inputs

The shared chemistry pipeline accepts three input styles.

1. Registry molecule names

Use molecule="..." with the built-in molecule registry when a named system is already supported.

Current registry molecules:

Category	Molecules
Hydrogen atoms and ions	H, H-
Helium systems	He, He+, He2, HeH+
First-row atoms and ions	Li, Li+, Be, Be+, B, B+, C, C+, N, N+, O, O+, F, F+, Ne
Hydrogen clusters	H2, H2+, H2-, H3, H3+, H4, H4+, H5+, H6
Small molecules	LiH, H2O, BeH2

Several common aliases are normalized automatically, for example:

• h2 -> H2

• H3PLUS -> H3+

• H2_PLUS -> H2+

2. Parametric geometry tags

Use molecule="..." with a geometry tag when you want a generated structure rather than a fixed registry entry.

Supported geometry tags:

• H2_BOND

• H3+_BOND

• LiH_BOND

• H2O_ANGLE

These are intended for scans and geometry studies.

3. Explicit geometry mode

Use explicit molecular data when the target system is not in the registry:

from common.hamiltonian import build_hamiltonian

H, n_qubits, hf_state = build_hamiltonian(
    symbols=["H", "H"],
    coordinates=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.7414]],
    charge=0,
    multiplicity=1,
    basis="sto-3g",
)

This same explicit-geometry input style is supported by the high-level runners such as run_vqe(...), run_qpe(...), run_qite(...), and run_qrte(...).

If molecule="..." is not a supported registry key or geometry tag, the builder raises a KeyError. In that case, use explicit geometry mode instead of expert mode whenever possible.

To inspect the currently supported built-in registry programmatically:

from common import summarize_registry_coverage

rows = summarize_registry_coverage()

---

Installation

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('All stacks OK')"

---

General Conventions

Output structure:

results/{vqe,qpe,qite}/
images/{vqe,qpe,qite}/

Execution behaviour:

• deterministic hashing defines run identity

• cached runs automatically reused

• cached records missing runtime metadata are treated as stale and refreshed on access

• --force bypasses cache

• identical Hamiltonians shared across algorithms

---

Method Support Summary

Method	Family	VQE reference required	Noise support
VQE	variational	no	yes
ADAPT-VQE	variational	no	yes
LR-VQE	post-VQE	yes	no
EOM-VQE	post-VQE	yes	no
QSE	post-VQE	yes	no
EOM-QSE	post-VQE	yes	no
SSVQE	variational excited	no	yes
VQD	variational excited	no	yes
QPE	phase estimation	no	yes
QITE	imaginary time	no	eval-only
QRTE	real-time dynamics	no	no

---

Quickstart

vqe --molecule H2

vqe -m H2 --lr-vqe --lr-k 4

qpe --molecule H2 --ancillas 4 --shots 1000 --trotter-steps 2

qite run --molecule H2 --steps 75 --dtau 0.2

qite run-qrte --molecule H2 --steps 20 --dt 0.05

Python expert-mode example:

import pennylane as qml

from qite.core import run_qite
from vqe.core import run_vqe

H_model = qml.Hamiltonian(
    [1.0, 0.4],
    [qml.PauliZ(0), qml.PauliX(0)],
)

vqe_res = run_vqe(
    hamiltonian=H_model,
    num_qubits=1,
    reference_state=[1],
    ansatz_name="RY-CZ",
    optimizer_name="Adam",
    steps=10,
    plot=False,
)

qite_res = run_qite(
    hamiltonian=H_model,
    num_qubits=1,
    reference_state=[1],
    ansatz_name="RY-CZ",
    steps=10,
    dtau=0.1,
    plot=False,
    show=False,
)

---