Troubleshooting
***************


SCF does not converge
=====================

Some systems are more difficult to converge than others. A Pd slab for
instance is easier to converge than an Fe slab. Generally, what you do
in a problematic case is to go for more conservative settings. The two
main option are to decrease "SCF%Mixing" and/or "DIIS%Dimix".

   SCF
      Mixing 0.05 ! more conservative mixing
   End

   Diis
      DiMix 0.1 ! also more conservative strategy for DIIS procedure
      Adaptable false ! disable automatic changing of dimix
   End

   Convergence
      Degenerate Default ! For most calculations this is quite a good idea anyway
   End

An other option is to first run the system with a SZ basis, which may
be easier to converge. Then you can Restart the SCF with a larger
basis set from this result.

Sometimes SCF convergence problems are caused by bad precision. An
indication of this is when there are many iteration after the HALFWAY
message. The simplest thing to try is to see whether increasing the
"NumericalAccuracy" helps. Specifically an insufficient quality of the
**density fit** may cause problems. For systems with heavy elements
the quality of the **Becke grid** may also play a role. Another
potential problem is using **only one k-point**.

Next thing to try is the MultiSecant method. This one comes at no
extra cost per SCF cycle compared to the DIIS method.

   SCF
     Method MultiSecant
   End

   MultiSecantConfig
      ! put here optional keywords to tweak the MultiSecant method
   End

An alternative is to try a **LIST** method. For sure the cost of a
single SCF iteration will increase, but it may reduce the number of
SCF cycles, see Diis%Variant.

   Diis
     Variant LISTi ! invoke the LISTi method
   End

For heavy elements the use of a small or no frozen core may complicate
the SCF convergence.


Finite temperature during geometry optimization
-----------------------------------------------

Often systems are more easy to converge when applying a finite
electronic temperature. By doing so your energy will deviate from the
ground state. If you are optimizing, say, a fancy molecule over a Ni
slab, then you do not care too much about this when the geometry is
not nearly converged yet (when the gradients are still big).

Using so-called automations, it is possible to instruct band to use a
higher electronic temperature in the beginning of a geometry
optimization, and a lower one at the end. Similarly you can allow for
more loose SCF convergence at the start of the geometry optimization.
You specify such "automations" inside the ams-level
GeometryOptimization block, for example

   GeometryOptimization

     EngineAutomations
        Gradient variable=Convergence%ElectronicTemperature InitialValue=0.01 FinalValue=0.001 HighGradient=0.1 LowGradient=1.0e-3
        Iteration variable=Convergence%Criterion InitialValue=1.0e-3 FinalValue=1.0e-6 FirstIteration=0 LastIteration=10
        Iteration variable=SCF%Iterations InitialValue=30 FinalValue=300 FirstIteration=0 LastIteration=10
     End
   End

Let us concentrate on the first "automation". What this will do is the
following.

* At the first step Convergence%ElectronicTemperature (kT) will be set
  to InitialValue, i.e. 0.01. (Temperatures are entered as kT in
  Hartree.)

* If at any step the gradient is bigger than HighGradient the
  temperature will be InitialValue

* If at any step the gradient is smaller than LowGradient the
  temperature will be FinalValue, i.e. 0.001

* If the gradient is in between HighGradient and LowGradient, a linear
  interpolation is done (on a logarithmic scale)

* At the last calculation FinalValue will be used, even if the
  geometry did not converge

Another trigger for automation is the number of geometry steps taken,
shown in the two automations with "Iteration".

Let us look at the second automation.

* At the first geometry the Convergence%Criterion is relaxed to
  1.0e-3.

* After the tenth geometry step this will be 1.0e-6

* In between an interpolated value will be used

The third automation shows that you can also automate SCF%Iterations.
Currently only three band keywords can be automated this way.


Geometry does not converge
==========================

One thing that you should make sure is that at least the **SCF
converges**. If that is so, then maybe the **gradients are not
accurate enough**. Here are some settings to improve the accuracy of
the gradients

   RadialDefaults
     NR 10000   ! more radial points
   End

   NumericalQuality Good


