VQE Tutorial: Build, Test, and Improve a Variational Quantum Eigensolver Workflow
VQEquantum-algorithmsquantum-chemistryvariational-algorithmshands-on-tutorial

VQE Tutorial: Build, Test, and Improve a Variational Quantum Eigensolver Workflow

QQubit Daily Editorial Team
2026-11-14
7 min read

A practical VQE tutorial covering Hamiltonians, ansätze, optimizers, convergence, noise testing, classical baselines, and experiment tracking.

This VQE tutorial presents a repeatable workflow for building, testing, and improving a variational quantum eigensolver experiment. You will learn how to construct a Hamiltonian, choose an ansatz and optimizer, measure convergence, test noise sensitivity, compare results with a classical reference, and keep an experiment log that makes future reruns meaningful.

Overview

The variational quantum eigensolver, or VQE, is a hybrid quantum-classical algorithm for estimating the lowest eigenvalue of a Hamiltonian. In quantum chemistry, that value can represent a ground-state energy under a chosen model. More generally, VQE can be applied whenever a problem can be expressed as minimizing the expectation value of an operator.

A VQE run alternates between two parts:

  1. A quantum circuit prepares a parameterized state and estimates the expectation value of a Hamiltonian.
  2. A classical optimizer updates the circuit parameters to seek a lower expectation value.

For a Hamiltonian written as H = Σᵢ cᵢPᵢ, where each Pᵢ is a Pauli term and cᵢ is its coefficient, the objective is to minimize E(θ) = ⟨ψ(θ)|H|ψ(θ)⟩. The parameter vector θ belongs to the ansatz, the circuit family used to prepare the trial state.

VQE is attractive for experimentation because it separates the quantum circuit from the classical search. It is also easy to misread. A lower reported energy does not automatically mean a better physical result. The outcome depends on Hamiltonian conventions, ansatz expressiveness, optimizer settings, measurement noise, shot count, simulator configuration, and the quality of the classical baseline.

Before coding, it helps to review the VQE implementation workflow and the quantum SDK comparison. The exact APIs and supported optimizers can change, so treat the code structure as a conceptual guide and verify syntax against the framework version used in your environment.

What to track

1. Hamiltonian construction

Start by recording the Hamiltonian rather than treating it as an invisible input. Capture the number of qubits, the number of Pauli terms, each coefficient, the operator ordering, and any energy shift or unit conversion. A sign error, omitted term, or inconsistent basis can produce a smooth-looking optimization curve with the wrong answer.

If your example comes from quantum chemistry, also record the molecule or model system, geometry assumptions, basis choice, active-space reduction, mapping convention, and symmetry restrictions. These details define the problem being solved. Two experiments can both be called VQE while targeting different Hamiltonians.

2. Ansatz structure

Track the ansatz family, number of layers, parameter count, entangling pattern, initial parameter values, and whether parameters are shared. A shallow hardware-efficient ansatz is often convenient for testing circuit execution, while a more problem-informed ansatz may encode useful structure with fewer layers. Neither is universally best.

Compare ansätze using the same Hamiltonian, initial conditions where practical, shot budget, optimizer budget, and stopping rule. Otherwise, an apparent improvement may come from a different experimental budget rather than the circuit design.

3. Optimizer and initialization

Record the optimizer name, learning-rate or step-size settings, maximum iterations, gradient method if applicable, parameter initialization, and random seed. VQE objectives can be noisy and may contain flat regions or local minima. A failed run does not by itself prove that the ansatz is unsuitable; it may reflect initialization or optimizer behavior.

Use several initializations when the experiment is small enough to permit them. Report the best result and the spread between runs instead of presenting one favorable trajectory as a general conclusion.

4. Measurement and execution settings

For every result, track whether the expectation value came from an exact statevector calculation, a shot-based simulator, a noisy simulator, or hardware. Record shots per circuit, measurement grouping if used, transpilation or compilation settings, backend identifier, and execution date. These variables affect both precision and comparability.

An exact simulator can help isolate algorithmic behavior, but it does not reproduce sampling uncertainty or device noise. A hardware run adds operational variability. For a practical introduction to resource accounting, see the quantum circuit resource estimation guide.

5. Validation metrics

Track more than the final energy. Useful metrics include:

  • Final objective value and the iteration at which it was reached.
  • Energy change between iterations and the stopping threshold.
  • Number of objective evaluations and total circuit executions.
  • Variance or confidence interval from finite-shot measurements.
  • Absolute and relative error against a trusted classical reference.
  • Ansatz depth, two-qubit gate count, and qubit count.
  • Difference between noiseless, noisy-simulator, and hardware results.

When relevant, also measure state overlap, symmetry violations, or expectation values of other observables. Energy alone may hide an incorrect state that happens to produce a plausible objective value.

Cadence and checkpoints

A useful VQE process has checkpoints before, during, and after optimization.

Before the run: verify the problem

First, evaluate the Hamiltonian with a classical method appropriate to its size. For a small demonstration, exact diagonalization is a useful reference. Confirm that the operator is Hermitian, that coefficient conventions are consistent, and that the number of qubits matches the circuit.

Next, run a deterministic or exact-simulator smoke test with a small ansatz. Confirm that the circuit accepts parameters, each Hamiltonian term is measured correctly, and the objective changes when parameters change. This catches wiring and observable-construction errors before shot noise complicates debugging.

During the run: inspect the trajectory

Save the objective after every iteration, not only the final value. A healthy-looking trajectory is not required to decrease at every step, especially with finite shots, but persistent oscillation, immediate stagnation, or large unexplained jumps deserves investigation.

Set a stopping rule based on an energy tolerance, a small change over several iterations, a gradient threshold when available, or an evaluation budget. Use more than one condition where possible. A maximum iteration count is a safety limit, not evidence of convergence.

After the run: repeat and compare

Repeat the experiment with at least one changed condition: a new initialization, a different optimizer, another ansatz depth, or a different shot count. Then compare the final energy, uncertainty, cost, and resource use. If only one configuration succeeds, describe that limitation clearly.

For noisy studies, use a staged progression: exact or noiseless simulation, shot-based simulation, noisy simulation, and hardware when access is available. Keep the Hamiltonian and ansatz fixed while changing the execution model. This makes it easier to identify where performance changes.

Compact experiment log

Use a record like the following for each run:

FieldExample entry
ProblemHamiltonian name, qubits, mapping, units
AnsatzFamily, layers, parameters, entangling pattern
OptimizerName, settings, maximum evaluations
ExecutionSimulator or backend, shots, noise model
ResultFinal energy, uncertainty, iterations
ReferenceClassical value and error
EnvironmentSDK version, Python version, seed, date
Next testSpecific variable to change

Versioning the code, environment, and data is especially important when SDK behavior changes. The guide to reproducible quantum computing experiments provides a broader workflow for preserving those details.

How to interpret changes

If increasing ansatz depth lowers the noiseless energy but worsens the hardware result, the added expressiveness may be outweighed by circuit depth and noise. That is a tradeoff, not a contradiction. Compare depth, two-qubit gates, measurement cost, and error together.

If more shots reduce variation without improving the average energy, sampling uncertainty was likely a limiting factor, but the ansatz or optimizer may still be the main source of bias. If a noiseless run performs well while a noisy run fails, inspect noise sensitivity and consider mitigation or circuit simplification. The quantum error mitigation benchmarking workflow can help structure that comparison.

If different optimizers reach different energies, repeat with matched initializations and evaluation budgets. A single successful run is weak evidence. Look for consistency across seeds, uncertainty intervals, and classical error.

Also distinguish optimization error from modeling error. An optimizer may find the minimum of the supplied Hamiltonian accurately even when the Hamiltonian is only an approximation of the physical system. Report both the computational result and the assumptions used to define the problem.

When to revisit

Revisit this VQE workflow whenever you change the SDK, simulator, optimizer implementation, backend, noise model, Hamiltonian, ansatz, or measurement strategy. A framework upgrade can alter parameter handling, transpilation, estimator behavior, or supported execution paths. Re-run the smoke test and at least one known baseline before comparing new results with old ones.

For an active project, review the experiment log monthly or after each meaningful batch of runs. Check whether resource estimates, convergence behavior, and hardware results still match the recorded assumptions. For a tutorial or shared reference implementation, perform a deeper refresh at least twice a year, and sooner after a major SDK release. Re-run every code example, update dependencies, and verify that simulator and hardware instructions remain valid.

Use this action list for your next experiment:

  1. Write down the Hamiltonian, units, qubit count, and classical reference.
  2. Select one baseline ansatz and one optimizer with explicit settings.
  3. Run an exact or noiseless smoke test before using finite shots.
  4. Log the full optimization trajectory, not just the final energy.
  5. Repeat with a changed seed or controlled configuration.
  6. Compare accuracy, uncertainty, depth, gate counts, and execution cost.
  7. Test noise separately and document any mitigation method.
  8. Save the environment, code version, backend details, and next experiment.

VQE becomes more informative when treated as a measured workflow rather than a single circuit demonstration. By tracking the problem definition, ansatz, optimizer, execution conditions, and validation baseline, you can tell whether a change improved the algorithm—or merely changed the experiment.

Related Topics

#VQE#quantum-algorithms#quantum-chemistry#variational-algorithms#hands-on-tutorial
Q

Qubit Daily Editorial Team

Quantum Computing Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.