1XCONTROL(7) XCONTROL(7)
2
6 xcontrol - instruction file for `xtb(1)` version 6.0 and newer
7
9 xtb -I,--input xcontrol FILE
10
12 The xcontrol(7) instruction set is the successor of the set-block
13 present in xtb(1) version 5.8 and earlier. The used instruction set is
14 similar to the data groups in Turbomole or the detailed input structure
15 of ORCA. Every instruction is started by a flag ($) and terminated by
16 the next flag. A instruction is only valid if the flag is in the first
17 column, the instruction name is the rest of the register. A valid
18 instruction opens its blocks with its own options, every option is a
19 key-value pair.
20 There are two kind of instructions, logical and groups. Logical
22 instructions toggle a specific operation and cannot contain a option
23 block while group instructions only open the option block without any
24 further actions.
25 A special instruction is the end instruction which is optional, as EOF
27 is a valid alternative in this implementation.
28 It should be noted that xtb(1) is able to produce xcontrol(7)
30 instructions by itself. You can tell xtb(1) by --copy to save you
31 original instructions, note that this implementation will strip all
32 comments while copying (print what you see, not what you read), to aid
33 debugging.
34 $fit
36 logical instruction to set xtb(1) in mfit(1) compatibility mode and
37 prints out further informations. This is a pure development feature and
38 therefore should be absent in every productive run.
39 $samerand
41 logical instruction to initialize the random number generator with the
42 same sequence
43 $chrg int
45 set the charge of the molecule
46 $spin int
48 set Nalpha-Nbeta of the molecule
49 $cma
51 shifts molecule to center of mass and transforms cartesian coordinates
52 into the coordinate system of the principle axis (not affected by
53 ‘isotopes’-file).
54 $constrain
56 Note
57 This data group refers to constraining the gradient by appling
58 potentials. Exact fixing is done with the fix data group.
59 force constant=real
61 force constant for constraining potential
62 all bonds=bool
64 generate potentials to constrain the length of all bonds
65 all angles=bool
67 generate potentials to constrain all bond angles
68 all torsions=bool
70 generate potentials to constrain the angles of all torsions
71 elements: symbol|number,...
73 constrains all elements of the same type, the atom type is
74 determined by the ordinal number or the element symbol
75 atoms: list,...
77 constrains the atom positions of all atoms in list. Needs at least
78 two atoms since potential is applied on all atoms in list.
79 distance: i,j,auto|real
81 constrain the distance between atom i and j to the actual length
82 (auto) or the value real, which has to be given in Ångström.
83 angle: i,j,k,auto|real
85 constrain the angle between atom i, j and k to the actual length
86 (auto) or the value real, which has to be given in degrees.
87 dihedral: i,j,k,l,auto|real
89 constrain the angle between atom i, j, k and l to the actual length
90 (auto) or the value real, which has to be given in degrees.
91 center: real,int
93 implemented and documented as in xtb 5.8, might use fragment1
94 information from split instruction.
95 cma[ interface]: auto|real
97 implemented and documented as in xtb 5.8, might use
98 fragment1/fragment2 information from split instruction.
99 z: real
101 implemented and documented as in xtb 5.8, might use fragment1
102 information from split instruction.
103 $cube
105 step=real
106 grid spacing for cube file
107 pthr=real
109 density matrix neglect threshold
110 cal=int
112 =1 switches on cube-file output (=0 means writing molden file
113 instead, -1=do nothing)
114 $embedding
116 at=int
117 default atom type for point charges
118 es=bool
120 use isotropic electrostatic with point charges
121 input=file
123 point charges are read from file (default: pcharge), format is: q x
124 y z [iat|gam], where q is the partial charges, xyz are the position
125 of the partial charge in bohr and iat is the ordinal number of the
126 atom. The corresponding gam-Parameter of the element will be used
127 in the potential. Alternatively the gam value can be given directly
128 as fifth argument, to simulate point charges provide a huge value
129 for gam.
130 gradient='file
132 gradient of the point charges is written to file (default: pcgrad)
133 $external
135 mopac bin=STRING
136 path to mopac(1) binary, will search PATH variable for binary if
137 not set
138 mopac input=STRING
140 input string used for mopac(1) calculation, make sure it generates
141 an aux file for xtb(1) to read in.
142 mopac file=STRING
144 name of the mopac(1) input file
145 orca bin=STRING
147 path to orca(1) binary, will search PATH variable for binary if not
148 set
149 orca input line=STRING
151 input string used for orca(1) calculation, will use engrad runtyp
152 by default
153 orca input file=STRING
155 name of the orca(1) input file
156 turbodir=STRING
158 path to your Turbomole directory (usually found in TURBODIR or
159 TURBOIMG variable)
160 $fix
162 Note
163 the fix group refers to exact fixing. For geometry optimizations
164 the gradient is set to zero, while for Hessians no displacements
165 are calculated. Constraining with external potentials is done by
166 the constrain data group.
167 elements: symbol|number,...
169 fixes all elements of the same type, the atom type is determined by
170 the ordinal number or the element symbol. This is automatically
171 deactivated for molecular dynamics since it leads to instabilities.
172 atoms: list,...
174 fixes all atoms in list by setting the gradient to zero. This is
175 automatically deactivated for molecular dynamics since it leads to
176 instabilities.
177 freeze frequency=real
179 diagonal element used for freezing atoms in numerical Hessian
180 calculation
181 freeze: list,...
183 freezes all atoms in list for hessian calculation
184 shake: i,j,...
186 use SHAKE to constrain the atompair ij in molecular dynamics.
187 $gbsa
189 solvent=string
190 solvent for the generalized born (GB) model with solvent accessable
191 surface area (SASA), requires .param_gbsa.solvent in XTBPATH. Does
192 not activate GBSA (use commandline).
193 ion_st=real
195 ion strength for salt screening in GBSA
196 ion_rad=real
198 ion radius for salt screening in GBSA
199 grid=level
201 changes the grid used for the surface accessable surface area
202 (normal, tight, vtight, extreme are available).
203 $gfn
205 method=int
206 version of the GFN Hamiltonian
207 dispscale=real
209 Scale dispersion energy of GFN-FF
210 $hess
212 sccacc=real
213 SCC accuracy level in Hessian runs
214 step=real
216 Cartesian displacement increment for numerical Hessian
217 scale=real
219 Scaling factor for the hessian elements (default: 1.0)
220 element mass: int,real,...
222 set mass of elements int to real
223 isotope: int,real,... (6.1 only)
225 set mass of atom number int to real
226 modify mass: int,real,... (6.1 only)
228 set mass of atom number int to real
229 scale mass: int,real,... (6.1 only)
231 scale mass of atom number int by real
232 $metadyn (6.1 only)
234 save=int
235 maximal number of structures for rmsd criteria
236 kpush=real,...
238 scaling factor for rmsd criteria can be positive and negative
239 modify factor=int,real,...
241 replace the factor int with real
242 scale factor=int,real,...
244 scales the factor int with real
245 alp=real
247 width of the Gaussian potential used in the rmsd criteria
248 coord=file
250 external structures to initialize the rmsd criteria (xmol format
251 required)
252 atoms: list,...
254 atoms to include in rmsd calculation, if not present all atoms are
255 taken into account
256 rmsd: real,...
258 target rmsd for biased hessian runs in Ångström
259 bias input=file
261 read static bias from file, requires xyz format with factor and
262 width of the potential in the comment line
263 bias atoms: list,...
265 atoms to include in static rmsd calculation, if not present all
266 atoms are taken into account
267 bias elements: id,...
269 elements to include in static rmsd calculation, if not present all
270 atoms are taken into account. Elements can be referenced by their
271 element symbol or their atomic number.
272 $md
274 temp=real
275 MD thermostat/GBSA temperature
276 time=real
278 MD run time in ps
279 dump=real
281 dump structure in every dump fs
282 sdump=real
284 dump structure as scoord.<num> every sdump fs
285 velo=int
287 set to 1 if dumps (trj file) should contain velocities
288 nvt=int
290 use thermostat (=1, =0 for NVE)
291 skip=int
293 skip interval in -mdav, -mdopt
294 step=real
296 MD time step in fs (automatically determined if < 0), could be 4-5
297 fs with shake =2, md_hmass=4
298 hmass=int
300 increase hydrogen mass to this value in amu (at const. tot. mass)
301 allowing large time steps (=0 off)
302 shake=int
304 shake on (=0: off which is default) for X-H bonds only (=1),
305 sccacc=real
307 SCC accuracy level in MD. Every 10th step the SCC is properly
308 converged at sccconv=1.0. sccmd should be < 5 in critical cases,
309 effects may show up as bad thermostating
310 $modef
312 n=int
313 of points along normal mode path scan
314 step=real
316 step lengths for scan (should be around 1 because its adjusted
317 internally to mode mass and FC)
318 updat=real
320 update search mode with a fraction of the displacement at every
321 step (0.0 means no update, 0.1-0.2 is a good choice)
322 local=int
324 use canonical normal modes (=0) or Pipek-Mezey localized ones (=1)
325 vthr=real
327 threshold up to which frequency modes are used for mode based
328 conformer search (def. is 300)
329 prj=int
331 number of second mode which should be projected out in mode
332 following (normally = 7 ie the TS mode which is fixed then)
333 mode=int
335 can set by --modef via cmdline
336 $opt
338 engine=method
339 method can be rf for ANCopt (default), lbfgs for L-ANCopt or
340 inertial for FIRE.
341 output=file
343 redirect output of optimization to file
344 logfile='file
346 write optimization log to file (default: xtbopt.log)
347 optlevel=level
349 convergence thresholds for the ancopt(3): crude = -3, sloppy =
350 -2, loose = -1, normal = 0, tight = 1, verytight =
351 2, extreme = 3
352 microcycle=int
354 number of optimization cycles before new ANC are made (default=25)
355 maxcycle=int
357 total number of opt. cycles, 0 means automatically determined
358 hlow=real
360 lowest force constant in ANC generation (should be > 0.005)
361 maxdispl=real
363 maximum coordinate displacement in ancopt(3)
364 average conv=bool
366 average the energy and gradient before checking for convergence to
367 accelerate numerically noisy potential energy surfaces (default:
368 false).
369 s6=real
371 dispersion scaling in ANC generation
372 hessian=lindh-d2|lindh|swart
374 model hessian for generation of ANC used in optimization
375 kstretch=real
377 stretch force constant in model hessian
378 kbend=real
380 bend force constant in model hessian
381 ktorsion=real
383 torsion force constant in model hessian
384 koutofp=real
386 out-of-plain force constant to model hessian
387 kvdw=real
389 additional vdW-contribution (lindh|swart only)
390 kes=real
392 electrostatic contribution to model hessian by EEQ model
393 rcut=real
395 distance cutoff for bonds in model hessian
396 $path (6.1 only)
398 nrun=int
399 number of runs for pathfinder
400 nopt=int
402 number of points on the path to optimize
403 anopt=int
405 number of steps to optimize the points on the path
406 kpush=real
408 factor for RMSD criterium pushing away from the reactant structure
409 kpull=real
411 factor for RMSD criterium pulling towards the product structure
412 alp=real
414 width of the RMSD criterium
415 product=file
417 file name of the product structure
418 $scan
420 mode=sequential|concerted
421 scans all constraints at once (concerted) or after each other
422 (sequential). in sequential mode the final value of the scanned
423 constraint is kept in place. in concerted mode all steps for the
424 scans have to be the same.
425 int: start,end,steps
427 where start and end are real values and steps is an integer value.
428 Defines a scan along constraint int (which has to be defined
429 before, of course), from start to end in a certain number of steps.
430 There is no limitation in the number of steps as in 5.8.
431 name: values; start,end,steps
433 defines the constrain name on which the scan is performed. See
434 above and the the constrain group for more information, since name
435 (e.g. distance) and values (e.g. i,j,value) are handed internally
436 to the constrain parser.
437 Note
439 the scan parser will always terminate in error if the instruction
440 could not be parsed correctly, while the constrain parser is able
441 to skip instructions with wrong input by raising a warning.
442 $scc
444 temp=real
445 electronic temperature for the Fermi smearing
446 broydamp=real
448 damping for the Broyden convergence accelerator
449 guess=gasteiger|goedecker|sad
451 different possible guess charges for GFN2-xTB SCC calculation
452 maxiteration=int
454 adjusts the number of SCC iterations in the first/last SCC
455 calculation
456 $split
458 fragment1: list,...
459 defines atoms belonging to fragment 1
460 fragment2: list,...
462 defines atoms belonging to fragment 2
463 fragment: i,list,...
465 defines atoms belonging to fragment i
466 $stm (6.1 only)
468 activate by $write/stm=true
469 broadening=real
471 width of tip DOS energy broadening (eV)
472 current=real
474 constant current value (arb.u.)
475 grid=real
477 grid width (Bohr), half that value along Z
478 thr=real
480 integral and density matrix neglect threshold
481 potential=real
483 potential of tip vs. molecule, negative values let e flow from mol
484 to tip i.e. occ space of mol is probed
485 $symmetry
487 desy=real
488 point group symmetrization threshold
489 maxat=int
491 point group determination skipped if # atoms > this value (i.e.
492 desymaxat 0 switches it off)
493 $thermo
495 temp=real
496 temperature for thermostatistical calculation (default: 298.15 K)
497 imagthr=real
499 threshold for inverting imaginary frequencies for thermo in cm-1
500 (default: -20.0)
501 scale=real
503 scaling factor for frequencies in vibrational partition function
504 (default: 1.0)
505 sthr=real
507 rotor cut-off (cm-1) in thermo (default: 50.0)
508 $wall
510 potential=logfermi|polynomial
511 sets kind of wall potential used (default: polynomial)
512 alpha=int
514 exponent of polynomial wall potential (default: 30)
515 beta=real
517 exponent of logfermi bias potential (default: 6.0)
518 autoscale=real
520 scales axis of automatic determined wall potentials by real
521 axisshift=real
523 constant offset used in automatic dermined wall potential axis
524 (default: 3.5)
525 temp=real
527 temperature of the logfermi wall (default: 300.0 K), wall energy of
528 logfermi is multiplied with kT.
529 sphere: auto|real,all|list,...
531 set up a spherical wall potential for all or the atoms in list with
532 the radius real or an automatical determined sphere radius
533 ellipsoid: auto|real,auto|real,auto|real,all|list,...
535 set up a ellipsoid wall potential for all or the atoms in list with
536 the radii real or an automatical determined sphere radius
537 $write
539 esp=bool
540 calculate and print electrostatic potential, this will create a
541 data file and a cosmo file
542 gridfile=file
544 read gridpoints for ESP calculation from file.
545 mos=bool
547 print molden file
548 lmo=bool
550 localize orbitals and print out LMO centers
551 density=bool
553 calculate density on a cube grid
554 spin population=bool
556 spin population analysis
557 spin density=bool
559 calculate spin density on a cube grid
560 fod=bool
562 calculate FOD on a cube grid (set electronic temperature to at
563 least 12500 K)
564 wiberg=bool
566 calculate and print Wiberg bond order
567 dipole=bool
569 calculate and print dipole moment
570 charges=bool
572 print charges file
573 mulliken=bool
575 print mulliken population analysis
576 orbital energies=bool
578 print orbital energies and occupation numbers
579 stm=bool
581 creates an STM image of the molecule, see stm group (6.1 only)
582 geosum=bool
584 old style geometry summary
585 inertia=bool
587 geometry summary on moments on inertia and rotational constants
588 (available with --define)
589 distances=bool
591 geometry summary on distances and bonds (available with --define)
592 angles=bool
594 geometry summary on angles (available with --define)
595 torsions=bool
597 geometry summary on dihedral angles and torsions (available with
598 --define)
599 vib_normal_modes=bool
601 write normal modes as Turbomole vibrational modes data group
602 hessian.out=bool
604 write DFTB+ style hessian.out file containing the unprojected
605 hessian
606 LEGACY
608 To ensure compatibility with older versions of the xtb(1) prior to
609 version 6.0 a group instruction set is allowed which accepts the same
610 syntax as the original set-block. Here we provide a list of set-block
611 commands and their corresponding instructions in xcontrol(7).
612 Note
614 xtb(1) can read a set-block by itself and will print out a
615 equivalent instruction set. This feature will be deprecated in
616 future versions since the set-block is less flexible than
617 xcontrol(7) and might be deactived without prior announcement!
618 broydamp
620 use broydamp in scc group instead
621 chrg, charge
623 use chrg logical instead
624 constrainallbo, constralltbo
626 currently not supported
627 constrainalltors, constralltors
629 currently not supported
630 constrain
632 use constrain group instead
633 constrainel
635 currently not supported
636 constrfc
638 use force constant in constrain group instead
639 constrxyz
641 use atoms in fix group instead
642 cube_cal
644 use cal in cube group instead
645 cube_pthr
647 use pthr in cube group instead
648 cube_step
650 use step in cube group instead
651 desymaxat
653 use maxat in symmetry group instead
654 desy
656 use desy in symmetry group instead
657 ellips
659 use ellipsoid in wall group instead
660 etemp
662 use temp in scc group instead
663 ex_open_HS
665 currently not supported
666 ex_open_LS
668 currently not supported
669 fit
671 use fit logical instead
672 fix
674 use atoms in fix/constrain group instead
675 fixfc
677 use force constant in constrain group instead
678 fragment1
680 use fragment1 in split group instead
681 fragment2
683 use fragment1 in split group instead
684 gbsa
686 use solvent in gbsa group instead
687 gfnver
689 use version in gfn group instead
690 hessa
692 currently not supported
693 hessf
695 use freeze in fix group instead
696 hlowopt
698 use hlow in opt group instead
699 ion_rad
701 use ion_rad in gbas group instead
702 ion_st
704 use ion_st in gbsa group instead
705 maxdispl
707 use maxdipl in opt group instead
708 maxopt
710 use maxcycle in opt group instead
711 mddumpxyz
713 use dump in md group instead
714 md_hmass
716 use hmass in md group instead
717 mdskip
719 use skip in md group instead
720 mdstep
722 use step in md group instead
723 mdtemp
725 use temp in md group instead
726 mdtime
728 use time in md group instead
729 microopt
731 use mircocycle in opt group instead
732 mode_local
734 use local in modef group instead
735 mode_n
737 use n in modef group instead
738 mode_prj
740 use prj in *modef group instead
741 mode_step
743 use step in modef group instead
744 mode_updat
746 use updat in modef group instead
747 mode_vthr
749 use vthr in modef group instead
750 nvt
752 use nvt in md group instead
753 optlev
755 use optlevel in opt group intead
756 orca_exe
758 currently not supported
759 orca_line
761 currently not supported
762 orca_mpi
764 currently not supported
765 restartmd, mdrestart
767 use restart in md group
768 runtyp
770 please use the commandline instead, might still work
771 s6opt
773 use s6 in opt group instead
774 samerand
776 use samerand logical instead
777 scan
779 use scan group instead
780 scchess
782 use sccacc in hess group instead
783 sccmd
785 use sccacc in md group instead
786 shake
788 use shake in md group instead
789 sphere
791 use sphere in sphere group instead
792 springexp
794 use springexp in fix group instead
795 stephess
797 use step in *hess group instead
798 thermo_sthr
800 use sthr in thermo group instead
801 thermo
803 use temp in thermo group instead
804 uhf
806 use uhf logical instead
807 velodump
809 use velo in md group instead
810
812 Please report all bugs with an example input, --copy dump of internal
813 settings and the used geometry, as well as the --verbose output to
814 xtb@thch.uni-bonn.de
815
817 Main web site: http://grimme.uni-bonn.de/software/xtb
818
820 Copyright (C) 2015-2020 S. Grimme. This work is licensed under the
821 Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA
822 4.0).
823 2022-08-02 XCONTROL(7)