This VQE quantum chemistry tutorial presents a repeatable workflow for setting up a molecular experiment, choosing an ansatz and qubit mapping, configuring the classical optimiser, and validating the resulting energy against a trustworthy reference. Use it as a working checklist when moving between molecules, basis sets, simulators, hardware backends, Qiskit, or PennyLane.
Overview
The variational quantum eigensolver (VQE) estimates the ground-state energy of a molecule by combining a parameterised quantum circuit with a classical optimisation loop. The circuit prepares a trial state, measurements estimate the expectation value of a molecular Hamiltonian, and a classical optimiser adjusts circuit parameters to reduce that energy.
In practice, the quantum circuit is only one part of the experiment. Results depend on the molecular geometry, charge and spin, basis set, active-space reduction, fermion-to-qubit mapping, ansatz, optimiser, shot budget, simulator settings and reference calculation. A low reported energy is not automatically a correct result: the experiment must preserve the intended chemistry and provide enough metadata to reproduce and assess it.
A robust workflow therefore has four stages:
- Define the chemistry: specify atoms, coordinates, charge, multiplicity, basis set and, where appropriate, an active space.
- Construct the problem: generate the electronic Hamiltonian and map its fermionic operators to qubit operators.
- Run the variational experiment: select an initial state, ansatz, optimiser and execution backend, then monitor convergence.
- Validate the result: compare with a classical reference and record enough information to explain discrepancies.
This separation is useful when debugging. If the Hamiltonian is wrong, changing the optimiser will not fix the experiment. If the Hamiltonian is correct but the ansatz cannot represent a suitable state, more shots may reduce noise without improving the answer.
What to track
1. Molecular definition and basis set
Start with an explicit geometry rather than an informal molecule name. Record element symbols, coordinate units, atom ordering, charge and spin multiplicity. Atom ordering can affect the generated orbital and qubit ordering, so preserve it when comparing runs.
The basis set controls the one-electron functions used to represent the molecular orbitals. A small basis is useful for a fast workflow test; a larger basis can describe the electronic structure more flexibly but usually increases the number of orbitals and qubits. Do not compare energies from different basis sets as though they were identical computational problems.
| Decision | Useful starting point | What to record |
|---|---|---|
| Workflow smoke test | Small molecule and compact basis | Geometry, basis, charge, multiplicity and software versions |
| Method comparison | Fixed geometry and fixed basis across all runs | Hamiltonian size, mapping, ansatz and optimiser settings |
| Higher-fidelity study | Larger basis or a justified active space | Orbital-selection rule, frozen orbitals and truncation assumptions |
| Hardware trial | Reduced problem sized for the selected backend | Transpilation, connectivity, shots, error mitigation and backend metadata |
2. Hamiltonian and qubit mapping
A chemistry library normally converts the electronic-structure problem into a second-quantised Hamiltonian and then maps fermionic operators to qubit operators. Common mappings include Jordan–Wigner, parity and Bravyi–Kitaev. The mapping changes the operator structure and may change how many qubits can be removed using symmetry or tapering techniques.
Track the number of spin orbitals, qubits, Hamiltonian terms and Pauli-term measurement groups. Also record whether nuclear repulsion energy is included separately. A frequent validation error is comparing a VQE electronic energy with a reference total energy without adding the same nuclear contribution.
Mapping choice should be treated as an experiment variable, not an incidental SDK default. When porting between Qiskit and PennyLane, verify operator ordering, qubit indexing, identity terms and energy conventions rather than assuming equivalent-looking circuits represent the same Hamiltonian.
3. Initial state and ansatz
The ansatz is the parameterised circuit used to represent candidate wavefunctions. A hardware-efficient ansatz can be compact and compatible with device connectivity, but may have difficulty preserving useful chemical structure. A chemistry-inspired ansatz, such as a unitary coupled-cluster variant, can encode more domain knowledge while requiring more gates and parameters.
For a first comparison, use the same Hamiltonian and optimiser with two deliberately different ansatz families. Track parameter count, circuit depth, two-qubit gate count, symmetry preservation, initial parameter values and whether the reference determinant is included. An ansatz that reaches a lower energy with a much deeper circuit may not be preferable for hardware execution.
4. Optimiser and execution settings
VQE is a hybrid quantum-classical workflow. The optimiser proposes parameters, the quantum execution estimates the energy, and the result is returned to the optimiser. Track the optimiser name, learning rate or step-size settings, stopping tolerances, maximum iterations, gradient method, initial point and random seed where supported.
On an ideal statevector simulator, expectation values can be deterministic. Shot-based simulation and hardware execution introduce sampling variation. Record shots per circuit, measurement grouping, retries, noise model, mitigation method and whether each iteration used the same sampling budget. Increasing shots can make an estimate less variable, but it cannot correct an unsuitable ansatz or a chemistry setup error.
5. Classical reference energy
Use a reference calculation that matches the VQE problem as closely as possible: geometry, basis, charge, multiplicity, frozen-core treatment and active space should agree. For small test systems, an exact diagonalisation or full configuration-interaction-style reference within the selected basis may be appropriate. For larger systems, compare with a clearly identified classical method and state its limitations.
Keep both absolute energies and differences. Useful quantities include the absolute error relative to the reference, the energy difference between successive iterations, and the gap between the best VQE value and the variational target. If the reference uses a different model, call it a comparison rather than ground truth.
Cadence and checkpoints
Run the workflow in checkpoints rather than beginning with hardware. This reduces the number of possible causes when results look wrong.
- Input checkpoint: print the geometry, units, charge, multiplicity, basis and active-space choices. Confirm that the molecule is chemically plausible and that the intended electronic sector is being represented.
- Hamiltonian checkpoint: record qubit count, term count, identity coefficient and operator ordering. Evaluate the Hamiltonian for the reference state before optimisation.
- Ansatz checkpoint: inspect depth, gate counts, parameter count and initial-state overlap where available. Confirm that the circuit can represent the chosen reference state.
- Ideal simulation checkpoint: run a noiseless or deterministic simulation to separate modelling and optimisation issues from sampling and hardware effects.
- Shot-based checkpoint: repeat the experiment with a fixed shot budget and several seeds or independent repetitions. Report spread, not just the best run.
- Hardware checkpoint: transpile for the target device, inspect the resulting circuit and compare its depth and two-qubit gates with the simulator version.
Use a consistent experiment log for every run:
experiment_id: YYYY-MM-DD-name-version
molecule_geometry: ...
charge_multiplicity: ...
basis_and_active_space: ...
mapping_and_qubits: ...
ansatz_and_parameters: ...
initial_point_and_seed: ...
optimizer_and_stopping_rule: ...
backend_shots_noise_mitigation: ...
best_energy_and_iteration: ...
reference_energy_and_method: ...
absolute_error_convergence_notes: ...
Review the log monthly or quarterly during active development, and whenever a chemistry library, quantum SDK, simulator, backend, mapping implementation or optimiser changes. Exact API names and supported transformations can change between releases, so pin environments for published results and re-run a small regression molecule after upgrades.
How to interpret changes
Energy decreases but remains above the reference
This may be a normal variational result: the ansatz has found a state above the best state available to the reference method. It may also indicate insufficient circuit expressivity, a poor initial point, an optimiser that stopped early, or sampling noise. Compare convergence traces, repeat the run, and test a second ansatz before drawing a hardware conclusion.
The energy falls below the expected variational target
Investigate conventions before celebrating. Check whether the nuclear repulsion term is included consistently, whether error mitigation was applied, whether the reference uses the same Hamiltonian, and whether post-processing or measurement grouping has introduced a bias. On noisy hardware, a value below a classical reference can be an artefact rather than evidence of a better wavefunction.
Different mappings produce different answers
Equivalent mappings should describe the same physical problem when implemented consistently, but they can differ substantially in circuit structure, measurement cost and susceptibility to noise. First compare the generated Hamiltonians and qubit ordering. Then compare ansatz depth, symmetry handling and optimisation settings. A mapping should be judged with these implementation costs in view, not by its name alone.
Repeated runs have a wide spread
Separate classical optimisation variability from quantum measurement variability. Hold the Hamiltonian, ansatz and shot budget fixed; vary one factor at a time. Report the median or mean alongside the range or standard deviation where appropriate, and preserve unsuccessful runs. Selecting only the lowest result gives an incomplete picture of reliability.
For broader benchmarking practice, see the quantum experiment reproducibility checklist and guide to benchmarking quantum algorithms against classical methods. If your chemistry workflow is part of an optimisation pipeline, the quantum optimisation problem formulation checklist can help keep the surrounding problem definition explicit.
When to revisit
Revisit this VQE workflow whenever the molecule, geometry, basis set, active space, mapping, ansatz, optimiser or execution backend changes. A change in any one of these variables can invalidate a direct comparison with earlier results.
For an active project, perform a short monthly or quarterly review. Re-run a small reference molecule, check that pinned dependencies still reproduce the expected Hamiltonian shape, confirm that backend constraints have not altered the transpiled circuit, and compare current convergence and error metrics with the previous log. After a major SDK or chemistry-library release, repeat the full regression suite before updating published results or production notebooks.
Before accepting a new result, ask:
- Is the molecular input and electronic sector documented?
- Does the Hamiltonian match the intended basis and active space?
- Are mapping, qubit order and energy conventions verified?
- Has the ansatz been tested for depth, expressivity and symmetry?
- Are optimiser settings, shots, seeds and backend details recorded?
- Is the classical comparison genuinely like-for-like?
- Do repeated runs support the conclusion?
Once these checks pass, publish the result with its assumptions and limitations. That makes the experiment useful to the next developer who changes the molecule, ports the workflow to another quantum SDK, or returns to the notebook after the next software release.