XTB(1) ====== :doctype: manpage NAME ---- xtb - performs semiempirical quantummechanical calculations, for version 6.0 and newer SYNOPSIS -------- *xtb* ['OPTIONS'] 'FILE' ['OPTIONS'] DESCRIPTION ----------- The `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 GFN-FF force field, and the PTB electronic structure method. Multiple implicit solvation models (ALPB, GBSA, ddCOSMO, ddCPCM, ddPCM, and CPCM-X) are 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 (default: 0 (singlet) for even electron number, 1 (doublet) for odd electron number) *--gfn* 'INT':: specify parametrisation of GFN-xTB (default = 2) *--gfnff, --gff* :: use the GFN-FF force field *--mcgfnff* :: use the mcGFN-FF force field for molecular crystals *--tblite* :: use tblite library as implementation for xTB (required for periodic GFN1-xTB and GFN2-xTB calculations) *--ceh* ['grad' ['REAL']]:: calculate CEH (Charge-Extended Hückel model) charges and write them to the ceh.charges file (requires tblite support); optionally, calculate numerical gradients and write them to the ceh.charges.numgrad file with an adjustable step size 'REAL' (default = 1e-5 Bohr) for the numerical gradients. *--ptb* :: performs single-point calculation with the density tight-binding method PTB (requires tblite support). Provides electronic structure and properties, such as, e.g., atomic charges, bond orders, and dipole moments. PTB itself does not provide total energies, nuclear gradients, or an energetic Hessian; Hessian workflows combine GFN2-xTB with PTB response properties. *--spinpol*:: enables spin-polarization for xTB methods (tblite required) *--oniom* ['METHOD'] 'LIST':: use subtractive embedding via ONIOM method. 'METHOD' is given as `inner:outer` (default: `gfn2:gfnff`) where `inner` can be 'orca', 'turbomole', 'gfn2', 'gfn1', or 'gfnff' and `outer` 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. Combine with --tblite to evaluate 'gfn2' and 'gfn1' with the tblite library. *--cut*:: create inner region for `--oniom` calculation without performing any calculation *--efield* 'REAL,REAL,REAL':: static electric field in Cartesian coordinates (in atomic units), overrides `.EFIELD` file, works only via tblite for the xTB Hamiltonians, or with GFN-FF and PTB. *--etemp* '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), overrides automatic optimization and Hessian accuracy settings *--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', 'ethanol', 'ether', 'ethylacetate', 'furane', 'hexadecane', '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 accessible surface (SASA) model, available solvents are 'acetone', 'acetonitrile', 'benzene', '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). *--gbe* 'SOLVENT/EPSILON':: generalized Born for finite epsilon (GBe) solvation model (tblite required), includes only the electrostatic solvation contribution (no SASA model), available solvents are all solvents that are available for alpb. Additionally, the dielectric constant can be set manually. *--gb* 'SOLVENT/EPSILON':: generalized Born (GB) solvation model (tblite required), includes only the electrostatic solvation contribution (no SASA model), available solvents are all solvents that are available for alpb. Additionally, the dielectric constant can be set manually. *--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. Available via tblite (requires ddX support) or in the native legacy version in xtb lacking density response to the continuum polarization (non-variational). *--cpcm* 'SOLVENT/EPSILON':: domain decomposition conductor-like polarizable continuum solvation model (ddCPCM), 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. Requires tblite with ddX support. *--pcm* 'SOLVENT/EPSILON':: domain decomposition polarizable continuum model (ddPCM), 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. Requires tblite with ddX support. *--tmcosmo* 'SOLVENT/EPSILON':: same as --cosmo, but uses TM convention for writing the .cosmo files (native xTB only). *--cpcmx* 'SOLVENT':: extended conductor-like polarizable continuum solvation model (CPCM-X, requires CPCM-X support; parameterized for GFN2-xTB; single-point only, not available for geometry optimization or with GFN-FF), 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 principal axis (not affected by `isotopes'-file). *--pop*:: requests printout of Mulliken population analysis (enabled by default) *--molden*:: requests printout of molden file (name: molden.input), format differs with --tblite *--alpha* :: requests the extension of electrical properties to static molecular dipole polarizabilities (requires `--ptb`) *--raman* ['TEMP' ['WAVELENGTH']]:: requests Raman spectrum calculation via combination of GFN2-xTB and PTB (requires `--ptb`) using the temperature 'TEMP' in K (default 298.15 K) and the wavelength of the incident laser 'WAVELENGTH' in nm (default 514 nm) *--dipole*:: requests dipole printout (enabled by default) *--quadrupole*:: requests quadrupole printout for tblite calculations *--wbo*:: requests Wiberg bond order printout (enabled by default) *--lmo*:: requests localization of orbitals *--fod*:: requests FOD calculation *--cycles* 'INT':: maximum number of optimization cycles *--imagmin* 'REAL':: magnitudes below this value (cm⁻¹) are ignored in the O1NumHess imaginary frequency repair (default 5). *--imagmax* 'REAL':: deepest imaginary frequency (cm⁻¹) considered in the O1NumHess imaginary frequency repair (default 200). 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 with GFN1-xTB. IPEA-xTB is used with *--vparam* param_ipea-xtb.txt. *--vea*:: performs calculation of electron affinity with GFN1-xTB. IPEA-xTB is used with *--vparam* param_ipea-xtb.txt. *--vipea*:: performs calculation of electron affinity and ionisation potential with GFN1-xTB. IPEA-xTB is used with *--vparam* param_ipea-xtb.txt. *--vfukui*:: performs calculation of Fukui indices. *--vomega*:: performs calculation of electrophilicity index with GFN1-xTB. IPEA-xTB is used with *--vparam* param_ipea-xtb.txt. *--grad*:: performs a gradient calculation *-o, --opt* ['LEVEL']:: perform a geometry optimization (nonperiodic: `ancopt(3)`, periodic with lattice-vector relaxation: `pbc_lbfgs`), levels from crude, sloppy, loose, normal (default), tight, verytight to extreme can be chosen, level sets also the default accuracy setting (overwritten by --acc flag) *--nocellopt*:: disable lattice-vector relaxation during periodic geometry optimization (atomic coordinates are optimized with fixed unit cell) *--hess*:: perform a numerical hessian calculation on input geometry, tightens the default SCC accuracy setting to 0.2 (overwritten by --acc flag) *--ohess* ['LEVEL']:: perform a numerical hessian calculation on an `ancopt(3)` optimized geometry, hessian uses 0.2 accuracy by default and follows tighter optimization levels (overwritten by --acc flag) *--bhess* ['LEVEL']:: perform a biased numerical hessian calculation on an `ancopt(3)` optimized geometry, hessian uses 0.2 accuracy by default and follows tighter optimization levels (overwritten by --acc flag) Hessian runs automatically perform a compliance analysis for nonperiodic systems with more than one atom and no frozen atoms. *--o1nh*:: perform the numerical hessian calculation using the ODLR approximation (O1NumHess) *--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, level sets also the default accuracy setting (overwritten by --acc flag) *--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. *--dipro* ['REAL']:: the dimer projection method for the calculation of electronic coupling integrals between two fragments (requires tblite support). '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 = false) *--[no]restart*:: restarts calculation from `xtbrestart` (`--norestart` disables reading existing restart files; default = true) *-P, --parallel* 'INT':: number of parallel processes *--define*:: performs automatic check of input and terminate *--json*:: write `xtbout.json` file for native xTB and PTB calculations *--citation*:: print citation and terminate *--license*:: print license and terminate *--version*:: print version 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 *--strict*:: turns all warnings into hard errors *-h, --help*:: show help page ENVIRONMENT VARIABLES --------------------- `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 sufficient but might lead to some cluttering. 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` since the `XTBHOME` variable is not used in production runs. LOCAL FILES ----------- `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. 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. *compliance.dat*:: compliance analysis from an eligible Hessian run. Lists every internal coordinate with C~ii~ and 1/C~ii~, followed by up to 20 strongest off-diagonal couplings per coordinate in descending order of magnitude. *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 ~~~~~ *xtbmdok*:: generated by successful MD *.xtbok*:: generated after each successful `xtb(1)` run *.sccnotconverged*:: generated after failed SCC with printlevel=2 ////////////////// NAMING CONVENTIONS ------------------ ////////////////// WARNINGS -------- `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! After `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 summarized in the end of the calculation in one block, right before 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 necessarily 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 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 on the issue tracker at https://github.com/grimme-lab/xtb/issues RESOURCES --------- Main repository: https://github.com/grimme-lab/xtb Documentation: https://xtb-docs.readthedocs.io/ COPYING ------- Copyright (C) 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 .