- Diagnosing failures
- Problem : Repeated
*safe*steps during NGWF Conjugate Gradients optimisation - Problem : Repeated
*safe*steps during LNV Conjugate Gradients optimisation. - Problem : Occupancies
*break*during LNV optimisation of kernel. - Problem : Occupancies are `broken' from start of calculation
- Problem : RMS Commutator (HKS-SKH) stagnates during LNV optimisation.
- Problem : RMS NGWF gradient stagnates during NGWF CG optimisation
- Good practices

Performing DFT calculations with ONETEP is, unfortunately, not yet quite as close to being a `black-box' type approach as is plane-wave DFT with codes such as CASTEP. With badly-chosen input settings, many fairly standard calculations in ONETEP will not converge, or may even converge to the wrong result. Fortunately, many of these problems are easy to fix with a bit of experience.

In general, it is advisable to run with full output verbosity (output_detail : VERBOSE) the first few times you run a new kind of system, and to be on the lookout for any warnings or garbage numbers in the output (eg ****'s in place of what should be real numbers). Remember that for the energy to be accurate, we must have simultaneous convergence of both the density kernel and the NGWFs. If either of these are not converging well by the end of the calculation, there may be a problem.

In this tutorial, we will briefly examine some reasons behind common types of convergence failure, and what to do to eliminate those failures and perform accurate simulations.

**Problem : ** Occupancies *break* during LNV optimisation of kernel. Examine the output with
output_detail: VERBOSE and look at the occupancy error, occupancy bounds and bandgap reported at the end of each cycle of LNV optimisation. Remember, a well-converged kernel has a very low RMS occupancy error (10^{-3} or less), no occupancies outside the ranges near 0 and 1 (approx -0.05:0.05 and 0.95:1.05) or RMS occupancy errors should be decreasing during the LNV cycle (particularly if no kernel truncation is applied). The bandgap estimator should be positive (if it is negative, something is badly wrong!).

**Problem : ** Occupancies are *broken* from start of calculation. Symptoms as above. Palser Manolopoulos or Penalty Functional may be unstable due to degeneracy or near-degeneracy at the Fermi level. Check the output of Palser Manolopoulos for warnings.

**Solution : ** If there is an initial degeneracy at the Fermi level, an O(N^{3}) diagonalisation may be required to get a good starting kernel. Set maxit_palser_mano : -1.

**Problem : ** RMS Commutator (HKS-SKH) of kernel and Hamiltonian stagnates (stops going down with each iteration) during LNV optimisation. This is a sign that the current set of NGWFs is not able to represent a density matrix that both reproduces the electron density
that generated the Hamiltonian while simultaneously describing the occupied eigenstates of that Hamiltonian. If this problem does not start to go away after a few steps of NGWF optimisation, a better or larger initial set of NGWFs may be required.

**Solution : ** Improve initial guess for NGWFs - examine reports from Pseudoatomic initialisation for clues on what might be missing.

**Problem : ** RMS NGWF gradient stagnates (stops going down) during NGWF CG optimisation, while energy is still going down slowly. This often suggests that the NGWFs may have expanded away from their centres to have signicant value near the edge of their localisation
region, and thus cannot optimise successfully.

**Solution : ** Increase NGWF radius. Sometimes increasing energy cutoff helps as well.

A useful check on the accuracy of the final result is to perform a full O(N^{3}) diagonalisation at the end of the calculation, if it is computationally feasible to do
so.

To activate this, turn on a properties calculation with do_properties : T, and then ask for an eigenvalue calculation of the first 100 eigenvalues either side of the Fermi energy, for the kernel and Hamiltonian matrices, by setting num_eigenvalues : 100.

If all is well, then the occupation eigenvalues should all be close to 0.00000 or 1.00000 (empty or full) and the Hamiltonian eigenvalues should all be within a sensible range.

One final note if you're not getting the result you expect check the units on your atomic positions! ONETEP expects positions in bohr if the units are not specied, so if your positions are in Angstroms, you will need to add 'ang' as the first line of the positions_abs block.