Skip to content

xtb

GFN xTB is a method of self-consistent, third-order, density functional tight-binding (DFTB3), suitable for the calculation of structures, vibrational frequencies, and non-covalent interactions in large molecular systems. A key feature of this model is that it almost entirely avoids element-pair-wise parameterisation. The GFN1 parameterisation consequently covers all spd-block elements and the lanthanides, up to Z = 86, using reference data at the hybrid density functional theory level.

The original model was developed by Stefan Grimme, Christoph Bannwarth and Philip Shushkov, and can found in J. Chem. Theory Comput., 2017, 13(5), pp 1989–2009

A GFN xTB calculation can be run using the following example:

xtb(
  structure(formula = HLi bond_length = 1.0 angstrom)
)
This command can appear in the global context.

Subcommands

Options

broyden_damping

Factor of new shell-resolved charges to be used in Broyden mixing: [ q_{n+1} = f * q_{n} + ... ] where \( f \) is the factor.

  • The type is real
  • The default is 0.4
broyden_small_gap

Value of HOMO-LUMO gap (in hartree) to switch to using broyden_small_gap_damping.

  • The type is real
  • The default is 0.001
broyden_small_gap_damping

Damping factor of new shell-resolved charges used in Broyden mixing when the HOMO-LUMO gap is less than broyden_small_gap.

  • The type is real
  • The default is 0.05
charge

Total molecular charge. No constraint is imposed, but clearly the value has to be such that for a given molecule the number of electrons is nonnegative, and that the number of electrons does not exceed the number that can be described with the given atomic-orbital basis. Note that non-integer values are possible as well.

This option is deprecated. Please use the charge option inside structure instead.

This option is deprecated.

  • The type is real
  • There is no default value.
charge_rms_threshold

Convergence threshold for RMS change of shell charges.

  • The type is real
  • The default is 1e-5
check_fock_norm

Check the norm of the Fock matrix against the numerical derivative of the energy before starting SCF. Only for debugging purposes.

  • The type is bool
  • The default is false
check_molecule

Check the molecule doesn't have any known problematic atoms.

  • The type is bool
  • The default is true
diis

Method of DIIS.

diis_max

Maximum number of vectors for DIIS.

  • The type is int
  • The default is 10
  • The value must be nonnegative
diis_shift

Diagonal shift for regularization of DIIS.

  • The type is real
  • The default is 0
  • The value must be nonnegative
diis_switch_threshold_grad

In DIIS modes ADIIS+CDIIS and EDIIS+CDIIS the algorithm is switched to CDIIS if the gradient falls below this threshold.

  • The type is real
  • The default is 1e-1
  • The value must be nonnegative
dispersion_cutoff

Cut-off for summation over unit cells in dispersion correction

  • The type is quantity
  • The default is 40.0 bohr
energy_threshold

SCF convergence threshold using the absolute value of the energy difference between iterations.

  • The type is real
  • The default is 1e-6
  • The value must be nonnegative
ewald_alpha

Broadening parameter for Gaussian screening of point charges in Ewald treatment of second and third order terms of xTB Hamiltonian. This effectively determines the relative contributions of real-space and reciprocal-space terms in the Ewald sum. As \(\alpha\) is increased, ewald_real_cutoff should be decreased, while ewald_reciprocal_cutoff should be increased. By default, entos determines this from ewald_real_cutoff and ewald_relative_error, using the expression: \( \alpha = \frac{1}{r_c} \bigg[ W \bigg( \frac{Q}{E}\sqrt{\frac{r_c}{2V}} \bigg) \bigg]^{1/2}, \) where \(r_c\) is the ewald_real_cutoff, \(E\) is the ewald_relative_error, \( Q = \sum^{N_{atoms}}_{i=1} q_i^2 \), \(\{q_i\}\) are atomic partial charges of neutral atoms, \(W\) is the Lambert W function, and \(V\) is the system volume. This approximation is not guaranteed to give ideal results, but it works fairly well for most systems. Further details can be found in A comparison of the Spectral Ewald and Smooth Particle Mesh Ewald methods in GROMACS.

  • The type is real
  • There is no default value.
ewald_real_cutoff

Real-space cut-off over unit cells in Ewald sum.

  • The type is quantity
  • The default is 10.0 bohr
ewald_reciprocal_cutoff

Reciprocal-space cut-off over k-vectors in Ewald sum. By default, entos determines this from ewald_real_cutoff and ewald_relative_error, using the expression: \( k_c = \frac{\sqrt{3} L \alpha}{2 \pi} \bigg[ W \bigg( \frac{4}{3L^2} \bigg(\frac{Q^2}{\pi \alpha E^2}\bigg)^{2/3} \bigg) \bigg]^{1/2} \) where \(\alpha\) is the ewald_alpha, \(E\) is the ewald_relative_error, \( Q = \sum^{N_{atoms}}_{i=1} q_i^2 \), \(\{q_i\}\) are atomic partial charges of neutral atoms, \(W\) is the Lambert W function, and \(L\) is the average system length. This approximation is not guaranteed to give ideal results, but it works fairly well for most systems. Further details can be found in A comparison of the Spectral Ewald and Smooth Particle Mesh Ewald methods in GROMACS.

  • The type is real
  • There is no default value.
ewald_relative_error

Approximate relative error in both the real-space and reciprocal-space terms of the Ewald sum. This should not be set if the user wishes to manually specify ewald_reciprocal_cutoff and ewald_alpha.

  • The type is real
  • The default is 1.e-8
fixed_shell_charges

Specify a list of fixed, shell-resolved partial charges. This results in a non-self-consistent calculation, for which the SCF driver will perform two iterations confirming no change in the charge density.

Using this option with the fixed shell charges set to zero corresponds to doing a non-self-consistent calculation with only the core Hamiltonian.

  • The type is [real]
  • There is no default value.
fock_damping

Amount of previous Fock matrix to use in Fock damping. The new Fock matrix for iteration \( n \): \( F_{n} = (1-\alpha) F_{n} + \alpha F_{n-1} \) where \( \alpha \) is the fock_damping_factor.

  • The type is real
  • The default is 0.8
fock_damping_gradient_threshold

XTB Fock matrix extrapolation is initially performed using a damping (see fock_damping). When the largest element of the absolute orbital gradient drops below fock_damping_gradient_threshold, DIIS will be used.

  • The type is real
  • The default is 0.2
guess

Initial guess for the xTB wavefunction.

  • The type is string
  • The default is SAD
  • The value must be one of:
    • SAD - Superposition of Atomic Densities (SAD).
    • H0 - Using eigenvectors of the core Hamiltonian as the initial guess. This is equivalent to setting the initial density to zero.
    • eeq - Use EEQ charges as the initial guess.
guess

Initial guess for the SCF wavefunction.

  • The type is string
  • The default is SAD
  • The value must be one of:
    • SAD - Superposition of Atomic Densities (SAD).
    • H0 - Using eigenvectors of the core Hamiltonian as the initial guess. This is equivalent to setting the initial density to zero.
h0_cutoff

Cut-off for summation over unit cells in H0

  • The type is quantity
  • The default is 10.0 bohr
initial_charges

Specify the list of atom resolved partial charges.

  • The type is [real]
  • There is no default value.
initial_shell_charges

Specify a list of initial shell-resolved partial charges.

  • The type is [real]
  • There is no default value.
k_point

Specify a point in the reciprocal lattice.

  • The type is (real, real, real)
  • There is no default value.
level_shift

Turn on level shifting to improve SCF convergence. Raises the energy of virtual orbitals by level shifting value. Whether to remove the level shift at the end is controlled by option remove_level_shift.

  • The type is real
  • The default is 0
  • The value must be nonnegative
load

Name of assigned result (containing orbitals) to start the SCF from.

  • The type is string
  • There is no default value.
max_iter

Maximum number of SCF iterations.

  • The type is int
  • The default is 128
  • The value must be nonnegative
model

Specify the xTB model. When gfn0 is used, setting solver = non_iterative is recommended.

  • The type is string-lowered
  • The default is gfn1
  • The value must be one of:
    • gfn0
    • gfn1
monkhorst_pack

Size of Monkhorst-Pack grid for sampling reciprocal space. The Monkhorst-Pack grid is implemented in accordance with https://doi.org/10.1103/PhysRevB.13.5188. All grids are centred on the Gamma point. An odd choice of integers includes the Gamma point in the grid, whereas an even choice of integers does not.

  • The type is (int, int, int)
  • There is no default value.
n_primitives

Number of primitive Gaussians per shell. This setting is only used if use_reference_basis is false

  • The type is int
  • The default is 6
  • The value must be one of:
    • 4
    • 5
    • 6
name

Specify the name of a set of results.

This option is deprecated.

  • The type is string
  • There is no default value.
no_fail

If set to true, the program will continue its execution even if the SCF does not converge. This is useful for frozen-orbital calculations.

  • The type is bool
  • The default is false
number_type

Number type for orbitals and operators, whether real or complex.

  • The type is string
  • The default is real
  • The value must be one of:
    • real - Use real numbers for orbital coefficents and fock matrices.
    • complex - Use complex numbers for orbitals coefficents and fock matrices.
orbital_grad_threshold

SCF convergence threshold using the infinity norm of the orbital gradient.

  • The type is real
  • The default is 1e-5
  • The value must be nonnegative
overlap_cutoff

Cut-off for summation over unit cells in overlap matrix

  • The type is quantity
  • The default is 10.0 bohr
overlap_screening_threshold

Value below which overlap matrix elements are considered negligible and are therefore set to zero

  • The type is real
  • The default is 1.e-10
potential_type

Treatment of the second-order potential in periodic GFN1-xTB

  • The type is string-lowered
  • There is no default value.
  • The value must be one of:
    • truncated - Achieve convergence in the real-space summation by smoothly forcing the potential: $$ \delta \phi^{xTB}{Al, Bl’}(|\mathbf{R}|) = \sum_\mathbf{T} f(|\mathbf{R}{AB}+\mathbf{T}|) \left( \left(\frac{1}{|\mathbf{R}+\mathbf{T}|^2 + \eta^{-2}{Al,Bl'}} \right)^{1/2} -\frac{1}{ |\mathbf{R} + \mathbf{T}|} \right), $$ to zero at a pairwise-dependent cut-off, where \((A,B)\) are atomic indices, \((l,'l)\) are shell indices, \(\mathbf{T}\) is a translation vector and \(f(|\mathbf{R}_{AB}+\mathbf{T}|)\) is a polynomial used to send \(\delta \phi^{xTB}\) to zero. The polynomial is defined as: $$ f(|\mathbf{R}|) = -6R^5 + 15R^4 - 10R^3 + 1, $$ which follows the treatment of CP2K (see their xtb_coulomb.F module). One notes that truncating the real-space sum will affect the final energies.
    • full - Define the damped xTB real-space potential as: $$ \delta \phi^{xTB}{Al, Bl’}(|\mathbf{R}|) = \sum_\mathbf{T} \left(\frac{1}{|\mathbf{R}{AB}+\mathbf{T}|^2 + \eta^{-2}} \right)^{1/2} -\frac{1}{ |\mathbf{R}{AB} + \mathbf{T}|} +\frac{1}{2 \eta^2 |\mathbf{R}_{AB} + \mathbf{T}|^3}, $$ and treat the \(+1/r\) and \(-1/r^3\) terms with standard Ewald summations.
print_basis

Print basis information.

  • The type is bool
  • The default is false
print_level

Print level.

  • The type is int
  • There is no default value.
  • The value must be one of:
    • -2 - No output
    • -1 - Minimum output
    • 0 - Output that doesn't scale with system size
    • 1 - Output that scales linearly with system size
    • 2 - (Debugging) output that scales quadratically with system size
    • 3 - (Debugging) output that scales cubically with system size
pseudo_diagonalization

Whether to use pseudo-diagonalization instead of full diagonalization of the Fock matrix. Recommended for calculations on very large systems or with a very large basis.

  • The type is bool
  • The default is false
remove_level_shift

Remove level shift from final orbitals.

  • The type is bool
  • The default is true
repulsive_cutoff

Cut-off for summation over unit cells in repulsive energy

  • The type is quantity
  • The default is 10.0 bohr
scramble_complex

Add noise to the imaginary part of the guess density while keeping it hermitian. This option is only used if number_type = complex.

  • The type is bool
  • The default is true
scramble_complex_density_only

Scramble only the initial density (leaving the orbitals unchanged) in complex orbital calculations. Use scramble_complex to scramble the density and orbitals.

The change in the guess density implies a change in the guess orbitals and/or occupation numbers which are needed for orbital-dependent potentials. To obtain the adapted orbitals and occupations, the density must be diagonalized, which may be expensive. Usually, most parts of the potential are calculated directly from the density and scrambling in these parts is sufficient to break the symmetry. Thus, one may be able to achieve symmetry-breaking even when the orbitals and occupations are left unchanged.

  • The type is bool
  • The default is false
scramble_parameter

The amount of noise that is added to the imaginary part of the guess density. This option is only relevant if scramble_complex is true.

  • The type is real
  • The default is 1e-5
smoothing_range

If potential_type is set to truncated, define the range over which the potential is smoothly forced to zero. The default of 1 bohr is consistent with CP2K.

  • The type is quantity
  • The default is 1 bohr
solver

Type of solver to use for determining the density and orbitals. The default is automatically set depending on the xTB model.

  • The type is string-lowered
  • There is no default value.
  • The value must be one of:
    • scf - Perform a standard self-consistent field calculation
    • scc - Perform a self-consistent charge calculation with Broyden mixing
    • non_iterative - Perform a non-iterative (single diagonalization) calculation
symmetry_reduction

Use symmetry to reduce the number of k-grid sampling points via point group operations. This reduces the number of xtb calculations to perform.

  • The type is bool
  • The default is true
temperature

Specify the temperature for the electrons and perform the SCF calculation in the canonical-ensemble. Convergence is often poor with the default convergence settings, and using the original Pulay DIIS method is recommended (see diis option).

  • The type is quantity
  • The default is 300 kelvin
use_atomization_correction

Include atomization energy correction in total energy and gradient

  • The type is bool
  • The default is false
use_reference_basis

This utilises 4 primitives for H 1s shell, 7 primitives for H 2s shell, 4 primitives for He 1s. For Z > 2, 6 primitives are used per s or p shell and 4 primitives for d shells. The number of primitives is consistent with the basis used by the GFN1 binary (available upon request from Stefan Grimme's group).

  • The type is bool
  • The default is true
version

Version of xtb. Deprecated - please use model instead.

This option is deprecated.

  • The type is string-lowered
  • There is no default value.
  • The value must be one of:
    • gfn0
    • gfn1