xcontrol - Man Page

instruction file for `xtb(1)` version 6.0 and newer

The xcontrol(7) instruction set is the successor of the set-block present in xtb(1) version 5.8 and earlier. The used instruction set is similar to the data groups in Turbomole or the detailed input structure of ORCA. Every instruction is started by a flag ($) and terminated by the next flag. A instruction is only valid if the flag is in the first column, the instruction name is the rest of the register. A valid instruction opens its blocks with its own options, every option is a key-value pair.

There are two kind of instructions, logical and groups. Logical instructions toggle a specific operation and cannot contain a option block while group instructions only open the option block without any further actions.

A special instruction is the end instruction which is optional, as EOF is a valid alternative in this implementation.

It should be noted that xtb(1) is able to produce xcontrol(7) instructions by itself. You can tell xtb(1) by --copy to save you original instructions, note that this implementation will strip all comments while copying (print what you see, not what you read), to aid debugging.

$fit

logical instruction to set xtb(1) in mfit(1) compatibility mode and prints out further informations. This is a pure development feature and therefore should be absent in every productive run.

$samerand

logical instruction to initialize the random number generator with the same sequence

$chrg int

set the charge of the molecule

$spin int

set Nalpha-Nbeta of the molecule

$cma

shifts molecule to center of mass and transforms cartesian coordinates into the coordinate system of the principle axis (not affected by ‘isotopes’-file).

$constrain

Note

This data group refers to constraining the gradient by appling potentials. Exact fixing is done with the fix data group.

force constant=real: force constant for constraining potential
all bonds=bool: generate potentials to constrain the length of all bonds
all angles=bool: generate potentials to constrain all bond angles
all torsions=bool: generate potentials to constrain the angles of all torsions
elements: symbol|number,...: constrains all elements of the same type, the atom type is determined by the ordinal number or the element symbol
atoms: list,...: constrains the atom positions of all atoms in list. Needs at least two atoms since potential is applied on all atoms in list.
distance: i,j,auto|real: constrain the distance between atom i and j to the actual length (auto) or the value real, which has to be given in Ångström.
angle: i,j,k,auto|real: constrain the angle between atom i, j and k to the actual length (auto) or the value real, which has to be given in degrees.
dihedral: i,j,k,l,auto|real: constrain the angle between atom i, j, k and l to the actual length (auto) or the value real, which has to be given in degrees.
center: real,int: implemented and documented as in xtb 5.8, might use fragment1 information from split instruction.
cma[ interface]: auto|real: implemented and documented as in xtb 5.8, might use fragment1/fragment2 information from split instruction.
z: real: implemented and documented as in xtb 5.8, might use fragment1 information from split instruction.

$cube

step=real: grid spacing for cube file
pthr=real: density matrix neglect threshold
boff=real: grid boundary offset (default: 3.0)

cal=int

=1 switches on cube-file output (=0 means writing molden file instead, -1=do nothing)

$embedding

at=int: default atom type for point charges
es=bool: use isotropic electrostatic with point charges
input=file: point charges are read from file (default: pcharge), format is: q x y z [iat|gam], where q is the partial charges, xyz are the position of the partial charge in bohr and iat is the ordinal number of the atom. The corresponding gam-Parameter of the element will be used in the potential. Alternatively the gam value can be given directly as fifth argument, to simulate point charges provide a huge value for gam.
gradient='file: gradient of the point charges is written to file (default: pcgrad)

$external

mopac bin=STRING: path to mopac(1) binary, will search PATH variable for binary if not set
mopac input=STRING: input string used for mopac(1) calculation, make sure it generates an aux file for xtb(1) to read in.
mopac file=STRING: name of the mopac(1) input file
orca bin=STRING: path to orca(1) binary, will search PATH variable for binary if not set
orca input line=STRING: input string used for orca(1) calculation, will use engrad runtyp by default
orca input file=STRING: name of the orca(1) input file
turbodir=STRING: path to your Turbomole directory (usually found in TURBODIR or TURBOIMG variable)

$fix

Note

the fix group refers to exact fixing. For geometry optimizations the gradient is set to zero, while for Hessians no displacements are calculated. Constraining with external potentials is done by the constrain data group.

elements: symbol|number,...: fixes all elements of the same type, the atom type is determined by the ordinal number or the element symbol. This is automatically deactivated for molecular dynamics since it leads to instabilities.
atoms: list,...: fixes all atoms in list by setting the gradient to zero. This is automatically deactivated for molecular dynamics since it leads to instabilities.
freeze frequency=real: diagonal element used for freezing atoms in numerical Hessian calculation
freeze: list,...: freezes all atoms in list for hessian calculation
shake: i,j,...: use SHAKE to constrain the atompair ij in molecular dynamics.

$gbsa

solvent=string: solvent for the generalized born (GB) model with solvent accessable surface area (SASA), requires .param_gbsa.solvent in XTBPATH. Does not activate GBSA (use commandline).
ion_st=real: ion strength for salt screening in GBSA
ion_rad=real: ion radius for salt screening in GBSA
grid=level: changes the grid used for the surface accessable surface area (normal, tight, vtight, extreme are available).

$gfn

method=int: version of the GFN Hamiltonian
dispscale=real: Scale dispersion energy of GFN-FF

$hess

sccacc=real: SCC accuracy level in Hessian runs
step=real: Cartesian displacement increment for numerical Hessian
scale=real: Scaling factor for the hessian elements (default: 1.0)
element mass: int,real,...: set mass of elements int to real
isotope: int,real,... (6.1 only): set mass of atom number int to real
modify mass: int,real,... (6.1 only): set mass of atom number int to real
scale mass: int,real,... (6.1 only): scale mass of atom number int by real

$metadyn (6.1 only)

save=int: maximal number of structures for rmsd criteria
kpush=real,...: scaling factor for rmsd criteria can be positive and negative
modify factor=int,real,...: replace the factor int with real
scale factor=int,real,...: scales the factor int with real
alp=real: width of the Gaussian potential used in the rmsd criteria
coord=file: external structures to initialize the rmsd criteria (xmol format required)
atoms: list,...: atoms to include in rmsd calculation, if not present all atoms are taken into account
rmsd: real,...: target rmsd for biased hessian runs in Ångström
bias input=file: read static bias from file, requires xyz format with factor and width of the potential in the comment line
bias atoms: list,...: atoms to include in static rmsd calculation, if not present all atoms are taken into account
bias elements: id,...: elements to include in static rmsd calculation, if not present all atoms are taken into account. Elements can be referenced by their element symbol or their atomic number.

$md

temp=real: MD thermostat/GBSA temperature
time=real: MD run time in ps
dump=real: dump structure in every dump fs
sdump=real: dump structure as scoord.<num> every sdump fs
velo=int: set to 1 if dumps (trj file) should contain velocities
nvt=int: use thermostat (=1, =0 for NVE)
skip=int: skip interval in -mdav, -mdopt
step=real: MD time step in fs (automatically determined if < 0), could be 4-5 fs with shake =2, md_hmass=4
hmass=int: increase hydrogen mass to this value in amu (at const. tot. mass) allowing large time steps (=0 off)
shake=int: shake on (=0: off which is default) for X-H bonds only (=1),
sccacc=real: SCC accuracy level in MD. Every 10th step the SCC is properly converged at sccconv=1.0. sccmd should be < 5 in critical cases, effects may show up as bad thermostating
forcewrrestart=logical: forces the writing of a restart file at each dump step

$modef

n=int: of points along normal mode path scan
step=real: step lengths for scan (should be around 1 because its adjusted internally to mode mass and FC)
updat=real: update search mode with a fraction of the displacement at every step (0.0 means no update, 0.1-0.2 is a good choice)
local=int: use canonical normal modes (=0) or Pipek-Mezey localized ones (=1)
vthr=real: threshold up to which frequency modes are used for mode based conformer search (def. is 300)
prj=int: number of second mode which should be projected out in mode following (normally = 7 ie the TS mode which is fixed then)
mode=int: can set by --modef via cmdline

$oniom

inner logs=bool: to print optimization log files for model region geometry (high.inner_region.log and low.inner_region.log)
derived k=bool: to calculate prefactor k and create jacobian dynamically (see more )
ignore topo=bool: to bypass topology check when breaking bonds
outer=bool: to saturate outer region
silent=bool: to hide the execution runs of external software

$opt

engine=method: method can be rf for ANCopt (default), lbfgs for L-ANCopt or inertial for FIRE.
output=file: redirect output of optimization to file
logfile='file: write optimization log to file (default: xtbopt.log)
optlevel=level: convergence thresholds for the ancopt(3): crude = -3, sloppy = -2, loose = -1, normal = 0, tight = 1, verytight = 2, extreme = 3
microcycle=int: number of optimization cycles before new ANC are made (default=25)
maxcycle=int: total number of opt. cycles, 0 means automatically determined
hlow=real: lowest force constant in ANC generation (should be > 0.005)
maxdispl=real: maximum coordinate displacement in ancopt(3)
average conv=bool: average the energy and gradient before checking for convergence to accelerate numerically noisy potential energy surfaces (default: false).
s6=real: dispersion scaling in ANC generation
hessian=lindh-d2|lindh|swart: model hessian for generation of ANC used in optimization
kstretch=real: stretch force constant in model hessian
kbend=real: bend force constant in model hessian
ktorsion=real: torsion force constant in model hessian
koutofp=real: out-of-plain force constant to model hessian
kvdw=real: additional vdW-contribution (lindh|swart only)
kes=real: electrostatic contribution to model hessian by EEQ model
rcut=real: distance cutoff for bonds in model hessian
exact rf=bool: use better solver during the rational function optimization

$path (6.1 only)

nrun=int: number of runs for pathfinder
nopt=int: number of points on the path to optimize
anopt=int: number of steps to optimize the points on the path
kpush=real: factor for RMSD criterium pushing away from the reactant structure
kpull=real: factor for RMSD criterium pulling towards the product structure
alp=real: width of the RMSD criterium
product=file: file name of the product structure

$scan

mode=sequential|concerted

scans all constraints at once (concerted) or after each other (sequential). in sequential mode the final value of the scanned constraint is kept in place. in concerted mode all steps for the scans have to be the same.

int: start,end,steps

where start and end are real values and steps is an integer value. Defines a scan along constraint int (which has to be defined before, of course), from start to end in a certain number of steps. There is no limitation in the number of steps as in 5.8.

name: values; start,end,steps

defines the constrain name on which the scan is performed. See above and the the constrain group for more information, since name (e.g. distance) and values (e.g. i,j,value) are handed internally to the constrain parser.
Note

the scan parser will always terminate in error if the instruction could not be parsed correctly, while the constrain parser is able to skip instructions with wrong input by raising a warning.

$scc

temp, etemp=real: electronic temperature for the Fermi smearing
broydamp=real: damping for the Broyden convergence accelerator
guess=gasteiger|goedecker|sad: different possible guess charges for GFN2-xTB SCC calculation
iterations, maxiterations=int: adjusts the number of SCC iterations in the first/last SCC calculation

$split

fragment1: list,...

defines atoms belonging to fragment 1

fragment2: list,...

defines atoms belonging to fragment 2

fragment: i,list,...

defines atoms belonging to fragment i

$stm (6.1 only)

activate by $write/stm=true
broadening=real: width of tip DOS energy broadening (eV)
current=real: constant current value (arb.u.)
grid=real: grid width (Bohr), half that value along Z
thr=real: integral and density matrix neglect threshold
potential=real: potential of tip vs. molecule, negative values let e flow from mol to tip i.e. occ space of mol is probed

$symmetry

desy=real: point group symmetrization threshold
maxat=int: point group determination skipped if # atoms > this value (i.e. desymaxat 0 switches it off)

$thermo

temp=real: temperature for thermostatistical calculation (default: 298.15 K)
imagthr=real: threshold for inverting imaginary frequencies for thermo in cm-1 (default: -20.0)
scale=real: scaling factor for frequencies in vibrational partition function (default: 1.0)
sthr=real: rotor cut-off (cm-1) in thermo (default: 50.0)

$wall

potential=logfermi|polynomial: sets kind of wall potential used (default: polynomial)
alpha=int: exponent of polynomial wall potential (default: 30)
beta=real: exponent of logfermi bias potential (default: 6.0)
autoscale=real: scales axis of automatic determined wall potentials by real
axisshift=real: constant offset used in automatic dermined wall potential axis (default: 3.5)
temp=real: temperature of the logfermi wall (default: 300.0 K), wall energy of logfermi is multiplied with kT.
sphere: auto|real,all|list,...: set up a spherical wall potential for all or the atoms in list with the radius real or an automatical determined sphere radius
ellipsoid: auto|real,auto|real,auto|real,all|list,...: set up a ellipsoid wall potential for all or the atoms in list with the radii real or an automatical determined sphere radius If auto is chosen for axes, sphere potential is applied, no ellipsoid!!!
sandwich: auto|real,all|list,...: set up a sandwich wall potential for all or the atoms in list with the radius real or an automatical determined sandwich radius in Bohr Only potential=logfermi ist available. diameter=2*radius+2*4A safety buffer

$write

esp=bool: calculate and print electrostatic potential, this will create a data file and a cosmo file
gridfile=file: read gridpoints for ESP calculation from file.
mos=bool: print molden file
lmo=bool: localize orbitals and print out LMO centers
density=bool: calculate density on a cube grid
spin population=bool: spin population analysis
spin density=bool: calculate spin density on a cube grid
fod=bool: calculate FOD on a cube grid (set electronic temperature to at least 12500 K)
wiberg=bool: calculate and print Wiberg bond order
dipole=bool: calculate and print dipole moment
charges=bool: print charges file
mulliken=bool: print mulliken population analysis
orbital energies=bool: print orbital energies and occupation numbers
stm=bool: creates an STM image of the molecule, see stm group (6.1 only)
geosum=bool: old style geometry summary
inertia=bool: geometry summary on moments on inertia and rotational constants (available with --define)
distances=bool: geometry summary on distances and bonds (available with --define)
angles=bool: geometry summary on angles (available with --define)
torsions=bool: geometry summary on dihedral angles and torsions (available with --define)
vib_normal_modes=bool: write normal modes as Turbomole vibrational modes data group
hessian.out=bool: write DFTB+ style hessian.out file containing the unprojected hessian

Legacy

To ensure compatibility with older versions of the xtb(1) prior to version 6.0 a group instruction set is allowed which accepts the same syntax as the original set-block. Here we provide a list of set-block commands and their corresponding instructions in xcontrol(7).

Note

xtb(1) can read a set-block by itself and will print out a equivalent instruction set. This feature will be deprecated in future versions since the set-block is less flexible than xcontrol(7) and might be deactived without prior announcement!

broydamp: use broydamp in scc group instead
chrg, charge: use chrg logical instead
constrainallbo, constralltbo: currently not supported
constrainalltors, constralltors: currently not supported
constrain: use constrain group instead
constrainel: currently not supported
constrfc: use force constant in constrain group instead
constrxyz: use atoms in fix group instead
cube_cal: use cal in cube group instead
cube_pthr: use pthr in cube group instead
cube_step: use step in cube group instead
desymaxat: use maxat in symmetry group instead
desy: use desy in symmetry group instead
ellips: use ellipsoid in wall group instead
etemp: use temp in scc group instead
ex_open_HS: currently not supported
ex_open_LS: currently not supported
fit: use fit logical instead
fix: use atoms in fix/constrain group instead
fixfc: use force constant in constrain group instead
fragment1: use fragment1 in split group instead
fragment2: use fragment1 in split group instead
gbsa: use solvent in gbsa group instead
gfnver: use version in gfn group instead
hessa: currently not supported
hessf: use freeze in fix group instead
hlowopt: use hlow in opt group instead
ion_rad: use ion_rad in gbas group instead
ion_st: use ion_st in gbsa group instead
maxdispl: use maxdipl in opt group instead
maxopt: use maxcycle in opt group instead
mddumpxyz: use dump in md group instead
md_hmass: use hmass in md group instead
mdskip: use skip in md group instead
mdstep: use step in md group instead
mdtemp: use temp in md group instead
mdtime: use time in md group instead
microopt: use mircocycle in opt group instead
mode_local: use local in modef group instead
mode_n: use n in modef group instead
mode_prj: use prj in *modef group instead
mode_step: use step in modef group instead
mode_updat: use updat in modef group instead
mode_vthr: use vthr in modef group instead
nvt: use nvt in md group instead
optlev: use optlevel in opt group intead
orca_exe: currently not supported
orca_line: currently not supported
orca_mpi: currently not supported
restartmd, mdrestart: use restart in md group
runtyp: please use the commandline instead, might still work
s6opt: use s6 in opt group instead
samerand: use samerand logical instead
scan: use scan group instead
scchess: use sccacc in hess group instead
sccmd: use sccacc in md group instead
shake: use shake in md group instead
sphere: use sphere in sphere group instead
springexp: use springexp in fix group instead
stephess: use step in *hess group instead
thermo_sthr: use sthr in thermo group instead
thermo: use temp in thermo group instead
uhf: use uhf logical instead
velodump: use velo in md group instead

xcontrol - Man Page

Synopsis

Description

$fit

$samerand

$chrg int

$spin int

$cma

$constrain

$cube

$embedding

$external

$fix

$gbsa

$gfn

$hess

$metadyn (6.1 only)

$md

$modef

$oniom

$opt

$path (6.1 only)

$scan

$scc

$split

$stm (6.1 only)

$symmetry

$thermo

$wall

$write

Legacy

Bugs

Resources

Copying

Referenced By