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)

runEDDB splits the electron density of a molecule into the part that stays localized on atoms and in two-centre bonds (EDLB) and the part that is delocalized over the bond system (EDDB). From that split it measures conjugation, resonance and aromaticity, and it carries the same split into NMR shieldings, ring currents and microscopy images. This page takes you from installation to your first results in a few minutes.

1. Install

Download the package for your system from the Download page, unpack it and run the installer (install.sh on Linux and macOS, install.bat on Windows); the Installation section there gives the details. runEDDB is a single executable with no runtime libraries. Check that it works:

terminal
$ runEDDB --help              # short help and the list of help topics

2. The first run

You do not need any input file to start: runEDDB carries a small library of molecules (-i @list shows it) and computes their electronic structure with its built-in GFN2-xTB engine.

terminal
$ runEDDB -i @benzene
▶ Loading built-in molecular model...                                                 0s
▶ Modelling one-electron density at the GFN2-xTB/vSTO-nG level...                     0s
▶ Building natural atomic orbitals (NAO, frozen-NMB two-cycle)...                     0s
▶ Performing multicenter bond-orbital projections (BOP)...                            0s
▶ Computing natural orbitals for bond delocalization (NOBD)...                        0s
▶ Printing summary of EDDB calculations:

        Total   ED_G population:           30.00000    per atom:     2.50000
        Total EDLB_G population:           24.19916    per atom:     2.01660
        Total EDDB_G population:            5.80084    per atom:     0.48340

The stages show what runEDDB does: it builds natural atomic orbitals (NAO), projects the density onto the bonds between them (bond-order projection, BOP), and finds the natural orbitals of the delocalized density (NOBD). The summary then reads:

LineMeaningBenzene
ED_Gall electrons in the analysis basis (default: the valence shells, so the core electrons are not counted)30 = 6 × 4 (C) + 6 × 1 (H)
EDLB_Gelectrons localized on atoms and in two-centre bonds24.2
EDDB_Gelectrons delocalized over the bond system; ED = EDLB + EDDB5.8

The suffix _G is the scope: G = the whole molecule (global). Other scopes look at a fragment, a pathway or rings (section 4).

3. The π electrons only

Aromaticity is mostly a π-electron story. -a selects the π-type natural orbitals of bond delocalization automatically and repeats the analysis for them alone:

terminal
$ runEDDB -i @benzene -a
        Total   ED_G population:            6.00000    per atom:     0.50000
        Total EDLB_G population:            0.65090    per atom:     0.05424
        Total EDDB_G population:            5.34910    per atom:     0.44576

Of the six π electrons of benzene 5.35 are delocalized: almost the whole π system. In the non-aromatic, tub-shaped cyclooctatetraene, with its alternating single and double bonds, only 1.18 of the eight π electrons are (runEDDB -i @rings/cot -a).

4. Rings and pathways

In a larger molecule you usually ask about one ring or one conjugation pathway. -r finds the rings of the given sizes and analyses their bonds (scope R); -p takes a pathway of atom numbers (scope P):

terminal
$ runEDDB -i @naphthalene -r 6 -a        # both six-membered rings, pi only
        Total   ED_R population:           10.00000    per atom:     1.00000
        Total EDLB_R population:            3.06882    per atom:     0.30688
        Total EDDB_R population:            6.93118    per atom:     0.69312
$ cat naphthalene.rings                  # the rings found, one -p string per line
1-2-3-4-9-10-1
4-5-6-7-8-9-4
$ runEDDB -i @naphthalene -p 1-2-3-4-9-10-1 -a      # one ring

The EDDB analysis page explains every scope, the selection of orbitals and the choice of the analysis basis.

5. Your own molecule

There are two ways in:

A geometry only (.xyz, .mol, .sdf, .mol2, .pdb, e.g. from a crystal structure or a drawing program): runEDDB computes the electronic structure with GFN2-xTB in seconds. Good for a first look; confirm important findings with DFT.
runEDDB -i molecule.xyz -a
A wavefunction from your quantum-chemistry program (.fchk, .json, .molden, .tmol, .gms): runEDDB analyses your DFT or post-HF density as it is.
runEDDB -i molecule.fchk -a

The Input files page says which file each program writes and which keywords it needs.

6. Help in the program

The program documents itself, by topic, with ready-to-run examples on the built-in molecules:

terminal
$ runEDDB --help                # the essential options and the list of topics
$ runEDDB --help nmr            # everything about one topic
$ runEDDB --examples nmr        # commands to try, with one line on what each shows
$ runEDDB --help full           # the complete reference

Topics: input, eddb, tables, export, nmr, afm, xtb, runtime. The Tutorials show complete studies step by step.

7. Four things to know

8. Methods and references

runEDDB lists the papers behind every run for you: add --cite both to write them to <stem>.bib and <stem>.refs.txt. The core methods are:

MethodReference
Natural atomic orbitals (NAO) and natural population analysisA.E. Reed, R.B. Weinstock, F. Weinhold, J. Chem. Phys. 83 (1985) 735, doi:10.1063/1.449486
Bond-order projection (BOP), alwaysD.W. Szczepanik, E.J. Zak, K. Dyduch, J. Mrozek, Chem. Phys. Lett. 593 (2014) 154, doi:10.1016/j.cplett.2014.01.006
EDDB / EDLB partition of the density, alwaysD.W. Szczepanik, Comput. Theor. Chem. 1080 (2016) 33, doi:10.1016/j.comptc.2016.02.003
Natural orbitals for bond delocalization (NOBD; -a, -s)D.W. Szczepanik, M. Andrzejak, K. Dyduch, E.J. Zak, M. Makowski, G. Mazur, J. Mrozek, Phys. Chem. Chem. Phys. 16 (2014) 20514, doi:10.1039/c4cp02932a
EDDB of pathways, fragments and rings (-p, -f, -r); EDDB as an aromaticity measureD.W. Szczepanik, M. Andrzejak, J. Dominikowska, B. Pawełek, T.M. Krygowski, H. Szatylowicz, M. Solà, Phys. Chem. Chem. Phys. 19 (2017) 28970, doi:10.1039/c7cp06114e
Three-centre orbital projection in EDDBD.W. Szczepanik, Comput. Theor. Chem. 1100 (2017) 13, doi:10.1016/j.comptc.2016.12.003
Review: EDDB as a measure of local and global aromaticityD.W. Szczepanik, M. Solà, in Aromaticity: Modern Computational Methods and Applications, ed. I. Fernández (Elsevier, 2021), ch. 8, doi:10.1016/b978-0-12-822723-7.00008-x
Bond-delocalization field (BDF)D.W. Szczepanik, P.A. Wieczorkiewicz, ACS Phys. Chem. Au (2026), doi:10.1021/acsphyschemau.6c00031
Frozen-NMB construction of the NAOs (the default)D.W. Szczepanik, J. Comput. Chem. (2026), in preparation
GFN2-xTB with DFT-D4 (built-in engine)C. Bannwarth, S. Ehlert, S. Grimme, J. Chem. Theory Comput. 15 (2019) 1652, doi:10.1021/acs.jctc.8b01176; E. Caldeweyher et al., J. Chem. Phys. 150 (2019) 154122, doi:10.1063/1.5090222

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual