Szczepanik Research Group

Department of Theoretical Chemistry
Faculty of Chemistry, Jagiellonian University
Gronostajowa 2, 30-387 Krakow, Poland
Tel: (+48) 12 686 23 90
E-mail: dariusz.szczepanik@uj.edu.pl

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual


Manual (2026-Nov-03)

Give runEDDB a bare geometry (an X-ray structure, an MD snapshot, a hand-built model or a built-in molecule) and it computes the electronic structure itself with the semi-empirical GFN2-xTB method, then runs the whole analysis on it: EDDB, tables, maps, even NICS and ring currents. No other program is needed and a molecule of a hundred atoms takes about a second. This page describes the engine, how close its results come to DFT, its settings, and the magnetic response it provides.

1. What the engine does

Any geometry file (.xyz .mol .sdf .mol2 .pdb) or -i @NAME selects this lane; the file formats, charge and multiplicity are described on the Input files page. Under -v the stage lists its settings:

terminal
$ runEDDB -i @benzene -v
▶ Modelling one-electron density at the GFN2-xTB/vSTO-nG level...
    Hamiltonian model:                 GFN2-xTB
    Dispersion correction:             DFT-D4
    Initial guess:                     SAD
    Algorithm:                         SCC
    Maximum SCC iterations (MAXITER):  1500
    Convergence criterion (CONV):      1.00E-04 (max|dq|)
    Anisotropic electrostatics (AES):  Enabled
    Spin polarization (SP):            Disabled
    Fermi smearing (ETEMP):            Enabled (300 K)
    Effective core potential:          Yes (12 core electrons)
    Number of basis functions:         30 (vSTO-nG)
    Total energy:                      -15.87828 Eh  (6 SCC iterations)
    Electron population (Tr[D*S]):     30.00000

2. How close to DFT

The π delocalization of conjugated molecules comes out close to B3LYP. The same geometries through both lanes (B3LYP/def2-TZVPP wavefunctions; -a, CDI from -p along each ring):

MoleculeEDDBπ xTBEDDBπ B3LYPCDI xTBCDI B3LYP
benzene5.3495.2930.8890.880
naphthalene7.7287.5290.4020.406
anthracene (outer / central ring)11.03010.5780.325 / 0.4140.318 / 0.419
pyrene (the two ring types)13.09312.9280.338 / 0.4040.332 / 0.402
coronene (outer / central ring)18.19818.1620.390 / 0.4150.392 / 0.411
pyridine5.2855.2350.8180.799
pyrrole3.7433.6730.5930.583
thiophene2.9152.9910.4020.436
borazine3.8043.3790.2540.194

For hydrocarbons and azines the π populations agree within 4 % and the CDIs within 0.02, including the ring-by-ring pattern of fused systems. Polar π systems are less reliable: borazine is too delocalized by a third, thiophene slightly too little. The total EDDB (without -a) agrees within 6 %. Range-separated functionals localize the π electrons more than B3LYP, so against them the xTB values are higher. Use the lane for a survey (which atoms and rings take part, which pathways are worth a closer look) and confirm the numbers that matter with a DFT wavefunction through one of the other input lanes.

3. SCC settings and convergence

OptionEffect
--xtb-etemp K (300)electronic temperature of the Fermi smearing; 0 = integer occupations (strict Aufbau). The analysis density is always refilled with integer occupations.
--xtb-conv X (1e-4)convergence threshold on the largest change of the atomic charges
--xtb-maxiter N (1500)maximum number of SCC iterations
--xtb-noaesswitch off the anisotropic electrostatics: faster, but not EDDB grade
--xtb-frac-occexperimental diagnostic: keep the smeared fractional occupations in the analysis density (a deliberately non-idempotent density for testing the post-HF path, not for EDDB values)

The SCC runs once; if it does not converge the program stops and says what to change:

terminal
  ERROR: GFN2-xTB did not converge / failed (error code -6).
    To force convergence, adjust one or more GFN2-xTB controls and re-run:
      --xtb-etemp 1000     raise the electronic (Fermi smearing) temperature
      --xtb-maxiter 3000   allow more SCC iterations
      --xtb-conv 1e-3      loosen the SCC convergence threshold

4. Charged and open-shell molecules

The charge and multiplicity come from the file or from --xyz-charge / --xyz-mult (Input files). A multiplicity above 1 runs the spin-polarized variant spGFN2-xTB (unrestricted); --xtb-nospin gives the restricted open-shell solution instead.

terminal
$ runEDDB -i @benzene --xyz-charge 1 --xyz-mult 2 -v      # benzene radical cation
    Hamiltonian model:                 spGFN2-xTB
    Spin polarization (SP):            Enabled
$ runEDDB -i @benzene --xyz-charge 1 --xyz-mult 2 --xtb-nospin

5. Saving the xTB wavefunction

OptionFile
--export-fchk xtbmol.XTB.fchk: orbitals, orbital energies, density and spin density, for viewers and as an SCF starting guess of a DFT job
--export-json xtbmol.XTB.json (+ .meta.json): the same in the ORCA JSON convention, with real occupations and orbital energies
--export-cube xtb[LIST]cubes of the listed molecular orbitals (mol.XTB_orb001.cube, ...)

