XTB(1)

📦
version 6.7.1 · 6 versions
, in ubuntu resolute, ubuntu stonking

okay bestie 💖 this is the manual for xtb(1) — the program that performs semiempirical quantummechanical calculations, for version 6.0 and newer. let's get into it! 🫶

✨ NAME ✨

xtb — performs semiempirical quantummechanical calculations, for version 6.0 and newer. 💅

🌸 SYNOPSIS 🌸

xtb [OPTIONS] FILE [OPTIONS]

💖 DESCRIPTION 💖

okay so bestie, the xtb(1) program does 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 in this version. Ground state calculations for the simplified Tamm-Dancoff approximation (sTDA) with the vTB model are currently not implemented. 🫶

🦋 GEOMETRY INPUT 🦋

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 qcschema_molecule or qcschema_input structure (json)
  • 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 .CHRG and .UHF files if present.

🌈 INPUT SOURCES 🌈

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 XTBPATH.

✨ OPTIONS ✨

  • -c, --chrg INT — specify molecular charge as INT, overrides .CHRG file and xcontrol option. 💖
  • -c, --chrg INT:INT — specify charges for inner region:outer region for oniom calculation, overrides .CHRG file and xcontrol option. 🌀
  • -u, --uhf INT — specify number of unpaired electrons as INT, overrides .UHF file and xcontrol option. 👑
  • --gfn INT — specify parametrisation of GFN-xTB (default = 2). ✨
  • --gfnff, --gff — specify parametrisation of GFN-FF. 🌸
  • --tblite — use tblite library as implementation for xTB. 🦋
  • --ceh* — calculate CEH (Charge-Extended Hückel model) charges and write them to ceh.charges file. 💅
  • --ptb — performs single-point calculation with the density tight-binding method PTB. Provides electronic structure and properties, such as, e.g., atomic charges, bond orders, and dipole moments, but does not provide any energy-related properties, such as, e.g., total energy, nuclear gradients, or vibrational frequencies. 😭
  • --spinpol — enables spin-polarization for xTB methods (tblite required). 🔥
  • --oniom METHOD LIST — use subtractive embedding via ONIOM method. METHOD is given as high:low where high can be orca, turbomole, gfn2, gfn1, or gfnff and low can be gfn2, gfn1, or gfnff. The inner region is given as comma-separated indices directly in the commandline or in a file with each index on a separate line. 🧚
  • --etemp, --temp REAL — electronic temperature for SCC (default = 300K). 🌡️
  • --esp — calculate electrostatic potential on VdW-grid. ⚡
  • --stm — calculate STM image. 🖼️
  • -a, --acc REAL — accuracy for SCC calculation, lower is better (default = 1.0). 🎯
  • --iterations, --maxiterations INT — maximum number of SCC iterations per single point calculation (default = 250). 🔁
  • --vparam FILE — Parameter file for xTB calculation. 📁
  • --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, bar1M, or gsolv (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, bar1M, or gsolv (default). 💧
  • --cosmo SOLVENT/EPSILON — domain decomposition conductor-like screening model (ddCOSMO) available solvents are all solvents that are available for alpb. Additionally, the dielectric constant can be set manually or an ideal conductor can be chosen by setting epsilon to infinity. 🌌
  • --tmcosmo SOLVENT/EPSILON — same as --cosmo, but uses TM convention for writing the .cosmo files. ✨
  • --cpcmx SOLVENT — extended conduction-like polarizable continuum solvation model (CPCM-X), available solvents are all solvents included in the Minnesota Solvation Database. 🗄️
  • --cma — shifts molecule to center of mass and transforms cartesian coordinates into the coordinate system of the principle axis (not affected by ‘isotopes’-file). ⚖️
  • --pop — requests printout of Mulliken population analysis. 📊
  • --molden — requests printout of molden file. 🧬
  • --alpha — requests the extension of electrical properties to static molecular dipole polarizabilities. ⚡
  • --raman — requests Raman spectrum calculation via combination of GFN2-xTB and PTB using the temperature REAL (default 298.15 K) and the wavelength of the incident laser which must be given in nm REAL (default 514 nm). 🌈
  • --dipole — requests dipole printout. 🧲
  • --wbo — requests Wiberg bond order printout. 🔗
  • --lmo — requests localization of orbitals. 🌀
  • --fod — requests FOD calculation. 💫

🎀 RUNTYPS 🎀

Note 📝 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. 🎯
  • --vip — performs calculation of ionisation potential. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian. ⚡
  • --vea — performs calculation of electron affinity. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian. 🌟
  • --vipea — performs calculation of electron affinity and ionisation potential. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian. 💥
  • --vfukui — performs calculation of Fukui indices. 🧪
  • --vomega — performs calculation of electrophilicity index. This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian. 🌀
  • --grad — performs a gradient calculation. 📉
  • -o, --opt [LEVEL] — call ancopt(3) to perform a geometry optimization, levels from crude, sloppy, loose, normal (default), tight, verytight to extreme can be chosen. 🏔️
  • --hess — perform a numerical hessian calculation on input geometry. 🎶
  • --ohess [LEVEL] — perform a numerical hessian calculation on an ancopt(3) optimized geometry. 🎵
  • --bhess [LEVEL] — perform a biased numerical hessian calculation on an ancopt(3) optimized geometry. 🎼
  • --md — molecular dynamics simulation on start geometry. 🎬
  • --metadyn [int] — meta dynamics simulation on start geometry, saving int snapshots of the trajectory to bias the simulation. 🌀
  • --omd — molecular dynamics simulation on ancopt(3) optimized geometry, a loose optimization level will be chosen. 🏃‍♀️
  • --metaopt [LEVEL] — call 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. 🛤️
  • --reactor — experimental. 🧪
  • --modef INT — modefollowing algorithm. INT specifies the mode that should be used for the modefollowing. 🎚️
  • --dipro [REAL] — the dimer projection method for the calculation of electronic coupling integrals between two fragments. REAL sets the threshold for nearly degenerate orbitals to still be considered (default = 0.1 eV). 🧲

🌟 GENERAL 🌟

  • -I, --input FILE — use FILE as input source for xcontrol(7) instructions. 📄
  • --namespace STRING — give this xtb(1) run a namespace. All files, even temporary ones, will be named according to STRING (might not work everywhere). 🏷️
  • --[no]copy — copies the xcontrol file at startup (default = true). 📋
  • --[no]restart — restarts calculation from xtbrestart (default = true). 🔄
  • -P, --parallel INT — number of parallel processes. ⚡
  • --define — performs automatic check of input and terminate. ✅
  • --json — write xtbout.json file. 📝
  • --citation — print citation and terminate. 📚
  • --license — 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). 🤫
  • --ceasefiles — reduce the amount of output and files written (e.g. xtbtopo.mol). 🗂️
  • --strict — turns all warnings into hard errors. ⚠️
  • -h, --help — show help page. 🆘
  • --cut — create inner region for oniom calculation without performing any calcultion. ✂️

🌸 ENVIRONMENT VARIABLES 🌸

okay so xtb(1) goes looking for its parameter files through a path-like variable, and bestie, you are the one who has to provide it — it's called XTBPATH, and you write it in exactly the same syntax as the system PATH variable. no cap.

  • if XTBPATH isn't set, xtb(1) will try to generate it from the XTBHOME variable — which is deprecated, fyi 💀
  • and if XTBHOME isn't set either, it gets generated from the HOME variable.

so technically?? storing your parameter files in the user's home directory is sufficient, but it might lead to some cluttering. like, it works, but the vibe is messy 🫠

since the XTBHOME variable is deprecated with version 6.0 and newer, xtb(1) will issue a warning if XTBHOME is not part of the XTBPATH, because XTBHOME is simply not used in production runs. periodt.

🎀 LOCAL FILES 🎀

xtb(1) accesses a whole bunch of local files in the current working directory, and it also writes some output into specific files. lowkey important: not all input and output files allow the --namespace option — so keep that in mind, queen 👑

✨ INPUT ✨

  • .CHRG — molecular charge as int
  • .UHF — Number of unpaired electrons as int
  • mdrestart — contains restart information for MD, --namespace compatible
  • pcharge — 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 😭
  • xcontrol — default input file in --copy mode, see xcontrol(7) for details, set by --input
  • xtbrestart — contains restart information for SCC, --namespace compatible

