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¶

Supported Python versions are 3.10–3.12, with numpy>=1.23,<2.0 and pennylane>=0.42,<0.45. Python 3.13 support is deferred until the NumPy 2 compatibility migration is complete.

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')"

Experiment Studio and Progress Observers¶

Version 0.3.28 adds an optional browser interface for VQE and ADAPT-VQE. From a source checkout with the package installed, run python -m studio and open http://127.0.0.1:8000. Studio is excluded from the wheel and source distribution. See the Studio guide for Codespaces setup, comparisons, JSON exports, cancellation, and persistence behavior. Queued and running experiments can be cancelled from their cards or detail views; Ctrl-C cancels unfinished work and cleans up isolated workers.

Python callers can observe actual energy samples without using Studio:

from vqe import run_vqe

result = run_vqe(steps=10, plot=False, progress_callback=print)

run_adapt_vqe() accepts the same optional callback. Observers receive fresh status dictionaries synchronously; a cache hit emits a single cache_hit event. Callbacks are excluded from cache identity, and their exceptions propagate. A completed iteration budget is not a convergence or accuracy certificate.

General Conventions¶

Output structure, relative to the runtime data root:

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

The default root is ~/.local/share/vqe-pennylane on Linux (or $XDG_DATA_HOME/vqe-pennylane), ~/Library/Application Support/vqe-pennylane on macOS, and %LOCALAPPDATA%/vqe-pennylane on Windows. Generated artifacts are stored outside the installed package.

Set VQE_PENNYLANE_DATA_DIR to override the root. To retain the old checkout-local layout, run export VQE_PENNYLANE_DATA_DIR="$PWD" from the repository. Python code can also set this environment variable after importing the solvers.

Version 0.3.27 versions cache signatures to invalidate results from earlier numerical implementations, including spin-reference and QPE term-order fixes. Old files remain available for inspection; matching runs are recomputed once.

Execution behaviour:

deterministic hashing defines run identity
cached runs automatically reused
VQE, QPE, VarQITE, and VarQRTE refresh cached records missing required runtime metadata; ADAPT retains legacy results and omits unavailable compute timings
--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,
)