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