1XTB(1) 2====== 3:doctype: manpage 4 5NAME 6---- 7xtb - performs semiempirical quantummechanical calculations, 8 for version 6.0 and newer 9 10SYNOPSIS 11-------- 12*xtb* ['OPTIONS'] 'FILE' ['OPTIONS'] 13 14DESCRIPTION 15----------- 16The `xtb(1)` program performs semiempirical quantummechanical calculations. 17The underlying effective Hamiltonian is derived from density functional 18tight binding (DFTB). This implementation of the xTB Hamiltonian is currently 19compatible with the zeroth (6.1 only), first and second level parametrisation for 20geometries, frequencies and non-covalent interactions (GFN) 21as well as with the ionisation potential and 22electron affinity (IPEA) parametrisation of the GFN1 Hamiltonian. 23The generalized born (GB) model with solvent accessable surface area (SASA) 24is also available available in this version. 25Ground state calculations for the simplified Tamm-Danceoff approximation (sTDA) 26with the vTB model are currently not implemented. 27 28GEOMETRY INPUT 29~~~~~~~~~~~~~~ 30The input coordinates can be presented in XMOL format and 31in Turbomole format. For most calculations no specific changes 32to these formats have to be made. 33The file type is determined automatically and the file extension 34can be freely chosen. XMOL coordinates must be given in Ångström, 35while in Turbomole format they can be given in Ångström as well 36as in Bohr (default). The corresponding keyword is given in the 37first line as `ang` or `bohr` instead of the `$coord` keyword. 38 39NOTE: This implementation of `xtb(1)` can only identify and read coordinate 40 files in Turbomole, if the `$coord` is in the first line of the 41 file, valid Turbomole coordinate files with the `$coord` datagroup 42 elsewhere will not be read in correctly and lead to abnormal termination 43 of the program. 44 45`xtb(1)` reads additionally `.CHRG` and `.UHF` files if present. 46 47INPUT SOURCES 48------------- 49`xtb(1)` gets its information from different sources. The one with highest 50priority is the commandline with all allowed flags and arguments described below. 51The secondary source is the `xcontrol(7)` system, which can in principle 52use as many input files as wished. The `xcontrol(7)` system is the successor 53of the set-block as present in version 5.8.2 and earlier. This implementation 54of `xtb(1)` reads the `xcontrol(7)` from two of three possible sources, 55the local xcontrol file or the 'FILE' used to specify the geometry 56and the global configuration file found in the `XTBPATH`. 57 58OPTIONS 59------- 60*-c, --chrg* 'INT':: 61 specify molecular charge as 'INT', overrides `.CHRG` file and `xcontrol` option 62 63*-u, --uhf* 'INT':: 64 specify Nalpha-Nbeta as 'INT', overrides `.UHF` file and `xcontrol` option 65 66*--gfn* 'INT':: 67 specify parametrisation of GFN-xTB (default = 2) 68 69*--gfnff, --gff* :: 70 specify parametrisation of GFN-FF 71 72*--etemp* 'REAL':: 73 electronic temperature (default = 300K) 74 75*--esp* :: 76 calculate electrostatic potential on VdW-grid 77 78*--stm* :: 79 calculate STM image 80 81*-a, --acc* 'REAL':: 82 accuracy for SCC calculation, lower is better (default = 1.0) 83 84*--vparam* 'FILE':: 85 Parameter file for vTB calculation 86 87*--xparam* 'FILE':: 88 Parameter file for xTB calculation (not used) 89 90*--alpb* 'SOLVENT' ['STATE']:: 91 analytical linearized Poisson-Boltzmann (ALPB) model, 92 available solvents are 'acetone', 'acetonitrile', 'aniline', 'benzaldehyde', 93 'benzene', 'ch2cl2', 'chcl3', 'cs2', 'dioxane', 'dmf', 'dmso', 'ether', 94 'ethylacetate', 'furane', 'hexandecane', 'hexane', 'methanol', 'nitromethane', 95 'octanol', 'woctanol', 'phenol', 'toluene', 'thf', 'water'. 96 The solvent input is not case-sensitive. 97 The Gsolv reference state can be chosen as 'reference' or 'bar1M' (default). 98 99*-g, --gbsa* 'SOLVENT' ['STATE']:: 100 generalized born (GB) model with solvent accessable surface (SASA) model, 101 available solvents are 'acetone', 'acetonitrile', 'benzene' (only GFN1-xTB), 102 'CH2Cl2', 'CHCl3', 'CS2', 'DMF' (only GFN2-xTB), 'DMSO', 'ether', 'H2O', 103 'methanol', 'n-hexane' (only GFN2-xTB), 'THF' and 'toluene'. 104 The solvent input is not case-sensitive. 105 The Gsolv reference state can be chosen as 'reference' or 'bar1M' (default). 106 107*--cma* :: 108 shifts molecule to center of mass and transforms cartesian coordinates 109 into the coordinate system of the principle axis (not affected by 110 `isotopes'-file). 111 112*--pop*:: 113 requests printout of Mulliken population analysis 114 115*--molden*:: 116 requests printout of molden file 117 118*--dipole*:: 119 requests dipole printout 120 121*--wbo*:: 122 requests Wiberg bond order printout 123 124*--lmo*:: 125 requests localization of orbitals 126 127*--fod*:: 128 requests FOD calculation 129 130RUNTYPS 131~~~~~~~ 132NOTE: You can only select *one* runtyp, only the first runtyp will be used 133 from the program, use implemented composite runtyps to perform several 134 operations at once. 135 136*--scc, --sp*:: 137 performs a single point calculation 138 139*--vip*:: 140 performs calculation of ionisation potential. 141 This needs the .param_ipea.xtb parameters 142 and a GFN1 Hamiltonian. 143 144*--vea*:: 145 performs calculation of electron affinity. 146 This needs the .param_ipea.xtb parameters 147 and a GFN1 Hamiltonian. 148 149*--vipea*:: 150 performs calculation of electron affinity and ionisation potential. 151 This needs the .param_ipea.xtb parameters 152 and a GFN1 Hamiltonian. 153 154*--vfukui*:: 155 performs calculation of Fukui indices. 156 157*--vomega*:: 158 performs calculation of electrophilicity index. 159 This needs the .param_ipea.xtb parameters 160 and a GFN1 Hamiltonian. 161 162*--grad*:: 163 performs a gradient calculation 164 165*-o, --opt* ['LEVEL']:: 166 call `ancopt(3)` to perform a geometry optimization, 167 levels from crude, sloppy, loose, normal (default), tight, verytight 168 to extreme can be chosen 169 170*--hess*:: 171 perform a numerical hessian calculation on input geometry 172 173*--ohess* ['LEVEL']:: 174 perform a numerical hessian calculation on an `ancopt(3)` optimized 175 geometry 176 177*--bhess* ['LEVEL']:: 178 perform a biased numerical hessian calculation on an `ancopt(3)` optimized 179 geometry 180 181*--md*:: 182 molecular dynamics simulation on start geometry 183 184*--metadyn* ['int']:: 185 meta dynamics simulation on start geometry, saving 'int' snapshots 186 of the trajectory to bias the simulation (6.1 only) 187 188*--omd*:: 189 molecular dynamics simulation on `ancopt(3)` optimized geometry, 190 a loose optimization level will be chosen 191 192*--metaopt* ['LEVEL']:: 193 call `ancopt(3)` to perform a geometry optimization, 194 then try to find other minimas by meta dynamics (6.1 only) 195 196*--path* ['FILE']:: 197 use meta dynamics to calculate a path from the input geometry 198 to the given product structure (6.1 only) 199 200*--reactor*:: 201 experimental (6.1 only) 202 203*--modef* 'INT':: 204 modefollowing algorithm. 'INT' specifies the mode that should be 205 used for the modefollowing. 206 207 208GENERAL 209~~~~~~~ 210*-I, --input* 'FILE':: 211 use 'FILE' as input source for `xcontrol(7)` instructions 212 213*--namespace* 'STRING':: 214 give this `xtb(1)` run a namespace. All files, even temporary 215 ones, will be named according to 'STRING' (might not work everywhere). 216 217*--[no]copy*:: 218 copies the `xcontrol` file at startup (default = true) 219 220*--[no]restart*:: 221 restarts calculation from `xtbrestart` (default = true) 222 223*-P, --parallel* 'INT':: 224 number of parallel processes 225 226*--define*:: 227 performs automatic check of input and terminate 228 229*--json*:: 230 write xtbout.json file 231 232*--citation*:: 233 print citation and terminate 234 235*--license*:: 236 print license and terminate 237 238*-v, --verbose*:: 239 be more verbose (not supported in every unit) 240 241*-s, --silent*:: 242 clutter the screen less (not supported in every unit) 243 244*--ceasefiles*:: 245 reduce the amount of output and files written 246 247*--strict*:: 248 turns all warnings into hard errors 249 250*-h, --help*:: 251 show help page 252 253ENVIRONMENT VARIABLES 254--------------------- 255`xtb(1)` accesses a path-like variable to determine the location of its 256parameter files, you have to provide the `XTBPATH` variable in the same 257syntax as the system `PATH` variable. If this variable is not set, `xtb(1)` 258will try to generate the `XTBPATH` from the deprecated `XTBHOME` variable. 259In case the `XTBHOME` variable is not set it will be generated from the 260`HOME` variable. So in principle storing the parameter files in the users 261home directory is suffient but might lead to come cluttering. 262 263Since the `XTBHOME` variable is deprecated with version 6.0 and newer 264`xtb(1)` will issue a warning if `XTBHOME` is not part of the `XTBPATH` 265since the `XTBHOME` variable is not used in production runs. 266 267LOCAL FILES 268----------- 269 270`xtb(1)` accesses a number of local files in the current working directory 271and also writes some output in specific files. Note that not all input 272and output files allow the *--namespace* option. 273 274INPUT 275~~~~~ 276 277*.CHRG*:: 278 molecular charge as 'int' 279 280*.UHF*:: 281 Nalpha-Nbeta as 'int' 282 283*mdrestart*:: 284 contains restart information for MD, *--namespace* compatible. 285 286*pcharge*:: 287 point charge input, format is 'real' 'real' 'real' 'real' ['int']. 288 The first real is used as partial charge, the next three entries 289 are the cartesian coordinates and the last is an optional atom type. 290 Note that the point charge input is not affected by a CMA transformation. 291 Also parallel Hessian calculations will fail due to I/O errors when using 292 point charge embedding. 293 294*solvent*:: 295 `qmdff(1)` input file 296 297*xcontrol*:: 298 default input file in *--copy* mode, see `xcontrol(7)` for details, 299 set by *--input*. 300 301*xtbrestart*:: 302 contains restart information for SCC, *--namespace* compatible. 303 304OUTPUT 305~~~~~~ 306 307*charges*:: 308 contains Mulliken partial charges calculated in SCC 309 310*wbo*:: 311 contains Wiberg bond order calculated in SCC, *--namespace* compatible. 312 313*energy*:: 314 total energy in Turbomole format 315 316*gradient*:: 317 geometry, energy and gradient in Turbomole format 318 319*hessian*:: 320 contains the (not mass weighted) cartesian Hessian, *--namespace* compatible. 321 322*xtbopt.xyz*, *xtbopt.coord*:: 323 optimized geometry in the same format as the input geometry. 324 325*xtbhess.coord*:: 326 distorted geometry if imaginary frequency was found 327 328*xtbopt.log*:: 329 contains all structures obtained in the geometry optimization 330 with the respective energy in the comment line in a XMOL formatted 331 trajectory 332 333*xtbsiman.log*,*xtb.trj.'int'*:: 334 trajectories from MD 335 336*scoord.'int'*:: 337 coordinate dump of MD 338 339*fod.cub*:: 340 FOD on a cube-type grid 341 342*spindensity.cub*:: 343 spindensity on a cube-type grid 344 345*density.cub*:: 346 density on a cube-type grid 347 348*molden.input*:: 349 MOs and occupation for visualisation and sTDA-xTB calculations 350 351*pcgrad*:: 352 gradient of the point charges 353 354*xtb_esp.cosmo*:: 355 ESP fake cosmo output 356 357*xtb_esp_profile.dat*:: 358 ESP histogramm data 359 360*vibspectrum*:: 361 Turbomole style vibrational spectrum data group 362 363*g98.out*, *g98l.out*, *g98_canmode.out*, *g98_locmode.out*:: 364 g98 fake output with normal or local modes 365 366*.tmpxtbmodef*:: 367 input for mode following 368 369*coordprot.0*:: 370 protonated species 371 372*xtblmoinfo*:: 373 centers of the localized molecular orbitals 374 375*lmocent.coord*:: 376 centers of the localized molecular orbitals 377 378*tmpxx*:: 379 number of recommended modes for mode following 380 381*xtb_normalmodes*, *xtb_localmodes*:: 382 binary dump for mode following 383 384TOUCH 385~~~~~ 386 387*xtbmdok*:: 388 generated by successful MD 389 390*.xtbok*:: 391 generated after each successful `xtb(1)` run 392 393*.sccnotconverged*:: 394 generated after failed SCC with printlevel=2 395 396////////////////// 397NAMING CONVENTIONS 398------------------ 399////////////////// 400 401WARNINGS 402-------- 403`xtb(1)` can generate the two types of warnings, the first warning section 404is printed immediately after the normal banner at startup, summing up the 405evaluation of all input sources (commandline, xcontrol, xtbrc). To check 406this warnings exclusively before running an expensive calculation a 407input check is implemented via the *--define* flag. Please, study this 408warnings carefully! 409 410After `xtb(1)` has evaluated the all input sources it immediately enters 411the production mode. Severe errors will lead to an abnormal termination 412which is signalled by the printout to STDERR and a non-zero return value 413(usually 128). All non-fatal errors are summerized in the end of the calculation 414in one block, right bevor the timing analysis. 415 416To aid the user to fix the problems generating these warnings a brief 417summary of each warning with its respective string representation in the 418output will be shown here: 419 420*ANCopt failed to converge the optimization*:: 421 geometry optimization has failed to converge in the given number 422 optimization cycles. This is not neccessary a problem if only a 423 small number of cycles was given for the optimization on purpose. 424 All further calculations are done on the last geometry of the 425 optimization. 426 427*Hessian on incompletely optimized geometry!*:: 428 This warning will be issued twice, once before the Hessian, 429 calculations starts (it would otherwise take some time before 430 this this warning could be detected) and in the warning block 431 in the end. The warning will be generated if the gradient norm 432 on the given geometry is higher than a certain threshold. 433 434EXIT STATUS 435----------- 436*0*:: 437 normal termination of `xtb(1)` 438 439*128*:: 440 Failure (termination via error stop generates 128 as return value) 441 442BUGS 443---- 444please report all bugs with an example input, `--copy` dump of internal settings 445and the used geometry, as well as the `--verbose` output to xtb@thch.uni-bonn.de 446 447RESOURCES 448--------- 449Main web site: http://grimme.uni-bonn.de/software/xtb 450 451COPYING 452------- 453Copyright \(C) 2015-2018 S. Grimme. For non-commerical, academia use only. 454