VQE Workflows

Supports:

• ground-state optimisation

• ADAPT-VQE ansatz growth

• geometry scans

• noise studies

• excited-state solvers

Canonical entrypoint:

from vqe.core import run_vqe

---

Basic VQE

vqe --molecule H2

Defaults:

• ansatz → UCCSD

• optimizer → Adam

• steps → 75

Equivalent Python:

from vqe.core import run_vqe

res = run_vqe(molecule="H2")

print(res["energy"])

Non-molecule expert mode

Use this when you already have a qubit Hamiltonian and want to benchmark VQE directly.

import pennylane as qml

from vqe.core import run_vqe

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

res = run_vqe(
    hamiltonian=H_model,
    num_qubits=1,
    reference_state=[1],
    ansatz_name="auto",
    optimizer_name="Adam",
    steps=20,
    plot=False,
)

Notes:

• expert-mode VQE is Python-only

• prebuilt-Hamiltonian runs use cache keys based on a canonical Pauli-term fingerprint, num_qubits, reference_state, resolved ansatz, solver settings, and seed

• reference_state should be a computational-basis bitstring of length num_qubits

• ansatz_name="auto" can select TFIM, XXZ/Heisenberg, SSH-like hopping, or generic fallback ansatzes from Hamiltonian structure

• generic model Hamiltonians should use non-chemistry ansatzes unless you also provide chemistry metadata

---

Ansatz selection

vqe -m H2 -a UCCSD
vqe -m H2 -a RY-CZ
vqe -m H2 -a StronglyEntanglingLayers

Guidance:

Ansatz	Typical use
UCCSD	chemistry baseline
RY-CZ	lightweight reference
StronglyEntanglingLayers	expressive hardware ansatz

See:

more_docs/vqe/ansatzes.md

---

Optimizer selection

vqe -m H2 -o Adam
vqe -m H2 -o GradientDescent
vqe -m H2 -o NesterovMomentum

Guidance:

Optimizer	Behaviour
Adam	robust default
GradientDescent	baseline
NesterovMomentum	faster convergence on smooth landscapes

If stepsize / --stepsize is omitted for VQE workflows, the calibrated default for the selected optimizer is used.

See:

more_docs/vqe/optimizers.md

---

Geometry scans

vqe \
  --scan-geometry H2_BOND \
  --range 0.5 1.5 7

Produces:

• energy curves

• cached intermediate Hamiltonians

• reproducible scan identifiers

---

Noise studies

vqe \
  -m H2 \
  --multi-seed-noise \
  --noise-type depolarizing

Noise options:

• depolarizing

• amplitude damping

• combined channels

---

Low-qubit benchmark

Use this when you want one decision-grade VQE summary across the supported small molecules instead of a single-molecule sweep.

Python:

from vqe import run_vqe_low_qubit_benchmark

bench = run_vqe_low_qubit_benchmark(
    max_qubits=10,
    ansatz_name="UCCSD",
    optimizer_name="Adam",
    seeds=[0, 1, 2],
    show=False,
)

for row in bench["rows"]:
    print(
        row["molecule"],
        row["num_qubits"],
        row["abs_error_mean"],
        row["runtime_mean_s"],
    )

Reported per molecule:

• resolved qubit count

• Hamiltonian term count

• exact ground-state reference energy

• mean / standard deviation of final VQE energy across seeds

• mean / standard deviation of absolute error against exact diagonalization

• mean / standard deviation of original compute runtime

By default, molecules that cannot be run with the selected ansatz are skipped and reported under bench["skipped"]. Set skip_failures=False if you want the first incompatible case to raise immediately.

When cached artifacts already exist, the benchmark prefers each run’s stored compute_runtime_s value over the current cache-hit wall time, so runtime tables still reflect the original compute cost.

---