Skip to content

2.4 Diagnose SCF mixing and charge sloshing

Version and execution status. Core syntax is checked against the official ABACUS v3.9.0 source documentation and example files, reviewed on 2026-10-05. The release list also contains stable v3.10.1 and 3.11 beta tags; v3.9.0 is this course’s reproducible baseline, not a claim about the newest release. These are unexecuted teaching templates. Initial numerical values are candidates for testing, not certified results. No energies, timings or convergence traces below are measurements.

Long-wavelength charge sloshing and schematic residual histories for stable and oscillatory mixing

Open figure at full size

2.4.1 The question: which part of the feedback loop fails?

SCF is a nonlinear fixed-point problem: an input density produces a potential, eigenstates and a new output density. Oscillation may reflect an overly aggressive update, long-wavelength charge sloshing, poor occupation sampling, insufficient bands, or a bad initial model. “More iterations” addresses none of these automatically. Begin with the complete aluminum parent and its separately checked cutoff/mesh/width settings; do not diagnose mixing while the integration problem remains uncontrolled.

The goal is a reproducible, successfully converged electronic state, not merely a log ending without a crash. This case separates mixing parameters from physical parameters. Do not change the geometry, functional or magnetic model merely to make a curve look smooth; such changes solve a different problem.

2.4.2 Worked diagnostic deltas

Copy all three aluminum files. Keep the accepted numerical model unchanged and replace only these INPUT values for a trial:

suffix al_mix_beta02
mixing_type broyden
mixing_beta 0.2
mixing_ndim 8
mixing_gg0 1.0
scf_nmax 200

This is a scoped delta, not a complete INPUT. Test mixing_beta candidates such as 0.4 and 0.2 under identical conditions. If needed, test pulay as a separate change, or a smaller history size if stored vectors become unhelpful. The baseline supports plain, pulay and broyden; do not invent an AMIX or BMIX tag borrowed from another code.

Version-specific trap: the v3.9.0 reference states that Kerker preconditioning is automatically disabled when mixing_beta <= 0.1. Thus mixing_beta 0.1 plus mixing_gg0 1.0 is not evidence that active Kerker scaling was tested. Use a controlled value above that boundary when testing Kerker, and verify effective behavior in the exact installed release. This condition is also present in the v3.10.1 reference checked for this course.

2.4.3 Residuals, damping and preconditioning

Define the unmixed fixed-point residual as

\[R[\rho]=\rho_{\mathrm{out}}[\rho]-\rho.\]

A simple mixing step is \(\rho_{n+1}=\rho_n+\beta R[\rho_n]\). If a linearized mode of the SCF map has eigenvalue \(\lambda\), its simple-mixing amplification is \(1+\beta(\lambda-1)\). Reducing \(\beta\) can damp an oscillatory unstable mode, but it can also slow a stable mode. Broyden and Pulay exploit histories rather than applying this simple formula alone, so the algebra explains the mechanism without predicting an exact iteration count.

An idealized Kerker factor is

\[P(q)=\frac{q^2}{q^2+q_0^2}.\]

It suppresses the small-\(q\), long-wavelength component relative to large-\(q\) components. This follows from the formula even though an imprecise sentence in a reference may describe frequency suppression differently. Do not treat mixing_gg0 as a universal material-independent cure. The baseline implementation’s availability condition and units/conventions must be checked before translating a \(q_0\) value from another code.

Finally, scf_thr is a density criterion, not an energy tolerance in eV. The default criterion type differs between PW and LCAO in the baseline. A numerical value of 1e-8 in the two bases is not necessarily the same mathematical residual norm. Validate the target energy or force on tightening the criterion rather than equating digits.

2.4.4 A diagnosis tree with observable evidence

Read residual and energy traces together. Alternating large residuals suggest overshoot or an occupation-driven oscillation. A nearly flat residual may indicate a slow mode, poor preconditioning or insufficiently solved eigenstates. Sudden spikes can follow changes in occupations or a restart inconsistency. These are hypotheses to test, not uniquely identifying fingerprints.

  1. Verify inputs, UPF, electron count, mesh, width and top-band occupations.
  2. Confirm the eigensolver is appropriate for the basis/build and that it is not failing.
  3. Change one mixing control, retaining all physical inputs and the same fresh initialization for the controlled comparison.
  4. Save the entire trace, not just the last iteration; compare iterations and final properties.
  5. Rerun the accepted setting from a fresh density or a separately documented compatible restart.

Do not loosen scf_thr simply to obtain a success label. If a looser threshold is used for a preliminary stage, reconverge at the final validated criterion before reporting the target property. For magnetic systems, multiple self-consistent states may be physically distinct; a smooth trace is not proof of the ground state.

2.4.5 A blank diagnostic ledger

Trial β Method/history Kerker actually active? SCF passed Iterations Final property change
Baseline 0.4 Broyden / recorded verify — — —
Damped 0.2 Broyden / 8 verify — — —
Alternative controlled Pulay / recorded verify — — —

Accept a setting only when it meets the validated residual criterion, produces stable target properties under tightening, and is reproducible. A shorter iteration count is a secondary performance benefit. Compare the chosen final energy definition consistently for metals. Never fit a convergence rate to the imaginary explanatory curves in the figure: they illustrate mode behavior, not measured aluminum iterations.

Archive unsuccessful trials as well as the successful one. They show which hypotheses were actually tested and prevent future users from repeating a failed recipe without its context. State if no setting meets the target; identifying unresolved SCF behavior is a useful result, not a reason to fabricate an energy.

2.4.6 Pitfalls and exercises

mixing_beta 0 freezes the density update; it is not a robust general-purpose convergence method. Raising scf_nmax is meaningful only when the trace is actually progressing. Aggressive history can amplify poorly conditioned information. A compatible restart may help, but reading a density from a different cell or species model requires its own validity check.

  1. Mode exercise. For a hypothetical scalar map with \(\lambda=-3\), compare simple mixing at \(\beta=0.5\) and \(\beta=0.2\). Answer guidance: the amplification factors are \(-1\) and \(0.2\), respectively. The first does not decay in this linear model; the second does. These are analytic toy values, not ABACUS iteration results, and do not predict Broyden histories exactly.
  2. Preconditioner exercise. Evaluate \(P(q)\) at \(q/q_0=0.1\) and 10, then explain which wavelength is damped. Answer guidance: approximately 0.0099 and 0.9901, so the long-wavelength small-\(q\) component is suppressed. Add the implementation check: in this baseline, choosing \(\beta\le0.1\) disables Kerker regardless of the printed mixing_gg0 value.

With electronic stability established, the next chapter can investigate forces and structures without confusing an SCF failure with a structural optimizer failure.

2.4.7 Official references and provenance

These references establish file grammar and available options. The explanations, comparison designs, algebraic exercises and figures are original teaching material; no published example energy is presented as a result of this course. Additional learning resources are collected in the course hub references section. The university-linked 2024 guide is supplementary teaching, not a substitute for the pinned input reference.