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)

The core of runEDDB: it splits the electron density into the part localized on atoms and in two-centre bonds (EDLB) and the part delocalized over the bond system (EDDB). You choose where to look (the whole molecule, a fragment, a pathway or rings), which electrons (all, or the π component), and in which orbital basis the populations are counted. This page shows each choice with an example and explains the tables the program can print.

1. Where to look: the scope

The scope decides which bonds enter the analysis. The wavefunction is always the whole molecule; only the populations, tables and cubes are restricted. The scope letter appears in every result (EDDB_G, EDDB_F, ...).

OptionScopeExample
-g (default)G: the whole molecule, every bonded atom pairrunEDDB -i @naphthalene
-hH: the whole molecule without the bonds to hydrogen (cleaner π selection, less C–H hyperconjugation; faster)runEDDB -i @naphthalene -h
-f LISTF: the bonds within a set of atomsrunEDDB -i @naphthalene -f 1:4,9,10 -a
-p CHAINP: only the listed bonds, in order; repeat the first atom to close a cyclerunEDDB -i @naphthalene -p 1-2-3-4-9-10-1 -a
-r SIZESR: the bonds of every ring of the given sizes, found automaticallyrunEDDB -i @coronene -r 6 -a
terminal
$ runEDDB -i @naphthalene -r 6 -a
$ cat naphthalene.rings
1-2-3-4-9-10-1
4-5-6-7-8-9-4
$ grep -v '^#' naphthalene.rings | while read -r r; do runEDDB -i @naphthalene -p "$r" -a -q; done

Under a restricted scope every density (EDDB, EDLB and BDF) is built only on the selected atoms, so the per-atom tables, the totals and the cube integrals agree with each other.

2. Pathways and the CDI

A closed pathway (-p with the first atom repeated) also gives the cyclic delocalization index (CDI): the smallest EDDB population on any atom of the cycle, i.e. the largest number of electrons per atom that can delocalize uniformly all around it. A CDI near 0.9 per atom (π) marks a strongly aromatic ring, near 0 a non- or antiaromatic one: benzene 0.89 (runEDDB -i @benzene -p 1-2-3-4-5-6-1 -a), tub-shaped cyclooctatetraene 0.03 (runEDDB -i @rings/cot -p 1-2-3-4-5-6-7-8-1 -a). With a π dissection two fractions follow:

terminal
$ runEDDB -i @naphthalene -p 1-2-3-4-9-10-1 -a
        Total   ED_P population:            5.98843    per atom:     0.99807
        Total EDLB_P population:            2.53388    per atom:     0.42231
        Total EDDB_P population:            3.45455    per atom:     0.57576

    Cyclic Delocal. Index (CDI):            0.40233
    Delocalized fraction (%del):              57.69 %
    Cyclic coherence (%cyc):                  40.31 %
LineMeaning
CDIthe smallest per-atom EDDB_P along the cycle
%delEDDB_P / ED_P: the delocalized fraction of the π electrons of the pathway
%cycN × CDI / ED_P: the part that is delocalized coherently around the whole cycle, limited by its weakest atom

The gap between %del and %cyc is delocalization that does not close the cycle ("islands"). In naphthalene the fusion atoms 4 and 9 share their π electrons with both rings, so each ring has %del = 58 % but %cyc = 40 %. The two fractions are printed only under -a or -s, where ED_P is a π population.

3. Which electrons: the π component

The delocalized density is diagonalised into natural orbitals for bond delocalization (NOBDs); each has an occupation (its share of EDDB) and an s/p/d/f character. Selecting some of them restricts every result to those orbitals.

terminal
$ runEDDB -i @benzene --table nobd
    Index  Sel   Occupancy    s (l=0)  %s    p (l=1)  %p    d (l=2)  %d    f (l=3)  %f
         1  *      1.78309     0.00000  0     1.78309 100    0.00000  0     0.00000  0
         2  *      1.78303     0.00000  0     1.78303 100    0.00000  0     0.00000  0
         3  *      1.78298     0.00000  0     1.78298 100    0.00000  0     0.00000  0
         4  *      0.05096     0.01287  25    0.03809  75    0.00000  0     0.00000  0
         ...
