Quickstart into Production

This chapter should serve as a quickstart tutorial guiding you through your first calculation employing the xTB methods. As an example, the equilibrium geometry of a water molecule is calculated. The description here is based on xtb version 6.2.2.

Note

The program can almost entirely controlled by the command-line, if you need more control you should resort to the Detailed Input file.

There are four main run types in xtb, most other run types are composite types that try to provide convenient combinations from those main run types.

Singlepoint Calculations

Independent of all other commands, there will always be a singlepoint calculation carried out at the very beginning. To calculate something xtb needs information about the molecular geometry and the kind of atoms present.

The default input format is either the Turbomole coordinate file as a $coord data group.

> cat coord
$coord
 0.00000000000000      0.00000000000000     -0.73578586109551      o
 1.44183152868459      0.00000000000000      0.36789293054775      h
-1.44183152868459      0.00000000000000      0.36789293054775      h
$end

> xtb coord

Like in Turbomole the coordinates can be given in Bohr (default) or Ångström ($coord angs) or fractional coordinates ($coord frac). Optional data groups like the systems periodicity ($periodic), lattice parameters ($lattice [bohr|angs]) and cell parameters ($cell [bohr|angs]) can be provided as well.

The following input for a MgO crystal utilize this data groups:

$coord frac
    0.00      0.00      0.00      mg
    0.50      0.50      0.50      o
$periodic 3
$cell
 5.798338236 5.798338236 5.798338236 60. 60. 60.
$end

Note

In previous version the coord data group had to start in the first line, this constraint has been relaxed by now.

Any valid xyz file can be used to provide coordinates and requires the file extension .xyz. This format does not support periodic boundary conditions.

xtb also supports DFTB+ genFormat files (.gen), protein database files (.pdb) mol-files (.mol) and structure-data files (.sdf), if the corresponding suffix is encountered. Note that you cannot provide a mol file with the extension sdf. Vasp’s POSCAR or CONTCAR files are read if the file is named as such.

By default xtb will search for .CHRG and .UHF files and obtain from these the molecular charge and the number of unpaired electrons, respectively. The molecular charge can also be specified by

> xtb molecule.xyz --chrg +1

which is equivalent to

> echo +1 > .CHRG && xtb molecule.xyz

This also works for the unpaired electrons as in

> xtb --uhf 2 input.sdf

Note that the position of the input coordinates is totally unaffected by any command-line arguments, if you are not sure, whether xtb tries to interpret your filename as flag use -- to stop the parsing as command-line options for all following arguments.

> xtb -- -oh.xyz

To select the parametrization of the xTB method you can currently choose from three different geometry, frequency and non-covalent interactions (GFN) parametrization, which differ mostly in the cost–accuracy ratio,

> xtb --gfn 2 coord

to choose GFN2-xTB, which is also the default parametrization. Also available are GFN1-xTB, and GFN0-xTB.

Sometimes you might face difficulties converging the self consistent charge iterations, in this case it is usually a good idea to increase the electronic temperature and to restart at normal temperature

> xtb --etemp 1000.0 coord && xtb --restart coord

Geometry Optimizations

The main purpose of the xTB methods is to provide good geometries, so the xtb comes with a build-in geometry optimizer, which usually does a decent job. It is invoked by

> xtb coord --opt
> ls
coord   xtbopt.coord   xtbopt.log   ...

The optimized coordinates is written to a new file (xtbopt.coord), which is in the same format as the input geometry. You can view the geometry optimization by opening the xtbopt.log with your favorite molecule viewer. The log-file is in Xmol format and contains the current total energy and the gradient norm in the comment line, gmolden usually works fine for this.

A successful geometry optimization will print somewhere along the lines

  *** GEOMETRY OPTIMIZATION CONVERGED AFTER 43 ITERATIONS ***

------------------------------------------------------------------------
 total energy gain :          -0.0094907 Eh       -5.9555 kcal/mol
 total RMSD        :           0.7677834 a0        0.4063 Å
------------------------------------------------------------------------

after finishing the optimization procedures, while in all other cases that not exit in error

*** FAILED TO CONVERGE GEOMETRY OPTIMIZATION IN 500 ITERATIONS ***

will be printed, additionally a NOT_CONVERGED file is created in the working directory, which might become handy for bulk jobs.

To get a geometry optimization to converge can be a hard job, usually the xTB methods can repair a lot, you might want to start from GFN0-xTB which does not have convergence issues and than improve with GFN2-xTB. Maybe you have to adjust the geometry by hand again, if even this fails.

xtb offers eight predefined levels for the geometry optimization, which can be chosen by appending the level to the optimization flag as in

> xtb coord --opt tight

The thresholds defined by simple keywords are given here

level Econv/Eh Gconv/Eh·α⁻¹ Accuracy
crude 5 × 10⁻⁴ 1 × 10⁻² 3.00
sloppy 1 × 10⁻⁴ 6 × 10⁻³ 3.00
loose 5 × 10⁻⁵ 4 × 10⁻³ 2.00
lax 2 × 10⁻⁵ 2 × 10⁻³ 2.00
normal 5 × 10⁻⁶ 1 × 10⁻³ 1.00
tight 1 × 10⁻⁶ 8 × 10⁻⁴ 0.20
vtight 1 × 10⁻⁷ 2 × 10⁻⁴ 0.05
extreme 5 × 10⁻⁸ 5 × 10⁻⁵ 0.01

The energy convergence (Econv) is the allowed change in the total energy at convergence, while the gradient convergence (Gconv) is the allowed change in the gradient norm at convergence. The accuracy is handed to the singlepoint calculations for integral cutoffs and self consistent field convergence criteria and is adjusted to fit the geometry convergence thresholds automatically.

The xTB methods are completely analytical, so you can in principle converge your results down to machine precision. Converging it down to the lower limit is more a development feature than a real life application but always possible.

Characterisation of Stationary Points

In xtb second derivatives are implemented by finite differences methods (numerical second derivatives). Normally you want to calculate the Hessian directly after a successful geometry optimization, this is done by using

> xtb coord --ohess

For the calculation on the input geometry use --hess instead.

Dealing with Small Imaginary Frequencies

For small imaginary modes xtb offers an automatic distortion feature of these modes, say you have optimized a geometry and performed a frequency calculation which leads to an imaginary frequency of 14 wavenumbers:

> xtb coord --ohess
 ...
           -------------------------------------------------
          |               Frequency Printout                |
           -------------------------------------------------
 projected vibrational frequencies (cm-1)
eigval :       -0.00    -0.00     0.00     0.00     0.00     0.00
eigval :      -14.26     8.12     9.26    12.09    15.85    17.73
eigval :       19.45    28.85    39.18    41.30    64.61    71.84
 ...
imag cut-off (cm-1) :    5.00
 found            1  significant imaginary frequency
 writing imag mode distorted coords to <xtbhess.coord>
 for further optimization.
 ...

In this case xtb will generate a distorted structure, you can continue to optimize with

> xtb xtbhess.coord --ohess
 ...
           -------------------------------------------------
          |               Frequency Printout                |
           -------------------------------------------------
 projected vibrational frequencies (cm-1)
eigval :       -0.00    -0.00    -0.00    -0.00     0.00     0.00
eigval :        2.02     7.99    10.10    12.08    16.16    18.57
eigval :       23.88    28.93    38.35    42.18    64.86    73.76
 ...

The optimization will only take a few steps and the artifical imaginary frequency is gone after checking the frequency calculation.