Variational quantum algorithms combine a parameterized quantum circuit with a classical optimizer. This guide shows how to implement VQE and QAOA in Python, define cost functions, measure convergence, estimate execution requirements, and diagnose results that look optimized but are not reliable.
Overview
Variational quantum algorithms are useful when a problem can be expressed as an objective function evaluated by a quantum circuit. The circuit contains adjustable parameters, the quantum processor or simulator produces expectation values or samples, and a classical optimizer updates the parameters. The loop continues until the objective stops improving or a practical budget is reached.
Two common examples are the Variational Quantum Eigensolver (VQE) and Quantum Approximate Optimization Algorithm (QAOA).
- VQE estimates the lowest eigenvalue of a Hamiltonian. In chemistry and physics workflows, that value can represent a ground-state energy under a chosen model.
- QAOA uses a parameterized circuit to search for good solutions to a discrete optimization problem, such as a graph or constraint problem encoded as a cost Hamiltonian.
Both algorithms use the same practical pattern:
- Encode the problem as observables or a cost function.
- Choose an ansatz, or parameterized circuit.
- Evaluate the objective for the current parameters.
- Use a classical optimizer to propose new parameters.
- Track objective values, parameter changes, and execution resources.
- Validate the final result against a known solution, a classical baseline, or repeated measurements.
The most important distinction is between a lower objective value and a trustworthy result. A simulator may converge smoothly while a hardware run is dominated by sampling uncertainty, gate noise, limited connectivity, or an unsuitable ansatz. Convergence must therefore be evaluated together with resource use and validation quality.
How to estimate convergence and execution cost
Before running a variational algorithm, estimate three quantities: the number of optimization iterations, the number of circuit evaluations per iteration, and the number of measurement shots per evaluation.
A useful first-order estimate is:
Total shots ≈ iterations × circuit evaluations per iteration × shots per circuit
For VQE, one objective evaluation usually requires measuring each Hamiltonian term, unless the framework groups compatible observables. If the Hamiltonian has M measured groups, the estimate becomes:
Total shots ≈ iterations × M × shots per group
For QAOA, the count depends on how the cost is measured. If the objective is calculated from sampled bitstrings, one circuit may produce many samples, but the number of shots still affects the uncertainty of the estimated cost.
Classical optimizer behavior changes the circuit count. A gradient-based method may require several shifted or differentiated evaluations per iteration. A gradient-free method may evaluate multiple candidate points in one optimizer step. Treat the circuit-evaluation multiplier as an assumption, not a fixed property of the algorithm.
| Algorithm | Primary goal | Typical ansatz | Useful optimizer families | Minimum validation |
|---|---|---|---|---|
| VQE | Minimize an energy expectation | Hardware-efficient or problem-inspired circuit | Gradient-based or gradient-free | Compare energy with a classical or exact reference when available |
| QAOA | Minimize or maximize a discrete cost | Alternating cost and mixer layers | Gradient-free, gradient-based, or layerwise methods | Decode samples and compare objective values with a baseline |
Record the objective after every iteration rather than saving only the final value. A simple convergence report should include the best objective, final objective, iteration count, total circuit evaluations, shots, parameter norm, and validation result. For measurement-based workflows, also record uncertainty or repeated-run variation. Guidance on interpreting shots, probabilities, and error bars is available in Quantum Measurement Results in Python.
Inputs and assumptions
1. Define the objective precisely
For VQE, write the Hamiltonian as a weighted sum of Pauli operators:
H = Σ cᵢ Pᵢ
The circuit estimates each expectation value and combines them using the coefficients cᵢ. Check the sign convention, qubit ordering, units, and whether the reference energy is expressed in the same model.
For QAOA, define the cost in ordinary Python first. Test it on a few bitstrings before translating it into a quantum cost operator. This catches indexing and sign errors earlier than circuit debugging does.
2. Choose an ansatz that can express the target state
A hardware-efficient ansatz may use layers of single-qubit rotations followed by entangling gates. It is compact to describe, but excessive depth can make optimization difficult on noisy devices. A problem-inspired ansatz may use more domain knowledge and fewer parameters, but it requires more careful construction.
For QAOA, the number of layers, usually written as p, is a direct resource assumption. Increasing p adds parameters and circuit depth. It may improve expressiveness, but it also increases the optimization search space and hardware exposure.
3. Select the optimizer for the evaluation environment
Gradient-based optimizers can be effective when gradients are informative and objective evaluations are sufficiently stable. Gradient-free methods are often easier to prototype with noisy or sampled objectives, although they may require many evaluations. No optimizer is universally best: compare at least two candidates using the same initialization, stopping rule, and evaluation budget.
4. Separate development and hardware assumptions
Start with exact or high-shot simulation to verify the objective and circuit. Then test finite-shot simulation to expose sampling variability. Only after those checks should you compare with hardware results. Keep the circuit, transpilation, backend, shots, and optimization settings in the experiment record. SDK interfaces change, so consult the installed version's documentation and migration notes; the Qiskit 2.x migration guide is a useful example of why version details matter.
Worked examples
A compact VQE workflow in PennyLane
The following template uses a small Hamiltonian and a parameterized circuit. It is intended for learning and testing the optimization loop, not for making a hardware performance claim.
import pennylane as qml
from pennylane import numpy as np
n_qubits = 2
dev = qml.device("default.qubit", wires=n_qubits, shots=None)
coeffs = np.array([0.5, -0.3, 0.2])
observables = [
qml.PauliZ(0),
qml.PauliZ(1),
qml.PauliX(0) @ qml.PauliX(1),
]
H = qml.Hamiltonian(coeffs, observables)
def ansatz(weights):
for wire in range(n_qubits):
qml.RY(weights[wire], wires=wire)
qml.CNOT(wires=[0, 1])
qml.RZ(weights[2], wires=1)
@qml.qnode(dev)
def energy(weights):
ansatz(weights)
return qml.expval(H)
weights = np.array([0.1, 0.2, 0.3], requires_grad=True)
opt = qml.AdamOptimizer(stepsize=0.05)
history = []
for step in range(100):
weights, previous = opt.step_and_cost(energy, weights)
value = float(energy(weights))
history.append(value)
if step % 10 == 0:
print(step, value)
print("best energy:", min(history))
For a finite-shot experiment, set shots to a chosen value and repeat the optimization with several random seeds. Compare the mean final energy and its spread, not just the best run. A smooth decline in an exact simulator does not prove that the same optimizer will behave smoothly with sampled measurements.
A QAOA cost workflow
For a small graph, first implement a classical cost function. Suppose a bitstring represents a partition and the goal is to count edges crossing between partitions:
edges = [(0, 1), (1, 2), (2, 3), (3, 0)]
def cut_value(bits):
return sum(bits[a] != bits[b] for a, b in edges)
for bits in [(0, 0, 0, 0), (0, 1, 0, 1), (1, 0, 1, 0)]:
print(bits, cut_value(bits))
After verifying the classical function, construct the corresponding phase-separation operator and mixer in the SDK of your choice. Optimize the expected cost or a sampled estimate of it. At the end, decode measured bitstrings and report both the best observed bitstring and its frequency. The best sample can be useful even when the average objective has not fully converged, but it should be labeled separately from the expected objective.
How to tell whether it is actually converging
- Plot objective value against iteration and evaluation count.
- Track the best-so-far value as well as the current value.
- Use a stopping rule based on improvement over a window, not a single unchanged value.
- Repeat from multiple initial parameters.
- Compare against a simple classical baseline or exact result for small instances.
- Repeat finite-shot or hardware runs to estimate variability.
A plateau may indicate convergence, an overly expressive search space, weak gradients, an unsuitable initialization, or measurement noise. If every initialization produces nearly identical values and gradients are small, test a shallower ansatz, a problem-inspired initialization, fewer layers, or a different parameterization. If the objective fluctuates widely, increase shots for diagnosis or use an optimizer designed to tolerate noisy evaluations.
When to recalculate
Recalculate the estimate whenever an input that affects evaluations or uncertainty changes. This includes the number of Hamiltonian terms, observable grouping, QAOA depth, ansatz layout, optimizer, stopping tolerance, shot count, simulator mode, backend, transpiled circuit depth, and error-mitigation procedure.
Review the workflow after changing SDK versions as well. Primitive interfaces, optimizer names, measurement behavior, and backend submission patterns can change even when the mathematical algorithm remains the same. Keep a pinned environment and a small regression test for the objective, parameter shape, and expected circuit structure. The guide to testing quantum circuits with pytest provides patterns for making these checks repeatable.
Before trusting a new result, use this short checklist:
- Verify the classical objective on known inputs.
- Run exact or high-precision simulation to validate the circuit.
- Estimate total circuit evaluations and shots before submitting jobs.
- Compare at least two initializations or optimizer settings.
- Inspect convergence plots, not only the final number.
- Repeat the best configuration and report variability.
- Compare the decoded solution or energy with an appropriate baseline.
Use the resulting record as a reusable experiment specification. When the problem, SDK, optimizer, or hardware changes, update the assumptions and rerun the same checks. That makes a VQE or QAOA experiment easier to compare, debug, and improve than a one-off circuit execution.