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       Quick Start       Manual


◼ Manual (2026-Aug-15)

Table of Contents
→ New here? Start with the Quick Start page

1. Introduction
2. Generating Input Files
3. Analysis Modes
4. Command-Line Reference
5. Output Files
6. Differential Maps
7. Understanding the Output
8. Known Issues and Limitations
9. Performance Tips
10. Citations
11. Contact

1. Introduction

runEDDB implements the Electron Density of Delocalized Bonds (EDDB) method and the corresponding electron-density partitioning schemes. The present release is a complete rewrite in Fortran 2008 of the original runEDDB R-script. Thanks to a modern linear-algebra backbone (BLAS-3 DGEMM, DSYGVD, DSYEVD, DPOSV, CGS2, etc.), the program now processes systems containing thousands of atoms on a single workstation in seconds to minutes. It is distributed as ready-to-run, pre-compiled binaries for all three major desktop platforms — Linux (x86_64), Windows (x86_64), and macOS (arm64). See the Download page for the current release and per-platform installation instructions.

The Bond-Order Projection (BOP) algorithm at the heart of EDDB requires the input wavefunction to be expressed in a basis of compact, valence-localized atomic orbitals with a hierarchical, L-resolved subshell orthogonalization — the Natural Atomic Orbital (NAO) basis. The NAO transformation maps the underlying Gaussian basis onto an atomic-orbital basis with a clean core (Cor) / valence (Val) / Rydberg (Ryd) hierarchy. Several implementations of the original definition are in routine use today (e.g., NBO7, JaNPA); runEDDB ships with its own internal implementation alongside two compact subsets — the Natural Minimal Basis (NMB = Cor ∪ Val) and the program-default Natural Valence Basis (NVB = Val).

New to runEDDB? Start with the Quick Start page — a one-page tour of the essential commands, followed by a full worked example.

2. Generating Input Files

The current version of runEDDB directly reads seven input formats — six wavefunction formats produced by external quantum-chemistry programs and one geometry-only XYZ format processed by the built-in GFN2-xTB engine:

FCHK (.fchk)

The most common input format. Supported routes:

Most of our FCHK testing focused on Gaussian and Q-Chem outputs. For post-HF methods the relaxed correlated density block has to be requested explicitly — in Gaussian via density=mp2 (MP2) or density=current (CCSD, CI, CASSCF) on the route line; in Q-Chem via cc_ref_prop = true for the CC family. (Q-Chem does not currently emit the MP2 density to FCHK; for MP2 use Gaussian or ORCA.)

Molden (.molden)

Molden is one of the most popular formats for molecular density and orbital visualization. Many quantum-chemistry programs can produce it through different mechanisms — please consult the manual of your particular package for the exact keyword. Multiwfn is also a convenient universal converter to and from Molden, and runEDDB has been validated against Multiwfn-generated files.

ORCA (.json or .molden)

For ORCA we strongly recommend using .json rather than .molden. The JSON format produced by ORCA carries a more complete description of the wavefunction — including ECP definitions and other metadata — that the Molden specification cannot represent. We have validated runEDDB against both formats, generated by ORCA's standard orca_2mkl and orca_2json post-processors.

Turbomole native (.tmol)

For Turbomole calculations, runEDDB reads a single .tmol bundle that you assemble by concatenating the four key files from the Turbomole working directory:

 terminal
$ cat control coord basis mos > molecule.tmol

The parser handles RHF, UHF, ROHF, and DFT wavefunctions in Turbomole's spherical basis representation, with angular momenta up to k (L = 7) — covering def2-{S,T,Q}ZVPP and cc-pVDZ through cc-pV8Z. The native Turbomole $ecp block is parsed automatically — ECP-bearing transition-metal calculations load directly without conversion. Cartesian d/f basis storage (forced by $pople CAO or $cao) is not supported — use Turbomole's default spherical mode.

C1 symmetry is required for the .tmol lane. Under any non-trivial point group Turbomole writes the wavefunction in two ways that need irrep-aware bookkeeping not present in the .tmol parser:

The fix is simple: re-run the SCF with $symmetry c1 in the control file (or remove the keyword). Population analysis with EDDB doesn't benefit from point-group symmetry being on during the SCF write-out, so this is the standard workflow. If a non-C1 .tmol is passed, the parser stops with an explanatory ERROR; the run does not silently produce wrong densities. The other input formats (.fchk, .json, .molden, .49, .gms) write full-AO MOs and global orbital ordering regardless of point group, so they have no equivalent restriction.

GAMESS-US (.gms)

GAMESS-US output files (the standard text log produced by rungms) are read directly. Just rename or symlink the log to a .gms extension — PUNCH (.dat) files are not used. Supported run types: RUNTYP=ENERGY, OPTIMIZE (final equilibrium geometry is auto-located), and SADPOINT (transition state). Supported wavefunction types: RHF, UHF, ROHF, and MCSCF natural orbitals. Spherical-harmonic basis (ISPHER=1) is recommended; standard Cartesian basis is also supported. The default GAMESS print precision (F11.6) is sufficient; for high-precision basis-set studies, set DGRID=.T. in $CONTRL for F17.10 MO output.

GAMESS $ECP blocks are parsed automatically (handles both WITH ZCORE n AND LMAX l and the shared-definition shorthand ARE THE SAME AS ATOM N). Symmetry-truncated basis sections (any GAMESS run with COORD=UNIQUE under Cs, C2v, D2h, etc.) are reconstructed automatically — the parser detects the symmetry-implied gaps in the printed basis section and replicates each per-atom block for its unprinted symmetry-equivalent partners.

NBO archive (.49) — legacy compatibility

