XCONTROL(7)

📦
version 6.7.1 · 2 versions
, in fedora 43

💖 NAME 💖

okay so XCONTROL(7) is literally the instruction file for xtb(1) version 6.0 and newer. That's the whole vibe. 💅

✨ SYNOPSIS ✨

xtb -I,--input xcontrol FILE

🦋 DESCRIPTION 🦋

bestie, the xcontrol(7) instruction set is the glow-up successor of the set-block that lived in xtb(1) version 5.8 and earlier. The instruction set is similar to the data groups in Turbomole or the detailed input structure of ORCA. Every instruction starts with a flag ($) and ends when the next flag shows up. An instruction is only valid if the flag is in the first column, and the instruction name is the rest of the register. A valid instruction opens its blocks with its own options, and every option is a key-value pair. No cap.

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. Periodt.

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

Also lowkey important: xtb(1) is able to produce xcontrol(7) instructions by itself. You can tell xtb(1) by --copy to save your original instructions. Note that this implementation will strip all comments while copying (print what you see, not what you read), to aid debugging. fr fr.

$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.

bestie, “pure development feature” means do not bring this to a 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 💅

okay bestie this is THE glow-up group, the one where you tell xtb how to actually hunt down your minimum instead of just vibing at a random geometry. tons of knobs, all of them matter, let's go ✨

  • engine=method — which optimizer is driving the bus. method can be rf for ANCopt (that's the default), lbfgs for L-ANCopt, or inertial for FIRE. pick your fighter 🥊
  • output=file — redirects the output of the optimization into file instead of your terminal.
  • logfile='file — writes the optimization log to file. default is xtbopt.log 🍓
  • optlevel=level — convergence thresholds for ancopt(3). the whole ladder: crude = -3, sloppy = -2, loose = -1, normal = 0, tight = 1, verytight = 2, extreme = 3. yes there are seven of them, she's thorough 💅
  • microcycle=int — how many optimization cycles happen before fresh ANCs get made. default is 25.
  • maxcycle=int — total number of opt. cycles. 0 means it's automatically determined (i.e. let her cook 👩‍🍳).
  • hlow=real — lowest force constant in ANC generation. it should be > 0.005, no cap.
  • maxdispl=real — maximum coordinate displacement in ancopt(3).
  • average conv=bool — averages the energy and gradient before checking for convergence, which accelerates things on numerically noisy potential energy surfaces. default: false.
  • s6=real — dispersion scaling in ANC generation.
  • hessian=lindh-d2|lindh|swart — the model hessian used to generate the ANC for the optimization.
  • kstretch=real — stretch force constant in the model hessian.
  • kbend=real — bend force constant in the model hessian.
  • ktorsion=real — torsion force constant in the model hessian.
  • koutofp=real — out-of-plain force constant to the model hessian.
  • kvdw=real — additional vdW contribution (lindh|swart only).
  • kes=real — electrostatic contribution to the model hessian, courtesy of the EEQ model.
  • rcut=real — distance cutoff for bonds in the model hessian.
  • exact rf=bool — uses a better solver during the rational function optimization. treat yourself 💖

🧭 $path (6.1 only) 🧭

the pathfinder era, only a thing in 6.1. she's out here tracing reaction paths like it's a group chat read receipt.

  • nrun=int — number of runs for the 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 the RMSD criterium pushing away from the reactant structure.
  • kpull=real — factor for the RMSD criterium pulling towards the product structure.
  • alp=real — width of the RMSD criterium.
  • product=file — file name of the product structure.

🌀 $scan 🌀

slowly dragging a coordinate across the whole vibe, step by step 🌈

  • mode=sequential|concerted — scans all constraints at once (concerted) or one after another (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. iykyk.
  • 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. and unlike 5.8, there is no limitation in the number of steps. glow up fr.
  • 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. so like… be careful with your syntax, bestie, she's not forgiving here 😭

⚡ $scc ⚡

the self-consistent-field group, aka the main character of every single-point energy.

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

🧩 $split 🧩

for when your molecule is really several molecules in a trench coat and you need to say so.

  • 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) 🔬

scanning tunneling microscopy sim hours. activate it with $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 🦋

letting the molecule remember it's beautiful and symmetric.

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

🌡️ $thermo 🌡️

temperature stuff, frequencies stuff, the whole thermal vibe check.

  • 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 the vibrational partition function. default: 1.0.
  • sthr=real — rotor cut-off (cm-1) in thermo. default: 50.0.

🧱 $wall 🧱

walls!! we love a boundary condition. keeping your atoms from wandering off into the void 🫶

  • potential=logfermi|polynomial — sets the kind of wall potential used. default: polynomial.
  • alpha=int — exponent of the polynomial wall potential. default: 30.
  • beta=real — exponent of the logfermi bias potential. default: 6.0.
  • autoscale=real — scales the axis of automatically determined wall potentials by real.
  • axisshift=real — constant offset used in the automatic dermined wall potential axis. default: 3.5.
  • temp=real — temperature of the logfermi wall. default: 300.0 K. the wall energy of logfermi is multiplied with kT.
  • sphere: auto|real,all|list,... — sets 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,... — sets up an 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, a sphere potential is applied, no ellipsoid!!! 🚨
  • sandwich: auto|real,all|list,... — sets 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 📝

the output group, aka the "show me everything" group. files go brrr 🖨️

  • esp=bool — calculate and print electrostatic potential. this will create a data file and a cosmo file.
  • gridfile=file — read gridpoints for the 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 the 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 the 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 a DFTB+ style hessian.out file containing the unprojected hessian.

👵 LEGACY 👵

okay so for the old heads: to keep compatibility with versions of xtb(1) from before version 6.0, a group instruction set is allowed that accepts the same syntax as the original set-block. here's the whole 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 an 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! so like, migrate bestie, for real 😭
  • broydamp — use broydamp in the scc group instead
  • chrg, charge — use chrg logical instead
  • constrainallbo, constralltbo — currently not supported
  • constrainalltors, constralltors — currently not supported
  • constrain — use the constrain group instead
  • constrainel — currently not supported
  • constrfc — use force constant in the constrain group instead
  • constrxyz — use atoms in the fix group instead
  • cube_cal — use cal in the cube group instead
  • cube_pthr — use pthr in the cube group instead
  • cube_step — use step in the cube group instead
  • desymaxat — use maxat in the symmetry group instead
  • desy — use desy in the symmetry group instead
  • ellips — use ellipsoid in the wall group instead
  • etemp — use temp in the scc group instead
  • ex_open_HS — currently not supported
  • ex_open_LS — currently not supported
  • fit — use fit logical instead
  • fix — use atoms in the fix/constrain group instead
  • fixfc — use force constant in the constrain group instead
  • fragment1 — use fragment1 in the split group instead
  • fragment2 — use fragment1 in the split group instead
  • gbsa — use solvent in the gbsa group instead
  • gfnver — use version in the gfn group instead
  • hessa — currently not supported
  • hessf — use freeze in the fix group instead
  • hlowopt — use hlow in the opt group instead
  • ion_rad — use ion_rad in the gbas group instead
  • ion_st — use ion_st in the gbsa group instead
  • maxdispl — use maxdipl in the opt group instead
  • maxopt — use maxcycle in the opt group instead
  • mddumpxyz — use dump in the md group instead
  • md_hmass — use hmass in the md group instead
  • mdskip — use skip in the md group instead
  • mdstep — use step in the md group instead
  • mdtemp — use temp in the md group instead
  • mdtime — use time in the md group instead
  • microopt — use mircocycle in the opt group instead
  • mode_local — use local in the modef group instead
  • mode_n — use n in the modef group instead
  • mode_prj — use prj in *modef group instead
  • mode_step — use step in the modef group instead
  • mode_updat — use updat in the modef group instead
  • mode_vthr — use vthr in the modef group instead
  • nvt — use nvt in the md group instead
  • optlev — use optlevel in the opt group intead
  • orca_exe — currently not supported
  • orca_line — currently not supported</p> 💀 sorry bestie, it's just not a thing rn
  • orca_mpi — also currently not supported</p> 😭
  • restartmd, mdrestart — nah, use restart in the md group instead ✨
  • runtyp — please use the commandline instead, it might still work but like… don't count on it 🙈
  • s6opt — use s6 in the opt group instead 🎀
  • samerand — use the samerand logical instead 🦋
  • scan — use the scan group instead ⭐
  • scchess — use sccacc in the hess group instead 💅
  • sccmd — use sccacc in the md group instead 💅
  • shake — use shake in the md group instead 🌸
  • sphere — use sphere in the sphere group instead 🌈
  • springexp — use springexp in the fix group instead 🧚
  • stephess — use step in the *hess group instead 👑
  • thermo_sthr — use sthr in the thermo group instead 🔥
  • thermo — use temp in the thermo group instead 🌡️
  • uhf — use the uhf logical instead 💜
  • velodump — use velo in the md group instead 🍓

🐛 BUGS 🐛

ok so if you find a bug (and you will, it's software, it's giving humble 💀) please report it with:

  • an example input 🫶
  • a --copy dump of the internal settings 📋
  • the geometry you used 📐
  • and the --verbose output 📢

…and send all of that to xtb@thch.uni-bonn.de 💌

bestie, no cap, sending all four of those is the move — it's literally impossible to help you without them 😭

🌐 RESOURCES 🌐

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

📜 COPYING 📜

Copyright (C) 2015-2020 S. Grimme. This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). 💖

and that's the whole page, bestie!! 🎀✨ you made it to the end, which is honestly iconic of you 👑 this was XCONTROL(7) from 2025-09-15 — mwah 💅💖

📦 where this page comes from