xTB interface

xTBTheory class:

class xTBTheory:
    def __init__(self, xtbdir=None, xtbmethod='GFN1', runmode='inputfile', numcores=1, printlevel=2, filename='xtb_',
                maxiter=500, electronic_temp=300, label=None, accuracy=0.1, hardness_PC=1000, solvent=None):

Keyword	Type	Default value	Details
`xtbdir`	string	None	Path to xTB directory. Optional. See "Finding the xTB program"
`xtbmethod`	string	'GFN1'	The xTB Hamiltonian to use. Options: 'GFN2', 'GFN1', 'GFN0', 'GFNFF', 'IPEA'
`runmode`	string	inputfile	Whether to run xTB using 'inputfile' mode (read/write files on disk) or using 'library' (share data in memory).
`numcores`	integer	1	The number of cores used in xTB parallelization (thread-based).
`printlevel`	integer	2	The level of printing desired.
`filename`	string	xtb_	The basename used to create the xTB XYZ-file read by xTB.
`maxiter`	integer	500	Max number of SCC iterations
`electronic_temp`	integer	300	The electronic temperature used by xTB in fractional occupation smearing.
`label`	string	None	Optional label to define for xTB object.
`accuracy`	integer	0.1	The xtB accuracy parameter in the SCC calculation. See xtb-docs
`hardness_PC`	integer	1000	What hardness to use for pointcharges in electrostatic QM/MM embedding. 1000 is recommended.
`solvent`	string	None	Name of solvent to use with the internal ALPB solvent model. Only available for inputfile interface. See xtbdocs

The xTB interface comes in two forms, a shared-library interface and a file-based interface.

The shared-library interface is generally recommended (limitation: no QM/MM yet) as no disk I/O is performed while running xTB. ASH and xTB communicate via a Python C-API. It requires first installation of xtb-python (https://xtb-python.readthedocs.io/en/latest/installation.html), e.g. via conda: conda install -c conda-forge xtb-python

The file-based interface writes an XYZ-file to disk, calls an xTB executable which reads the XYZ file, runs the job and writes the output to disk which is then read by ASH. For regular jobs, e.g. geometry optimizations, the speed-difference between interfaces will probably not matter.

Finding the xTB program

ASH can find the xTB program in a few different ways. For the inputfile-based runmode:

ASH will first check if the xtbdir argument has been set which should be a string that points to the directory where the xtb program is located, e.g. "xtbdir=/path/to/xtb_6_4_0/bin". This option takes precedence.
If the xtbdir argument has not been provided ASH will next see if xtbdir has been provided in the ASH settings: Basic usage
If xtbdir has also not been defined there, ASH will search the PATH environment variable for an executable "xtb" and if found will set the xtbdir accordingly. This can be a convenient option if you make sure to define your shell environments carefully in your jobscript or shell-startup file. Be careful, however, if you have multiple version of the program available.

runmode='library' on the other hand requires the installation of the xtb-python interface to your Python environment. ASH will check and complain if it does not find the library.

Examples

To use either interface is quite simple, when an xTB object is created, the xtbmethod keyword is used to select xTB method: "GFN2", "GFN1" for the GFN2-xTB and GFN1-xTB Hamiltonians, respectively. The optional runmode argument is also available: runmode='library' or runmode='inputfile'. Default runmode: "inputfile"

#Create fragment object from XYZ-file
HF_frag=Fragment(xyzfile='hf.xyz', charge=0, mult=1)
xTBcalc = xTBTheory(xtbmethod='GFN2', runmode='library')

#Run a single-point energy job on the fragment associated with the xtb-object
Singlepoint(theory=xTBcalc, fragment=HF_frag)
#An Energy+Gradient calculation running on 8 cores
Singlepoint(theory=xTBcalc, fragment=HF_frag, Grad=True)

Parallelization

The xTB parallelization is OpenMP or MKL thread-based and can be controlled via the numcores keyword. Currently OMP threads are set equal to numcores and MKL threads are set equal to 1.