NBO7 .49 archives are still accepted in NAO-only mode (population analyses + BOP only; cube grids and orbital FCHK exports are disabled because NBO uses a different AO-basis convention than runEDDB's native pipeline). The .49 path is provided for backward compatibility and will be removed in a future release once the native NAO driver completes its acceptance suite. Users are strongly encouraged to switch to .fchk / .json / .molden / .tmol / .gms as soon as practical.

XYZ geometry (.xyz) — built-in GFN2-xTB engine

One of runEDDB’s most distinctive capabilities is that it can analyse chemical bonding straight from a bare set of atomic coordinates — for example a structure solved by X-ray diffraction, a molecular-dynamics snapshot, or a hand-built model — with no separate quantum-chemistry calculation. Give it a plain .xyz geometry and it builds the electronic structure itself, on the fly, using a fast built-in GFN2-xTB engine (a semi-empirical tight-binding model; Bannwarth, Ehlert & Grimme, JCTC 15 (2019) 1652), and then runs the complete EDDB analysis on top of it.

The practical payoff: in a single command, and in seconds rather than the hours a full DFT study would take, you obtain a map of where the electrons delocalize — a direct picture of the molecule’s resonance / conjugation pattern and bonding skeleton — without any external software, wavefunction file, or DFT step. This makes runEDDB a quick, stand-alone way to look at the bonding in a freshly determined or modelled structure; promising findings can then be confirmed with a higher-level wavefunction (DFT, post-HF, …) run through one of the other input lanes — again analysed by runEDDB — for a fully validated picture. The entire XYZ pipeline (GFN2-xTB SCC in its minimal valence vSTO-nG basis → AO→NAO localisation → BOP and EDDB analysis) runs end-to-end on the plain XYZ file, and the internal engine is validated against the reference tblite implementation across 81 systems covering 26 elements (H…W) at chemical accuracy.

About the GFN2-xTB basis (vSTO-nG). GFN2-xTB is a minimal valence tight-binding method: its atomic-orbital basis has just one Slater-type orbital per valence shell (e.g. one s and one p for C, N, O; one s for H; with a d shell added for heavier elements), and each Slater orbital is expanded as a short contraction of n Gaussians (an STO-nG fit). We abbreviate this vSTO-nG = valence STO-nG. It is therefore a compact, single-zeta-quality valence basis — not a double-zeta or polarized basis — which is exactly why an NAO/NBO-style decomposition of a GFN2 wavefunction looks minimal-basis-like. This keeps GFN2-xTB fast and is appropriate for the qualitative bonding screening the .xyz lane is meant for; for quantitative work, validate with a larger-basis DFT / wavefunction calculation through one of the other input lanes.

The XYZ file uses the standard XYZ format, with a runEDDB-specific optional extension on line 1 that carries the molecular charge and spin multiplicity:

 molecule.xyz
N_atoms [ charge multiplicity ]
comment line
Sym1   x1   y1   z1
Sym2   x2   y2   z2
...

The optional charge and multiplicity tokens on line 1 (after the atom count) default to 0 and 1 respectively, so plain XYZ files (with only N_atoms on the first line) are processed as neutral closed-shell singlets by default. Coordinates are in Ångström. Total energies reported in the verbose output of the GFN2-xTB stage match Grimme’s reference xtb executable to within ~10−4 Eh, allowing direct sanity-checking against an external xtb run on the same geometry.

Trajectories and geometry alignment (--xyz-*)

A .xyz file may hold a trajectory — many structures concatenated one after another (e.g. an MD run or an optimisation path). By default runEDDB analyses the first structure and prints a note reporting how many it found; use --xyz-frame N to pick the N-th structure instead (1-based). Requesting a frame that does not exist is a clear error reporting the actual count.

Two further options rigid-translate the input geometry (bond lengths, angles and dihedrals are untouched, so the EDDB analysis is unchanged — only the absolute coordinates written to any exported cube / FCHK move). They apply to every input format, not just .xyz (legacy .49 excepted):

Trajectory tip — comparable cubes across frames. Centering each frame independently with --xyz-center would re-centre every structure on its own (drifting) centroid, so the resulting cubes would not line up. Instead, centre one reference frame with --xyz-center geom -v, read off the printed translation vector, then run every frame with that same fixed vector via --xyz-translate (optionally combined with --cube-ref reference.cube to clone the grid) — the frames then share one coordinate frame and the EDDB cubes are directly comparable / subtractable.

Both closed- and open-shell systems are supported. Closed-shell molecules (the default, multiplicity = 1) are treated as restricted; any higher multiplicity is solved as a true spin-polarised unrestricted (UHF) calculation (spin-polarized GFN2-xTB / spGFN2-xTB; see the method references in §10) — just put the spin multiplicity on line 1 (e.g. 2 for a doublet radical, 3 for a triplet, 4 for a quartet, …).

For any open-shell run, runEDDB prints a spin-density topology table right after the GFN2-xTB step: the per-atom spin population, i.e. where the unpaired electrons actually sit. This is a quick way to read off the magnetic / radical centres of a structure — and a practical screen for diradical / broken-symmetry character: run the molecule as a triplet and, if the spin localises on two well-separated atoms or fragments, that is a strong hint of an open-shell singlet (diradical) ground state worth investigating. The NO analysis (--table no for the table, --export-fchk no for the orbitals) adds complementary diradical / multireference diagnostics — including the ⟨S²⟩ spin-contamination value, which counts roughly how many electron pairs are genuinely unpaired.

Diradicals / broken-symmetry singlets. GFN2-xTB’s simplified spin treatment cannot reliably converge a genuine broken-symmetry singlet — it tends to collapse back to the closed-shell solution or stop at partial open-shell character. Use the triplet spin-topology read-out above as a qualitative pointer only, and confirm any suspected diradical / broken-symmetry singlet with a proper broken-symmetry DFT calculation (e.g. CAM-B3LYP), which can then be analysed by runEDDB through one of the wavefunction input lanes.

Note — the GFN2-xTB lane is a qualitative screening tool. GFN2-xTB does not capture long-range exchange correctly, so the resulting EDDB indices (NOBD occupancies, CDI, EDDBG/F/P populations) are systematically inflated by ~10–20% relative to range-separated hybrid DFT. The lane is excellent for surveying the qualitative bonding topology — identifying which atoms / orbitals participate in delocalization, which interactions look chemically interesting, and which pathways are worth a closer look — on systems for which no wavefunction file is yet available (X-ray geometries, MD snapshots, hand-built coordinates). Chemically interesting findings should always be confirmed with a follow-up ab initio (DFT, post-HF, …) single-point on the same geometry, processed through one of the other input lanes. See the Quick Start worked example for a full GFN2-xTB walk-through on this metallacycle.

f-block elements. GFN2-xTB’s spin-polarisation parameters are defined only for s, p and d shells, so the open-shell character of lanthanide / actinide f electrons is not described — this is a property of the GFN2 model itself, shared with the reference tblite. f-block compounds still run, but any spin / delocalization assigned to the f shell should be interpreted with care, and a few lanthanide halides cannot even be cross-checked against tblite because the reference implementation does not handle them.

MDL Molfile (.mol) and SDF (.sdf)

The MDL Molfile (.mol) and its multi-record container SDF (.sdf) are a second geometry-only lane: like .xyz they carry just a structure (and, optionally, formal charges / radical flags), so runEDDB builds the electronic structure with the same built-in GFN2-xTB engine and runs the full EDDB analysis on top — everything said above about the GFN2-xTB lane (the vSTO-nG basis, the qualitative-screening caveat, open-shell handling, the geometry options below) applies unchanged. .mol / .sdf are ubiquitous in cheminformatics (PubChem, ChEMBL, RDKit, drawing programs), so this lets you analyse a structure straight from those sources.

runEDDB reads the standard V2000 connection table. Coordinates are in Ångström; the bond block is ignored (GFN2-xTB rebuilds connectivity itself). Molecular charge and spin are taken from the property block: total charge is summed from the M  CHG entries (falling back to the legacy per-atom charge column if absent), and multiplicity from M  RAD radical flags (doublet → 1, triplet → 2 unpaired electrons); when no radical flag is present the multiplicity follows the electron-count parity (even → singlet, odd → doublet). Two cases are refused with a clear message: the free-form V3000 format (re-export as V2000), and files explicitly flagged 2D (the dimensional code on line 2) — GFN2-xTB needs real 3D coordinates.

An .sdf file may hold many structures (conformer sets, compound libraries), each record separated by a $$$$ line. As with multi-frame .xyz (see above), runEDDB analyses the first record by default and prints a note with the count; --xyz-frame N selects the N-th record. The --xyz-center / --xyz-translate geometry options apply here too.

Tripos MOL2 (.mol2)

The Tripos .mol2 format is another geometry-only lane feeding the same GFN2-xTB engine. runEDDB reads the @<TRIPOS>MOLECULE atom count and the @<TRIPOS>ATOM records; each element is taken from the SYBYL atom type (C.3 → C, N.ar → N, or a bare symbol such as Li), and the bond block is ignored. Coordinates are in Ångström. Multiple @<TRIPOS>MOLECULE records are treated as a multi-structure file (--xyz-frame N selects one). MOL2 carries only per-atom partial charges, not a formal total charge or spin, so runEDDB defaults to a neutral closed-shell singlet; set a different state with --xyz-charge / --xyz-mult (below).

Protein Data Bank (.pdb / .ent)

The PDB lane reads ATOM / HETATM records (coordinates in Ångström). The element is taken from the dedicated element columns (77–78) when present — as written by Open Babel, PyMOL, etc. — and otherwise guessed from the atom name. Only the first alternate location (altLoc blank or A) of any disordered atom is kept. A multi-MODEL file (NMR ensembles, MD frames) is multi-structure: the first model is used by default, --xyz-frame N selects another. PDB carries no charge or spin, so the default is a neutral closed-shell singlet (override with --xyz-charge / --xyz-mult).

Hydrogens. Crystallographic PDB structures often omit hydrogens. GFN2-xTB needs a complete all-atom geometry, so a carbon-containing PDB with no hydrogens triggers a warning — add hydrogens first (e.g. obabel in.pdb -O out.pdb -h, or in PyMOL / Avogadro). Pure inorganic / metal structures that legitimately have no hydrogens are not flagged.

Overriding charge and multiplicity (--xyz-charge / --xyz-mult)

For any geometry input (.xyz, .mol, .sdf, .mol2, .pdb) the molecular charge and spin multiplicity can be set on the command line with --xyz-charge N (a signed integer) and --xyz-mult M (2S+1, a positive integer). When given they take precedence over whatever the file specifies (the .xyz header, or the M  CHG / M  RAD records of a molfile). For .mol2 and .pdb, which carry no usable charge / spin information (default: neutral singlet), these flags are the way to study an ion or an open-shell state — e.g. --xyz-charge -1 --xyz-mult 2 for a radical anion. They are rejected for the wavefunction lanes (.fchk / .json / .molden / .tmol / .gms / .49), where the charge and spin come from the wavefunction itself.

Crystallographic data (.cif) — convert to .xyz first

Crystallographic Information Files (.cif) are periodic data — a unit cell, an asymmetric unit (often only a fragment of a molecule, sitting on a symmetry element), and symmetry operators — not a ready molecular geometry. Turning that into a single, complete, chemically-sensible molecule (apply symmetry, grow the molecule across cell boundaries, resolve disorder and partial occupancies) is exactly what dedicated crystallography programs already do well. So rather than re-implement that, the recommended route is to export a complete molecule to .xyz from the tool you already use, then analyse that .xyz with runEDDB:

Once you have the molecule as .xyz, the full GFN2-xTB → EDDB pipeline runs on it directly (add hydrogens first if the structure lacks them, and set the charge / multiplicity with --xyz-charge / --xyz-mult if needed). This keeps the resonance / delocalization analysis one short step away from raw crystallographic data without duplicating the symmetry-and-disorder machinery your crystallography software already provides.

Effective Core Potentials (ECP)

Heavy elements are routinely treated with Effective Core Potentials (ECPs), which replace the chemically inert inner shells with an analytical pseudopotential. runEDDB consumes already-converged MOs and never evaluates ECP integrals itself; what each parser must do is read the per-atom effective nuclear charge Zeff = Zatomic − Ncore,replaced so that atomic charges, total molecular charge, and the per-atom population tables balance. The NAO classification (Core / Val / Rydberg) also uses each atom's Z to decide how many core/valence shells to expect, so getting Zeff right is essential — a wrong value silently misclassifies orbitals and can drop the heavy atom from the per-atom tables.

How each parser obtains Zeff:

Once Zeff is known, the NAO machinery automatically labels the surviving valence shells with the chemically correct principal quantum numbers. For example, tungsten under def2-ECP60 shows its valence as 6s, 5d1..5d5 (the actually-present W valence shells) rather than the misleading 1s, 3d1..3d5 labels that an ECP-blind labelling would produce.

Supported wavefunctions:

3. Analysis Modes

runEDDB offers five scope modes, two NOBD-dissection options, and three analysis-basis subsets.

Scope modes (mutually exclusive):

Under a restricted scope (-f / -p / -r) every scope-dependent density — EDDB, EDLB and BDF — is built from density matrices with exactly the atomic support of the selected atoms, so the per-atom tables, the summary totals and the cube integrals are mutually consistent (see the note in §5).

NOBD dissection (can combine with any scope):

When dissection is active, the atom table and summary show only the density of the selected NOBDs; the star marker (*) in the NOBD table flags them.

Analysis basis subset, selected by --basis VALUE (or -b VALUE). VALUE is one of:

VALUE is fully case-insensitive (Nao, NMB, nVb, etc. all work).

.49 input note. The NBO7 .49 archive flags every NAO as either NMB or Rydberg, with no further Cor/Val partition. -b nvb therefore cannot be honoured on .49 input and silently falls back to -b nmb. When -b nvb is requested explicitly, a one-line clarifier — (.49 archives carry no Cor / Val split) — is printed directly under the Target NAO representation: entry in the Stage 2 detail block, aligned with the basis-label value. The clarifier is verbose-only (-v), keeping the default-mode output clean. To get a real Cor/Val split, use the matching native input (FCHK / JSON / Molden).

Basis-independent connectivity (always on). The atom-pair connectivity that BOP analyses is always derived from Wiberg bond orders evaluated in the full NAO representation (Cor + Val + Ryd), whatever -b selects; that one mask is then handed unchanged to a BOP run that uses the -b working density. Consequently a nao / nmb / nvb series differs only in the density BOP integrates, on a fixed set of atom pairs. Why it matters: the Rydberg shell carries the weak through-space and hyperconjugative couplings that sit near the 0.001 gate, so deriving the mask in a truncated basis silently prunes them — and a change in EDDB population would then mix a genuine basis effect with a change in which bonds were counted at all. The bond-order threshold, the BOP equations and the working density matrix are untouched; only the pair selection is basis-fixed. Notes: with -f the NAO connectivity is built first and the fragment restriction applied to it afterwards; -p supplies the connectivity explicitly and therefore overrides it entirely, while -r auto-detects its rings from the NAO bond-order graph. Under -v the Stage 3 detail block reports the basis actually used, as Connectivity mask basis: full NAO. Cost is negligible — one extra Wiberg pass over the NAO density; BOP itself, which dominates the runtime, still runs at nmb / nvb size. (This was briefly the opt-in --nao-mask flag in July 2026; it is now unconditional and the flag has been removed.)

Post-HF layer basis (always full NAO). For correlated (post-HF) densities the BOP analysis uses the cumulative-idempotent layer scheme: the 1-RDM is partitioned into quasi-degenerate (QD) groups of natural orbitals, and a standard BOP is run on each cumulative idempotent projector. That QD partition is always derived from the full NAO density, never from the -b sub-block. This is essential rather than cosmetic: the sub-block of an idempotent density is not idempotent (Rydberg projection removes a fraction of each MO), so grouping the sub-block reads basis truncation as correlation and shatters what should be a single layer into many, inflating EDDB. BOP, the working density and every threshold remain in the -b basis — only the layer partition is derived in full NAO. Under -v the Stage 3 block reports QD layer basis: full NAO. For an idempotent reference all occupied natural orbitals share one occupation, so there is exactly one layer and the scheme reduces to a single standard BOP call — recovering the HF/DFT answer exactly, as it must.

Bond-order thresholds. runEDDB applies two distinct Wiberg cutoffs, and only the second is user-tunable:

NAO construction algorithm, selected by --nao-algorithm ALG (native input only; .49 archives carry NBO7’s own NAOs and ignore the flag with a printed note). Background: in strongly polarised basis sets (cc-pVQZ and beyond) the textbook NAO definition suffers from High-L Redundancy Leakage (HLRL) — the molecule-wide occupancy-weighted orthogonalisation stores each NAO as a huge, near-cancelling coefficient expansion routed through the chemically insignificant high-angular-momentum shells and neighbouring centres (a benzene “carbon 2p” at cc-pV5Z carries a coefficient norm of ~12 with ~30% of it on the bonded hydrogen, cancelling down to a perfectly atom-localised orbital). The real-space orbital stays localised and integrated populations stay basis-stable, but the ill-conditioned representation has two practical consequences: most molecular viewers (Avogadro2, IQMol — verified Jul 2026; Multiwfn is correct) misrender the exported orbitals as delocalised artefacts, because their approximate high-L handling breaks the coefficient cancellation; and the NPA charges themselves lose numerical conditioning at cardinal ≥ 5. ALG is one of:

The exported .NAO/.NMB/.NVB.fchk header records which variant produced it (| frozen-NMB, | cc-layers, | raw NAO for rigorous / nbo7legacy, or | L-projected when --export-lproj is given), so orbital pictures remain traceable to the algorithm that generated them.

4. Command-Line Reference

Basic usage:

 terminal
$ runEDDB --input FILE.ext   [ Options ]

  ext = {mol | mol2 | pdb | sdf | xyz}              geometry (built-in GFN2-xTB)
        {fchk | json | molden | tmol | gms | 49}    wavefunction

The input file is the only required argument — the recognised extensions are listed right under the syntax line above (geometry formats run through the built-in GFN2-xTB engine; the rest are read as wavefunctions). Everything else has a sensible default. Output is requested with three verbs — --export-cube, --export-fchk and --table — each taking a comma-separated list of content tokens.

Two built-in help screens. --help (or a no-argument run) prints a short, curated list — just the options most analyses reach for: the five scope modes (-g / -h / -f / -p / -r), NOBD selection (-a / -s), the three output verbs, and the common controls (-b, -c, --cube-ref, the --xtb-* engine controls, --xyz-charge / --xyz-mult, -n, -q, -v). To keep that screen uncluttered, the more specialised flags are deliberately left out of it. Run --full-help for the complete reference, which breaks the --xtb-* controls out flag-by-flag and additionally documents the less-common geometry options (--xyz-center, --xyz-translate, --xyz-frame), citation export (--cite), output naming (--out-prefix / --out-dir), the ASCII toggle (--ascii), the ring-graph cutoff (--ring-thresh), the NAO algorithm selector (--nao-algorithm) and the developer / diagnostic flags (--test-*, --no-nrep / --force-nrep, --no-ecp, --nao-debug*, --nao-atdiag-form, --density-source, --dump-element-table).

The reference table below documents every user-facing option — the curated --help set and the specialised flags that only --full-help shows on screen (the low-level diagnostic flags are listed by --full-help itself):

 command-line options
    --input, -i FILE          Input file (.fchk / .json / .molden / .tmol / .gms / .49 / .xyz / .mol / .sdf / .mol2 / .pdb)

    --xyz-frame N             Select structure N from a multi-frame .xyz/.sdf/.mol2/.pdb (default: 1)
    --xyz-center [geom|mass]  Recenter geometry at origin: geometric centroid (geom, default) or mass
    --xyz-translate x,y,z     Apply a fixed translation vector (Angstrom) to every atom
    --xyz-charge N            Override molecular charge      (geometry input only)
    --xyz-mult M              Override spin multiplicity 2S+1 (geometry input only)

    --global, -g              EDDB_G - entire molecular system (default)
    --heavy-atoms, -h         EDDB_H - entire system, hydrogens excluded from connectivity
    --fragment, -f ...        EDDB_F - molecular fragment, e.g., -f 1:6,10,12
    --pathway, -p ...         EDDB_P - specific bond pathway, e.g., -p 1-2-3-4-5-6-1
    --ring-detect, -r ...     EDDB_R - auto-detect n-membered rings, e.g., -r 5,6:8
    --ring-thresh X           Wiberg ring-bond cutoff for -r (default: 0.30)
    --wbo-thresh, -w X        Wiberg cutoff for the BOP pair gate (default: 0.001; 0 = keep all)

    --select-nobd, -s ...     Select NOBDs for dissection, e.g., -s 1:3,4,5
    --auto-pi, -a             Auto-select pi-type NOBDs to get pi-density component

    --basis, -b ...           NAO basis subset: nao | nmb | nvb (default: nvb; .49 input: nmb)

    --nao-algorithm ALG       NAO construction (native input only):
                                frozen-nmb : two-cycle frozen-NMB construction (DEFAULT);
                                             well-conditioned NAOs at any basis-set size
                                rigorous   : standard NBO-style pipeline (NBO7-equivalent)
                                cc-layers  : correlation-consistent layered NAOs (ccNAO);
                                             Rydberg space frozen shell-layer by shell-layer
                                             in the Dunning progression -> monotonic radial
                                             occupations (aliases: cclayers, cc)
                                nbo7legacy : alias of rigorous (kept for reproducing
                                             published raw-NAO exports)
    --export-lproj            Apply the legacy Galerkin L-projection to the coefficients
                              written by --export-fchk ao (retired former default; cubes
                              are never projected - they are exact grid evaluations)

    Output is requested with three verbs, each taking a comma-separated LIST of
    content tokens (order preserved, duplicates ignored, case-insensitive):

    --export-cube LIST        Volumetric fields to Gaussian CUBE. Tokens:
                                ed | eddb | edlb | bdf
                                ded | deddb | dedlb | dbdf   (differentials; need --cube-ref)
                                ao | no | nobd | bo | xtb    (ORBITAL cubes, one file per
                                orbital; optional 1-based [LIST], e.g. ao[2,4,11-15];
                                no list = every orbital of the lane, guarded at 64)
                              e.g.  --export-cube ed,eddb,deddb --cube-ref baseline.cube
                                    --export-cube ao[2,4] -b nmb     (NMB orbital cubes)
    --cube-ref FILE           Reference cube. Voxel-aligns EVERY exported cube to FILE's grid,
                              and supplies the grid + values baseline for the differential
                              tokens (required when a d-token is present; differentials: not .49)
    --cube-align [FRAGMENT]   Rigidly superpose the current geometry onto the --cube-ref frame
                              (Kabsch fit of a conserved fragment), then map the exported
                              field(s) into that frame -- differential maps AND orbital cubes
                              (ao/no/bo/nobd/xtb). Removes an arbitrary translation + rotation
                              only, reports the post-fit RMSD + max residual. No FRAGMENT =>
                              reuse --fragment. Opt-in; needs --cube-ref.
    --cube-orb2dens           Collapse each orbital lane (ao/no/bo/nobd/xtb[LIST]) into ONE
                              occupation-weighted density cube rho = sum occ_i*|psi_i|^2
                              (<stem>.<LANE>_density.cube) instead of one cube per orbital;
                              composes with --cube-ref / --cube-align. Opt-in.

    --export-fchk LIST        Orbitals / wavefunction to Gaussian FCHK. Tokens:
                                no    natural orbitals of the total density
                                nobd  natural orbitals of bond delocalization
                                ao    AO (NAO-basis) vectors, in the subset set by -b
                                bo    bond-order orbitals (one MO set; alias boo|nba)
                                xtb   GFN2-xTB wavefunction (.xyz input)
                              e.g.  --export-fchk nobd,ao   or   --export-fchk no,bo
                              (the AO subset is chosen ONLY by -b; default nvb)

    --table LIST               Analysis tables to the terminal. Tokens:
                                mo | no | bo | nobd | ao | shell | npa | all
                              mo  = per-MO ED/EDLB/EDDB decomposition (needs canonical MOs).
                              no  = NO occupancy table (the MR / spin-contamination
                                    indices print in the NO stage's -v detail block).
                              bo  = bond-order orbitals (Theta_cov + sigma/pi/delta/phi,
                                    in the chosen NAO|NMB|NVB basis; alias: boo|nba).
                              ao  = per-orbital (atomic-orbital) populations in the -b basis.
                              shell = subshell-resolution populations: (atom, n, L) sums of
                                    the ao rows, e.g. 2p = 2p1+2p2+2p3 (alias: subshell).
                              npa = condensed-atomic populations led by the natural charge q_N.
                              All requested tables print together in one captioned
                              "> Printing analysis details:" section before the summary,
                              in the order mo -> no -> bo -> nobd -> ao -> shell -> npa.

    --cite LIST               References to cite for THIS run -> file. Tokens:
                                bib | txt | both    (-> .bib / .refs.txt)
                              The reference set depends on the methods actually used;
                              it is also shown per-stage on screen under -v.

    --out-prefix NAME         Override the output filename stem for the whole batch
    --out-dir DIR             Write all generated files into DIR (created if absent)

    (The legacy --output-* flags were removed in v2.0 -- see the migration
     table in section 6 for the old -> new mapping.)

    GFN2-xTB engine (.xyz input only):
    --xtb-etemp K             Electronic (Fermi smearing) temperature in K (default ~300; 0 = off)
    --xtb-conv X              SCC convergence threshold on max|dq| (default: 1e-4)
    --xtb-maxiter N           Maximum number of SCC iterations (default: 1500)
    --xtb-noaes               Disable anisotropic electrostatics (faster; not EDDB-grade)
    --xtb-frac-occ            EXPERIMENTAL: keep fractional (smeared) occupations
    --xtb-nospin              Open-shell: use ROHF instead of the default spin-polarised UHF

    --cube-size, -c N         Grid points per axis, ~|N|^3 total (default: 100; N=0 skips; integer only)
    --ncores,    -n ...       Number of CPU cores, 0 = all available (default: 1)
    --quiet,     -q           True-quiet: banner + EDDB summary block only
    --verbose,   -v           Add per-stage detail blocks (tables are opt-in via --table)
    --ascii                   Force plain 7-bit ASCII output (default: UTF-8)
    --help                    Print the short, curated end-user help (also shown with no args;
                              NOTE: -h is the EDDB_H scope, not a help alias)
    --full-help               Print the complete reference (adds --cite, --out-*, --ascii,
                              --ring-thresh, --xyz-center/-translate/-frame, per-flag --xtb-*
                              detail + diagnostics)

runEDDB has three verbosity tiers:

Analysis tables are printed only when requested via --table (independent of the verbosity tier): --table mo for the per-MO ED / EDLB / EDDB decomposition (when canonical MOs are available), --table no for the NO-occupancy table (its multireference / spin-contamination indices print in the NO stage's -v detail block), --table bo for the bond-order orbitals (aliases boo / nba), --table nobd for the NOBD-resolution table, --table ao for the per-orbital (atomic-orbital) populations, --table subshell for the subshell-resolution populations (per-(atom, n, L) sums of the AO rows), --table shell for the shell-resolution populations (per-(atom, n) sums over L), --table npa for the condensed-atomic table (led by the natural charge qN), or --table all for every table. All requested tables are emitted together in one captioned > Printing analysis details: section immediately before the EDDB summary, in the order mo → no → bo → nobd → ao → subshell → shell → npa (the orbital-based tables MO / NO / BOO come before the NOBD-driven dissection; AO / SUBSHELL / SHELL / NPA come after it). Using -s without a list still shows the NOBD-resolution table (so you can pick indices for a follow-up run). In true-quiet mode the EDDB summary still prints, and --table tables requested alongside -q are honoured.

Citing the methods you used (--cite)

runEDDB can tell you exactly which papers to cite for a given run — the set is method- and option-dependent, emitted by the stage that uses each reference:

The remaining algorithmic ingredients (the Wiberg index, the per-pair NBA / BOO decomposition, OWSO / Gram-Schmidt orthogonalisation, the multireference indices, ring detection, …) are not in the end-user list — they are attributed in the source-code comments instead. Two ways to get the references:

GFN2-xTB engine controls (--xtb-*)

These flags tune the built-in GFN2-xTB SCC and apply only to .xyz input (they are ignored for the wavefunction-file lanes). The defaults are chosen to be robust and EDDB-appropriate, so most runs need none of them; they exist for the occasional stiff or unusual system.

If the SCC does not converge, runEDDB stops and prints a short reminder suggesting exactly these knobs (a higher --xtb-etemp, a larger --xtb-maxiter, or a looser --xtb-conv), so you rarely need to remember them in advance.

5. Output Files

Outputs are generated only when explicitly requested with --export-cube (cube files) or --export-fchk (FCHK files); --table prints analysis tables to the terminal without writing any file.

Gaussian cube files (.cube) — via --export-cube LIST; 3D electron density on a PCA-aligned grid; viewable in VMD, Chemcraft, GaussView, Avogadro2, IQmol, or any cube-compatible program. Tokens:

Scoped runs (-f / -p / -r) — exact atomic support. All three scope-dependent densities share exactly the atomic support of the selected atoms: after the congruence transformation the EDDB matrix is purified (rows and columns of out-of-scope atoms zeroed), and — as of Jul 2026 — the auxiliary π-electron density entering the EDLB difference (Dtot − Ddel) and the BDF combination (2·Ddel − Dtot) receives the same purification (it is reconstructed from the full molecular density via the selected π-NOBDs, so it would otherwise retain contributions on atoms outside the scope). Consequently the integrated cube density, the printed basis-trace reference and the per-atom table sums agree exactly — e.g. the EDLBF cube integrates to EDF − EDDBF. The same purified matrices feed the differential tokens (dedlb / dbdf).

Grid quality is controlled by --cube-size N (default: 100), with the grid covering the molecular bounding box (or a fragment subset, when -f / -p / -r is in effect) plus a small margin. The sign and zero of N select between three modes:

Gaussian FCHK files (.fchk) — via --export-fchk LIST; viewable in GaussView, Avogadro2, IQmol, or Chemcraft. Tokens:

For all three FCHK exports the per-orbital occupation (NAO population, NOBD occupation, or NO occupation number) is stored in the Alpha Orbital Energies field, pre-scaled so that the value Avogadro2 shows in its eV-labelled energy column reads back numerically as the unscaled occupation. So a doubly-occupied orbital appears as "2.00 eV", a singly-occupied one as "1.00 eV", and so on — the unit label is technically eV but the number is the actual occupation. Other viewers (GaussView, IQmol, Chemcraft) that read FCHK energies in hartree will show the raw small values; if you need the actual occupations there, multiply by 27.2114.

Terminal tables (--table) — no file written. Every table requested with --table is collected into a single captioned > Printing analysis details: section, emitted just before the always-on EDDB summary, in the order mo → no → bo → nobd → ao → subshell → shell → npa. Tokens: mo (per-MO ED / EDLB / EDDB decomposition, when canonical MOs are present), no (NO occupancy + multireference diagnostics), bo (bond-order orbitals; σ/π/δ/φ resolution; aliases boo/nba), nobd (NOBD-resolution table), ao (per-orbital atomic-orbital populations in the -b basis), subshell (subshell-resolution populations: per-(atom, n, L) sums of the AO rows), shell (shell-resolution populations: per-(atom, n) sums over L), npa (condensed-atomic populations led by the natural charge qN), and all (every table). The orbital-based tables (MO / NO / BOO) print before the NOBD-driven dissection; ao / subshell / shell / npa print after it. Each table is introduced by a capitalised caption; see §7 for what every column means.

Reference list (--cite) — <stem>.bib / <stem>.refs.txt. --cite bib writes a BibTeX file, --cite txt a plain numbered list, and --cite both writes both. The contents are the exact, de-duplicated set of papers to cite for the run — method- and input-dependent — and honour --out-prefix / --out-dir like every other output. The same references are shown per-stage on screen under -v (see §4); the full reference list is in §10.

Filename rules. Filenames are standardized and deterministic — each token names its own file as <stem>.<TOKEN>_<SCOPE>.<ext>, so a single verb can emit many files coherently. The <stem> is the input basename (override the whole batch with --out-prefix); <SCOPE> is the scope letter G/F/P/R (from -g/-f/-p/-r), baked into the name for scope-dependent tokens (eddb, edlb, bdf, nobd, and the differentials) and omitted for scope-independent ones (ed, no, xtb, AO). The AO export names itself by the resolved basis (NAO/NMB/NVB):

 filename examples
Input:   molecule.fchk          (or .json / .molden / .49 / .xyz)
ed       -> molecule.ED.cube
eddb     -> molecule.EDDB_G.cube       (_H / _F / _P / _R under -h / -f / -p / -r)
edlb     -> molecule.EDLB_G.cube
bdf      -> molecule.BDF_G.cube
ded      -> molecule.DED_G.cube        (differentials; need --cube-ref)
deddb    -> molecule.DEDDB_G.cube
dedlb    -> molecule.DEDLB_G.cube
dbdf     -> molecule.DBDF_G.cube
ao[2,4]  -> molecule.NVB_orb002.cube, molecule.NVB_orb004.cube
            (orbital cubes: one file per orbital, <stem>.<LANE>_orbNNN.cube;
             the AO lane is named for -b, the others NO / NOBD / BO / XTB)
nobd     -> molecule.NOBD_G.fchk
no       -> molecule.NO.fchk
ao       -> molecule.NVB.fchk          (named for -b: NAO / NMB / NVB; default nvb)
bo       -> molecule.BO.fchk           (bond-order orbitals)
xtb      -> molecule.XTB.fchk          (from .xyz input)

The scope (-g / -f / -p / -r) is encoded in the _G / _F / _P / _R suffix so two cubes that differ only by scope never collide. --auto-pi / --select-nobd dissection is reflected in the file contents, not the name. The export verbs deliberately drop per-file naming — use --out-prefix NAME to set the stem for the whole batch and --out-dir DIR to choose the location.

Migration from the legacy --output-* flags

The old one-flag-per-thing --output-* family (from the released runEDDB_nbo49) was removed in v2.0 — the three verbs replace it. Update old commands as follows:

 migration: old → new
--output / -o                  ->  --export-cube eddb --export-fchk nobd
--output-ed                    ->  --export-cube ed
--output-eddb                  ->  --export-cube eddb
--output-edlb                  ->  --export-cube edlb
--output-bdf                   ->  --export-cube bdf
--output-ded   REF [OUT]       ->  --export-cube ded   --cube-ref REF [--out-prefix OUT]
--output-deddb REF [OUT]       ->  --export-cube deddb --cube-ref REF [--out-prefix OUT]
--output-dedlb REF [OUT]       ->  --export-cube dedlb --cube-ref REF [--out-prefix OUT]
--output-dbdf  REF [OUT]       ->  --export-cube dbdf  --cube-ref REF [--out-prefix OUT]
--output-nobd                  ->  --export-fchk nobd
--output-no                    ->  --export-fchk no
--output-ao                    ->  --export-fchk ao           (basis via -b)
--output-xtb  [FILE]           ->  --export-fchk xtb [--out-prefix FILE]
--cube-size 0 FILE             ->  --cube-ref FILE

Lists let you combine these in one call, e.g. the old --output-eddb --output-edlb --output-bdf becomes --export-cube eddb,edlb,bdf.

6. Differential Maps (ΔED / ΔEDDB / ΔEDLB / ΔBDF)

A differential map subtracts one runEDDB density field from another, point-by-point on a shared grid, to reveal how the electron structure reorganizes between a reference and a perturbed system — a substituent change, a hydrogen / halogen bond, a π···cation or π···HF contact, solvation, or a redox step. The differential of the bond-delocalization field, ΔBDFπ, maps π-electron (de)localization changes directly in the language of resonance; the same operation applies to every density in the EDDB decomposition, so there is one differential token per density (all sharing a single --cube-ref):

The reference is a cube of the same density written by an earlier run, supplied via --cube-ref FILE: it provides both the grid (origin / points / steps, cloned exactly) and the reference values, so the subtraction is point-for-point and no external cube-arithmetic tool (Multiwfn, VMD, …) is needed. Outputs follow the standard naming scheme (<stem>.DED_G.cube, .DEDDB_G.cube, …; set the stem with --out-prefix). The differential maps run on the native lane (not the legacy .49).

π-resolved (ΔBDF) versus full (ΔEDDB / ΔEDLB). ΔBDF is normally a π-only quantity, so it should be built from the π-delocalization (π-NOBDs; see the workflow below). When a clean π-dissection is awkward, ΔEDDB and ΔEDLB on the full delocalized / localized densities need no π-selection at all and still show where delocalization is gained or lost — frequently the easier and more robust route.

Recommended ΔBDFπ workflow. The map is only as good as the set of NOBDs included, and the BDF cubes for both systems must be built the same way. (1) compute and save the reference π-BDF cube, e.g. runEDDB -i ref.fchk --auto-pi --export-cube bdf --out-prefix ref (writes ref.BDF_G.cube); (2) for the perturbed system run runEDDB -i pert.fchk --auto-pi --export-cube dbdf --cube-ref ref.BDF_G.cube. Capture the π-system consistently in both molecules: --auto-pi selects π-symmetry NOBDs automatically, but a perturbation can change how many NOBDs carry the π-delocalization (and the classifier may miss one in a given system). Inspect the NOBD-resolution table for each molecule (printed with --select-nobd / --auto-pi / --verbose) and, if needed, replace --auto-pi with an explicit --select-nobd LIST so that all NOBDs contributing to the π-(de)localization are included in both runs — otherwise ΔBDF shows a spurious feature wherever a real contributor was dropped from one side. Typical ΔBDFπ isosurfaces are around ±0.010.

Same coordinate frame, same scope. A point-by-point subtraction is only meaningful if the two systems share one frame. The most robust route is to align them before the wavefunction calculation — keep the common fragment’s Cartesian coordinates fixed. Alternatively, apply an after-the-fact rigid superposition at export time with --cube-align (see the box below), which absorbs an arbitrary translation and rotation. runEDDB warns if the reference and current geometries do not overlap. Both runs must also use the same scope (--global / the same --fragment / --pathway / --ring-detect) and the same density flavour, so that their grids, NOBD sets and densities are comparable.

Large, flexibly-reorganizing systems — focus on a fragment. When a perturbation reshapes a remote reactive site so the whole molecule no longer overlaps, restrict the analysis to the conserved region of interest with --fragment (or --pathway). This focuses the EDDB density, the cube grid and the geometry-overlap check on the selected atoms only, so the differential reports how that fragment’s π-system responds to a change happening elsewhere — without being penalised for motion in the part you are not studying. The overlap check is purely spatial and element-based, so the reference and perturbed structures may number their atoms differently: as long as the studied fragment is physically superimposed, the overlap is recognised. (Keep that fragment’s coordinates frozen between the two systems, so the differential reflects electronic reorganization rather than atomic displacement.)

Automatic rigid alignment — --cube-align [FRAGMENT]. When the reference and perturbed geometries are not in the same frame (e.g. two optimisations, two solvation environments, or coordinates from different sources), you do not have to pre-align them by hand. Add --cube-align to a differential or orbital-cube run: runEDDB performs a rigid-body Kabsch superposition of a conserved fragment onto its counterpart in the --cube-ref cube (finding the rotation R and translation t with xaligned = R·x + t), then evaluates the exported field — and writes the shown geometry — in that reference frame. Because the density is a scalar field, this is done by sampling it at the back-mapped grid points; no rotation of the wavefunction or density matrix is involved, and the result is exact. The very same back-map carries the per-orbital cubes (ao / no / bo / nobd / xtb) into the reference frame — each orbital is a scalar field too — so orbital cubes emitted alongside a differential map are aligned identically; the superposition is fitted and reported once and shared by every lane. Without a FRAGMENT list it reuses the --fragment selection. The alignment atoms must appear at the same index and carry the same element in both the perturbed input and the reference cube (a mismatch is a hard error).

# ΔBDFπ of the same chromophore in two solvation environments.
# The porphyrin core (atoms 1-24) is conserved; the two geometries
# differ by an arbitrary translation + rotation (and local relaxation).

$ runEDDB -i gas.fchk    --auto-pi --export-cube bdf  --out-prefix gas
                                          # writes gas.BDF_G.cube (reference)

$ runEDDB -i water.fchk  --auto-pi --export-cube dbdf \
          --cube-ref gas.BDF_G.cube --cube-align 1:24    # aligns the core, then subtracts

# console report emitted for the aligned differential:
    Alignment atoms (--cube-align):    24
    RMSD after rigid alignment:           0.03812 Angstrom
    Max residual displacement:            0.07105 Angstrom
    (arbitrary translation + rotation removed; residual = internal deformation)

What --cube-align does and does not remove. It cancels only an arbitrary rigid translation and rotation of the perturbed system relative to the chosen fragment. It does not remove genuine internal (non-rigid) deformation: any such change of the alignment fragment survives the fit and is reported as the post-fit RMSD and the maximum residual displacement (the two lines above). When those residuals are small, the map is a clean electronic-reorganization picture; when they are large, the perturbation has deformed the fragment beyond the perturbative regime and ΔBDFπ is no longer well defined — the alignment does not, and cannot, repair that. Treat the reported RMSD as the validity gauge for the difference map.

7. Understanding the Output

Analysis tables are printed only when requested with --table — no tables appear by default (the default view is the stage messages plus the EDDB summary block). All requested tables are collected into one captioned > Printing analysis details: section, printed just before the summary in the order mo → no → bo → nobd → ao → subshell → shell → npa: --table mo adds the per-MO ED / EDLB / EDDB table (when canonical MOs are present), --table no the NO table, --table bo the bond-order orbitals (aliases boo/nba), --table nobd the NOBD table, --table ao the per-orbital (atomic-orbital) population table, --table subshell the subshell-resolution population table, --table shell the shell-resolution population table, --table npa the condensed-atomic table (led by the natural charge), and --table all every table. The orbital-based tables (MO / NO / BOO) print before the NOBD-driven dissection; ao / subshell / shell / npa print after it. --verbose adds per-stage detail (and, under it, the per-stage Papers to be cited (DOI): lists) but not tables; -q (true-quiet) suppresses stage messages and timings too — only the banner, the EDDB summary block, and the two bookend stage lines around it are emitted.

NOBD-resolution table: appears with --table nobd (also shown by -s used without a list, so you can pick NOBD indices for a follow-up run). Each row is one NOBD (Natural Orbital for Bond Delocalization):

Per-MO decomposition (MO): appears with --table mo, when the input carries canonical molecular orbitals (HF / DFT references; rejected for densities with no MOs). One row per MO — its energy and occupation, and its contribution decomposed into ED (total), EDLB (localized) and EDDB (delocalized) — so you can read off which orbitals carry the delocalized density (e.g. the ring-current-active π set). Printed before the dissection, so the numbers reflect the full, undissected density.

Bond-order orbitals (BOO): appears with --table bo (aliases --table boo / --table nba; orbitals exportable with --export-fchk bo). Each row is one atom pair, whose (Wiberg) bond order is resolved into orthonormal bond-order orbitals — the natural orbitals of that single bond. The columns give the Index of the pair’s first BOO (matching the MO numbering in the exported FCHK; the pair’s last BOO is implicit — one below the next row’s Index), the atom-index and element pairs joined by ~, the Total bond order WBO (the full Wiberg index, summed over all BOOs), and the twelve largest BOO occupations (σ2) above the listing threshold, each tagged with a σ / π / δ / φ symmetry label (from the two-centre (n·L)2 classifier about the bond axis). Only those are listed, so they need not sum exactly to WBO — the small remaining tail is omitted from the printout but written in full by --export-fchk bo. The resolution is spin- and correlation-consistent — identical for restricted / unrestricted and HF / DFT / post-HF densities — and is evaluated in the basis selected by -b (default NVB; use -b nao for the full textbook Mayer index).

Large systems — scope the bond-order analysis. Both --table bo and --export-fchk bo honour the analysis scope: they resolve BOOs only for the atom pairs in the active --fragment / --pathway / --ring-detect selection, using the same connectivity that drives the EDDB. On a large molecule, prefer one of these scopes over --global: a global run diagonalises a bond-order operator for every connected pair in the structure, which is rarely what you want when you are studying one bond, ring or fragment. Scoping also keeps the exported <stem>.BO.fchk small — it contains only the selected pairs’ BOOs (each still expanded in the full AO basis, so the file stays a valid “partial MO set” that most FCHK viewers accept), making it ideal for inspecting the bonding pattern of a specific fragment.

Orbital-resolution table (AO): appears with --table ao. One row per NAO in the active -b subset. The columns are: Index (the orbital number — it matches the MO index in the --export-fchk ao FCHK 1:1, so the table doubles as a navigation key in Avogadro2 / IQmol / GaussView), the NAO label (its angular type, e.g. 2s, 2p — the header carries the basis name NAO / NMB / NVB) and its Atom, then the orbital’s total electron population ED and its delocalized part EDDB (both tagged with the scope suffix _G / _F / _P / _R). Each of ED and EDDB has α and β sub-columns for open-shell inputs; for a closed-shell (restricted) reference these are not defined and print a centred dash (–).

Subshell-resolution table (SUBSHELL): appears with --table subshell — the intermediate resolution between ao and npa, new in Aug 2026 (until mid-Aug 2026 this table answered to --table shell, which now prints the coarser shell-resolution table below). One row per subshell (atom, n, L): the ED / EDDB populations (and their α / β sub-columns for open-shell inputs) are the sums over the 2L+1 magnetic components of the corresponding AO-table rows — e.g. the 2p row is 2p1 + 2p2 + 2p3. The summation is keyed by the NAO quantum labels, never by table position, so it is correct for any AO display ordering (the .49 lane and the different --nao-algorithm constructors order the AO rows differently). Rows print in canonical order — atom by atom, ascending n, then L (1s, 2s, 2p, 3s, 3p, 3d, …); there is no Index column (subshell rows do not map to AO / FCHK orbital indices — use the ao table for that). Works for every -b subset; with --nao-algorithm cc-layers the rows directly display the frozen shell-layer hierarchy.

Shell-resolution table (SHELL): appears with --table shell — the coarsest orbital-resolved view, new in Aug 2026. One row per principal shell (atom, n): the ED / EDDB populations (and α / β sub-columns for open-shell inputs) are the sums over all L of the subshell rows — e.g. shell 2 is 2s + 2p. Shells are labelled by the plain principal number 1, 2, 3, … (no spectroscopic K / L / M letters: those end at n = 8, while decontracted bases reach far higher n, and custom sets may lack the highest-L members). Because the NAO Rydberg populations fall roughly an order of magnitude per shell, this table exposes the Rydberg population ladder at a glance — a fast diagnostic of the shell truncation point when selecting compact, shell-structured virtual subspaces (pairs naturally with --nao-algorithm cc-layers, where each row is exactly one frozen layer). Same accumulation and ordering rules as the subshell table.

NO-resolution table: appears with --table no. One row per natural orbital with non-trivial occupation, sorted by descending NOON. Each row reports the NOON itself plus the breakdown of its occupation into Core (Cor), Valence (Val), and Rydberg (Ryd) NAO contributions, with percentages. Row index matches the MO index in the --export-fchk no FCHK 1:1.

Multireference / spin-contamination indices. These are reported in the NO stage’s verbose (-v) detail block — not inside the table — right after the occupation-spectrum summary, each with its source DOI in brackets (run --table no -v to see them):

Together they are a quick MR-character sanity check on post-HF or broken-symmetry inputs.

Condensed-atomic table (NPA): appears with --table npa (the orbital-resolution table is now the separate --table ao token; when both are requested, AO prints just before NPA). Each row leads with the natural atomic charge qN = Zeff(A) − NA, where NA is the full natural electron population on the atom (core + valence + Rydberg) and Zeff is the effective nuclear charge — so the charges are correct, and sum to the molecular charge, even with ECP-replaced cores or the valence-only GFN2-xTB core (computed from the undissected density, so independent of --auto-pi / --select-nobd). The remaining columns give the per-atom total electron population (ED) and electron delocalization (EDDB, the EDDB density integrated over the atom), each tagged with the scope suffix _G / _F / _P / _R. ED and EDDB each carry α and β sub-columns for open-shell inputs; for a closed-shell (restricted) reference these are undefined and print a centred dash (–).

Summary: three population numbers — ED (total electrons in the active subset), EDLB (localized; ED − EDDB), and EDDB (delocalized). For UHF / ROHF the α and β components are reported separately in the orbital and atomic tables.

Cyclic Delocalization Index (CDI): reported only for --pathway runs. CDI equals the smallest per-atom EDDB along the pathway — the maximum population of electrons that can delocalize uniformly around the cycle. CDI ≈ 0.9 per atom is strongly aromatic; CDI ≈ 0 is non- or anti-aromatic.

Closing line and the warning counter: the run terminates with a one-line time-stamp such as > Calculation completed on 2026-MM-DD. Total time: Xs. Whenever any non-fatal warning fired during the run, the closing line is annotated with a parenthetical count: > Calculation completed (with 1 warning!) on 2026-MM-DD. Total time: Xs. The annotation appears even in true-quiet (-q) mode where the warning text itself is suppressed — so a batch user always knows when something needs a closer look. To see the actual warning message, rerun the same command without -q. ECP-related inconsistencies (missing [Pseudo] in molden, Q-Chem GUI=2 quirk in fchk) are fatal errors — they stop the run rather than just counting; see §2 for the recovery steps.

8. Known Issues and Limitations

Tested QC programs and formats: validated against .fchk files from Gaussian 16 and Q-Chem 6 (HF / DFT and post-HF), .json and .molden files from ORCA 6 (HF / DFT and post-HF via orca_2json and orca_2mkl), .molden files from Multiwfn-converted wavefunctions, native .tmol bundles from Turbomole, and .gms output files from GAMESS-US (RHF / UHF / ROHF / MCSCF on RUNTYP = ENERGY / OPTIMIZE / SADPOINT). Cross-program agreement on benzene at cc-pVDZ is 4–5 significant figures for both MP2 and CCSD; the WF6 ECP benchmark agrees to ~3 significant figures across Gaussian / ORCA fchk / json / molden at RHF / def2-TZVPP. The built-in GFN2-xTB engine for the .xyz lane is validated against the reference tblite implementation across 81 systems covering 26 elements (H…W) including first / second / third-row transition metals, lanthanides, and main-group hypervalent compounds — final per-atom Mulliken charges agree to ~10−6e at tight SCC convergence, and total energies match Grimme’s reference xtb binary to within ~10−4 Eh.

Supported basis functions. The native lane (.fchk / .json / .molden) supports angular momenta up to k-type (l = 7), covering every standard basis set in routine use including cc-pV6Z. Overlaps are evaluated by direct Gauss-Hermite quadrature (no Obara-Saika recursion), so each shell is treated explicitly. The legacy .49 visualisation lane supports up to h-type (l = 5) only; for cc-pV6Z and similar (i / k functions) please use the matching native input format.

Post-HF density requirements. The QC program must be told to write the relaxed (or linearized) correlated density:

If the correlated block is missing, runEDDB silently falls back to the SCF reference density and the run is (correctly) classified as plain HF/DFT. The Reference type: line in the verbose-mode Stage 1 detail block reports the actual classification.

HLRL — NAO pictures at large basis sets, and a viewer warning. From cc-pVQZ onwards (worse at cc-pV5Z/6Z, def2-QZVPP) the rigorous NAO algorithm stores each NMB orbital as a large, near-cancelling coefficient expansion spread over high-L shells and neighbouring atoms — an inherent property of the NAO method, not a runEDDB artefact (NBO7 produces the same representation). The orbital function remains atom-localised; the fragile representation is the problem. Most molecular viewers evaluate high-L (f/g/h) pure harmonics approximately, which breaks the cancellation and displays the exported raw NAOs as heavily delocalised junk — verified (Jul 2026) in current Avogadro2 and IQMol, while Multiwfn (and exact grid evaluation) render the same files correctly. runEDDB’s fchk conventions are validated against Gaussian-written references. Mitigations, in order of preference: the default frozen-nmb algorithm has no L>3 content by construction — it renders correctly in every viewer and shows the physically polarised orbitals; orbital cubes (--export-cube ao[LIST]) are exact grid evaluations and immune to viewer basis handling for ANY algorithm (and are the only option beyond h functions, where no mainstream viewer reads the fchk at all); --nao-algorithm rigorous/nbo7legacy writes the raw standard coefficients for reproducing the viewer artefact itself. (The former Galerkin display projection of exported standard NAOs is opt-in via --export-lproj — its free-atom-like pictures over-correct by stripping the genuine polarisation tails, so it is no longer applied silently.) See the NAO construction algorithm paragraph in Section 4.

NBO archive (.49) — legacy lane. Population analyses (NOBD / orbital / atomic tables, summary) and all six visualisation outputs work via a parallel NBO-convention pipeline that mirrors the legacy runEDDB_nbo49 writers. The .49 path is provided for legacy compatibility only and will be removed once the native NAO driver completes its acceptance suite; for new projects, please use .fchk / .json / .molden.

Cube grid quality. The default grid (~100³ points) gives integration accuracy within ~1% for most systems. For publication images, use -c 150 or higher. The integrated density and its percentage of the analytical value are printed after each cube export for quality control.

9. Performance Tips

Parallel BOP analysis: use --ncores N to parallelize the BOP step. Speedup is nearly linear for large systems (100+ atoms).

 terminal
$ runEDDB -i large_molecule.fchk --ncores 4

Using every core (-n 0): --ncores 0 (equivalently -n auto) asks runEDDB to detect how many cores it may use and to run on all of them, so the one command adapts itself to whatever machine it lands on — laptop, workstation or node. It behaves identically on Linux, Windows and macOS, and the detected count is echoed right below the banner (Auto-detected N available CPU cores), so every log records the thread count that was actually used. On Linux the number comes from the process’ CPU affinity mask rather than from the machine as a whole, so a batch allocation is honoured: a job given 8 cores of a 128-core node through SLURM / taskset resolves -n 0 to 8, not to 128.

NOTE — more cores is not always faster. -n 0 is deliberately literal: it takes every core it is allowed to use, which is what you want on a desktop, a laptop or a single-socket server, but is rarely what you want on a large many-core machine. The dense linear algebra that dominates the NAO/BOP stages stops scaling after a few tens of threads, and past that point the extra threads spend their time synchronising instead of computing — a cost that grows sharply on dual- or multi-socket systems, where threads on one socket must reach across the interconnect for memory attached to the other. The effect is not subtle: on a dual-socket 128-core EPYC, a large-basis (aug-cc-pV5Z) benchmark took 2.2 s with -n 8 and 41 s with -n 0 — roughly 20× slower while burning 75 CPU-minutes instead of 16 CPU-seconds. As a rule of thumb: use -n 0 on laptops, desktops and single-socket servers; on big multi-socket nodes set an explicit -n 8–32 (and, if the node is shared, confine the job with numactl / taskset so that -n 0 follows the affinity mask — but see the NUMA note below before confining it to a single socket for speed, which is counter-productive). Cube-grid evaluation is the exception — it parallelises almost perfectly, so grid-dominated jobs do benefit from high core counts. When in doubt, time a short run at a few settings rather than assuming.

Large NUMA machines — interleave memory only when the job spans several nodes. Linux places each memory page on the NUMA node of whichever thread first touches it, which for runEDDB is the input-parsing stage. That default is ideal as long as the worker threads stay on that same node, and harmful once they do not: the large matrices stay concentrated on one node while every thread elsewhere reaches for them across the interconnect. Which regime you are in depends on how -n compares with the cores per NUMA node (numactl --hardware).

$ numactl --hardware   # how many nodes, how many cores each
$ numactl --interleave=all runEDDB -i large.fchk -n 128   # only when spanning nodes

Measured on a dual-socket AMD EPYC 9554 (128 cores, 8 NUMA nodes of 16 cores, SMT off):

So: leave the default alone when -n is at or below the cores per node, and add --interleave=all when you deliberately spread a big job across nodes. Note also that binding a large job to a single socket for speed is counter-productive — the workload is limited by memory bandwidth, and one socket has half the memory controllers.

GFN2-xTB on multiple cores: for the .xyz lane, --ncores N also parallelizes the GFN2-xTB SCC itself (the heaviest step for large molecules). The engine auto-sizes its thread pools to the cores you request, so requesting more cores than the job can use no longer wastes CPU. As a rule of thumb, the GFN2-xTB SCC keeps speeding up to roughly --ncores 16–32 on a few-hundred-atom system; beyond that the gains taper off (it is dominated by linear-algebra steps that do not scale indefinitely). For small molecules, --ncores 1–4 is plenty.

Analysis basis subset: the default -b nvb (Val-only) is the fastest option, since the BOP cycle scales with the number of NAOs in the working basis. -b nmb (Cor + Val) costs only marginally more (~10–30% depending on element). -b nao (Cor + Val + Ryd) is significantly slower at large basis sets — use it for completeness checks rather than routine analysis.

Cube grid sizing: the default --cube-size 100 (~1M points) is fine for routine work; for publication-quality figures and large systems we recommend at least 150. Grid evaluation can be demanding but parallelizes perfectly, so use as many cores as you can (--ncores / -n).

10. Citations

If you use runEDDB in your research, please consider to cite the following works:

Tip — let runEDDB pick the references for you. Add --cite both to any run to write the exact, de-duplicated set of papers for that run to <stem>.bib (BibTeX) and <stem>.refs.txt (plain list). The set is method- and option-dependent: the NAO / NPA (Reed et al.), BOP and core EDDB papers always; the NOBD paper with -s / -a; the EDDBP (-p / -r) or EDDBF (-f) paper; the AO-resolved EDDB paper with --table / --export-fchk ao; the Bond-Delocalization-Field paper for a bdf / dbdf cube; the frozen-NMB NAO paper (in preparation) whenever the default --nao-algorithm frozen-nmb is active; and, for the .xyz lane, GFN2-xTB + DFT-D4 (spGFN2-xTB on spin-polarised runs). Add -v to also see them on screen, grouped by analysis stage. The runEDDB-method catalogue follows (the NAO / NPA reference is Reed, Weinstock, Weinhold, J. Chem. Phys. 83, 735−746, 1985, DOI 10.1063/1.449486; GFN2-xTB / DFT-D4 are listed under it).

  1. Electron delocalization index based on bond order orbitals.
    D.W. Szczepanik (), E.J. Zak, K. Dyduch, J. Mrozek
    Chemical Physics Letters  593 (2014) 154−159. DOI: 10.1016/j.cplett.2014.01.006.   URL 

  2. A uniform approach to the description of multicenter bonding.
    D.W. Szczepanik (), M. Andrzejak, K. Dyduch, E.J. Zak, M. Makowski, G. Mazur, J. Mrozek,
    Physical Chemistry Chemical Physics  16 (2014) 20514−20523. DOI: 10.1039/c4cp02932a.   URL 

  3. A new perspective on quantifying electron localization and delocalization in molecular systems.
    D.W. Szczepanik ()
    Computational and Theoretical Chemistry  1080 (2016) 33−37. DOI: 10.1016/j.comptc.2016.02.003.   URL 

  4. On the three-center orbital projection formalism within the electron density of delocalized bonds method.
    D.W. Szczepanik ()
    Computational and Theoretical Chemistry  1100 (2017), 13−17. DOI: 10.1016/j.comptc.2016.12.003.   URL 

  5. The electron density of delocalized bonds (EDDB) applied for quantifying aromaticity.
    D.W. Szczepanik (), M. Andrzejak, J. Dominikowska, B. Pawełek, T.M. Krygowski, H. Szatylowicz, M. Solà
    Physical Chemistry Chemical Physics  19 (2017) 28970−28981. DOI: 10.1039/c7cp06114e.   URL 

  6. Electron delocalization in planar metallacycles: Hückel or Möbius aromatic?
    D.W. Szczepanik (), M. Solà ()
    ChemistryOpen  8 (2019) 219−227. DOI: 10.1002/open.201900014.   URL 

  7. The electron density of delocalized bonds (EDDB) as a measure of local and global aromaticity
    D.W. Szczepanik (), M. Solà ()
    in
    Aromaticity: Modern Computational Methods and Applications
    Edited by I. Fernández
    Chapter 8 (pp. 259−283), Elsevier, 2021.
    ISBN: 978-0-12-822723-7
    DOI: 10.1016/b978-0-12-822723-7.00008-x.

  8. Decoding chemical resonance in π-conjugated systems.
    D.W. Szczepanik (), P.A. Wieczorkiewicz
    ACS Physical Chemistry Au  (2026). DOI: 10.1021/acsphyschemau.6c00031.   URL 
    — the Bond-Delocalization-Field (BDF) paper, cited whenever a bdf / dbdf cube is exported.

  9. Natural atomic orbitals at the complete-basis-set limit: a frozen-minimal-basis two-cycle construction.
    D.W. Szczepanik ()
    Journal of Computational Chemistry  (2026), in preparation.
    — the frozen-NMB NAO construction, cited whenever the default --nao-algorithm frozen-nmb is active.

When you analyse a plain .xyz geometry through the built-in GFN2-xTB lane, the underlying electronic-structure method is not ours — it is the work of Grimme and co-workers. Please also cite the relevant original method papers:

  1. GFN2-xTB — An Accurate and Broadly Parametrized Self-Consistent Tight-Binding Quantum Chemical Method with Multipole Electrostatics and Density-Dependent Dispersion Contributions.
    C. Bannwarth, S. Ehlert, S. Grimme
    Journal of Chemical Theory and Computation  15 (2019) 1652−1671. DOI: 10.1021/acs.jctc.8b01176.   URL 
    — the GFN2-xTB Hamiltonian used for every .xyz calculation (minimal valence vSTO-nG basis, multipole / anisotropic electrostatics, density-dependent dispersion).

  2. A generally applicable atomic-charge dependent London dispersion correction.
    E. Caldeweyher, S. Ehlert, A. Hansen, H. Neugebauer, S. Spicher, C. Bannwarth, S. Grimme
    The Journal of Chemical Physics  150 (2019) 154122. DOI: 10.1063/1.5090222.   URL 
    — the self-consistent DFT-D4 dispersion correction (charge-dependent C6 coefficients + ATM three-body term) included in the GFN2-xTB energy.

  3. High-throughput screening of spin states for transition metal complexes with spin-polarized extended tight-binding methods.
    H. Neugebauer, B. Bädorf, S. Ehlert, A. Hansen, S. Grimme
    Journal of Computational Chemistry  44 (2023) 2120−2129. DOI: 10.1002/jcc.27185.   URL 
    — the spin-polarized extension (spGFN2-xTB) used for open-shell systems (multiplicity > 1).

runEDDB’s GFN2-xTB lane implements the GFN2-xTB and DFT-D4 methods described above and is validated against Grimme’s reference implementation. Portions of it are derived from the corresponding open-source reference code — dftd4 and tblite (LGPL-3.0-or-later) and mctc-lib (Apache-2.0) — and are used and redistributed under those licenses. See the THIRD-PARTY-LICENSES.txt file included with the program for full attributions and license texts.

11. Contact

Author and main contributor: dr hab. Dariusz W. Szczepanik, prof. UJ

Contributors: mgr Pawel A. Wieczorkiewicz, dr Ouissam El Bakouri.

Project e-mail: runeddb@gmail.com


HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Quick Start       Manual