The files describe the minimal basis with an effective core: right for viewing and as a guess, not an all-electron wavefunction. More on the formats: Maps & files.

6. NICS and ring currents from xTB

Any --nics* option on a geometry computes the magnetic response from the xTB orbitals, with the full EDLB / EDDB partition, ring and bond currents, MO sets and maps (see NMR & currents for the commands). GFN2-xTB has no exact exchange, so its response to a magnetic field is uncoupled: a sum over states of the tight-binding orbitals, evaluated in the ipsocentric CTOCD-DZ gauge. This is London's tight-binding ring-current theory with all valence electrons. The minimal basis carries the π → π* excitations that make the ring current, but not the circulation around the nuclei, so nuclear shieldings are not computed and a --nics* probe is required.

The uncoupled current is too small. Benzene, the same geometry, ring current (nA/T) and NICS(1)zz (ppm):

LaneIcyc totalIcyc EDDBNICS(1)zz
xTB, uncoupled (default)6.306.35−17.3
xTB, uncoupled, EDDB × 1.6–10.16–
xTB, --xtb-coupled9.048.81−24.6
B3LYP/def2-TZVPP, NMR=CSGT11.979.98−29.7

NICS(1)zz is the NICS index to read from this lane. Its sign and the order of the rings within a molecule are right, but the raw values are about 40 % too small. Multiplied by 1.6 (the factor of the current) they come within 3 ppm of B3LYP for benzenoid rings and pyridine; --xtb-coupled gives a similar accuracy without a factor. Other rings are less reliable: the five-membered ring of azulene is 7–12 ppm too weak, pyrrole (a π-donor ring, below) a third. Same geometries, ppm:

RingxTBxTB × 1.6--xtb-coupledB3LYP/def2-TZVPP, CSGT
benzene−17.3−27.8−24.6−29.7
naphthalene−17.8−28.5−27.0−30.5
anthracene, central / outer ring−20.2 / −17.0−32.3 / −27.1−32.4 / −28.6−35.3 / −28.8
pyrene, the two ring types−21.0 / −11.0−33.6 / −17.6−32.9 / −18.8−36.7 / −19.2
pyridine−16.4−26.2−23.5−29.0
thiophene−21.3−34.1−27.8−30.0
pyrrole (π-donor N–H)−13.2−21.1−16.8−31.6
azulene, five / seven-membered ring−18.5 / −11.2−29.7 / −18.0−34.6 / −17.4−41.7 / −13.6
biphenylene, four-membered ring+38.4+61.4+77.7+56.7
Read before using the numbers. Read NICS(1)zz (scaled by 1.6, or from --xtb-coupled), NICS scans and the currents. Never read NICS(0), NICS(0)zz, isotropic NICS or nuclear shieldings from this lane: their in-plane σ terms near the nuclei are not described by the minimal basis. Never compare rings of different size by NICS (use the current).
  • Works: hydrocarbons, azines, borazine, thiophenes, thiazoles, tropylium; the ring order inside fused systems (pyrene, triphenylene, phenanthrene, porphine) is reproduced. Non-aromatic rings come out with small currents.
  • Rings with a π-donor N–H or O (pyrrole, furan, imidazole, the pyrrole rings of porphyrins) and anions: about 1.5× too small, coupled or not; tagged [pi-donor N-H/O] in the table. Sign and trend only.
  • 4n rings: the sign is right, the magnitude is not (too paratropic by up to 2×); the coupled response is unstable at ax = 0.2 and falls back to the uncoupled one with a WARNING (ax ≈ 0.1 works).

7. Cost

The SCC and the whole analysis take well under a second for the built-in kekulene (72 atoms), [12]cycloparaphenylene (120 atoms) and superazanaphthalene (128 atoms). More threads (-n) pay off only for several hundred atoms. The NICS response, the current maps and the ICSS maps cost more than the SCC; see NMR & currents.

8. Limits

9. Methods and references

MethodReference
GFN2-xTBC. Bannwarth, S. Ehlert, S. Grimme, J. Chem. Theory Comput. 15 (2019) 1652, doi:10.1021/acs.jctc.8b01176
DFT-D4 dispersionE. Caldeweyher, S. Ehlert, A. Hansen, H. Neugebauer, S. Spicher, C. Bannwarth, S. Grimme, J. Chem. Phys. 150 (2019) 154122, doi:10.1063/1.5090222
Spin-polarized GFN2-xTB (multiplicity > 1)H. Neugebauer, B. Bädorf, S. Ehlert, A. Hansen, S. Grimme, J. Comput. Chem. 44 (2023) 2120, doi:10.1002/jcc.27185
CTOCD-DZ (ipsocentric) responseP. Lazzeretti, M. Malagoli, R. Zanasi, Chem. Phys. Lett. 220 (1994) 299, doi:10.1016/0009-2614(94)00158-8
sTDA exchange kernel (--xtb-coupled)S. Grimme, J. Chem. Phys. 138 (2013) 244104, doi:10.1063/1.4811331
sTDA-xTB (--xtb-coupled)S. Grimme, C. Bannwarth, J. Chem. Phys. 145 (2016) 054103, doi:10.1063/1.4959605
← AFM / STM  |  Next: Options →

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual