Architecture of votca-xtp

xtp has 4 major subfolders.

  1. include contains nearly all the header files, these are also installed and can be included from other libraries

  2. scripts contains a small number of python scripts, which do small operations on xml and hdf5 files.

  3. share contains information about basissets and pseudopotentials which can be then used in calculations. They are saved in xml file format. Additionally share also contains xml files with the descriptions of all options for all calculators in xtp (If you do not know, what a calculator is, do the tutorial first).

  4. src: src/libxtp contains all the source files for the header files in include and a bit more. src/tests contains all the unittests for xtp (if you want to run them go to the builddir and run ctest). Lastly src/tools contains the executables, which you should have seen in the tutorial.

For more information look at the developer guide on the votca webpage and maybe watch this video. In the following I want to try to explain some major information flows/designs in xtp.

How electronic structure calculations are run

So DFT calculations need as an input a basisset, which tells you which kind of basisfunctions belong to a certain element and we need a list of atoms, their element and coordinates. xtp comes with a number of basissets in the share/xtp/basis_sets directory. So the basisset class loads the basisset, loading a list of atoms is normally done via the qmmolecule class, which can read xyz files. Otherwise you can use a QMMapper to convert a molecular dynamics molecule into a qmmolecule. Combining a basisset with a qmmolecule gives you an AOBasis, which contains the information about the shells/basisfunctions for each atom. For most functionality you also need an auxiliary basisset for the RI approximation, you find more information about that here. Using the AOBasis you can create the single electron matrices and electron-electron integrals, which are mostly produced via the libint and libecpint libraries (the latter is for pseudopotentials). For the exchange correlation functionals we use the libxc library. To evaluate this you have to perform a numerical integration on a grid and evaluate the functional . For DFT you have to do this in a self-consisten way which is done in the dftengine.

If you instead do not want to use the internal DFT implementation but use ORCA, this is all wrapped in an abstract class qmpackage , where you can choose ORCA or xtpdft, see for example dftgwbse.cc. The results of DFT calculations are stored in the orbitals class

The GW-BSE calculations are wrapped in gwbse. They typically consist of a GW and a BSE step. The GW step is in the GW class which can choose different ways to evaluate the self-energy, Sigma, which is implemented via a factory. The BSE is found in the bse class. Technically the BSE is mostly an eigenvalue decomposition of a very large matrix, which we never explicitly build, but only calculate its effects on a testvector in the davidson solver. The results of the GW and BSE calculations are stored in the orbitals class

How options are parsed in xtp

So all calculators can be supplied options in two ways via the -o flag and then giving an xml file with the options or via the -c flag and then adding a string like TAG=VALUE or a combination of both. In xtp application first it is checked if options are given via the -o flag and otherwise an empty Property object is created, to which then the options from the -c are added. Then a Optionshandler is created with the location of the default option files. First the optionhandler loads the default option file for that calculator, e.g. dftgwbse then it replaces all links in that file with the subpackages e.g. dftpackage and then adds the useroptions. It checks if the useroptions exist and if an errors are in there. Afterwards the options are forwarded to the specific calculator.

How statefiles are parsed in

Statefiles are only used in the xtp_parallel and xtp_run executables, which derive from stateapplication, which again derives from the above mentioned xtp application. Their parsing is implemented in statesaver. Underlying all statefiles are the hdf5interfaces that are also used for the orbitals file and are implemented in checkpointwriter and checkpointreader.

How the cuda support works

CUDA support is optional and is enabled via -DUSE_CUDA=ON in cmake and then enabled via votca_xtp_config. CUDA is basically only used for matrix multiplication. The matrix class which wraps the CUBLAS class is CudaMatrix, which has ownwership of gpumemory. Calling the CUDA code inside openmp is handled via OpenMP_CUDA class, which also implements the specific commands for CPU and GPU calls.

How code is executed

In general you either call xtp_parallel xtp_run or xtp_tools which then call xtpapplication or stateapplication which creates the specific calculator gives it some options and runs it.