1XCONTROL(7)                                                        XCONTROL(7)
2
3
4

NAME

6       xcontrol - instruction file for `xtb(1)` version 6.0 and newer
7

SYNOPSIS

9       xtb -I,--input xcontrol FILE
10

DESCRIPTION

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
21       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
26       A special instruction is the end instruction which is optional, as EOF
27       is a valid alternative in this implementation.
28
29       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
35   $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
40   $samerand
41       logical instruction to initialize the random number generator with the
42       same sequence
43
44   $chrg int
45       set the charge of the molecule
46
47   $spin int
48       set Nalpha-Nbeta of the molecule
49
50   $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
55   $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
60       force constant=real
61           force constant for constraining potential
62
63       all bonds=bool
64           generate potentials to constrain the length of all bonds
65
66       all angles=bool
67           generate potentials to constrain all bond angles
68
69       all torsions=bool
70           generate potentials to constrain the angles of all torsions
71
72       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
76       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
80       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
84       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
88       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
92       center: real,int
93           implemented and documented as in xtb 5.8, might use fragment1
94           information from split instruction.
95
96       cma[ interface]: auto|real
97           implemented and documented as in xtb 5.8, might use
98           fragment1/fragment2 information from split instruction.
99
100       z: real
101           implemented and documented as in xtb 5.8, might use fragment1
102           information from split instruction.
103
104   $cube
105       step=real
106           grid spacing for cube file
107
108       pthr=real
109           density matrix neglect threshold
110
111       cal=int
112           =1 switches on cube-file output (=0 means writing molden file
113           instead, -1=do nothing)
114
115   $embedding
116       at=int
117           default atom type for point charges
118
119       es=bool
120           use isotropic electrostatic with point charges
121
122       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
131       gradient='file
132           gradient of the point charges is written to file (default: pcgrad)
133
134   $external
135       mopac bin=STRING
136           path to mopac(1) binary, will search PATH variable for binary if
137           not set
138
139       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
143       mopac file=STRING
144           name of the mopac(1) input file
145
146       orca bin=STRING
147           path to orca(1) binary, will search PATH variable for binary if not
148           set
149
150       orca input line=STRING
151           input string used for orca(1) calculation, will use engrad runtyp
152           by default
153
154       orca input file=STRING
155           name of the orca(1) input file
156
157       turbodir=STRING
158           path to your Turbomole directory (usually found in TURBODIR or
159           TURBOIMG variable)
160
161   $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
168       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
173       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
178       freeze frequency=real
179           diagonal element used for freezing atoms in numerical Hessian
180           calculation
181
182       freeze: list,...
183           freezes all atoms in list for hessian calculation
184
185       shake: i,j,...
186           use SHAKE to constrain the atompair ij in molecular dynamics.
187
188   $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
194       ion_st=real
195           ion strength for salt screening in GBSA
196
197       ion_rad=real
198           ion radius for salt screening in GBSA
199
200       grid=level
201           changes the grid used for the surface accessable surface area
202           (normal, tight, vtight, extreme are available).
203
204   $gfn
205       method=int
206           version of the GFN Hamiltonian
207
208       dispscale=real
209           Scale dispersion energy of GFN-FF
210
211   $hess
212       sccacc=real
213           SCC accuracy level in Hessian runs
214
215       step=real
216           Cartesian displacement increment for numerical Hessian
217
218       scale=real
219           Scaling factor for the hessian elements (default: 1.0)
220
221       element mass: int,real,...
222           set mass of elements int to real
223
224       isotope: int,real,... (6.1 only)
225           set mass of atom number int to real
226
227       modify mass: int,real,... (6.1 only)
228           set mass of atom number int to real
229
230       scale mass: int,real,... (6.1 only)
231           scale mass of atom number int by real
232
233   $metadyn (6.1 only)
234       save=int
235           maximal number of structures for rmsd criteria
236
237       kpush=real,...
238           scaling factor for rmsd criteria can be positive and negative
239
240       modify factor=int,real,...
241           replace the factor int with real
242
243       scale factor=int,real,...
244           scales the factor int with real
245
246       alp=real
247           width of the Gaussian potential used in the rmsd criteria
248
249       coord=file
250           external structures to initialize the rmsd criteria (xmol format
251           required)
252
253       atoms: list,...
254           atoms to include in rmsd calculation, if not present all atoms are
255           taken into account
256
257       rmsd: real,...
258           target rmsd for biased hessian runs in Ångström
259
260       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
264       bias atoms: list,...
265           atoms to include in static rmsd calculation, if not present all
266           atoms are taken into account
267
268       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
273   $md
274       temp=real
275           MD thermostat/GBSA temperature
276
277       time=real
278           MD run time in ps
279
280       dump=real
281           dump structure in every dump fs
282
283       sdump=real
284           dump structure as scoord.<num> every sdump fs
285
286       velo=int
287           set to 1 if dumps (trj file) should contain velocities
288
289       nvt=int
290           use thermostat (=1, =0 for NVE)
291
292       skip=int
293           skip interval in -mdav, -mdopt
294
295       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
299       hmass=int
300           increase hydrogen mass to this value in amu (at const. tot. mass)
301           allowing large time steps (=0 off)
302
303       shake=int
304           shake on (=0: off which is default) for X-H bonds only (=1),
305
306       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
311   $modef
312       n=int
313           of points along normal mode path scan
314
315       step=real
316           step lengths for scan (should be around 1 because its adjusted
317           internally to mode mass and FC)
318
319       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
323       local=int
324           use canonical normal modes (=0) or Pipek-Mezey localized ones (=1)
325
326       vthr=real
327           threshold up to which frequency modes are used for mode based
328           conformer search (def. is 300)
329
330       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
334       mode=int
335           can set by --modef via cmdline
336
337   $opt
338       engine=method
339           method can be rf for ANCopt (default), lbfgs for L-ANCopt or
340           inertial for FIRE.
341
342       output=file
343           redirect output of optimization to file
344
345       logfile='file
346           write optimization log to file (default: xtbopt.log)
347
348       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
353       microcycle=int
354           number of optimization cycles before new ANC are made (default=25)
355
356       maxcycle=int
357           total number of opt. cycles, 0 means automatically determined
358
359       hlow=real
360           lowest force constant in ANC generation (should be > 0.005)
361
362       maxdispl=real
363           maximum coordinate displacement in ancopt(3)
364
365       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
370       s6=real
371           dispersion scaling in ANC generation
372
373       hessian=lindh-d2|lindh|swart
374           model hessian for generation of ANC used in optimization
375
376       kstretch=real
377           stretch force constant in model hessian
378
379       kbend=real
380           bend force constant in model hessian
381
382       ktorsion=real
383           torsion force constant in model hessian
384
385       koutofp=real
386           out-of-plain force constant to model hessian
387
388       kvdw=real
389           additional vdW-contribution (lindh|swart only)
390
391       kes=real
392           electrostatic contribution to model hessian by EEQ model
393
394       rcut=real
395           distance cutoff for bonds in model hessian
396
397   $path (6.1 only)
398       nrun=int
399           number of runs for pathfinder
400
401       nopt=int
402           number of points on the path to optimize
403
404       anopt=int
405           number of steps to optimize the points on the path
406
407       kpush=real
408           factor for RMSD criterium pushing away from the reactant structure
409
410       kpull=real
411           factor for RMSD criterium pulling towards the product structure
412
413       alp=real
414           width of the RMSD criterium
415
416       product=file
417           file name of the product structure
418
419   $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
426       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
432       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
438           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
443   $scc
444       temp=real
445           electronic temperature for the Fermi smearing
446
447       broydamp=real
448           damping for the Broyden convergence accelerator
449
450       guess=gasteiger|goedecker|sad
451           different possible guess charges for GFN2-xTB SCC calculation
452
453       maxiteration=int
454           adjusts the number of SCC iterations in the first/last SCC
455           calculation
456
457   $split
458       fragment1: list,...
459           defines atoms belonging to fragment 1
460
461       fragment2: list,...
462           defines atoms belonging to fragment 2
463
464       fragment: i,list,...
465           defines atoms belonging to fragment i
466
467   $stm (6.1 only)
468       activate by $write/stm=true
469
470       broadening=real
471           width of tip DOS energy broadening (eV)
472
473       current=real
474           constant current value (arb.u.)
475
476       grid=real
477           grid width (Bohr), half that value along Z
478
479       thr=real
480           integral and density matrix neglect threshold
481
482       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
486   $symmetry
487       desy=real
488           point group symmetrization threshold
489
490       maxat=int
491           point group determination skipped if # atoms > this value (i.e.
492           desymaxat 0 switches it off)
493
494   $thermo
495       temp=real
496           temperature for thermostatistical calculation (default: 298.15 K)
497
498       imagthr=real
499           threshold for inverting imaginary frequencies for thermo in cm-1
500           (default: -20.0)
501
502       scale=real
503           scaling factor for frequencies in vibrational partition function
504           (default: 1.0)
505
506       sthr=real
507           rotor cut-off (cm-1) in thermo  (default: 50.0)
508
509   $wall
510       potential=logfermi|polynomial
511           sets kind of wall potential used (default: polynomial)
512
513       alpha=int
514           exponent of polynomial wall potential (default: 30)
515
516       beta=real
517           exponent of logfermi bias potential (default: 6.0)
518
519       autoscale=real
520           scales axis of automatic determined wall potentials by real
521
522       axisshift=real
523           constant offset used in automatic dermined wall potential axis
524           (default: 3.5)
525
526       temp=real
527           temperature of the logfermi wall (default: 300.0 K), wall energy of
528           logfermi is multiplied with kT.
529
530       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
534       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
538   $write
539       esp=bool
540           calculate and print electrostatic potential, this will create a
541           data file and a cosmo file
542
543       gridfile=file
544           read gridpoints for ESP calculation from file.
545
546       mos=bool
547           print molden file
548
549       lmo=bool
550           localize orbitals and print out LMO centers
551
552       density=bool
553           calculate density on a cube grid
554
555       spin population=bool
556           spin population analysis
557
558       spin density=bool
559           calculate spin density on a cube grid
560
561       fod=bool
562           calculate FOD on a cube grid (set electronic temperature to at
563           least 12500 K)
564
565       wiberg=bool
566           calculate and print Wiberg bond order
567
568       dipole=bool
569           calculate and print dipole moment
570
571       charges=bool
572           print charges file
573
574       mulliken=bool
575           print mulliken population analysis
576
577       orbital energies=bool
578           print orbital energies and occupation numbers
579
580       stm=bool
581           creates an STM image of the molecule, see stm group (6.1 only)
582
583       geosum=bool
584           old style geometry summary
585
586       inertia=bool
587           geometry summary on moments on inertia and rotational constants
588           (available with --define)
589
590       distances=bool
591           geometry summary on distances and bonds (available with --define)
592
593       angles=bool
594           geometry summary on angles (available with --define)
595
596       torsions=bool
597           geometry summary on dihedral angles and torsions (available with
598           --define)
599
600       vib_normal_modes=bool
601           write normal modes as Turbomole vibrational modes data group
602
603       hessian.out=bool
604           write DFTB+ style hessian.out file containing the unprojected
605           hessian
606
607   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
613           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
619       broydamp
620           use broydamp in scc group instead
621
622       chrg, charge
623           use chrg logical instead
624
625       constrainallbo, constralltbo
626           currently not supported
627
628       constrainalltors, constralltors
629           currently not supported
630
631       constrain
632           use constrain group instead
633
634       constrainel
635           currently not supported
636
637       constrfc
638           use force constant in constrain group instead
639
640       constrxyz
641           use atoms in fix group instead
642
643       cube_cal
644           use cal in cube group instead
645
646       cube_pthr
647           use pthr in cube group instead
648
649       cube_step
650           use step in cube group instead
651
652       desymaxat
653           use maxat in symmetry group instead
654
655       desy
656           use desy in symmetry group instead
657
658       ellips
659           use ellipsoid in wall group instead
660
661       etemp
662           use temp in scc group instead
663
664       ex_open_HS
665           currently not supported
666
667       ex_open_LS
668           currently not supported
669
670       fit
671           use fit logical instead
672
673       fix
674           use atoms in fix/constrain group instead
675
676       fixfc
677           use force constant in constrain group instead
678
679       fragment1
680           use fragment1 in split group instead
681
682       fragment2
683           use fragment1 in split group instead
684
685       gbsa
686           use solvent in gbsa group instead
687
688       gfnver
689           use version in gfn group instead
690
691       hessa
692           currently not supported
693
694       hessf
695           use freeze in fix group instead
696
697       hlowopt
698           use hlow in opt group instead
699
700       ion_rad
701           use ion_rad in gbas group instead
702
703       ion_st
704           use ion_st in gbsa group instead
705
706       maxdispl
707           use maxdipl in opt group instead
708
709       maxopt
710           use maxcycle in opt group instead
711
712       mddumpxyz
713           use dump in md group instead
714
715       md_hmass
716           use hmass in md group instead
717
718       mdskip
719           use skip in md group instead
720
721       mdstep
722           use step in md group instead
723
724       mdtemp
725           use temp in md group instead
726
727       mdtime
728           use time in md group instead
729
730       microopt
731           use mircocycle in opt group instead
732
733       mode_local
734           use local in modef group instead
735
736       mode_n
737           use n in modef group instead
738
739       mode_prj
740           use prj in *modef group instead
741
742       mode_step
743           use step in modef group instead
744
745       mode_updat
746           use updat in modef group instead
747
748       mode_vthr
749           use vthr in modef group instead
750
751       nvt
752           use nvt in md group instead
753
754       optlev
755           use optlevel in opt group intead
756
757       orca_exe
758           currently not supported
759
760       orca_line
761           currently not supported
762
763       orca_mpi
764           currently not supported
765
766       restartmd, mdrestart
767           use restart in md group
768
769       runtyp
770           please use the commandline instead, might still work
771
772       s6opt
773           use s6 in opt group instead
774
775       samerand
776           use samerand logical instead
777
778       scan
779           use scan group instead
780
781       scchess
782           use sccacc in hess group instead
783
784       sccmd
785           use sccacc in md group instead
786
787       shake
788           use shake in md group instead
789
790       sphere
791           use sphere in sphere group instead
792
793       springexp
794           use springexp in fix group instead
795
796       stephess
797           use step in *hess group instead
798
799       thermo_sthr
800           use sthr in thermo group instead
801
802       thermo
803           use temp in thermo group instead
804
805       uhf
806           use uhf logical instead
807
808       velodump
809           use velo in md group instead
810

BUGS

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

RESOURCES

817       Main web site: http://grimme.uni-bonn.de/software/xtb
818

COPYING

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
824
825
826                                  2021-07-23                       XCONTROL(7)
Impressum