Parameter file
Contents
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 standardcompliant 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]
format = 1
name = "GFN2xTB"
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.xtb]
wexp = 0.5
enscale = 2.0e2
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 XY entry implies the YX entry and only one will be read and used since the pair parameters cannot be asymetric. The default value is one for each pair.
[hamiltonian.xtb.kpair]
HH = 0.96
HB = 0.95
HN = 1.04
NSi = 1.01
BP = 0.97
ScSc = 1.10
ScTi = 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 
shellspecific scaling 
table of reals 
dimensionless 
kpair 
pairwise scaling for elements 
table of reals 
dimensionless 
Dispersion section#
The dispersion section supports the d4 subtable for DFTD4 type dispersion corrections and the d3 subtable for DFTD3 type dispersion corrections. The rational (Becke–Johnson) damping scheme is always used.
[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 tripledipole terms 
real 
dimensionless 
sc 
use selfconsistent dispersion 
logical 
Repulsion section#
The xTB repulsion term can be specified in the effective subtable.
[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 GFN1xTB specific halogen bonding correction can be specified in the classical subtable.
[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 shellresolved values. The exponent of the kernel can be modified as well as the averaging scheme for the Hubbard parameters. Available averaging schemes are arithmetic (GFN2xTB), harmonic (GFN1xTB) and geometric. The electrostatic is always constructed shellresolved.
[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 shellresolved values. The electrostatic is always constructed shellresolved.
[charge]
gamma = {}
Thirdorder section#
An onsite thirdorder charge is supported, to use atomic Hubbard derivatives the shell keyword can be set to false, while for shellresolved 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.
[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 atomresolved thirdorder model.
Multipole section#
The anisotropic electrostatic of GFN2xTB can be enabled using the damped subtable. It requires five parameters to setup the damping function to reduce the shortrange contributions from the multipole electrostatics.
[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.
[element.H]
shells = [ "1s" ]
levels = [ 10.707211 ]
slater = [ 1.23 ]
ngauss = [ 3 ]
refocc = [ 1.0 ]
kcn = [ 5.0e2 ]
gam = 0.405771
lgam = [ 1.0 ]
gam3 = 0.08
zeff = 1.105388
arep = 2.213717
en = 2.20
dkernel = 5.563889e2
qkernel = 2.7431e4
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.02144e2, 1.61657e2 ]
gam = 5.38015e1
lgam = [ 1.0, 1.1056358 ]
gam3 = 1.50e1
zeff = 4.231078
arep = 1.247655
en = 2.55
dkernel = 4.11674e3
qkernel = 2.13583e3
mprad = 3.0
mpvcn = 3.0
Allowed entries:
Keyword 
Description 
Type 
Unit 

shells 
included valence shells 
array of strings 
dimensionless 
levels 
atomic selfenergies 
array of reals 
eV 
slater 
exponents of basis functions 
array of reals 
1/Bohr² 
ngauss 
number of STONG primitives 
array of integers 
dimensionless 
refocc 
reference occupation of atom 
array of reals 
Unitcharge 
kcn 
CN dependent selfenergy 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 
onsite dipole kernel 
real 
Hartree 
qkernel 
onsite 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 