1XTB(1) XTB(1)
2
6 xtb - performs semiempirical quantummechanical calculations, for
7 version 6.0 and newer
8
10 xtb [OPTIONS] FILE [OPTIONS]
11
13 The xtb(1) program performs semiempirical quantummechanical
14 calculations. The underlying effective Hamiltonian is derived from
15 density functional tight binding (DFTB). This implementation of the xTB
16 Hamiltonian is currently compatible with the zeroth, first and second
17 level parametrisation for geometries, frequencies and non-covalent
18 interactions (GFN) as well as with the ionisation potential and
19 electron affinity (IPEA) parametrisation of the GFN1 Hamiltonian. The
20 generalized born (GB) model with solvent accessable surface area (SASA)
21 is also available in this version. Ground state calculations for the
22 simplified Tamm-Dancoff approximation (sTDA) with the vTB model are
23 currently not implemented.
24 GEOMETRY INPUT
26 The wide variety of input formats for the geometry are supported by
27 using the mctc-lib. Supported formats are:
28 • Xmol/xyz files (xyz, log)
30 • Turbomole’s coord, riper’s periodic coord (tmol, coord)
32 • DFTB+ genFormat geometry inputs as cluster, supercell or fractional
34 (gen)
35 • VASP’s POSCAR/CONTCAR input files (vasp, poscar, contcar)
37 • Protein Database files, only single files (pdb)
39 • Connection table files, molfile (mol) and structure data format
41 (sdf)
42 • Gaussian’s external program input (ein)
44 • JSON input with qcschema_molecule or qcschema_input structure
46 (json)
47 • FHI-AIMS' input files (geometry.in)
49 • Q-Chem molecule block inputs (qchem)
51 For a full list visit:
53 https://grimme-lab.github.io/mctc-lib/page/index.html
54 xtb(1) reads additionally .CHRG and .UHF files if present.
56
58 xtb(1) gets its information from different sources. The one with
59 highest priority is the commandline with all allowed flags and
60 arguments described below. The secondary source is the xcontrol(7)
61 system, which can in principle use as many input files as wished. The
62 xcontrol(7) system is the successor of the set-block as present in
63 version 5.8.2 and earlier. This implementation of xtb(1) reads the
64 xcontrol(7) from two of three possible sources, the local xcontrol file
65 or the FILE used to specify the geometry and the global configuration
66 file found in the XTBPATH.
67
69 -c, --chrg INT
70 specify molecular charge as INT, overrides .CHRG file and xcontrol
71 option
72 -c, --chrg INT:INT
74 specify charges for inner region:outer region for oniom
75 calculation, overrides .CHRG file and xcontrol option
76 -u, --uhf INT
78 specify number of unpaired electrons as INT, overrides .UHF file
79 and xcontrol option
80 --gfn INT
82 specify parametrisation of GFN-xTB (default = 2)
83 --gfnff, --gff
85 specify parametrisation of GFN-FF
86 --tblite
88 use tblite library as implementation for xTB
89 --spinpol
91 enables spin-polarization for xTB methods (tblite required)
92 --oniom METHOD LIST
94 use subtractive embedding via ONIOM method. METHOD is given as
95 high:low where high can be orca, turbomole, gfn2, gfn1, or gfnff
96 and low can be gfn2, gfn1, or gfnff. The inner region is given as
97 comma-separated indices directly in the commandline or in a file
98 with each index on a separate line.
99 --etemp REAL
101 electronic temperature (default = 300K)
102 --esp
104 calculate electrostatic potential on VdW-grid
105 --stm
107 calculate STM image
108 -a, --acc REAL
110 accuracy for SCC calculation, lower is better (default = 1.0)
111 --vparam FILE
113 Parameter file for xTB calculation
114 --alpb SOLVENT [STATE]
116 analytical linearized Poisson-Boltzmann (ALPB) model, available
117 solvents are acetone, acetonitrile, aniline, benzaldehyde, benzene,
118 ch2cl2, chcl3, cs2, dioxane, dmf, dmso, ether, ethylacetate,
119 furane, hexandecane, hexane, methanol, nitromethane, octanol,
120 woctanol, phenol, toluene, thf, water. The solvent input is not
121 case-sensitive. The Gsolv reference state can be chosen as
122 reference or bar1M (default).
123 -g, --gbsa SOLVENT [STATE]
125 generalized born (GB) model with solvent accessable surface (SASA)
126 model, available solvents are acetone, acetonitrile, benzene (only
127 GFN1-xTB), CH2Cl2, CHCl3, CS2, DMF (only GFN2-xTB), DMSO, ether,
128 H2O, methanol, n-hexane (only GFN2-xTB), THF and toluene. The
129 solvent input is not case-sensitive. The Gsolv reference state can
130 be chosen as reference or bar1M (default).
131 --cma
133 shifts molecule to center of mass and transforms cartesian
134 coordinates into the coordinate system of the principle axis (not
135 affected by ‘isotopes’-file).
136 --pop
138 requests printout of Mulliken population analysis
139 --molden
141 requests printout of molden file
142 --dipole
144 requests dipole printout
145 --wbo
147 requests Wiberg bond order printout
148 --lmo
150 requests localization of orbitals
151 --fod
153 requests FOD calculation
154 RUNTYPS
156 Note
157 You can only select one runtyp, only the first runtyp will be used
158 from the program, use implemented composite runtyps to perform
159 several operations at once.
160 --scc, --sp
162 performs a single point calculation
163 --vip
165 performs calculation of ionisation potential. This needs the
166 .param_ipea.xtb parameters and a GFN1 Hamiltonian.
167 --vea
169 performs calculation of electron affinity. This needs the
170 .param_ipea.xtb parameters and a GFN1 Hamiltonian.
171 --vipea
173 performs calculation of electron affinity and ionisation potential.
174 This needs the .param_ipea.xtb parameters and a GFN1 Hamiltonian.
175 --vfukui
177 performs calculation of Fukui indices.
178 --vomega
180 performs calculation of electrophilicity index. This needs the
181 .param_ipea.xtb parameters and a GFN1 Hamiltonian.
182 --grad
184 performs a gradient calculation
185 -o, --opt [LEVEL]
187 call ancopt(3) to perform a geometry optimization, levels from
188 crude, sloppy, loose, normal (default), tight, verytight to extreme
189 can be chosen
190 --hess
192 perform a numerical hessian calculation on input geometry
193 --ohess [LEVEL]
195 perform a numerical hessian calculation on an ancopt(3) optimized
196 geometry
197 --bhess [LEVEL]
199 perform a biased numerical hessian calculation on an ancopt(3)
200 optimized geometry
201 --md
203 molecular dynamics simulation on start geometry
204 --metadyn [int]
206 meta dynamics simulation on start geometry, saving int snapshots of
207 the trajectory to bias the simulation
208 --omd
210 molecular dynamics simulation on ancopt(3) optimized geometry, a
211 loose optimization level will be chosen
212 --metaopt [LEVEL]
214 call ancopt(3) to perform a geometry optimization, then try to find
215 other minimas by meta dynamics
216 --path [FILE]
218 use meta dynamics to calculate a path from the input geometry to
219 the given product structure
220 --reactor
222 experimental
223 --modef INT
225 modefollowing algorithm. INT specifies the mode that should be used
226 for the modefollowing.
227 GENERAL
229 -I, --input FILE
230 use FILE as input source for xcontrol(7) instructions
231 --namespace STRING
233 give this xtb(1) run a namespace. All files, even temporary ones,
234 will be named according to STRING (might not work everywhere).
235 --[no]copy
237 copies the xcontrol file at startup (default = true)
238 --[no]restart
240 restarts calculation from xtbrestart (default = true)
241 -P, --parallel INT
243 number of parallel processes
244 --define
246 performs automatic check of input and terminate
247 --json
249 write xtbout.json file
250 --citation
252 print citation and terminate
253 --license
255 print license and terminate
256 -v, --verbose
258 be more verbose (not supported in every unit)
259 -s, --silent
261 clutter the screen less (not supported in every unit)
262 --ceasefiles
264 reduce the amount of output and files written
265 --strict
267 turns all warnings into hard errors
268 -h, --help
270 show help page
271 --cut
273 create inner region for oniom calculation without performing any
274 calcultion
275
277 xtb(1) accesses a path-like variable to determine the location of its
278 parameter files, you have to provide the XTBPATH variable in the same
279 syntax as the system PATH variable. If this variable is not set, xtb(1)
280 will try to generate the XTBPATH from the deprecated XTBHOME variable.
281 In case the XTBHOME variable is not set it will be generated from the
282 HOME variable. So in principle storing the parameter files in the users
283 home directory is suffient but might lead to come cluttering.
284 Since the XTBHOME variable is deprecated with version 6.0 and newer
286 xtb(1) will issue a warning if XTBHOME is not part of the XTBPATH since
287 the XTBHOME variable is not used in production runs.
288
290 xtb(1) accesses a number of local files in the current working
291 directory and also writes some output in specific files. Note that not
292 all input and output files allow the --namespace option.
293 INPUT
295 .CHRG
296 molecular charge as int
297 .UHF
299 Number of unpaired electrons as int
300 mdrestart
302 contains restart information for MD, --namespace compatible.
303 pcharge
305 point charge input, format is real real real real [int]. The first
306 real is used as partial charge, the next three entries are the
307 cartesian coordinates and the last is an optional atom type. Note
308 that the point charge input is not affected by a CMA
309 transformation. Also parallel Hessian calculations will fail due to
310 I/O errors when using point charge embedding.
311 xcontrol
313 default input file in --copy mode, see xcontrol(7) for details, set
314 by --input.
315 xtbrestart
317 contains restart information for SCC, --namespace compatible.
318 OUTPUT
320 charges
321 contains Mulliken partial charges calculated in SCC
322 wbo
324 contains Wiberg bond order calculated in SCC, --namespace
325 compatible.
326 energy
328 total energy in Turbomole format
329 gradient
331 geometry, energy and gradient in Turbomole format
332 hessian
334 contains the (not mass weighted) cartesian Hessian, --namespace
335 compatible.
336 xtbopt.xyz, xtbopt.coord
338 optimized geometry in the same format as the input geometry.
339 xtbhess.coord
341 distorted geometry if imaginary frequency was found
342 xtbopt.log
344 contains all structures obtained in the geometry optimization with
345 the respective energy in the comment line in a XMOL formatted
346 trajectory
347 xtbsiman.log,xtb.trj.int
349 trajectories from MD
350 scoord.int
352 coordinate dump of MD
353 fod.cub
355 FOD on a cube-type grid
356 spindensity.cub
358 spindensity on a cube-type grid
359 density.cub
361 density on a cube-type grid
362 molden.input
364 MOs and occupation for visualisation and sTDA-xTB calculations
365 pcgrad
367 gradient of the point charges
368 xtb_esp.cosmo
370 ESP fake cosmo output
371 xtb_esp_profile.dat
373 ESP histogramm data
374 vibspectrum
376 Turbomole style vibrational spectrum data group
377 g98.out, g98l.out, g98_canmode.out, g98_locmode.out
379 g98 fake output with normal or local modes
380 .tmpxtbmodef
382 input for mode following
383 coordprot.0
385 protonated species
386 xtblmoinfo
388 centers of the localized molecular orbitals
389 lmocent.coord
391 centers of the localized molecular orbitals
392 tmpxx
394 number of recommended modes for mode following
395 xtb_normalmodes, xtb_localmodes
397 binary dump for mode following
398 TOUCH
400 xtbmdok
401 generated by successful MD
402 .xtbok
404 generated after each successful xtb(1) run
405 .sccnotconverged
407 generated after failed SCC with printlevel=2
408
410 xtb(1) can generate the two types of warnings, the first warning
411 section is printed immediately after the normal banner at startup,
412 summing up the evaluation of all input sources (commandline, xcontrol,
413 xtbrc). To check this warnings exclusively before running an expensive
414 calculation a input check is implemented via the --define flag. Please,
415 study this warnings carefully!
416 After xtb(1) has evaluated the all input sources it immediately enters
418 the production mode. Severe errors will lead to an abnormal termination
419 which is signalled by the printout to STDERR and a non-zero return
420 value (usually 128). All non-fatal errors are summerized in the end of
421 the calculation in one block, right before the timing analysis.
422 To aid the user to fix the problems generating these warnings a brief
424 summary of each warning with its respective string representation in
425 the output will be shown here:
426 ANCopt failed to converge the optimization
428 geometry optimization has failed to converge in the given number
429 optimization cycles. This is not neccessary a problem if only a
430 small number of cycles was given for the optimization on purpose.
431 All further calculations are done on the last geometry of the
432 optimization.
433 Hessian on incompletely optimized geometry!
435 This warning will be issued twice, once before the Hessian,
436 calculations starts (it would otherwise take some time before this
437 this warning could be detected) and in the warning block in the
438 end. The warning will be generated if the gradient norm on the
439 given geometry is higher than a certain threshold.
440
442 0
443 normal termination of xtb(1)
444 128
446 Failure (termination via error stop generates 128 as return value)
447
449 please report all bugs with an example input, --copy dump of internal
450 settings and the used geometry, as well as the --verbose output to
451 xtb@thch.uni-bonn.de
452
454 Main web site: http://grimme.uni-bonn.de/software/xtb
455
457 Copyright © 2017-2023 Stefan Grimme
458 xtb is free software: you can redistribute it and/or modify it under
460 the terms of the GNU Lesser General Public License as published by the
461 Free Software Foundation, either version 3 of the License, or (at your
462 option) any later version.
463 xtb is distributed in the hope that it will be useful, but WITHOUT ANY
465 WARRANTY; without even the implied warranty of MERCHANTABILITY or
466 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
467 License for more details.
468 You should have received a copy of the GNU Lesser General Public
470 License along with xtb. If not, see https://www.gnu.org/licenses/.
471 2023-08-14 XTB(1)