Installing and running · xtb User Guide

On this page

Installation
A first calculation
Output files
Parallel settings
A cluster job script

Installation

conda-forge is the simplest route. It installs into your home directory without admin rights, so it works the same on a cluster.

# install miniforge first if you do not have conda
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh -b -p $HOME/miniforge3
source $HOME/miniforge3/etc/profile.d/conda.sh

# xtb and crest in one environment
conda create -n xtb -c conda-forge xtb crest
conda activate xtb
xtb --version
crest --version

Statically linked binaries from the GitHub releases (grimme-lab/xtb, crest-lab/crest) placed on your PATH work as well. The otool_xtb that ORCA calls is this same binary; setting it up for ORCA is covered in chapter 16 of the ORCA guide.

A first calculation

All it needs is an xyz file. Without options, xtb computes a GFN2-xTB single-point energy.

xtb ala.xyz > sp.out

A summary box appears near the end of the output. This is the actual output for the alanine dipeptide starting geometry used throughout this guide.

         :::::::::::::::::::::::::::::::::::::::::::::::::::::
         ::                     SUMMARY                     ::
         :::::::::::::::::::::::::::::::::::::::::::::::::::::
         :: total energy             -32.968780800655 Eh    ::
         :: gradient norm              0.060736909638 Eh/a0 ::
         :: HOMO-LUMO gap              4.201966619930 eV    ::
         ::.................................................::
         :: SCC energy               -33.334018569053 Eh    ::
         :: -> isotropic ES            0.076928930387 Eh    ::
         :: -> anisotropic ES          0.004824182260 Eh    ::
         :: -> anisotropic XC          0.011329018690 Eh    ::
         :: -> dispersion             -0.015484427685 Eh    ::
         :: repulsion energy           0.365237768398 Eh    ::
         :: add. restraining           0.000000000000 Eh    ::
         :: total charge              -0.000000000000 e     ::
         :::::::::::::::::::::::::::::::::::::::::::::::::::::

With --opt the box appears twice: first for a single point at the starting geometry, and last for the optimised geometry. Optimising this structure with --opt tight brings the total energy down to −32.975847892266 Eh and the gradient norm to 0.00016 Eh/a0.

xtb writes its result files into the current directory under fixed names. Unless each calculation gets its own directory, the next run overwrites the previous results.

Output files

File	Contents
`xtbopt.xyz`	Optimised geometry (`--opt`)
`xtbopt.log`	Optimisation path as multi-frame xyz; opens directly in a viewer.
`charges`, `wbo`	Atomic partial charges and Wiberg bond orders
`vibspectrum`, `hessian`, `g98.out`	Frequency results (`--hess`, `--ohess`); `g98.out` is for animating modes
`xtb.trj`	MD trajectory (`--md`)
`xtbrestart`	Wavefunction read as the initial guess by the next run. Delete it before computing a different molecule.

Leftover xtbrestart

If an xtbrestart from another molecule is in the same directory, xtb tries to read it. It is usually ignored because the atom count differs, but with one directory per calculation you never have to think about it.

Parallel settings

xtb is parallelised with OpenMP. Set the core count and stack size through environment variables.

export OMP_NUM_THREADS=8,1
export OMP_STACKSIZE=4G
export OPENBLAS_NUM_THREADS=1
ulimit -s unlimited

xtb ala.xyz --opt -P 8 > opt.out

With too small a stack, larger molecules segfault for no obvious reason. Molecules of a few dozen atoms do not get faster with many cores, so when running several calculations at once, fewer cores per job gives better total throughput.

OPENBLAS_NUM_THREADS=1

The conda-forge xtb is linked against OpenBLAS. OpenBLAS ignores MKL_NUM_THREADS and starts its own thread pool for each OpenMP thread, so without this variable far more threads than allocated cores compete for the CPU. When the examples in this guide were first run on an 8-core NUS HPC compute node, the gas-phase optimisation took 20.2 s (159.6 s of CPU time), and the 100 ps MD was on course to overrun the 4-hour limit. With OPENBLAS_NUM_THREADS=1 the same optimisation took 0.52 s. The results are not wrong, only slow, which makes this easy to miss.

A cluster job script

The examples in this guide were run on the Vanda cluster at NUS HPC (PBS Pro) with xtb 6.7.1 and CREST 3.0.2 from conda-forge. This is the skeleton of the script used there.

#!/bin/bash
#PBS -N xtb-opt
#PBS -l select=1:ncpus=8:mem=16gb
#PBS -l walltime=04:00:00
#PBS -j oe
#PBS -q auto_free
cd $PBS_O_WORKDIR
source $HOME/miniforge3/etc/profile.d/conda.sh
conda activate xtb
export OMP_NUM_THREADS=$NCPUS,1 OMP_STACKSIZE=4G
export OPENBLAS_NUM_THREADS=1
ulimit -s unlimited

mkdir -p opt && cd opt
xtb ../ala.xyz --opt tight > opt.out

The #PBS -q line is site-specific. On Vanda the execution queues only accept jobs through a routing queue, so -q cpu_parallel is rejected with Access to queue is denied. These jobs went to auto_free, which sent the 8-core request on to cpu_parallel, where it started straight away. On other clusters, check qstat -Q and the site documentation for the queue name; if there is a default queue, leave the line out.