💖 OUTPUT 💖

  • charges — contains Mulliken partial charges calculated in SCC
  • ceh.charges — contains CEH (Charge-Extended Hückel) charges
  • wbo — contains Wiberg bond order calculated in SCC, --namespace compatible
  • energy — total energy in Turbomole format
  • gradient — geometry, energy and gradient in Turbomole format
  • hessian — contains the (not mass weighted) cartesian Hessian, --namespace compatible
  • xtbtopo.mol — topology information written in molfile format
  • xtbopt.xyz, xtbopt.coord — optimized geometry in the same format as the input geometry
  • xtbhess.coord — distorted geometry if imaginary frequency was found
  • xtbopt.log — contains all structures obtained in the geometry optimization with the respective energy in the comment line in a XMOL formatted trajectory
  • xtbsiman.log, xtb.trj.int — trajectories from MD
  • scoord.int — coordinate dump of MD
  • fod.cub — FOD on a cube-type grid
  • spindensity.cub — spindensity on a cube-type grid
  • density.cub — density on a cube-type grid
  • molden.input — MOs and occupation for visualisation and sTDA-xTB calculations
  • pcgrad — gradient of the point charges
  • xtb_esp.cosmo — ESP fake cosmo output
  • xtb_esp_profile.dat — ESP histogramm data
  • vibspectrum — Turbomole style vibrational spectrum data group
  • g98.out, g98l.out, g98_canmode.out, g98_locmode.out — g98 fake output with normal or local modes
  • .tmpxtbmodef — input for mode following
  • coordprot.0 — protonated species
  • xtblmoinfo — centers of the localized molecular orbitals
  • lmocent.coord — centers of the localized molecular orbitals
  • tmpxx — number of recommended modes for mode following
  • xtb_normalmodes, xtb_localmodes — binary dump for mode following

🦋 TOUCH 🦋

(these are the lil' marker files that get created, iykyk)

  • xtbmdok — generated by successful MD
  • .xtbok — generated after each successful xtb(1) run
  • .sccnotconverged — generated after failed SCC with printlevel=2

👑 WARNINGS 👑

okay bestie, listen up, because xtb(1) can generate two types of warnings and you should NOT ignore them 💅

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 these warnings exclusively before running an expensive calculation, an input check is implemented via the --define flag. Please, study these warnings carefully! fr fr.

After xtb(1) has evaluated all the input sources, it immediately enters 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 at the end of the calculation in one block, right before the timing analysis.

To aid the user in fixing the problems generating these warnings, here's a brief summary of each warning with its respective string representation in the output:

  • ANCopt failed to converge the optimization — geometry optimization has failed to converge in the given number of 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 calculation starts (it would otherwise take some time before 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.

🌈 EXIT STATUS 🌈

  • 0 — normal termination of xtb(1) ✨
  • 128 — Failure (termination via error stop generates 128 as return value)

🐛 BUGS 🐛

please report all bugs with an example input, --copy dump of internal settings and the used geometry, as well as the --verbose output to xtb@thch.uni-bonn.de 🫶

⭐ RESOURCES ⭐

Main web site: http://grimme.uni-bonn.de/software/xtb

💜 COPYING 💜

Copyright © 2017-2023 Stefan Grimme

xtb is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

xtb is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with xtb. If not, see https://www.gnu.org/licenses/.

aaaaand that's the whole page, bestie!! 🎀 this beauty is dated 09/16/2025 and belongs to XTB(1) — go forth and do iconic computational chemistry, mwah 💋✨

📦 where this page comes from