Fixing SCF Convergence Problems in Quantum ESPRESSO

Few things are as frustrating as watching a Quantum ESPRESSO SCF run oscillate for a hundred iterations and then die without converging. The good news is that convergence failures almost always trace back to a small set of causes, and each has a well-understood fix. This guide explains why the SCF loop stalls and gives you a concrete, ordered strategy to get it converging again.

Why the SCF Loop Fails to Converge

The self-consistent field loop iterates until the input and output charge densities agree. Density mixing damps the update:

where \(\beta\) is mixing_beta. The loop fails when successive densities never settle — either oscillating between values or drifting without approaching a fixed point. Three broad situations cause most failures.

• Metals without smearing. A sharp, partially filled band at the Fermi level makes the number of occupied states change discontinuously between iterations, so the density lurches back and forth.
• Magnetic systems with a poor initial guess. Spin-polarized calculations have multiple nearby solutions; a bad starting magnetization sends the loop wandering between them.
• Bad geometry or cell. Atoms placed too close together, an unreasonable lattice constant, or a broken structure create pathological potentials that no mixing scheme can tame.

Recognizing which category you are in is the first diagnostic step. Watch the estimated scf accuracy line: if it oscillates the problem is usually mixing or smearing; if it plateaus at a large value the culprit is often geometry or an eigensolver breakdown.

flowchart TD
  A[SCF not converging] --> B{Accuracy oscillates?}
  B -->|Yes, metal| C[occupations = smearing<br/>degauss = 0.01–0.02]
  B -->|Yes, insulator| D[Lower mixing_beta<br/>try local-TF]
  B -->|No, plateaus high| E{eigenvalues not converged?}
  E -->|Yes| F[diagonalization = cg]
  E -->|No| G{Magnetic system?}
  G -->|Yes| H[Larger starting_magnetization<br/>+ small mixing_beta]
  G -->|No| I[Check geometry, ecutrho,<br/>nbnd, atom overlaps]
  C --> J[Re-run SCF]
  D --> J
  F --> J
  H --> J
  I --> J
  J --> K{Still stuck?}
  K -->|Yes| L[Staged recipe:<br/>stabilize then tighten conv_thr]
  K -->|No| M[Converged]

Tuning the Charge-Density Mixing

The mixing step blends the new density with previous ones to damp oscillations. The controlling variable is mixing_beta in &ELECTRONS, the fraction of the new density mixed in each iteration.

• The default 0.7 is aggressive and works for well-behaved insulators.
• Lower it to 0.3, 0.2, or even 0.1 for metals, magnetic systems, or large cells. Smaller values are slower but far more stable.

&ELECTRONS
    conv_thr        = 1.0d-8
    mixing_beta     = 0.2
    mixing_mode     = 'local-TF'
    mixing_ndim     = 8
/

The mixing_mode variable chooses the scheme. 'plain' is standard, but 'local-TF' (local Thomas-Fermi screening) dramatically helps large, inhomogeneous, or metallic slabs where charge sloshes between regions. mixing_ndim sets how many previous iterations the Broyden mixer remembers; raising it from the default 8 to 12-20 can rescue stubborn cases at the cost of memory.

Smearing: The Fix for Metals

If your system is metallic, the single most important change is switching from fixed occupations to smearing. This replaces the sharp step \(f(\varepsilon)=\theta(E_{\mathrm{F}}-\varepsilon)\) at the Fermi level with a smooth function such as the Fermi–Dirac distribution

(or Marzari–Vanderbilt / Methfessel–Paxton forms), letting occupations vary continuously and stabilizing the loop.

&SYSTEM
    ibrav       = 3
    celldm(1)   = 5.42
    nat         = 1
    ntyp        = 1
    ecutwfc     = 45.0
    ecutrho     = 360.0
    occupations = 'smearing'
    smearing    = 'mv'
    degauss     = 0.02
/

The key variables:

• occupations = 'smearing' turns on the smooth filling.
• smearing selects the function. 'mv' (Marzari-Vanderbilt cold smearing) and 'mp' (Methfessel-Paxton) are preferred because the total energy depends only weakly on degauss. 'gauss' and 'fd' (Fermi-Dirac) are alternatives; use 'fd' only when the smearing represents a real electronic temperature.
• degauss is the broadening width in Rydberg. A value of 0.01-0.02 Ry is typical. Too small brings back the convergence trouble; too large smears out physical features and biases the energy.

Remember that degauss interacts with k-point density: smaller broadening demands a denser k-grid to integrate the Fermi surface accurately, so converge them together.

Choosing the Diagonalization Algorithm

