# DFTB Model Hamiltonian¶

The mandatory DFTB key allows to specify and control different aspects of how the DFTB Hamiltonian is created and how the stationary Schroedinger equation is solved.

DFTB
ResourcesDir  relativepath
{Model DFTB0|SCC-DFTB|DFTB3
{SCC
{Unrestricted yes|no}
{OrbitalDependent yes|no}
{HXdamping}
{iterations NIter}
{converge charge=QDiff}
{mixing Mix}
{ndiis}
{InitialCharges
...
End}
End}
{Occupation aufbau|fermi {temperature=FermiTemp}}
{UnpairedElectrons Number}
{Dispersion
method UFF|ULG|D2|D3-BJ
End}
{Purify
tolerance r
iterations n
End}
{SparsityThreshold sparsitythreshold}
{Repulsion
forcePolynomial
End}
{UseSymmetry  yes|no}
{StoreMatrices yes|no}
End

ResourcesDir

Allows to specify the path (relative to $ADFRESOURCES/DFTB) of the directory containing DFTB parameter files. Different parameters may be suitable for different DFTB evaluations. It is important to choose the appropriate parameter set for the type of calculation and molecular system under study, see parameter sets. Alternatively, an absolute path (starting with a slash character) can be specified to have complete freedom over the location of the directory. Examples: ResourcesDir Dresden Uses the Resource directory$ADFRESOURCES/DFTB/Dresden
ResourcesDir /home/myusername/myskfdir
Uses the specified path /home/myusername/myskfdir as the resource directory

NOTE: Each resource directory must contain a file called metainfo.yaml, which specifies the capabilities of the parameter set. For details see metainfo.yaml.

Model
Selects the model Hamiltonian used in the DFTB calculation. Can be either DFTB0 for the classic DFTB method without self-consistency cycle, SCC-DFTB for the self-consistent charge method, or DFTB3 for the self-consistent charge method with third-order constributions. The default is SCC-DFTB.
SCC

This optional section configures various details of the self-consistent charge cycle. If Model is set to DFTB0, none of this information is used and the entire section will be ignored.

Unrestricted yes|no
Enables spin unrestricted calculations. The default is a restricted calculation. Only collinear spin polarization is supported, see Theor Chem Acc (2016) 135: 232, for details. Must be supported by the chosen parameter set. Not yet compatible with DFTB3 or k-space sampling periodic calculations.
OrbitalDependent yes|no
Activates or disables orbital resolved calculations. Standard is set by the chosen parameter set, only set this option if you want to change the default (see metainfo.yaml).
hxdamping
This option activates the H-X damping. Note that this treatment is also automatically enabled if the model key is set to DFTB3.
iterations NIter
Allows to specify the maximum number of SCC iterations. Default is 100 iterations, which suffices for most standard calculations. If convergence issues are encountered, choosing a smaller value mixing parameter (see below) often provides a more stable but slower way to converge the SCC cycle. Convergence issues may also arise due to the use of the Aufbau occupations for systems with small HOMO-LUMO gaps. In this case the use of a Fermi broadening strategy may improve convergence (see below).
converge charge=QDiff
SCC convergence threshold in terms of maximum change in the atomic charges (in atomic units) between two succeeding SCC cycles. Default converge charge 1.0E-8.
ndiis Ndiis
Specifies the maximum number of samples considered during the direct inversion of iteration of subspace (DIIS) extrapolation of the atomic charges in during the SCC iterations (default ndiis 20). A smaller number of samples potentially leads to a more aggressive convergence acceleration, while a larger number often guarantees a more stable iteration. Due to often occurring linear dependencies within the set of sample vectors, the maximum number of samples is reached only in very rare cases.
mixing Mix
Mix is the parameter used to mix the DIIS linear combination of previously sampled atomic charge vectors with an analogous linear combination of charge vectors resulting from population analysis combination. The default for the mixing parameter is 0.2 and it can assume real values between 0 and 1.
InitialCharges
This section allows to set initial Mulliken charges for the SCC cycle. Specify one number per line and atom (or shell if running an orbital-resolved calculation). The order has to be the same as in the atoms block.
Occupation
This optional key allows to specify the fill strategy to use for the orbitals. It can be either “aufbau”, to fill the orbitals according to the Hund’s rule, or “fermi”, to perform electronic charge distribution over the orbitals. If “fermi” is specified, a further “temperature” option must be present, specifying the Fermi temperature in Kelvin (K). If this key is absent, the default is Fermi occupation with a temperature of 5K.
UnpairedElectrons
This optional key allows to specify the number of unpaired electrons (not the multiplicity!). This number will then be used in the orbital-filling strategy, even if it is unreasonable. Has to be compatible with the total number of electrons, meaning it must be an even number (or zero) if the total number of electrons is even and odd if the total number is odd. Must be an integer value. Note that this does not activate spin polarization, it only affects the filling of the orbitals.
Dispersion

This key allows to specify options for the London dispersion correction. If it does not exist, no dispersion correction will be included.

method UFF|ULG|D2|D3-BJ

This subkey is used to specify a dispersion model. Please refer to the literature for details on the different methods:

• UFF: L. Zhechkov et al., J. Chem. Theory Comput., 2005, 1 (5), pp 841-847
• ULG: H. Kim et al., J. Phys. Chem. Lett., 2012, 3 (3), pp 360-363
• D2: S. Grimme, J. Comput. Chem., 2006, 27: 1787-1799
• D3-BJ: S. Grimme et al., J. Comput. Chem., 2011, 32: 1456-1465

If no method specified in the Dispersion block, a default dispersion correction defined in the metainfo.yaml file (depends on “ResourcesDir”, see metainfo.yaml) will be used. Note that not all dispersion models are supported by all parameter sets. A list of supported models can be found in the parameter’s metainfo.yaml file.

Purify

By default (when the Purify section is not present), the next step’s density matrix is calculated from molecular orbitals obtained as eigenvectors of the charge-dependent Hamiltonian. An alternative way to obtain the density matrix is using an iterative purification procedure enabled by this keyword. Note also that molecular orbitals are not calculated when using the density matrix purification method, meaning that any subsequent calculations using molecular orbitals (e.g. TD-DFTB or Mayer bond order analysis) are incompatible with this keyword. Density matrix purification can be considerably faster than diagonalization for molecular of gamma-only periodic systems with large HOMO-LUMO gaps. Note that density matrix purification is faster for systems where the density matrix is sparse. The fill-in of the density matrix is printed to the standard output during the calculation. If it is too large (e.g. >50%), it is probably faster to use normal diagonalization.

tolerance r
Accepts a single real number r that defines the purification convergence threshold. Purification is considered converged when the trace of the density matrix becomes equal to the total number of electrons within r. The default value is 1.0e-8.
iterations
Accepts a single integer number n that determines the maximum number of steps in the purification cycle. If the desired tolerance is not reached during n steps, the calculation is aborted. The default value is 50.
Repulsion
This key allows to specify some details about the repulsion contribution evaluation. It currently accepts only one sub-key “forcePolynomial”, which forces the use of the polynomial representation (as defined in the header of the Slater-Koster parameter files), in place of the Spline description.
RadialExtrapolation

Advanced control option. Overrides the extrapolation method for Slater-Koster grid values between the end of the tabulated grid and the cutoff distance (value for which atoms are considered too far to interact). Depending on the structure of your Slater-Koster tables, a different radial extrapolation method may be needed in order to guarantee correct behavior, in particular for large and periodic systems. Five different extrapolation strategies are available:

none
Performs no extrapolation. All matrix elements for distances greater than the range of the tables in the Slater-Koster files are zero.
linear
Performs a linear interpolation between the last point of the grid and the value zero at cutoff distance.
improved (default)
Perform a 9th grade polynomial interpolation between 6 points of the grid and three zeros. This interpolation may prove unstable for particular Slater-Koster data.
bezier
Uses a Bezier curve passing through the last grid point and the cutoff point, guaranteeing continuity and smoothness. This is the suggested method in case of unexpected behavior.
original
Same as improved, but reproducing behavior of previous reference programs. This method is only available for backwards compatibility and should not be used anymore.
UseSymmetry yes|no
Enables or disables the use of symmetry. Currently only used in periodic calculations with >1 k-point. The key is optional, and in its absence the default is yes. For MD calculations, no symmetry will be used.
StoreMatrices yes|no
Default: no. If yes, save the Hamiltonian and Overlap matrices to the results file dftb.rkf.