$ runEDDB -i @benzene -s 1:3          # the three pi NOBDs = what -a picks here
Check the selection on non-planar molecules. The π test needs a locally planar framework. On a puckered ring -a may pick σ-mixed orbitals, or all of them: on the force-field model @rings/cyclobutadiene it selects all eight non-zero NOBDs. Look at --table nobd and use -s when in doubt.

4. Analysis tables

By default runEDDB prints only the summary. Tables are requested with --table LIST (comma separated) and are printed in a fixed order before the summary.

TokenTable
nobdNOBDs: occupation, s/p/d/f character, selection star
npaper atom: natural charge, population ED and its delocalized part EDDB
moper canonical MO: energy, occupation, ED / EDLB / EDDB (HF/DFT input)
bobond-order orbitals: the Wiberg bond order of every pair resolved into σ, π, δ, φ components
ao, subshell, shellpopulations per NAO (2px), per subshell (2p) or per shell (2 = 2s + 2p)
nonatural orbitals: occupation and its core / valence / Rydberg composition
allevery applicable table
terminal
$ runEDDB -i @benzene --table nobd,npa
$ runEDDB -i @benzene --table bo
$ runEDDB -i mol.fchk --table no -v     # + multireference indices in the -v block
Details of the tables
  • npa: the charge is q = Zeff − NA with the full natural population, correct with ECPs and on the GFN2-xTB lane; computed from the undissected density. Open shells have α and β columns.
  • mo: printed before the dissection, so it describes the full density; shows which orbitals carry the delocalized density (e.g. the π set).
  • bo: one row per atom pair: the first orbital index (matching --export-fchk bo), the total Wiberg bond order and the largest components with their σ/π/δ/φ label. The total equals the full bond order only with -b nao (benzene C–C 1.440 vs 1.418 in the default basis); the π share is practically the same. On large molecules use it with -f/-p/-r: the bond-order orbitals are then built only for the selected pairs. -v writes the complete balance to <stem>.NBA_DIAG.csv.
  • ao / subshell / shell: the ao index matches --export-fchk ao 1:1; the shell table shows the Rydberg population ladder at a glance.
  • no: with -v the multireference indices follow: Yamaguchi y0 biradical index, Bofill–Pulay and Head-Gordon unpaired-electron indices, and ⟨S2⟩ spin contamination for open shells, each with its DOI.
  • The closing line counts the warnings of the run, also under -q: Calculation completed (with 1 warning!); rerun without -q to read them.

5. The analysis basis (-b)

Populations are counted in natural atomic orbitals (NAOs), which come in three shells: core, valence and Rydberg. -b picks which of them are analysed:

ValueNAOsUse
nvb (default)valencestandard for aromaticity and bonding studies; fastest
nmbcore + valence (natural minimal basis)the legacy default; the only choice for NBO .49 files
naoall (core + valence + Rydberg)completeness check; nvb and nmb usually agree with it within a few per cent

Which atom pairs are analysed does not depend on -b: the bond connectivity is always taken from the full NAO basis, so a series nvb / nmb / nao differs only in the density, never in the set of bonds. For correlated densities the layers of natural orbitals are also always formed in the full basis.

6. Bond-order thresholds

OptionDefaultDecides
-w X (--wbo-thresh)0.001which atom pairs enter the analysis. Deliberately loose: it keeps hyperconjugation, weak hydrogen bonds and through-space contacts. Results are comparable only between runs at the same value; keep the default unless you study the threshold itself.
--ring-thresh X0.30which bonds count as covalent when -r searches for rings. Raise it to suppress rings closed through weak contacts, lower it (e.g. 0.15) to catch a ring closed by a weak bond. Changes nothing else.