The diagonalization variable selects how the Hamiltonian is diagonalized within each SCF step. Occasionally the iterative solver itself is the point of failure, throwing errors like “eigenvalues not converged.”

Davidson ('david') is the default and fastest, but it can struggle with difficult metallic or near-degenerate systems. Switching to conjugate gradient is a reliable fallback:

&ELECTRONS
    diagonalization = 'cg'
    diago_thr_init  = 1.0d-4
/

If Davidson runs out of memory on a large cell, reducing diago_david_ndim from 4 to 2 shrinks its workspace. The 'cg' solver uses much less memory and, while slower per iteration, often converges the overall SCF when Davidson cannot.

Getting Magnetism Started Correctly

Spin-polarized calculations need both nspin = 2 and a sensible initial spin arrangement. Without a good guess the loop may collapse to a nonmagnetic solution or oscillate between competing states.

&SYSTEM
    nspin                   = 2
    starting_magnetization(1) = 0.7
    starting_magnetization(2) = -0.7
    occupations             = 'smearing'
    smearing                = 'mv'
    degauss                 = 0.01
/

starting_magnetization(i) sets the initial polarization per species, ranging from -1 to +1. For an antiferromagnet, give two sublattices opposite signs by defining them as separate species. Provide a large initial value (0.5-1.0) rather than a timid one — it is easier for the loop to relax an overestimated moment down than to grow one from near zero. Combining a strong starting guess with a small mixing_beta is the standard recipe for magnetic convergence.

Checking Geometry and Other Culprits

When mixing and smearing do not help, suspect the structure. Overlapping atoms produce enormous forces and singular potentials. Verify bond lengths, confirm your CELL_PARAMETERS units, and make sure no two atoms share a position. A quick relax from a slightly perturbed geometry can shake a system out of a pathological configuration.

Other frequent offenders:

• Underconverged ecutrho causes egg-box noise that prevents tight convergence. Raise it to 8-12x ecutwfc for ultrasoft potentials.
• Too tight conv_thr too early. Converge loosely first (1.0d-6), then restart tighter.
• Wrong number of bands. For metals, add empty states with nbnd so the smeared Fermi level has room; a rule of thumb is 20% more bands than occupied states.

Reading the Warning Signs in the Output

Quantum ESPRESSO leaves clues in the output that tell you which fix to reach for. Learning to read them turns guesswork into diagnosis.

• c_bands: N eigenvalues not converged repeated across iterations points at the diagonalizer. Switch to 'cg' or loosen diago_thr_init.
• The estimated accuracy bouncing up and down by orders of magnitude signals a mixing or smearing problem, not an eigensolver one.
• Not enough space allocated for radial FFT or negative charge warnings usually mean ecutrho is too low for your pseudopotential.
• A warning that the system is metallic while you used occupations = 'fixed' is the code telling you outright to switch on smearing.
• SCF correction compared to forces is large at the end of a relaxation means the SCF was not tight enough for reliable forces; lower conv_thr.

A Staged Strategy for Stubborn Systems

When a difficult system refuses every single change, combine fixes in stages rather than flipping one switch at a time. A robust recipe for a hard magnetic metal looks like this: start with occupations = 'smearing', smearing = 'mv', and degauss = 0.02; set mixing_beta = 0.1 with mixing_mode = 'local-TF'; give a strong starting_magnetization; and use diagonalization = 'cg'. Converge loosely at conv_thr = 1.0d-6 first, then restart from the saved charge density with a tighter threshold. This staged approach — stabilize first, tighten second — resolves the overwhelming majority of cases that resist any individual fix.

A Troubleshooting Checklist

Work through these in order — the earlier fixes solve the majority of cases.

Run the corrected input as usual and watch the accuracy fall steadily:

mpirun -np 8 pw.x -in metal.scf.in > metal.scf.out
grep 'estimated scf accuracy' metal.scf.out

For the complete list of &ELECTRONS variables and their defaults, consult the Quantum ESPRESSO documentation. Our convergence testing tutorial explains how cutoffs and k-points interact with these settings, and the computational engines page covers the solvers under the hood.

Run it on Simatra

Debugging convergence is far less painful when each test run finishes fast. Simatra runs Quantum ESPRESSO on GPU-accelerated clusters through GPU-Opt-V2 instances, delivering up to 5x faster convergence and handling supercells up to ~2,000 atoms — so you can iterate on mixing_beta, smearing, and diagonalization settings in minutes rather than waiting on a queue. Pair Quantum ESPRESSO with KRONOS, our native engine, described on the computational engines page. Start free with $100 in credits at app.simatra.io.