xtb - Man Page
performs semiempirical quantummechanical calculations, for version 6.0 and newer
xtb [Options] FILE [Options]
xtb(1) program performs semiempirical quantummechanical calculations. The underlying effective Hamiltonian is derived from density functional tight binding (DFTB). This implementation of the xTB Hamiltonian is currently compatible with the zeroth, first and second level parametrisation for geometries, frequencies and non-covalent interactions (GFN) as well as with the ionisation potential and electron affinity (IPEA) parametrisation of the GFN1 Hamiltonian. The generalized born (GB) model with solvent accessable surface area (SASA) is also available available in this version. Ground state calculations for the simplified Tamm-Danceoff approximation (sTDA) with the vTB model are currently not implemented.
The wide variety of input formats for the geometry are supported by using the mctc-lib. Supported formats are:
- Xmol/xyz files (xyz, log)
- Turbomole’s coord, riper’s periodic coord (tmol, coord)
- DFTB+ genFormat geometry inputs as cluster, supercell or fractional (gen)
- VASP’s POSCAR/CONTCAR input files (vasp, poscar, contcar)
- Protein Database files, only single files (pdb)
- Connection table files, molfile (mol) and structure data format (sdf)
- Gaussian’s external program input (ein)
- JSON input with
- FHI-AIMS' input files (geometry.in)
- Q-Chem molecule block inputs (qchem)
For a full list visit: https://grimme-lab.github.io/mctc-lib/page/index.html
xtb(1) reads additionally
.UHF files if present.
xtb(1) gets its information from different sources. The one with highest priority is the commandline with all allowed flags and arguments described below. The secondary source is the
xcontrol(7) system, which can in principle use as many input files as wished. The
xcontrol(7) system is the successor of the set-block as present in version 5.8.2 and earlier. This implementation of
xtb(1) reads the
xcontrol(7) from two of three possible sources, the local xcontrol file or the FILE used to specify the geometry and the global configuration file found in the
- -c, --chrg INT
specify molecular charge as INT, overrides
- -u, --uhf INT
specify number of unpaired electrons as INT, overrides
- --gfn INT
specify parametrisation of GFN-xTB (default = 2)
- --gfnff, --gff
specify parametrisation of GFN-FF
- --oniom METHOD LIST
use subtractive embedding via ONIOM method. METHOD is given as
innercan be orca, turbomole, gfn2, gfn1, or gfnff and
outercan be gfn2, gfn1, or gfnff. The inner region is given as a comma separated indices directly in the commandline or in a file with each index on a separate line.
- --etemp REAL
electronic temperature (default = 300K)
calculate electrostatic potential on VdW-grid
calculate STM image
- -a, --acc REAL
accuracy for SCC calculation, lower is better (default = 1.0)
- --vparam FILE
Parameter file for vTB calculation
- --xparam FILE
Parameter file for xTB calculation (not used)
- --alpb SOLVENT [STATE]
analytical linearized Poisson-Boltzmann (ALPB) model, available solvents are acetone, acetonitrile, aniline, benzaldehyde, benzene, ch2cl2, chcl3, cs2, dioxane, dmf, dmso, ether, ethylacetate, furane, hexandecane, hexane, methanol, nitromethane, octanol, woctanol, phenol, toluene, thf, water. The solvent input is not case-sensitive. The Gsolv reference state can be chosen as reference or bar1M (default).
- -g, --gbsa SOLVENT [STATE]
generalized born (GB) model with solvent accessable surface (SASA) model, available solvents are acetone, acetonitrile, benzene (only GFN1-xTB), CH2Cl2, CHCl3, CS2, DMF (only GFN2-xTB), DMSO, ether, H2O, methanol, n-hexane (only GFN2-xTB), THF and toluene. The solvent input is not case-sensitive. The Gsolv reference state can be chosen as reference or bar1M (default).
shifts molecule to center of mass and transforms cartesian coordinates into the coordinate system of the principle axis (not affected by ‘isotopes’-file).
requests printout of Mulliken population analysis
requests printout of molden file
requests dipole printout
requests Wiberg bond order printout
requests localization of orbitals
requests FOD calculation
You can only select one runtyp, only the first runtyp will be used from the program, use implemented composite runtyps to perform several operations at once.
- --scc, --sp
performs a single point calculation
performs calculation of ionisation potential. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian.
performs calculation of electron affinity. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian.
performs calculation of electron affinity and ionisation potential. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian.
performs calculation of Fukui indices.
performs calculation of electrophilicity index. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian.
performs a gradient calculation
- -o, --opt [LEVEL]
ancopt(3)to perform a geometry optimization, levels from crude, sloppy, loose, normal (default), tight, verytight to extreme can be chosen
perform a numerical hessian calculation on input geometry
- --ohess [LEVEL]
perform a numerical hessian calculation on an
- --bhess [LEVEL]
perform a biased numerical hessian calculation on an
molecular dynamics simulation on start geometry
- --metadyn [int]
meta dynamics simulation on start geometry, saving int snapshots of the trajectory to bias the simulation
molecular dynamics simulation on
ancopt(3)optimized geometry, a loose optimization level will be chosen
- --metaopt [LEVEL]
ancopt(3)to perform a geometry optimization, then try to find other minimas by meta dynamics
- --path [FILE]
use meta dynamics to calculate a path from the input geometry to the given product structure
- --modef INT
modefollowing algorithm. INT specifies the mode that should be used for the modefollowing.
- -I, --input FILE
use FILE as input source for
- --namespace STRING
xtb(1)run a namespace. All files, even temporary ones, will be named according to STRING (might not work everywhere).
xcontrolfile at startup (default = true)
restarts calculation from
xtbrestart(default = true)
- -P, --parallel INT
number of parallel processes
performs automatic check of input and terminate
write xtbout.json file
print citation and terminate
print license and terminate
- -v, --verbose
be more verbose (not supported in every unit)
- -s, --silent
clutter the screen less (not supported in every unit)
reduce the amount of output and files written
turns all warnings into hard errors
- -h, --help
show help page
xtb(1) accesses a path-like variable to determine the location of its parameter files, you have to provide the
XTBPATH variable in the same syntax as the system
PATH variable. If this variable is not set,
xtb(1) will try to generate the
XTBPATH from the deprecated
XTBHOME variable. In case the
XTBHOME variable is not set it will be generated from the
HOME variable. So in principle storing the parameter files in the users home directory is suffient but might lead to come cluttering.
XTBHOME variable is deprecated with version 6.0 and newer
xtb(1) will issue a warning if
XTBHOME is not part of the
XTBPATH since the
XTBHOME variable is not used in production runs.
xtb(1) accesses a number of local files in the current working directory and also writes some output in specific files. Note that not all input and output files allow the --namespace option.
molecular charge as int
Number of unpaired electrons as int
contains restart information for MD, --namespace compatible.
point charge input, format is real real real real [int]. The first real is used as partial charge, the next three entries are the cartesian coordinates and the last is an optional atom type. Note that the point charge input is not affected by a CMA transformation. Also parallel Hessian calculations will fail due to I/O errors when using point charge embedding.
default input file in --copy mode, see
xcontrol(7)for details, set by --input.
contains restart information for SCC, --namespace compatible.
contains Mulliken partial charges calculated in SCC
contains Wiberg bond order calculated in SCC, --namespace compatible.
total energy in Turbomole format
geometry, energy and gradient in Turbomole format
contains the (not mass weighted) cartesian Hessian, --namespace compatible.
- xtbopt.xyz, xtbopt.coord
optimized geometry in the same format as the input geometry.
distorted geometry if imaginary frequency was found
contains all structures obtained in the geometry optimization with the respective energy in the comment line in a XMOL formatted trajectory
trajectories from MD
coordinate dump of MD
FOD on a cube-type grid
spindensity on a cube-type grid
density on a cube-type grid
MOs and occupation for visualisation and sTDA-xTB calculations
gradient of the point charges
ESP fake cosmo output
ESP histogramm data
Turbomole style vibrational spectrum data group
- g98.out, g98l.out, g98_canmode.out, g98_locmode.out
g98 fake output with normal or local modes
input for mode following
centers of the localized molecular orbitals
centers of the localized molecular orbitals
number of recommended modes for mode following
- xtb_normalmodes, xtb_localmodes
binary dump for mode following
generated by successful MD
generated after each successful
generated after failed SCC with printlevel=2
xtb(1) can generate the two types of warnings, the first warning section is printed immediately after the normal banner at startup, summing up the evaluation of all input sources (commandline, xcontrol, xtbrc). To check this warnings exclusively before running an expensive calculation a input check is implemented via the --define flag. Please, study this warnings carefully!
xtb(1) has evaluated the all input sources it immediately enters the production mode. Severe errors will lead to an abnormal termination which is signalled by the printout to STDERR and a non-zero return value (usually 128). All non-fatal errors are summerized in the end of the calculation in one block, right bevor the timing analysis.
To aid the user to fix the problems generating these warnings a brief summary of each warning with its respective string representation in the output will be shown here:
ANCopt failed to converge the optimization
geometry optimization has failed to converge in the given number optimization cycles. This is not neccessary a problem if only a small number of cycles was given for the optimization on purpose. All further calculations are done on the last geometry of the optimization.
Hessian on incompletely optimized geometry!
This warning will be issued twice, once before the Hessian, calculations starts (it would otherwise take some time before this this warning could be detected) and in the warning block in the end. The warning will be generated if the gradient norm on the given geometry is higher than a certain threshold.
normal termination of
Failure (termination via error stop generates 128 as return value)
please report all bugs with an example input,
--copy dump of internal settings and the used geometry, as well as the
--verbose output to email@example.com
Main web site: http://grimme.uni-bonn.de/software/xtb
Copyright (C) 2015-2018 S. Grimme. For non-commerical, academia use only.