-w 0 keeps every pair (N(N−1)/2): fine for small molecules, expensive for large ones (benzene 51 → 66 pairs, a 59-atom RNA fragment 260 → 1711); combine it with a scope.

7. NAO construction

The NAOs are built by runEDDB itself. --nao-algorithm chooses the construction; the default suits every use, and the others exist for comparisons and special studies.

AlgorithmWhat it is
frozen-nmb (default)the core and valence NAOs are built on a per-atom, angular-momentum-truncated density and frozen, the Rydberg space is built around them. Well conditioned at any basis size; atomic populations agree with rigorous within 0.001 e up to cc-pV5Z and stay symmetric where the standard construction breaks down (cc-pV6Z).
rigorousthe standard NBO-style construction, directly comparable with NBO 7 and the published NPA literature (nbo7legacy is an alias)
cc-layersRydberg space built shell layer by shell layer in Dunning's correlation-consistent order, with monotonic radial occupations; for truncated virtual spaces in correlated calculations (--table shell shows the layers)
ano-layers, iano-layersthe same layers with directions from tabulated atomic natural orbitals (built-in ano-pV5Z, H–Ar, or --ano-basis FILE); iano-layers builds the minimal basis as intrinsic atomic orbitals

Only for native input; .49 files carry NBO's own NAOs. The header of an exported NAO file records which construction made it. Full option list: runEDDB --help eddb.

Why the default changed (large basis sets and orbital viewers)

In strongly polarized basis sets (cc-pVQZ and beyond) the textbook NAOs are stored as large, near-cancelling coefficient expansions over high-angular-momentum shells and neighbouring atoms. The orbitals in space stay localized and the populations stable, but most viewers (Avogadro2, IQmol) render the exported orbitals as delocalized artefacts, and the charges lose numerical conditioning at cardinal number 5 and above. The frozen-NMB construction has no such coefficients by construction. For pictures of the rigorous NAOs prefer orbital cubes (--export-cube ao[LIST]) or --export-lproj.

8. Reproducibility

Within one compilation a run repeated with the same number of threads gives the same digits every time; a different -n may change the last printed digit of the EDLB / EDDB columns (the order of the sums changes). For bit-identical numbers state the compilation date (printed in the banner) and -n; -n 1 is the reference. Later compilations may change numbers slightly; every such change is listed in the changelog with its scale. Archival compilations are available from the author on request by e-mail.

9. Methods and references

MethodReference
Natural atomic orbitals, natural population analysisA.E. Reed, R.B. Weinstock, F. Weinhold, J. Chem. Phys. 83 (1985) 735, doi:10.1063/1.449486
Frozen-NMB NAO construction (default)D.W. Szczepanik, J. Comput. Chem. (2026), in preparation
Bond-order projection (BOP)D.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 partitionD.W. Szczepanik, Comput. Theor. Chem. 1080 (2016) 33, doi:10.1016/j.comptc.2016.02.003
NOBDs and their dissection (-a, -s)D.W. Szczepanik et al., Phys. Chem. Chem. Phys. 16 (2014) 20514, doi:10.1039/c4cp02932a
EDDB of fragments, pathways and rings; CDID.W. Szczepanik et al., Phys. Chem. Chem. Phys. 19 (2017) 28970, doi:10.1039/c7cp06114e
Orbital-resolved EDDB (--table ao)D.W. Szczepanik, M. Solà, ChemistryOpen 8 (2019) 219, doi:10.1002/open.201900014
ANO guide of ano-layersF. Neese, E.F. Valeev, J. Chem. Theory Comput. 7 (2011) 33, doi:10.1021/ct100396y
Intrinsic atomic orbitals (iano-layers)G. Knizia, J. Chem. Theory Comput. 9 (2013) 4834, doi:10.1021/ct400687b

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual