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 boff=real
112 grid boundary offset (default: 3.0)
113 cal=int
115 =1 switches on cube-file output (=0 means writing molden file
116 instead, -1=do nothing)
117 $embedding
119 at=int
120 default atom type for point charges
121 es=bool
123 use isotropic electrostatic with point charges
124 input=file
126 point charges are read from file (default: pcharge), format is: q x
127 y z [iat|gam], where q is the partial charges, xyz are the position
128 of the partial charge in bohr and iat is the ordinal number of the
129 atom. The corresponding gam-Parameter of the element will be used
130 in the potential. Alternatively the gam value can be given directly
131 as fifth argument, to simulate point charges provide a huge value
132 for gam.
133 gradient='file
135 gradient of the point charges is written to file (default: pcgrad)
136 $external
138 mopac bin=STRING
139 path to mopac(1) binary, will search PATH variable for binary if
140 not set
141 mopac input=STRING
143 input string used for mopac(1) calculation, make sure it generates
144 an aux file for xtb(1) to read in.
145 mopac file=STRING
147 name of the mopac(1) input file
148 orca bin=STRING
150 path to orca(1) binary, will search PATH variable for binary if not
151 set
152 orca input line=STRING
154 input string used for orca(1) calculation, will use engrad runtyp
155 by default
156 orca input file=STRING
158 name of the orca(1) input file
159 turbodir=STRING
161 path to your Turbomole directory (usually found in TURBODIR or
162 TURBOIMG variable)
163 $fix
165 Note
166 the fix group refers to exact fixing. For geometry optimizations
167 the gradient is set to zero, while for Hessians no displacements
168 are calculated. Constraining with external potentials is done by
169 the constrain data group.
170 elements: symbol|number,...
172 fixes all elements of the same type, the atom type is determined by
173 the ordinal number or the element symbol. This is automatically
174 deactivated for molecular dynamics since it leads to instabilities.
175 atoms: list,...
177 fixes all atoms in list by setting the gradient to zero. This is
178 automatically deactivated for molecular dynamics since it leads to
179 instabilities.
180 freeze frequency=real
182 diagonal element used for freezing atoms in numerical Hessian
183 calculation
184 freeze: list,...
186 freezes all atoms in list for hessian calculation
187 shake: i,j,...
189 use SHAKE to constrain the atompair ij in molecular dynamics.
190 $gbsa
192 solvent=string
193 solvent for the generalized born (GB) model with solvent accessable
194 surface area (SASA), requires .param_gbsa.solvent in XTBPATH. Does
195 not activate GBSA (use commandline).
196 ion_st=real
198 ion strength for salt screening in GBSA
199 ion_rad=real
201 ion radius for salt screening in GBSA
202 grid=level
204 changes the grid used for the surface accessable surface area
205 (normal, tight, vtight, extreme are available).
206 $gfn
208 method=int
209 version of the GFN Hamiltonian
210 dispscale=real
212 Scale dispersion energy of GFN-FF
213 $hess
215 sccacc=real
216 SCC accuracy level in Hessian runs
217 step=real
219 Cartesian displacement increment for numerical Hessian
220 scale=real
222 Scaling factor for the hessian elements (default: 1.0)
223 element mass: int,real,...
225 set mass of elements int to real
226 isotope: int,real,... (6.1 only)
228 set mass of atom number int to real
229 modify mass: int,real,... (6.1 only)
231 set mass of atom number int to real
232 scale mass: int,real,... (6.1 only)
234 scale mass of atom number int by real
235 $metadyn (6.1 only)
237 save=int
238 maximal number of structures for rmsd criteria
239 kpush=real,...
241 scaling factor for rmsd criteria can be positive and negative
242 modify factor=int,real,...
244 replace the factor int with real
245 scale factor=int,real,...
247 scales the factor int with real
248 alp=real
250 width of the Gaussian potential used in the rmsd criteria
251 coord=file
253 external structures to initialize the rmsd criteria (xmol format
254 required)
255 atoms: list,...
257 atoms to include in rmsd calculation, if not present all atoms are
258 taken into account
259 rmsd: real,...
261 target rmsd for biased hessian runs in Ångström
262 bias input=file
264 read static bias from file, requires xyz format with factor and
265 width of the potential in the comment line
266 bias atoms: list,...
268 atoms to include in static rmsd calculation, if not present all
269 atoms are taken into account
270 bias elements: id,...
272 elements to include in static rmsd calculation, if not present all
273 atoms are taken into account. Elements can be referenced by their
274 element symbol or their atomic number.
275 $md
277 temp=real
278 MD thermostat/GBSA temperature
279 time=real
281 MD run time in ps
282 dump=real
284 dump structure in every dump fs
285 sdump=real
287 dump structure as scoord.<num> every sdump fs
288 velo=int
290 set to 1 if dumps (trj file) should contain velocities
291 nvt=int
293 use thermostat (=1, =0 for NVE)
294 skip=int
296 skip interval in -mdav, -mdopt
297 step=real
299 MD time step in fs (automatically determined if < 0), could be 4-5
300 fs with shake =2, md_hmass=4
301 hmass=int
303 increase hydrogen mass to this value in amu (at const. tot. mass)
304 allowing large time steps (=0 off)
305 shake=int
307 shake on (=0: off which is default) for X-H bonds only (=1),
308 sccacc=real
310 SCC accuracy level in MD. Every 10th step the SCC is properly
311 converged at sccconv=1.0. sccmd should be < 5 in critical cases,
312 effects may show up as bad thermostating
313 forcewrrestart=logical
315 forces the writing of a restart file at each dump step
316 $modef
318 n=int
319 of points along normal mode path scan
320 step=real
322 step lengths for scan (should be around 1 because its adjusted
323 internally to mode mass and FC)
324 updat=real
326 update search mode with a fraction of the displacement at every
327 step (0.0 means no update, 0.1-0.2 is a good choice)
328 local=int
330 use canonical normal modes (=0) or Pipek-Mezey localized ones (=1)
331 vthr=real
333 threshold up to which frequency modes are used for mode based
334 conformer search (def. is 300)
335 prj=int
337 number of second mode which should be projected out in mode
338 following (normally = 7 ie the TS mode which is fixed then)
339 mode=int
341 can set by --modef via cmdline
342 $oniom
344 inner logs=bool
345 to print optimization log files for model region geometry
346 (high.inner_region.log and low.inner_region.log)
347 derived k=bool
349 to calculate prefactor k and create jacobian dynamically (see more
350 )
351 silent=bool
353 to hide the execution runs of external software
354 $opt
356 engine=method
357 method can be rf for ANCopt (default), lbfgs for L-ANCopt or
358 inertial for FIRE.
359 output=file
361 redirect output of optimization to file
362 logfile='file
364 write optimization log to file (default: xtbopt.log)
365 optlevel=level
367 convergence thresholds for the ancopt(3): crude = -3, sloppy =
368 -2, loose = -1, normal = 0, tight = 1, verytight =
369 2, extreme = 3
370 microcycle=int
372 number of optimization cycles before new ANC are made (default=25)
373 maxcycle=int
375 total number of opt. cycles, 0 means automatically determined
376 hlow=real
378 lowest force constant in ANC generation (should be > 0.005)
379 maxdispl=real
381 maximum coordinate displacement in ancopt(3)
382 average conv=bool
384 average the energy and gradient before checking for convergence to
385 accelerate numerically noisy potential energy surfaces (default:
386 false).
387 s6=real
389 dispersion scaling in ANC generation
390 hessian=lindh-d2|lindh|swart
392 model hessian for generation of ANC used in optimization
393 kstretch=real
395 stretch force constant in model hessian
396 kbend=real
398 bend force constant in model hessian
399 ktorsion=real
401 torsion force constant in model hessian
402 koutofp=real
404 out-of-plain force constant to model hessian
405 kvdw=real
407 additional vdW-contribution (lindh|swart only)
408 kes=real
410 electrostatic contribution to model hessian by EEQ model
411 rcut=real
413 distance cutoff for bonds in model hessian
414 $path (6.1 only)
416 nrun=int
417 number of runs for pathfinder
418 nopt=int
420 number of points on the path to optimize
421 anopt=int
423 number of steps to optimize the points on the path
424 kpush=real
426 factor for RMSD criterium pushing away from the reactant structure
427 kpull=real
429 factor for RMSD criterium pulling towards the product structure
430 alp=real
432 width of the RMSD criterium
433 product=file
435 file name of the product structure
436 $scan
438 mode=sequential|concerted
439 scans all constraints at once (concerted) or after each other
440 (sequential). in sequential mode the final value of the scanned
441 constraint is kept in place. in concerted mode all steps for the
442 scans have to be the same.
443 int: start,end,steps
445 where start and end are real values and steps is an integer value.
446 Defines a scan along constraint int (which has to be defined
447 before, of course), from start to end in a certain number of steps.
448 There is no limitation in the number of steps as in 5.8.
449 name: values; start,end,steps
451 defines the constrain name on which the scan is performed. See
452 above and the the constrain group for more information, since name
453 (e.g. distance) and values (e.g. i,j,value) are handed internally
454 to the constrain parser.
455 Note
457 the scan parser will always terminate in error if the instruction
458 could not be parsed correctly, while the constrain parser is able
459 to skip instructions with wrong input by raising a warning.
460 $scc
462 temp=real
463 electronic temperature for the Fermi smearing
464 broydamp=real
466 damping for the Broyden convergence accelerator
467 guess=gasteiger|goedecker|sad
469 different possible guess charges for GFN2-xTB SCC calculation
470 maxiteration=int
472 adjusts the number of SCC iterations in the first/last SCC
473 calculation
474 $split
476 fragment1: list,...
477 defines atoms belonging to fragment 1
478 fragment2: list,...
480 defines atoms belonging to fragment 2
481 fragment: i,list,...
483 defines atoms belonging to fragment i
484 $stm (6.1 only)
486 activate by $write/stm=true
487 broadening=real
489 width of tip DOS energy broadening (eV)
490 current=real
492 constant current value (arb.u.)
493 grid=real
495 grid width (Bohr), half that value along Z
496 thr=real
498 integral and density matrix neglect threshold
499 potential=real
501 potential of tip vs. molecule, negative values let e flow from mol
502 to tip i.e. occ space of mol is probed
503 $symmetry
505 desy=real
506 point group symmetrization threshold
507 maxat=int
509 point group determination skipped if # atoms > this value (i.e.
510 desymaxat 0 switches it off)
511 $thermo
513 temp=real
514 temperature for thermostatistical calculation (default: 298.15 K)
515 imagthr=real
517 threshold for inverting imaginary frequencies for thermo in cm-1
518 (default: -20.0)
519 scale=real
521 scaling factor for frequencies in vibrational partition function
522 (default: 1.0)
523 sthr=real
525 rotor cut-off (cm-1) in thermo (default: 50.0)
526 $wall
528 potential=logfermi|polynomial
529 sets kind of wall potential used (default: polynomial)
530 alpha=int
532 exponent of polynomial wall potential (default: 30)
533 beta=real
535 exponent of logfermi bias potential (default: 6.0)
536 autoscale=real
538 scales axis of automatic determined wall potentials by real
539 axisshift=real
541 constant offset used in automatic dermined wall potential axis
542 (default: 3.5)
543 temp=real
545 temperature of the logfermi wall (default: 300.0 K), wall energy of
546 logfermi is multiplied with kT.
547 sphere: auto|real,all|list,...
549 set up a spherical wall potential for all or the atoms in list with
550 the radius real or an automatical determined sphere radius
551 ellipsoid: auto|real,auto|real,auto|real,all|list,...
553 set up a ellipsoid wall potential for all or the atoms in list with
554 the radii real or an automatical determined sphere radius
555 $write
557 esp=bool
558 calculate and print electrostatic potential, this will create a
559 data file and a cosmo file
560 gridfile=file
562 read gridpoints for ESP calculation from file.
563 mos=bool
565 print molden file
566 lmo=bool
568 localize orbitals and print out LMO centers
569 density=bool
571 calculate density on a cube grid
572 spin population=bool
574 spin population analysis
575 spin density=bool
577 calculate spin density on a cube grid
578 fod=bool
580 calculate FOD on a cube grid (set electronic temperature to at
581 least 12500 K)
582 wiberg=bool
584 calculate and print Wiberg bond order
585 dipole=bool
587 calculate and print dipole moment
588 charges=bool
590 print charges file
591 mulliken=bool
593 print mulliken population analysis
594 orbital energies=bool
596 print orbital energies and occupation numbers
597 stm=bool
599 creates an STM image of the molecule, see stm group (6.1 only)
600 geosum=bool
602 old style geometry summary
603 inertia=bool
605 geometry summary on moments on inertia and rotational constants
606 (available with --define)
607 distances=bool
609 geometry summary on distances and bonds (available with --define)
610 angles=bool
612 geometry summary on angles (available with --define)
613 torsions=bool
615 geometry summary on dihedral angles and torsions (available with
616 --define)
617 vib_normal_modes=bool
619 write normal modes as Turbomole vibrational modes data group
620 hessian.out=bool
622 write DFTB+ style hessian.out file containing the unprojected
623 hessian
624 LEGACY
626 To ensure compatibility with older versions of the xtb(1) prior to
627 version 6.0 a group instruction set is allowed which accepts the same
628 syntax as the original set-block. Here we provide a list of set-block
629 commands and their corresponding instructions in xcontrol(7).
630 Note
632 xtb(1) can read a set-block by itself and will print out a
633 equivalent instruction set. This feature will be deprecated in
634 future versions since the set-block is less flexible than
635 xcontrol(7) and might be deactived without prior announcement!
636 broydamp
638 use broydamp in scc group instead
639 chrg, charge
641 use chrg logical instead
642 constrainallbo, constralltbo
644 currently not supported
645 constrainalltors, constralltors
647 currently not supported
648 constrain
650 use constrain group instead
651 constrainel
653 currently not supported
654 constrfc
656 use force constant in constrain group instead
657 constrxyz
659 use atoms in fix group instead
660 cube_cal
662 use cal in cube group instead
663 cube_pthr
665 use pthr in cube group instead
666 cube_step
668 use step in cube group instead
669 desymaxat
671 use maxat in symmetry group instead
672 desy
674 use desy in symmetry group instead
675 ellips
677 use ellipsoid in wall group instead
678 etemp
680 use temp in scc group instead
681 ex_open_HS
683 currently not supported
684 ex_open_LS
686 currently not supported
687 fit
689 use fit logical instead
690 fix
692 use atoms in fix/constrain group instead
693 fixfc
695 use force constant in constrain group instead
696 fragment1
698 use fragment1 in split group instead
699 fragment2
701 use fragment1 in split group instead
702 gbsa
704 use solvent in gbsa group instead
705 gfnver
707 use version in gfn group instead
708 hessa
710 currently not supported
711 hessf
713 use freeze in fix group instead
714 hlowopt
716 use hlow in opt group instead
717 ion_rad
719 use ion_rad in gbas group instead
720 ion_st
722 use ion_st in gbsa group instead
723 maxdispl
725 use maxdipl in opt group instead
726 maxopt
728 use maxcycle in opt group instead
729 mddumpxyz
731 use dump in md group instead
732 md_hmass
734 use hmass in md group instead
735 mdskip
737 use skip in md group instead
738 mdstep
740 use step in md group instead
741 mdtemp
743 use temp in md group instead
744 mdtime
746 use time in md group instead
747 microopt
749 use mircocycle in opt group instead
750 mode_local
752 use local in modef group instead
753 mode_n
755 use n in modef group instead
756 mode_prj
758 use prj in *modef group instead
759 mode_step
761 use step in modef group instead
762 mode_updat
764 use updat in modef group instead
765 mode_vthr
767 use vthr in modef group instead
768 nvt
770 use nvt in md group instead
771 optlev
773 use optlevel in opt group intead
774 orca_exe
776 currently not supported
777 orca_line
779 currently not supported
780 orca_mpi
782 currently not supported
783 restartmd, mdrestart
785 use restart in md group
786 runtyp
788 please use the commandline instead, might still work
789 s6opt
791 use s6 in opt group instead
792 samerand
794 use samerand logical instead
795 scan
797 use scan group instead
798 scchess
800 use sccacc in hess group instead
801 sccmd
803 use sccacc in md group instead
804 shake
806 use shake in md group instead
807 sphere
809 use sphere in sphere group instead
810 springexp
812 use springexp in fix group instead
813 stephess
815 use step in *hess group instead
816 thermo_sthr
818 use sthr in thermo group instead
819 thermo
821 use temp in thermo group instead
822 uhf
824 use uhf logical instead
825 velodump
827 use velo in md group instead
828
830 Please report all bugs with an example input, --copy dump of internal
831 settings and the used geometry, as well as the --verbose output to
832 xtb@thch.uni-bonn.de
833
835 Main web site: http://grimme.uni-bonn.de/software/xtb
836
838 Copyright (C) 2015-2020 S. Grimme. This work is licensed under the
839 Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA
840 4.0).
841 2023-08-14 XCONTROL(7)