Parameter file

The tblite parameter files are written in TOML. Each major contribution to the energy is specified in its own table. The presence of the table enables the contribution in the method. The parameters are splitted in global and element specific parameters, global parameters are specified in the respective method table, while element specific parameters are collected together in the element records. The exception are the optional element pairwise parameters for the scaling of the Hamiltonian elements which are specified in the Hamiltonian section.

TOML quickstart

Note

This guide will only cover the aspects of TOML relevant for representing the parameter file in this project. For an extensive guide on TOML visit its homepage.

We choose TOML to represent our parameter files since it produces both human and machine readable files and has good support over all major progamming languages. TOML is a configuration file format, which allows to represent data in tables, arrays and values. Values can have data types of integer, boolean, real, and string.

Note

Integers do not cast implicitly to real numbers in TOML, make sure to actually specify a real number in the parametrization file if a real is required. Some TOML parsers offer an implicit conversion but this behaviour is not generally available in standard-compliant TOML parser.

Tables are specified by headers enclosed in brackets, nesting is represented by dots in the header name.

[hamiltonian]
# ...
[hamiltonian.xtb]
# ...
[hamiltonian.xtb.kpair]
# ...

The toplevel header is optional as long as the table only contains other tables, the hamiltonian header can be left away without changing the data structure. Small tables can be represented by inline tables with curly braces:

[dispersion]
d4 = {sc=true, s8=2.70, a1=0.52, a2=5.00, s9=5.00}

The above structure is equivalent to

[dispersion.d4]
s6 = 1.00
s8 = 2.70
a1 = 0.52
a2 = 5.00
s9 = 5.00
sc = true

Arrays can be created by using brackets after a key

[element.C]
shells = [ "2s", "2p" ]
levels = [ -13.970922, -10.063292 ]
slater = [ 2.096432, 1.80 ]
ngauss = [ 4, 4 ]
refocc = [ 1.0, 3.0 ]
# ...

Note

In TOML 0.5.0 arrays were constrained to equivalent data only, this restriction was lifted in TOML 1.0.0. In this format no mixed data arrays are required, which allows the usage of TOML 0.5.0 compliant parsers as well, if no updated library is available yet.

For libraries to handle TOML documents visit the TOML wiki.

Meta section

The meta section allows to specify data describing the parametrization, like the name of the method, the version of the parametrization and the format used to specify it as well as relevant publications for this parametrizations. Only the data type of the entries is checked and whether the format version is supported by the library. The current format version is 1, specifying a higher version will result in an error.

meta section example for GFN2-xTB

[meta]
format = 1
name = "GFN2-xTB"
version = 1
reference = "DOI: 10.1021/acs.jctc.8b01176"

Allowed entries:

Keyword	Description	Type
format	version of the parameter file format	integer
name	name of the parametrization	string
version	version of the parametrization data	integer
reference	relevant publications for this parameters	string

Hamiltonian section

The Hamiltonian section is used to declare the details of the used Hamiltonian. Currently, only xTB type Hamiltonians can be declared in the xtb subtable.

Hamiltonian section example for GFN2-xTB

[hamiltonian.xtb]
wexp = 0.5
enscale = 2.0e-2
cn = "gfn"
shell = {ss=1.85, pp=2.23, dd=2.23, sd=2.0, pd=2.0}

Pair parameters can be specified for all elements of the element records. Specifying an X-Y entry implies the Y-X entry and only one will be read and used since the pair parameters cannot be asymetric. The default value is one for each pair.

Start of the GFN1-xTB kpair table

[hamiltonian.xtb.kpair]
H-H = 0.96
H-B = 0.95
H-N = 1.04
N-Si = 1.01
B-P = 0.97
Sc-Sc = 1.10
Sc-Ti = 1.10
# ...

Note

The kpair section can be used to tune the Hamiltonian to better describe certain bonding situations. The suitable range parameters is close to one and large deviations from unity will create an instable Hamiltonian.

Allowed entries:

Keyword	Description	Type	Unit
wexp	scaling from slater exponents	real	dimensionless
enscale	scaling from EN difference	real	dimensionless
cn	CN type for selfenergy shift	string
shell	shell-specific scaling	table of reals	dimensionless
kpair	pairwise scaling for elements	table of reals	dimensionless

Dispersion section

The dispersion section supports the d4 subtable for DFT-D4 type dispersion corrections and the d3 subtable for DFT-D3 type dispersion corrections. The rational (Becke–Johnson) damping scheme is always used.

Self-consistent D4 dispersion section

[dispersion]
d4 = {sc=true, s8=2.70, a1=0.52, a2=5.00, s9=5.00}

Allowed entries:

Keyword	Description	Type	Unit
s6	scaling for C6 dispersion terms	real	dimensionless
s8	scaling for C8 dispersion terms	real	dimensionless
a1	scaling of critical radius	real	dimensionless
a2	offset for critical radius	real	Bohr
s9	scaling for triple-dipole terms	real	dimensionless
sc	use self-consistent dispersion	logical

Repulsion section

The xTB repulsion term can be specified in the effective subtable.

Repulsion for GFN1-xTB

[repulsion]
effective = {kexp=1.5}

Allowed entries:

Keyword	Description	Type	Unit
kexp	exponent for repulsion	real	dimensionless
klight	exponent for light atom pairs	real	dimensionless

Halogen section

The GFN1-xTB specific halogen bonding correction can be specified in the classical subtable.

Halogen bonding correction

[halogen]
classical = {rscale=1.3, damping=0.44}

Allowed entries:

Keyword	Description	Type	Unit
rscale	scaling parameter for radii	real	dimensionless
damping	damping parameter	real	dimensionless

Charge section

The Klopman–Ohno parametrized electrostatic model is available with the effective subtable, while the DFTB γ-functional electrostatic can be enabled with the gamma subtable. Only one electrostatic model can be active at a time.

Klopman–Ohno electrostatic

The gam parameter in the element records is used as atomic Hubbard parameters and scaled with the lgam parameter to obtain shell-resolved values. The exponent of the kernel can be modified as well as the averaging scheme for the Hubbard parameters. Available averaging schemes are arithmetic (GFN2-xTB), harmonic (GFN1-xTB) and geometric. The electrostatic is always constructed shell-resolved.

Isotropic electrostatic for GFN2-xTB

[charge]
effective = {gexp=2.0, average="arithmetic"}

Allowed entries:

Keyword	Description	Type	Unit
gexp	exponent of kernel	real	dimensionless
average	averaging scheme	string

DFTB γ-functional electrostatic

The gam parameter in the element records is used as Hubbard parameter and scaled with the lgam parameter to obtain shell-resolved values. The electrostatic is always constructed shell-resolved.

Isotropic electrostatic for DFTB

[charge]
gamma = {}

Thirdorder section

An on-site thirdorder charge is supported, to use atomic Hubbard derivatives the shell keyword can be set to false, while for shell-resolved Hubbard derivatives the scaling parameters for the respective shells have to specified. The highest specified angular momentum is implicitly used for all but absent higher momenta.

On-site shell-resolved third-order contribution

[thirdorder]
shell = {s=1.00, p=0.50, d=0.25}

Important

While the following setup uses the atomic Hubbard derivative for all shells

[thirdorder]
shell.s = 1.0

it is fundamentally different from using an atom-resolved third-order model.

Multipole section

The anisotropic electrostatic of GFN2-xTB can be enabled using the damped subtable. It requires five parameters to setup the damping function to reduce the short-range contributions from the multipole electrostatics.

Damped multipole electrostatic for GFN2-xTB

[multipole]
damped = {dmp3=3.0, dmp5=4.0, kexp=4.0, shift=1.2, rmax=5.0}

Allowed entries:

Keyword	Description	Type	Unit
dmp3	damping for quadratic terms	real	dimensionless
dmp5	damping for cubic terms	real	dimensionless
kexp	exponent for multipole radii	real	dimensionless
shift	shift for valence CN value	real	dimensionless
rmax	maximum multipole radius	real	dimensionless

Element records

The main body of the parameter file contains of element records. The parameters here are used to initialize contributions from the tables other tables, but are collected in the element records for easy usage. Most keywords require entries, even if the respective contribution is not used in the method.

Note

Each record is identified by its symbol, which allows to have multiple parameter sets for the same element. Input elements which do not match any symbol, will use the parametrization of the first element record with the same atomic number. To ensure that the right element is used as fallback an ordered dictionary is recommended to represent the element records.

Hydrogen and carbon records for GFN2-xTB

[element.H]
shells = [ "1s" ]
levels = [ -10.707211 ]
slater = [ 1.23 ]
ngauss = [ 3 ]
refocc = [ 1.0 ]
kcn = [ -5.0e-2 ]
gam = 0.405771
lgam = [ 1.0 ]
gam3 = 0.08
zeff = 1.105388
arep = 2.213717
en = 2.20
dkernel = 5.563889e-2
qkernel = 2.7431e-4
mprad = 1.4
mpvcn = 1.0

[element.C]
shells = [ "2s", "2p" ]
levels = [ -13.970922, -10.063292 ]
slater = [ 2.096432, 1.80 ]
ngauss = [ 4, 4 ]
refocc = [ 1.0, 3.0 ]
kcn = [ -1.02144e-2, 1.61657e-2 ]
gam = 5.38015e-1
lgam = [ 1.0, 1.1056358 ]
gam3 = 1.50e-1
zeff = 4.231078
arep = 1.247655
en = 2.55
dkernel = -4.11674e-3
qkernel = 2.13583e-3
mprad = 3.0
mpvcn = 3.0

Allowed entries:

Keyword	Description	Type	Unit
shells	included valence shells	array of strings	dimensionless
levels	atomic self-energies	array of reals	eV
slater	exponents of basis functions	array of reals	1/Bohr²
ngauss	number of STO-NG primitives	array of integers	dimensionless
refocc	reference occupation of atom	array of reals	Unitcharge
kcn	CN dependent self-energy shift	array of reals	eV
shpoly	polynomial enhancement factor	array of reals	dimensionless
gam	atomic Hubbard parameter	real	Hartree/Unitcharge²
lgam	relative shell hardness	array of reals	dimensionless
gam3	atomic Hubbard derivative	real	Hartree/Unitcharge³
zeff	effective nuclear charge	real	Unitcharge
arep	repulsion exponent	real	dimensionless
dkernel	on-site dipole kernel	real	Hartree
qkernel	on-site quadrupole kernel	real	Hartree
mprad	critical multipole radius	real	Bohr
mpvcn	multipole valence CN	real	dimensionless
xbond	halogen bonding strength	real	Hartree
en	atomic electronegativity	real	dimensionless