Introduction#

This document is a collection of examples demonstrating the usage of the atomistic quantum mechanical software DFTB+.

Before you start#

The examples assume that you have the latest stable version of DFTB+ installed (although many of the recipes may also work with older versions of the code). Additionally the examples require some parameterisation files (Slater-Koster files), which can be downloaded from dftb.org.

The recipes in this document often only show the relevant parts of the input. In order to obtain the full input files and in order to run the examples yourself, please download the archive containing all the inputs of the individual recipes.

Download archive with all inputs.

In each recipe we indicate where to find the corresponding directories in the archive with square brackets after the section title (e.g. [Input: recipes/basics/firstcalc/]).

Getting Slater-Koster data#

After unpacking the archive, you must also download all Slater-Koster-files needed by the examples in this tutorial, by using the supplied script as

./scripts/get_slakos

in the root folder of the archive. You should then be able to run each example by calling dftb+ from the corresponding input folder (assuming that dftb+ is installed in your executable path). For some examples, there is also a supplied script file in the directory to run examples of multistage calculations, called run.sh which contains the individual commands needed to run the full example.

Installing DFTB+ from conda-forge#

DFTB+ is available with the cross platform package manager conda on the conda-forge channel.

If you have no conda installation yet, we recommend you bootstrap an installation with the conda-forge distribution miniforge or the anaconda distribution miniconda. If you are unfamiliar with conda, their getting started guide introduces the environment.

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

conda config --add channels conda-forge

We suggest using the mamba installer with conda-forge, as we have experienced dependency resolution problems with the original conda installer:

conda install -n base mamba

Depending on the order of the channels in your ~/.condarc file, the install may pick the wrong version of some packages. Therefore, it is important to ensure, that “conda-forge” comes before “defaults” in your ~/.condarc file

channels:
   - conda-forge
   - defaults

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

mamba install 'dftbplus=*=nompi_*'

If you prefer to install an MPI parallel version you have to explicitly request it with

mamba install 'dftbplus=*=mpi_mpich_*'

for MPICH, or

mamba install 'dftbplus=*=mpi_openmpi_*'

with Open MPI.

There are some differences in functionality between the serial/OpenMP and MPI versions of the code. The non-MPI version supports more excited state methods, while the MPI version has better parallelism for many tasks.

You may want to set up separate environments for the MPI and non-MPI dftb+ versions:

conda create --name dftbplus
conda activate dftbplus
mamba install 'dftbplus=*=nompi_*'
conda deactivate

and likewise for your choice of MPI:

conda create -n dftbplusMPI
mamba install -n dftbplusMPI 'dftbplus=*=mpi_openmpi_*'

Then list available environments:

conda info --envs

Additional components like the dptools and the Python API, are available as separate packages on the same channel. You can install them with

mamba install dftbplus-tools dftbplus-python

It is possible to list all of the versions of dftb+ and its additional components that are available on your platform with:

mamba search 'dftbplus*' --channel conda-forge

Where to start with the tutorials#

The individual chapters of this document are more or less independent from each other, so you may go directly to the relevant one for your interests. However, if you are new to DFTB+, please make sure to work through the relevant introductory examples in the Basic usage chapters first.

The recipes are to introduce you to specific functionalities of DFTB+ and so are therefore rather short and focused. Please also always consult the corresponding sections of the DFTB+ manual for further details and possibilities.

Please note that the example outputs in the recipes may have been created with older versions of DFTB+ and therefore could differ slightly in format from output of the most recent code. The corresponding inputs in the archive should work, without any changes, with the last stable release of DFTB+.