VQE Tutorial: Build and Evaluate a Variational Quantum Eigensolver Experiment

Overview

The Variational Quantum Eigensolver (VQE) is a hybrid quantum-classical algorithm for estimating the lowest eigenvalue of a Hamiltonian. In quantum chemistry, that value is often related to the ground-state energy of a molecular model. More generally, VQE can be used for optimization problems that can be expressed as finding the minimum expectation value of an operator.

VQE separates the work into two loops. A parameterized quantum circuit, called an ansatz, prepares a trial state. The quantum backend measures the expectation value of a Hamiltonian for that state. A classical optimizer then changes the circuit parameters and submits another evaluation. The process continues until the objective value appears to stabilize or a stopping condition is reached.

In simplified form, the objective is:

E(θ) = ⟨ψ(θ)|H|ψ(θ)⟩

Here, H is the Hamiltonian, |ψ(θ)⟩ is the state prepared by the ansatz, and θ is the vector of trainable parameters. The variational principle means that the measured energy is expected to be an upper bound on the true ground-state energy when the calculation and Hamiltonian assumptions are valid. In practice, finite shots, noise, an unsuitable ansatz, and optimizer behavior can all affect the result.

A practical VQE experiment should therefore report more than its final number. Record the Hamiltonian representation, qubit count, ansatz structure, parameter initialization, optimizer, number of iterations, shots, backend, stopping rule, final energy, and a classical reference. Without those details, it is difficult to reproduce or meaningfully evaluate the result.

Framework choices

APIs change, so treat framework examples as patterns rather than permanent interfaces. Pin your environment and test a small circuit before building the full experiment.

Checklist by scenario

Before writing code

• Define the problem: State whether you are estimating a molecular ground-state energy, minimizing a custom cost Hamiltonian, or testing the algorithm itself.
• Construct the Hamiltonian: Express the operator as a sum of measurable terms, such as Pauli operators and their coefficients. Keep a record of units, constants, and any transformations used to map the original problem to qubits.
• Choose the system size: Start with a small, classically verifiable instance. A small model makes debugging and convergence analysis much easier.
• Set an acceptance target: Decide in advance whether you care about absolute error, relative error, chemical-model accuracy, convergence behavior, or simply a working software pipeline.

For a first simulator experiment

• Select a simple ansatz: Begin with a shallow circuit that can represent the expected state reasonably well. A hardware-efficient ansatz may be easy to construct, while a problem-informed ansatz can reduce the search space when domain knowledge is available.
• Initialize parameters deliberately: Use zeros, small random values, or a domain-informed starting point, then repeat with several seeds. One successful run does not demonstrate reliable convergence.
• Choose an optimizer: Compare at least one gradient-based method with an optimizer that does not require analytic gradients when appropriate. The best choice depends on shot noise, parameter count, objective smoothness, and backend behavior.
• Use exact evaluation first: If your simulator supports statevector or exact expectation-value evaluation, use it to validate circuit logic before adding finite-shot sampling.
• Log every iteration: Save iteration number, objective value, parameter vector, evaluation count, and any error or convergence signal.

For a finite-shot or hardware run

• Estimate measurement cost: Each Hamiltonian term may require measurements. Account for the number of terms, shots per term, optimizer evaluations, and circuit repetitions.
• Keep the circuit shallow where possible: Depth, two-qubit gates, connectivity constraints, and measurement overhead can influence the quality and cost of the result.
• Repeat selected evaluations: Re-evaluate the initial and final parameters with additional shots or repeated jobs to distinguish genuine improvement from sampling variation.
• Track backend details: Record the simulator or device, compilation settings, noise model if used, execution date, shot count, and mitigation settings.
• Compare like with like: If the quantum result includes sampling noise or a noise model, explain how the classical reference and error metric were produced.

For measurement interpretation, review how to interpret quantum measurement and probability distributions. For resource planning, use the quantum circuit resource estimation guide.

What to double-check

Hamiltonian and reference

Confirm that coefficients, qubit ordering, sign conventions, and identity terms are correct. A constant energy offset can make an otherwise correct VQE result appear wrong if it is omitted from the comparison. Generate a classical reference using a method appropriate to the same reduced model and document the reference's assumptions.

Ansatz quality

An optimizer cannot recover a target state that the ansatz cannot represent. Compare ansatz depth, parameter count, symmetries, and gate connectivity. A larger circuit is not automatically better: it can increase measurement cost and expose the experiment to more noise.

Convergence

Inspect the full objective trace rather than only the final iteration. Look for a plateau, oscillation, sudden jumps, or apparent improvement that disappears when the final parameters are re-evaluated. Define a stopping rule such as a small objective change over several iterations, a maximum evaluation budget, or a gradient threshold. Under finite-shot noise, use a tolerance that reflects measurement uncertainty instead of expecting every iteration to improve.

Evaluation quality

Report both accuracy and cost. Useful metrics include absolute error from the classical reference, number of circuit evaluations, total shots, circuit depth, number of parameters, runtime where available, and repeatability across initializations. If hardware or a noise model is involved, a noiseless baseline is essential.

For noisy experiments, the quantum error mitigation benchmarking workflow provides a useful comparison structure. Before submitting to a cloud QPU, work through the hardware job submission checklist.

Common mistakes

• Using a final value without a trace: A single number hides failed runs, unstable optimization, and lucky initialization.
• Changing several variables at once: Keep the Hamiltonian, ansatz, optimizer, and shot budget fixed when comparing one factor. Otherwise, the cause of an improvement is unclear.
• Assuming simulator success proves hardware readiness: Exact simulation does not model all compilation effects, sampling variation, or device noise.
• Ignoring parameter initialization: Repeat runs with controlled seeds and report the spread of outcomes.
• Overbuilding the ansatz: Extra layers can create optimization difficulty and increase resource requirements without improving the result.
• Comparing incompatible references: Check that the classical calculation uses the same Hamiltonian, basis, mapping, and energy convention.
• Failing to pin software: Save package versions, environment files, and a small regression test. Framework interfaces and default behaviors can change.

If the circuit produces unexpected results, use a structured quantum circuit debugging workflow before tuning the optimizer.

When to revisit

Revisit this VQE checklist whenever the underlying inputs change: a new Hamiltonian, molecule, qubit mapping, ansatz, optimizer, simulator, noise model, or hardware backend. Also review it before a seasonal planning cycle if you are budgeting cloud jobs, preparing a teaching example, or deciding whether a prototype is ready for a larger benchmark.

At minimum, rerun a small regression experiment after upgrading Qiskit, PennyLane, Cirq, a simulator, or a numerical dependency. Compare the new objective trace and final error with a saved baseline rather than relying on a successful import. If an API has changed, update the implementation and the experiment record together.

Reusable results template

• Problem and Hamiltonian: ___
• Qubit mapping and constants: ___
• Backend, simulator, or device: ___
• Ansatz and depth: ___
• Initial parameters and random seed: ___
• Optimizer and stopping rule: ___
• Shots and measurement method: ___
• Final energy: ___
• Classical reference and absolute error: ___
• Evaluations, depth, and total shots: ___
• Repeatability across runs: ___
• Next change to test: ___

Start with a small, exact, reproducible case; add sampling; then introduce noise or hardware. That progression turns VQE from a demonstration into an experiment whose accuracy, cost, and limitations can be evaluated.