Lattice optimization does not converge for gga
==============================================

What can help is use to use analytical stress rather than numerical
stress. There are three things to change for this to work.

   SoftConfinement Radius=10.0

   StrainDerivatives Analytical=yes

   XC
     libxc PBE     # may also be another GGA, but not a metaGGA
   End

Here follows an explanation why. The SoftConfinement is set to a fixed
value, rather than one depending on the lattice vectors, because that
is not covered by the analytical stress code. The normal value for
this radius is 10, except for 3D bulk systems with a small lattice
where it is set to something like the size of the lattice vector.

The other two bits are needed to trigger the use of analytical stress
(which are strain derivatives of the energy). The use of the libxc
library is needed, as it affords derivatives required for the stress.


I see two band gaps, which one is best?
=======================================

The band gap is the difference between the bottom of the conduction
band (BOCB) and the top of the valence band (TOVB).

It is now important to distinguish two methods to arrive at the
information of TOVB, BOCB, and hence the gap. The first is the one
coming from the analytical k-space integration scheme determining the
fermi level and occupations, let us call this the interpolation
method. The second one is a strictly post SCF method that cannot be
used to determine the fermi energy and occupations. This is about
calculating the bands along a path through the BZ assuming a certain
fixed density/potential. Let us call this second method the from band
structure method.

The advantage of the "band structure" method is that is you can use a
very dense sampling of k-points along the chosen path (DeltaK).
Normally this is the better way to get the gap, but you assume that
both the TOVB and BOCB are on the specified path, which is not a
mathematical necessity (although in practice very often true). The
advantage of the "interpolation" method that is really follows the
(quadratically interpolated) bands over the whole BZ. Typically the
spacing between k-points is much larger than DeltaK from the plot (as
the number of points for the first grows cubic and the latter only
linear).

Finally the gap printed in the kf file is the one from the
"interpolation method".


Band structure does not match the DOS
=====================================

This problem may be related to the previous topic. The DOS is derived
from true k-space integration called the "interpolation method" in the
previous topic: it samples through interpolation the whole BZ. For the
band structure plot a single line is used, and typically a much denser
grid can be afforded. So make sure that the DOS is converged with
respect to the KSpace%Quality paramter: try a better (or worse) value.

Ultimately a converged DOS may still not match a band structure as it
is possible that the chosen line misses some features (it does not
cover the whole BZ).

Finally the energy grid for the DOS may be too coarse, it can be made
smaller with DOS%DeltaE.


Missing core bands or DOS peaks in amsbands
===========================================

If you do a calculation on, say, an Al chain you may expect a core
like band and corresponding DOS peak at -1500 eV. To achieve this you
first need to set the frozen core to None. Even then it still does not
show up, because by default BandStructure%EnergyBelowFermi is 10
Hartree (~300 eV). If you set it to something large (10000) you will
now see the 1s band showing up near -1500 eV, however the
corresponding DOS peak appears invisible... that is, until you zoom in
the y-axis appropriately. If the DeltaE used for the dos is smaller
than the height of a pixel the peak will be invisible, or very faint.


Negative frequencies in phonon spectra
======================================

When doing a phonon calculation one sometimes encounter unphysical
negative frequencies. There are two likely causes: either the
**geometry was not in the minimum geometry**, or the **step size**
used in the Phonon run is too large. Also **general accuracy** issues
may be the cause, such as numerical integration, k-space integration
and fit error.


Too much scratch disk space is used
===================================

For systems having either many basis functions or many k-points the
required disk space demand can grow and te program can crash. The
needed scratch space is overwhelmingly determined by (temporary)
matrices written to disk. How this is done is determined by an input
key. In case of this problem  set

   Programmer Kmiostoragemode=1   ! 1 means: fully distributed, 2 is the default meaning distributed only within (ShM) nodes

You can increase the available scratch disk space by using more nodes.
The number of nodes (according to the AMS definition) is printed in
the output and logfile

   AMS 2021.105  RunTime: Feb08-2022 19:27:17  ShM Nodes: 1  Procs: 24

