Setup and Installation

This guide deal with the general setup and local installation of the xtb program.

Getting the Program

There are several ways to obtain the xtb program.

Precompiled Binaries from GitHub

A precompiled version of the program can be obtained from the latest release page on GitHub. To get the newest features an automatically generated development version is available for the latest commit on the default branch. At the release page you find the a compressed tarball (tar xf xtb*.tar.xz) usually containing the following content:

.
├── bin
│   └── xtb
├── include
│   └── xtb
│       └── xtb.h
├── lib
│   ├── libxtb.so -> libxtb.so.6
│   ├── libxtb.so.6 -> libxtb.so.6.*.*
│   ├── libxtb.so.6.*.*
│   └── pkgconfig
│       └── xtb.pc
└── share
    ├── man
    │   ├── man1
    │   │   └── xtb.1
    │   └── man7
    │       └── xcontrol.7
    ├── modules
    │   └── modulefiles
    │       └── xtb
    │           └── 6.*.*
    └── xtb
        ├── param_gfn2-xtb.txt
        ├── param_gfn1-xtb.txt
        ├── param_gfn0-xtb.txt
        ├── param_ipea-xtb.txt
        └── .param_gfnff.xtb

The binary is usually compiled with the Intel Fortran compiler and statically linked against Intel’s Math Kernel Library (Intel MKL). Newer versions of xtb (6.2 and newer) additionally include a shared library, the header specification of the C-API.

First check the version by

> xtb --version
      -----------------------------------------------------------
     |                   =====================                   |
     |                           x T B                           |
     |                   =====================                   |
     |                         S. Grimme                         |
     |          Mulliken Center for Theoretical Chemistry        |
     |                    University of Bonn                     |
      -----------------------------------------------------------

   * xtb version 6.2.1 (bf8695d) compiled by 'ehlert@majestix' on 2019-10-25

normal termination of xtb

This should print some fancy banner, the version number, say 6.2.1, the git commit hash, the user and host name of the programmer compiled the program and at date. Make sure the version is matching the version from the release page and the commit hash is the actual commit hash of the release, also the date of the compilation should match. We compile the program on our clusters in Bonn, so the host name is usually majestix (or hedy20 for the old-kernel version). You get also the user name of the programmer drafting the release, testing the binary and packing the tarball.

This line is very important when reporting a bug to us, because we can validate the binary you were using and easier reproduce it.

Installing with Conda

Note

To bootstrap a conda installation we recommend to either use the conda-forge distribution miniforge or the anaconda distribution miniconda.

Installing xtb from the conda-forge channel can be achieved by adding conda-forge to your channels with:

conda config --add channels conda-forge

Once the conda-forge channel has been enabled, xtb can be installed with:

conda install xtb

It is possible to list all of the versions of xtb available on your platform with:

conda search xtb --channel conda-forge

Note

The conda package manager can become quite slow when adding large channels like conda-forge, for a more performant alternative you can try to use mamba instead, which can be conveniently installed from the conda-forge channel with

conda install mamba -c conda-forge

Alternatively, the mambaforge installed can be used to bootstrap a conda installation with mamba preinstalled.

Setting up xtb

This section will give you the basic information you need to know about the xtb program. Some of the steps are elemental for your calculation to succeed, so please consider to follow my instructions carefully.

Some part of the xtb program can be quite wasteful with stack memory, to avoid stack overflows when calculating large molecules, you should unlimit the system stack, e.g. with bash by

> ulimit -s unlimited

Note that the memory management of xtb is constantly improved to avoid using large amounts of stack memory, but to be on the save side include this option for production runs.

Parallelisation

The xtb program uses shared memory OpenMP parallelisation, to calculate larger systems an appropriate OMP stacksize must be provided, chose a reasonable large number by

> export OMP_STACKSIZE=4G

Note

Note that the memory requirement will increase with the system size and the number of requested threads. Currently, for 3000 atom system each thread requires around 16GB of memory due to the usage of dense matrix algebra for the xTB Hamiltonian. You have to account for this by allowing an accordingly larger OpenMP stacksize.

To distribute the number of threads reasonable in the OpenMP section it is recommended to use

> export OMP_NUM_THREADS=<ncores>,1

You might want to deactivate nested OMP constructs by

> export OMP_MAX_ACTIVE_LEVELS=1

Tip

Most OpenMP regions allow to customize the scheduling by setting OMP_SCHEDULE, for many threads the dynamic schedule has proven to give a good load-balance between all threads.

The default linear algebra backend of xtb is the Math Kernel Library, which usually comes as OpenMP threaded version and respects the settings of OMP_NUM_THREADS. You can however still adjust the MKL parallelisation separately by setting

> export MKL_NUM_THREADS=<ncores>

Environment Variables for xtb

A number of environment variables is used by xtb to perform calculations. Please set the XTBPATH variable to include all locations were you store information relevant for your xtb calculation, like configuration files and parameter files. The present working directory is implicitly included for most files that are searched in the XTBPATH.

Environment Module

Note

Available since version 6.3.2

A tcl environment module is provided and can be used with usual module systems. For installations from the tarball the prefix variable in the module file has to be adjusted accordingly

--- ./share/modules/modulefiles/xtb/6.3.1
+++ ./share/modules/modulefiles/xtb/6.3.1
@@ -1,5 +1,5 @@
 #%Module
-set prefix /
+set prefix /absolute/path/to/xtb

 module-whatis "Semiempirical Extended Tight-Binding Program Package"

If the share/modules/modulesfiles directory is included in your MODULEPATH you should be able to load xtb with

module load xtb

Important

If you plan to use the xtb shared library in your build system you have to do a similar adjustment to the lib/pkgconfig/xtb.pc file.

Sourceable Shell Scripts

Example scripts to be sourced in your shells rc file are included in the distributed tarball:

source ./share/xtb/config_env.bash

and should setup all environment variables correctly in most cases.

Getting Help from xtb

Beside this manual you can check the in-program help by

> xtb --help

Unfortunately, this might be outdated, therefore, you should refer to the man-pages distributed with the xtb program. Please check for the man-pages of xtb(1) and xcontrol(7). There is also an online documentation, but you already now that one, of course.

The Verbose Mode

If you think some information is missing in your calculation you can switch to the verbose mode by using --verbose in the command line arguments. This will increase the print level almost everywhere in the xtb program, also the input parser will print a lot of information that might be interesting for your current calculation.

Overall this can be an awful lot of information, so it is not recommended as a default option.

Using xTB with Orca

Orca 4.2 implements support for xTB calculations using an IO based interface calling the xtb binary and parsing its output.

The binaries of Orca will call an executable called otool_xtb, which should be placed in the directory containing the Orca binaries. We recommend to create a symbolic link to your local xtb binary by

> ln -s $(which xtb) otool_xtb

Important

xtb version 6.2.3 produces an energy printout which cannot be processes by the reader in Orca, to fix this issue, use the provided script to wrap the xtb binary instead of creating a symbolic link.

You can invoke xTB calculations in Orca by using one of the simple keywords

! XTB1 # for GFN1-xTB
! XTB2 # for GFN2-xTB

in your Orca input file, for more details refer to the Orca manual.

Orca will communicate with xtb mainly by using commandline arguments, requesting singlepoint calculations and parsing the total energy and gradient from the program output.

Of course you should setup the xtb related environment variables, such that xtb can find its parameter files and configuration files. The .xtbrc is still read if it is contained in XTBPATH and can be used to change the behaviour of xTB calculations in Orca, e.g. for setting the electronic temperature.