and you can search for "ShM Nodes".


Basis set dependency
====================

A calculation aborts with the message: dependent basis. It means that
for at least one k-point in the BZ the set of Bloch functions,
constructed from the elementary basis functions is so close to linear
dependency that the numerical accuracy of results is in danger. To
check this, the program computes, for each k-point separately, the
overlap matrix of the Bloch basis (normalized functions) and
diagonalizes it. If the smallest eigenvalue is zero, the basis is
linearly dependent. (Negative values should not occur at all!). Given
the limited precision of numerical integrals and other aspects in the
calculation, you are bound for trouble already if the smallest
eigenvalue is very small, even if not exactly zero. The program
compares it against a criterion that can be set in input (key
"Dependency" option *Bas*).

If you encounter such an error abort, you are strongly advised not to
adjust the criterion so as to pass the internal test: there were good
reasons to implement the test and to set the default criterion at its
current value. Rather, you should adjust your basis set. There are two
ways out: using confinement or removing basis functions.


Using confinement
-----------------

Usually the dependency problem is due to the diffuse basis functions.
This is especially so for highly coordinated atoms. One way to reduce
the range of the functions is to use the Confinement key. In a slab
you could consider to use confinement only in the inner layers, and to
use the normal basis to the surface layers. The idea is that basis
functions of the surface atoms can describe the decay into the vacuum
properly, and that inside the slab the diffuseness of the functions is
not needed. If all the atoms of the slab are of the same type, you
should make a special type for the inner layers: simply put them in a
separate Atoms block. The confinement can be specified per type.


Frozen core too large
=====================

BAND calculates the overlap matrix of the core functions, and this
should approximate the unit matrix. To validate that this is the case
two numbers are checked: the smallest eigenvalue of the overlap matrix
(which should be larger than "Dependency%Core") and the maximum
absolute deviation of diagonal elements from one, which should be
smaller than 1-"Dependency%Core". When the deviation is larger then
the frozen-core overlap criterion the program stops. The default
("Dependency%Core" = 0.80) is fairly tolerant. The safest solution is
to choose a smaller Frozen core, this can also be controller per atom
type (element) or per region, see More Basis input options. In the
text output the name of the element is printed that seeems to be most
responsible for the frozen core too large error. For performance
reasons, however, this may not be the preferred option. In practice
you might still get reliable results by setting the criterion to 0.5,
see the Dependency block. For the *5d* transition metals, for
instance, you can often freeze the 4f orbital (using the more tolerant
setting), thus reducing the basis set considerably. If you loosen the
criterion we strongly advise you to compare these results to a
calculation with a smaller core. Such tests can be performed with a
smaller unit cell or with a lower quality for the "KSPACE" block key.


requested kgrid appears to break the symmetry
=============================================

Band creates by default a regular k-grid. In the case of 3D the size
is determined by k1,k2, and k3. Normally the values are derived from
KSpace%Quality and the length of the trhee reciprocal lattice vectors.
If a lattice vector is long enough the corresponding k may be set to
1, which is a special value. For instance if you get for your system a
3x5x1 grid it means that effectively we have a 2 dimensional problem.

This can be problematic when there is symmetry. Perhaps there are
symmetry relations between the "remaining" two vectors and the
"removed" lattice vector. If such is the case the error "kgrid appears
to break the symmetry" is raised.

You can either disable the symmetry

   UseSymmetry No # inside the BandEngine block

or you can figure out what the automatic values for k1,k2, and k3 are.

In case of the error you see in the output

   grid method with params           3           3           1
   ERROR: requested kgrid appears to break the symmetry
           there are two solutions
           1) Disable symmetry for the engine
           2) Avoid a automatic grid like 3x3x1. Try a better KSpace%Quality.

So that in this case a 3x3x1 grid was chosen. In this example you
probably want to increase k3

   KSpace
       Regular
          NumberOfPoints 3 3 3 # specify k1,k2,k3 "by hand"
       End
   end
