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)

Every option of runEDDB, by topic, as the program itself prints it with runEDDB --help TOPIC; runEDDB --examples TOPIC gives ready-to-run commands. This page is generated from the program's help text, so it always matches the compilation it belongs to. What each option is for, with worked examples, is on the guide page linked under every topic.

Topics
  1. input: input formats, built-in models (@NAME), geometry options
  2. eddb: EDDB scopes, NOBD dissection, analysis basis, NAO algorithms
  3. tables: analysis tables printed to the terminal (--table)
  4. export: CUBE / FCHK / JSON files, 2D maps, file naming, grids
  5. nmr: NMR shielding, NICS, ring / bond currents, current-density maps
  6. afm: nc-AFM and STM model images
  7. xtb: built-in GFN2-xTB engine
  8. runtime: cores, verbosity, citations, diagnostics

1. Input formats, built-in models (@NAME), geometry options --help input

Guide: input

Basic usage

runEDDB --input FILE.ext  [ Options ]
FILE.ext:  geometry     {mol | mol2 | pdb | sdf | xyz}   (built-in GFN2-xTB)
           wavefunction {49 | fchk | gms | json | molden | tmol}

Input

--input, -i FILEInput structure / wavefunction file (extensions above)
--input, -i @NAMEBuilt-in molecular model library (educational / test geometries compiled into the binary). Flat names and dataset paths both work: -i @coronene, -i @porphine, -i @gmtkn55/c60iso/5. `-i @list` prints the catalog; -v shows the model name + geometry level at load.
--density-source XForce density SCF|MP2|CI|CC|RhoCI|Rho2 (default: highest)
--no-ecp(.molden) assert no ECP cores present; skip the ECP check

Geometry (geometry input only)

--xyz-center [geom|mass]Recenter at origin: geometric centroid (geom, default) or center of mass (mass). Rigid; keeps bonds/angles. OFF by default. Not for .49.
--xyz-translate x,y,zExplicit fixed translation (Angstrom); exclusive with --xyz-center. Reuse one vector to keep a trajectory in a single frame (voxel-comparable cubes).
--xyz-frame NPick structure N (1-based) from a multi-frame .xyz /.sdf / .mol2 / .pdb (default 1).
--xyz-charge NOverride molecular charge (signed integer; default 0).
--xyz-mult MOverride spin multiplicity 2S+1 (M>=1; default 1).

Examples

runEDDB -i @listcatalog of the built-in molecules
runEDDB -i @porphine -v-v also prints the model name and its geometry level
runEDDB -i @rings/cot2-charged model: charge and multiplicity come from the library
runEDDB -i @benzene --xyz-charge 1 --xyz-mult 2benzene radical cation (UHF GFN2-xTB)
runEDDB -i traj.xyz --xyz-frame 3 --xyz-centerframe 3 of a trajectory, centred (your own file)
runEDDB -i mol.molden -b nmbany wavefunction format: 49 fchk gms json molden tmol (your own file)

2. EDDB scopes, NOBD dissection, analysis basis, NAO algorithms --help eddb

Guide: analysis

EDDB scope (mutually exclusive; default: global)

--global, -gEDDB_G - entire molecular system (default)
--heavy-atoms, -hEDDB_H - like EDDB_G (whole system) but every bond to a hydrogen is removed from the connectivity / BOP mask, so delocalization is analysed on the heavy-atom framework only (fast for pi-systems; avoids sigma/pi mixing from C-H hyperconjugation). NOTE: -h is this scope, NOT help.
--fragment, -f LISTEDDB_F - a chosen fragment, e.g. -f 1:6,10,12
--pathway, -p CHAINEDDB_P - a bond pathway, e.g. -p 1-2-3-4-5-6-1
--ring-detect, -r LISTEDDB_R - auto-detect rings of the listed sizes (3..999),
e.g. -r 5 | -r 6,7,8 | -r 5,6:8. Rings are found in the Wiberg bond graph; their edges form the BOP pair matrix (an automatic -p). The full list goes to <stem>.rings (one -p string per line); the on-screen block shows 20.
--wbo-thresh, -w XWiberg cutoff for the BOP pair gate (default 0.001); X >= 0; X = 0 keeps every pair with any non-zero coupling (cost grows as N^2 -- pair with -f/-p/-r on large systems). WARNING: EDDB values from a run at a non-default gate are NOT comparable with default-gate or published values; -v flags the override. The --table bo / NBA gate tracks it at 10x. Distinct from --ring-thresh, which only shapes the -r graph.
--ring-thresh XWiberg cutoff for the ring graph (default 0.30, covalent bonds only; independent of the 0.001 BOP pair gate)

NOBD selection (dissection)

--select-nobd, -s LISTSelect NOBDs to dissect, e.g. -s 1:3,4,5 (LIST required; use --table nobd to view indices)
--auto-pi, -aAuto-select pi-type NOBDs (the pi-density component)

Analysis basis subset (default: nvb; .49 input: nmb)

--basis, -b VALUEnao: full NAO basis (Cor+Val+Ryd; slowest, complete)
nmb: Natural Minimal Basis (Cor+Val; default for .49)
nvb: Natural Valence Basis (Val; default, native input) Case-insensitive. On .49 (no Cor/Val split) nvb falls back to nmb (a one-line note prints under -v).
NOTE: the BOP atom-pair connectivity is ALWAYS built in the FULL NAO basis (Cor+Val+Ryd), whatever -b says; BOP then runs in the -b density. A -b series therefore differs only in the density, never in which pairs were counted. -f restricts that NAO mask afterwards; -p and -r remain authoritative.
--nao-algorithm ALGfrozen-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
ano-layers: cc-layers packaging, but each Rydberg layer direction is projected from tabulated atomic ANO vectors (built-in ano-pV5Z, H-Ar) -> correlation-aware layers from a plain SCF density
iano-layers: ano-layers with the NMB built as IAOs (Knizia) on the ANO-MB template: exact occupied-span coverage + fully ANO-referenced construction; needs occupied MOs in the input (restricted, no ECP)
nbo7legacy: alias of rigorous (kept for reproducing published raw-NAO exports)
--ano-basis FILEExternal ANO guide for ano-layers: a Gaussian94 .gbs file (Basis Set Exchange export). Elements present in the file override the built-in ano-pV5Z tables.
--ano-order MODERung ordering in ano-layers: molecular (DEFAULT; the ANO rungs are the candidate SET, the molecular occupation of each projected candidate picks the ORDER on strong evidence - fixes lone-pair/covalent reordering, e.g. N, C) or atomic (the tabulated occupation ladder; pre-2026-08-29 behavior).
--ano-core-rungs MODECore-correlating ANO rungs in the ano-layers ladder: skip (DEFAULT; such rungs correlate the frozen core and waste active-space slots under frozen-core MP2/CCSD replays) or keep (include them; use for all-electron correlation studies). Tagged elements: B-Ne, Al-Ar (H/He have no core; Li/Be/Na/Mg ladders are kept untagged in v1 and warn under skip).
--ano-override-gate MODEChannel gate for the molecular rung override: nmb (DEFAULT; override considered only in channels where the free atom has a valence shell - the P0 calibration verdict: harmful overrides live exclusively in valence-less channels), sphys (nmb plus the dens-vs-IAO s_phys threshold; needs occupied MOs, falls back to nmb) or off (pre-gate behavior).
--no-nrepSkip the N-representability correction (default: on)
--force-nrepLegacy alias; the correction is now the default

Examples

runEDDB -i @naphthalene -hEDDB_H: the heavy-atom framework (bonds to H removed)
runEDDB -i @naphthalene -f 1:6EDDB_F of the fragment made of atoms 1-6
runEDDB -i @naphthalene -p 1-2-3-4-9-10-1EDDB_P of one ring given as a closed pathway
runEDDB -i @coronene -r 6 -api-EDDB_R of every six-membered ring; list in coronene.rings
runEDDB -i @benzene -s 1:3 --table nobddissect NOBDs 1-3 (indices from --table nobd)
runEDDB -i @benzene -a -b naoanalysis in the full NAO basis instead of the default nvb

3. Analysis tables printed to the terminal (--table) --help tables

Guide: analysis

Print analysis tables to the terminal (comma-separated LIST)

--table LISTmo: per-MO ED/EDLB/EDDB (needs canonical SCF MOs)
no: NO occupancy (MR / spin-contamination under -v)
bo: bond-order orbitals, sigma/pi/delta/phi
nobd: NOBD-resolution table
ao: natural population, atomic-orbital resolution
subshell: natural population, subshell resolution (2p = 2p1+2p2+2p3)
shell: natural population, shell resolution (2 = 2s+2p; Rydberg-layer truncation diagnosis)
npa: natural population, condensed-atomic (charge q_N)
afm | stm: nc-AFM / STM model values above every bond (runEDDB --help afm)
nmr | nmr-nobd | nmr-mo | nmr-homo[N] | nmr-somo: NMR shielding tables (runEDDB --help nmr)
all: every applicable table (nmr is never implied)
order: mo,no,bo (pre) -> nobd -> ao,subshell,shell,npa,nmr

Examples

runEDDB -i @benzene --table nobd,npaNOBD resolution and natural charges
runEDDB -i @benzene --table moED / EDLB / EDDB carried by every MO
runEDDB -i @benzene --table bobond-order orbitals: sigma / pi / delta / phi parts
runEDDB -i @naphthalene -a --table allevery applicable table at once

4. CUBE / FCHK / JSON files, 2D maps, file naming, grids --help export

Guide: maps

Export volumetric data to Gaussian CUBE (comma-separated LIST, order kept)

--export-cube LISTed: electron density (pi-ED under -a / -s)
eddb: EDDB (delocalized) density
edlb: EDLB (localized) density = D_tot - D_del
bdf: bond-delocalization field = 2*D_del - D_tot
ded | deddb | dedlb | dbdf: differentials vs --cube-ref
icss* | acid* | divj*: magnetic maps (runEDDB --help nmr)
ao|no|nobd|bo|xtb: ORBITAL cubes (one .cube per orbital), optional [LIST] of 1-based indices, e.g. ao[2,4,11-15]; no list = all orbitals of the lane (guarded at 64)
e.g. --export-cube ed,eddb,deddb --cube-ref base.cube --export-cube ao[2,4] -b nmb (NMB orbital cubes)
--cube-ref FILEVoxel-align every exported cube to FILE's grid and supply the baseline for the differential tokens (which require it). Differentials: native lane only; geometries must share a common frame (or use --cube-align).
--cube-align [FRAGMENT]Rigidly superpose the current geometry onto the --cube-ref frame (Kabsch: x_aligned = R*x + t), then map the exported field(s) into that frame. Works for the differential tokens AND the orbital lanes (ao/no/bo/nobd/xtb). Removes arbitrary translation + rotation only; internal deformation stays (RMSD reported). Needs --cube-ref. No FRAGMENT list => reuse --fragment. Opt-in.
--cube-orb2densCollapse an orbital lane (ao/no/bo/nobd/xtb) into ONE occupation-weighted density cube rho = sum occ_i*|psi_i|^2 (<stem>.<LANE>_density.cube), not one cube per orbital; composes with --cube-ref / --cube-align. Opt-in.
--export-lprojApply the legacy Galerkin L-projection to the coefficients written by --export-fchk ao (retired former default: compact free-atom-like pictures, polarization tails stripped). Cubes are never projected — they are exact grid evaluations.

2D maps in a plane (--export-map, comma-separated LIST)

--export-map LIST2D maps on a lattice in a plane, written as .map.dat (u v x y z value per line, blocks per u: gnuplot pm3d, numpy):
ed | eddb | edlb | bdf: density slices (e/bohr^3, same scope and dissection as the cubes: <stem>.EDDB_G.map.dat)
icss* | jcur*: runEDDB --help nmr; afm* | stm* : runEDDB --help afm
--map-plane SPECThe plane: ring N[,h] = h Angstrom above NICS ring N (normal of the ring; needs --nics-rings/--nics-ring); fit[,h] = best-fit plane of the heavy atoms (default, h = 1.0); atoms i,j,k[,h] = plane through three atoms; x=V | y=V | z=V = a frame plane. The lattice covers the atoms plus the box margin (--cube-margin, 10 A). radial[,h] (--table afm / stm): every bond gets its own normal from the molecular centroid (cages, e.g. C60).
--map-slab h1,h2[,n]The map = mean of n planes (5) between h1 and h2 Angstrom above the base plane; 'none' = one plane. Default for the density slices: 1.5,2.5 (a plane at one height under- or over-states N/O whose 2p are contracted); the ICSS maps use one plane unless --map-slab is given.
--map-step HLattice step of the 2D maps in Angstrom (default 0.25).

Export orbitals / wavefunction to Gaussian FCHK (comma-separated LIST)

--export-fchk LISTno: natural orbitals of the total density
nobd: natural orbitals of bond delocalization
ao: AO vectors in the -b basis; <stem>.<BASIS>.fchk
bo: bond-order orbitals (aliases: boo, nba)
xtb: GFN2-xTB wavefunction (vSTO-nG; geometry input)
e.g. --export-fchk nobd,ao or --export-fchk bo -b nao

Export to ORCA-convention JSON (comma-separated LIST)

--export-json LISTao: the FULL NAO set (every T_aonao column, independent of -b) written numerically in the native ORCA JSON conventions, for any --nao-algorithm: cc-layers -> <stem>.ccNAO.json (with ccLayer indices); rigorous / frozen-nmb / nbo7legacy -> <stem>.NAO.json (ccLayer = -1). A metadata sidecar <stem>.*.meta.json is always written. Occupancy / OrbitalEnergy in the file are 0.0 placeholders; per-NAO populations live in the runEDDB metadata block.
no: natural orbitals of the total density, REAL occupancies in Occupancy (Tr = N_electrons), all n_nao columns (square/gbw-safe when n_nao = n_ao) -> <stem>.NO.json (+ sidecar).
nobd: natural orbitals for bond delocalization with REAL occupancies in Occupancy (Tr = EDDB population), padded with the exactly S-orthonormal NAO complement (Occupancy 0.0) to a square, gbw-safe MO matrix -> <stem>.NOBD_<SCOPE>.json (+ sidecar); basis follows -b, scope follows -g/-h/-f/-p/-r.
bo: NBA bond-order orbitals in --table bo order, REAL sigma^2 occupancies (aliases: boo, nba) -> <stem>.BO.json (+ sidecar). CAUTION: BOOs of different pairs overlap -> NOT S-orthonormal, NOT square, NOT for orca_2json -gbw (consume the .json directly).
xtb: converged GFN2-xTB wavefunction (vSTO-nG), REAL occupancies AND REAL orbital energies (Eh); UHF layout (alpha block + beta block) for open shells -> <stem>.XTB.json (+ sidecar). Geometry input only; GFN2 effective core, NOT all-electron (see metadata).
raweddb: diagnostic; the BOP matrix DDM BEFORE the congruence D_eddb = D.DDM.D (forces -g -b nao; HF/DFT only) as three square sets, eigenvalues in Occupancy: <stem>.RAWEDDB_bond.json (bonding channel), <stem>.RAWEDDB_anti.json (anti-bonding channel), <stem>.RAWEDDB_sum.json (DDM = bond + anti; block-diagonal over atoms, one-centre columns) and <stem>.RAWEDDB_meta.json (formulas, pairs, EDDB_G). ao/no/nobd/bo/raweddb require ORCA .json input (restricted, spherical, no ECP). Every file ships with a <name>.meta.json metadata sidecar.

Output naming (files: <stem>.<TOKEN>_<SCOPE>.<ext>)

--out-prefix NAMEOverride the filename stem for the whole batch
--out-dir DIRWrite all generated files into DIR (created if absent)

Grid

--cube-size, -c NPoints per axis, ~|N|^3 total (default 100): N>0 scope-aware grid; N<0 whole molecule; N=0 skip cubes. Clone an existing grid with --cube-ref FILE.
--cube-margin RMargin (Angstrom) added around the atoms of the scope on every side of the box (default 3.2 = 6 Bohr). The ICSS maps use 10 unless given (Kleinpeter's lattice; their 0.1 ppm surfaces reach 7-9 A). Ignored with --cube-ref.

Examples

runEDDB -i @naphthalene -a --export-cube eddb,bdfpi-EDDB and BDF cubes
runEDDB -i @benzene --export-cube nobd[1-3]one cube per NOBD (orbitals 1-3)
runEDDB -i @benzene --export-map ed,eddbdensity slices 1.5-2.5 A above the plane
runEDDB -i @benzene --export-fchk xtbthe GFN2-xTB wavefunction as a Gaussian FCHK
runEDDB -i @benzene --export-json xtbthe same in the ORCA JSON convention
runEDDB -i @naphthalene -a --export-cube eddb --out-dir mapsall files go to maps/

5. NMR shielding, NICS, ring / bond currents, current-density maps --help nmr

Guide: nmr

NMR shielding tables (--table, comma-separated LIST)

--table LISTnmr: isotropic shielding of every nucleus (GIAO, or CTOCD-DZ with --nmr-log) split into EDLB_G, EDDB_G (each as total|dia|para or total|trans|rot) and other; with -a/-s every column is restricted to the selected NOBDs. Input: Gaussian .fchk of an NMR job (Magnetic Field P1 (GIAO)) or ORCA .json, '! NMR KeepDens', exported by orca_2json with BaseName.json.conf = { Densities : [ all ] }; with -f/-p/-r/-h the columns are rest_X | EDDB_X (rest_X = valence - EDDB_X, not EDLB). Geometry input (.xyz, .mol, ...): NICS only, from the uncoupled GFN2-xTB response in the CTOCD-DZ gauge (no nuclei table, no .nmrref; a --nics* probe is required); see --xtb-coupled for the coupled response.
nmr-nobd: the nmr tables + <stem>.NMR_NOBD.txt: EDDB_G column resolved by NOBD for every nucleus / NICS probe: ALL non-zero-occupied NOBDs or only the -a/-s selected ones (recommended: without -a/-s the file can be huge).
nmr-mo: the nmr tables + <stem>.NMR_MO.txt: total shielding resolved by occupied canonical MO (alpha and beta sections for UHF); always ALL occupied MOs and the FULL sigma (-a/-s select NOBDs only).
nmr-homo[N]: the nmr tables + a table with the shielding carried by HOMO-N..HOMO (N = 0..9; nmr-homo = the HOMO) split into EDLB_G / EDDB_G / other + rest (all other occupied MOs). UHF: level k pairs alpha_k with beta_k; the top levels are the singly occupied alphas (Steiner-Fowler picture).
nmr-somo: same table for all singly occupied MOs.

NICS probes and ring / bond currents (NICS = -sigma, same partition)

--nics-rings LISTDetected rings, -r syntax (e.g. 6 or 5,6:8): NICS(0), NICS(1) = mean of the +1/-1 faces and their zz components
--nics-ring CHAINExplicit atom cycle(s), -p syntax (e.g. 1-2-3-4-5-6-1,7-8-9-10-11-12-7)
--nics-scan R[,step]Scan along the ring normal from -R to +R Angstrom (step 0 or omitted: only -R and +R); iso and zz rows
--nics x,y,z[,x,y,z...]Explicit probe points (Angstrom, frame of the .fchk = Gaussian standard orientation)
--ring-current [LIST]Ring current strengths I_cyc (nA/T): the Ampere line
--rcs [LIST]integral of the induced field around a rectangle through a bond (cycle centre -> beyond the bond, +-h along the normal) = the GIMIC plane integral (Stokes), split into EDLB/EDDB (and -a/-s); I_cyc = min over the planes from the centre to the vacuum (outward bonds; every bond shared: planes through the neighbours) = the mesh current of the cycle (the coherent cyclic current, analogue of the CDI). No LIST: every NICS ring. LIST (-p syntax, comma separated): closed cycles i-j-k-...-i only (own centre, need not be a NICS ring); an open chain or a bond is an error.
--bond-current [LIST]Bond current strengths I_bond (nA/T), the same
--bcs [LIST]integral bond by bond: every bond of every NICS ring (no LIST), or of the listed cycles i-j-k-...-i (plus their I_cyc row), chains i-j-k-... and bonds i-j (from the centre of the ring / listed cycle that contains the bond). Both options may be combined; parallel over probes.
--bcs-box L,h[,n]Box beyond the bond midpoint L, half-height h (Angstrom, default 5,5) and Gauss points per edge n (default 12)

NMR lanes, MO sets and chemical shifts

--nmr-kernel [SPEC]Wavefunction file WITHOUT NMR response data: the NMR /NICS / ring-current tables are still computed, as the APPROXIMATE CTOCD-DZ response of the input MOs (all MOs + energies, SCF reference; the stage line, every caption and a WARNING say so). SPEC = the method that made the MOs (b3lyp, pbe0, hf, pbe, ...; @list prints the table with its exact-exchange fraction a_x): pure functionals need no kernel (exact for GGA, meta-GGA ~2 %); hybrids and HF get the sTDA-type exchange kernel in the natural minimal basis at a_x (no free parameter, basis independent): hybrid ring currents within ~3 %, HF ~10 % low, pi-donor rings 5-20 % low. Without SPEC the method is read from the .fchk header, the Gaussian route, the ORCA .out next to a .json/.molden, the Turbomole control or the GAMESS log; if none, the DFT default a_x = 0.20 is used and the first table says so. A given SPEC overrides the detected method; dft asks for the default; a_x[,y] is an explicit fraction (research). Range-separated and double hybrids: short-range / hybrid part with a WARNING. Ignored when the input has NMR data (unless --nmr-approx).
--nmr-approxUse the APPROXIMATE CTOCD-DZ lane (--nmr-kernel) even when the input carries NMR response data (WARNING says so):
e.g. ipsocentric MO layers (--nmr-mos) from a GIAO job, whose own per-MO split is not ipsocentric. Implies --nmr-kernel; the method is detected or given by SPEC.
--nmr-mos LISTSame table as nmr-homo[N] for an explicit set of occupied MOs (numbering of --table mo): n, n:m, all, homo, homo-N, ranges ending at homo-N (homo-2:homo, 5:homo-1), and -TOKEN removes (all,-homo = every occupied MO but the HOMO; 21:22; all,-1:6); UHF: a/b prefixes pick one spin (a5:12,b5:11,ahomo), no prefix = both. Implies --table nmr; the set also gets its own current-density maps. With --rcs / --bcs: a RING CURRENTS OF table for the set (set | EDLB | EDDB | rest = total - set; I_cyc on the plane of the total's I_cyc). Ipsocentric (Steiner-Fowler) on the CTOCD-DZ lane only, not on GIAO.
--nmr-ref SPECChemical shifts delta = sigma(ref) - sigma (implies --table nmr). Two steps: (1) runEDDB -i tms.fchk --table nmr writes tms.nmrref (element-averaged sigma AND its EDLB/EDDB partition columns); (2) runEDDB -i mol.fchk --nmr-ref tms.nmrref adds a CHEMICAL SHIFTS table, delta column by column (positive = deshielded vs. the reference). SPEC = FILE.nmrref, or an explicit list H=31.7,C=185.4 (delta_iso only). Same method, basis, gauge (GIAO/CTOCD-DZ) and -b in both runs; elements absent from the reference are skipped; under -a/-s no .nmrref is written and --nmr-ref is ignored (run the molecule twice for shifts AND the pi dissection).
--nmr-xdens FILETurbomole: XDENS written by mpshift with $gimic in control (GIAO response densities for a .tmol input). Default: XDENS in the directory of the .tmol file.
--nmr-log FILEGaussian .log written with IOp(10/33=2): the CPHF response densities are read from its P1 blocks instead of the .fchk. REQUIRED for NMR=CSGT (6 response sets: field + momentum; the .fchk carries none). Default
probe: <stem>.log / .out when the .fchk has no P1 section. Gauge method (GIAO/CSGT) is detected from the file and shown in the table title.

Magnetic maps: ICSS, ACID, div J and the current density J

--export-cube LISTicss | icss-edlb | icss-eddb: ICSS shielding maps, the isotropic shielding sigma_iso (ppm, shielding sign: NICS = -value) on the grid and its EDLB_G / EDDB_G shares (-a/-s: EDDB_G of the selected NOBDs); implies the NMR stage (any lane, APPROXIMATE ones marked); default grid: 0.5 A step and a 10 A box margin unless -c / --cube-margin are given
acid | acid-edlb | acid-eddb: ACID (Herges 2001), the anisotropy of the induced current density tensor dT_S [a.u., standard isolevel 0.05] of the total current, of its EDLB_G / EDDB_G parts (-a/-s: the selected NOBDs); an active MO set adds <stem>.ACID_MOS.cube; grid as jcur (0.20 A, 4.0 A margin); needs the three field directions
divj | divj-edlb | divj-eddb: the divergence div J of the induced current density (nA T^-1 A^-3; central differences of the kernel, step 1e-4 A) for the field of --field-axis: total current (exactly 0 in a complete basis: the residual is the finite-basis charge-conservation error), EDLB_G /EDDB_G parts (-a/-s: selected NOBDs; their divergence is the exchange of current between the channels), MO set -> <stem>.DIVJ_MOS.cube; prints the divergence table (maxima, integrated sources and sinks); grid as jcur
--icss-checkpoint [MIN]Checkpoint the 3D ICSS pass: every MIN minutes (10) the partial sums go to <stem>.ICSS*.tmp; a run that finds a matching file (same grid, lane, components) resumes from it with a result identical to an uninterrupted pass; the file is removed when the pass completes.
--export-map LISTicss | icss-edlb | icss-eddb: the ICSS maps (ppm; --icss-axis adds the nn maps ICSS_zz... / ICSS_nn...)
jcur | jcur-edlb | jcur-eddb: the magnetically induced current density J/B (nA T^-1 A^-2) in the plane for a unit field along the plane normal (or --field-axis): columns Ju Jv Jn and J_dia = the in-plane modulus signed diatropic +, about the plane origin; default height 1 A; an active MO set (--nmr-mos, nmr-homo[N], nmr-somo) adds <stem>.JCUR_MOS.map.dat; -a/-s: the EDDB_G(sel) field
--export-vtk acidAdds the ACID scalars ACID_total, ACID_EDLB, ... [a.u.] to <stem>.JCUR.vtk (implies jcur): isosurface + the J arrows on it is the classic ACID picture (Contour + Glyph)
--export-vtk divjAdds the divergence scalars divJ_total, divJ_EDLB, ... [nA T^-1 A^-3] to <stem>.JCUR.vtk (implies jcur), prints the divergence table (see --export-cube divj)
--export-vtk jcurThe induced current density J/B on the cube grid (0.20 A step, 4.0 A margin unless -c/--cube-margin) as ONE legacy VTK file <stem>.JCUR.vtk: vector fields J_total, J_EDLB, J_EDDB, J_other [, J_EDDB_sel] [, J_MOset] and the signed moduli J_*_dia (diatropic +), plus <stem>.JCUR_atoms.vtk (the skeleton); ParaView: Glyph / Stream Tracer / Slice. Every lane: GIAO (.fchk/ORCA/Turbomole), CSGT .log, the automatic --nmr-kernel lane, GFN2-xTB; field along --field-axis, default the ring-1 normal / best fit plane RUNEDDB_JCUR_CHECK=1: flux through the --bcs planes vs the Ampere table (Stokes) and the AO-gradient self-test.
--icss-axis SPECAlso write the nn component of the ICSS maps (field and probe along n; the NICS_zz analogue): SPEC = z | x | y (frame axes, files ICSS_zz...), ring N (normal of NICS ring N, needs --nics-rings/--nics-ring) or x,y,z (a vector; files ICSS_nn...). The isotropic maps stay.
--field-axis SPECThe same SPEC as the field direction of current density maps (--export-vtk jcur, --export-map jcur*); alias.
Plane of the 2D maps: --map-plane / --map-slab /--map-step (runEDDB --help export)

Examples

runEDDB -i @benzene --nics-rings 6NICS(0), NICS(1), NICS(1)zz split into EDLB / EDDB
runEDDB -i @benzene --nics-rings 6 --nics-scan 3,0.5NICS scan along the ring normal
runEDDB -i @naphthalene --nics-rings 6 --rcs -n 4ring current strengths I_cyc (nA/T)
runEDDB -i @rings/cyclobutadiene --nics-rings 4 --rcsparatropic current of a 4n ring
runEDDB -i @benzene --nics-rings 6 --nmr-mos homo-1:homo --rcscurrent carried by the two highest occupied MOs (MO layer)
runEDDB -i @benzene --nics-rings 6 --export-vtk jcur,acidcurrent density J and ACID in one .vtk file for ParaView
runEDDB -i @benzene --nics-rings 6 --export-map jcurJ in a plane 1 A above the ring
runEDDB -i mol.fchk --table nmrDFT: Gaussian NMR=GIAO .fchk (or ORCA .json) (your own file)
runEDDB -i mol.fchk --nmr-log mol.log --nmr-mos all,-homo --rcsDFT: NMR=CSGT with IOp(10/33=2); ipsocentric MO layers (your own file)
runEDDB -i mol.fchk --nmr-ref tms.nmrrefchemical shifts vs TMS (tms.fchk --table nmr) (your own file)

6. Nc-AFM and STM model images --help afm

Guide: afm

nc-AFM and STM model images

--table LISTafm: nc-AFM model contrast d2V/dz2 (eV/A^2) above every bond midpoint (WBO >= 0.3): total, EDLB_G, EDDB_G, with the bond length and the Wiberg bond order; model and tip height as --export-map afm
stm: STM window density (e/bohr^3, Tersoff-Hamann, --stm-bias) above each bond midpoint (WBO >= 0.3): total, EDLB_G, EDDB_G, next to R and the WBO; tip height as --export-map stm
--export-map LISTafm | afm-edlb | afm-eddb: rigid-tip nc-AFM model image d2V/dz2 [eV/A^2] of the Pauli repulsion V = A rho^alpha (Moll 2012) at the tip height (--map-plane h, 3.5 A) and its EDLB_G / EDDB_G shares V rho_X/rho (additive)
stm | stm-edlb | stm-eddb: constant-height STM image in the Tersoff-Hamann approximation: the density (e/bohr^3) of the MOs inside the bias window (--stm-bias) at the tip height (--map-plane h, 3.5 A) and its EDLB_G /EDDB_G parts (additive; occupied window only)
--stm-bias VBias window of the stm maps / table in volts (default -2.0): V < 0 images the occupied MOs from the HOMO down to HOMO - |V| eV, V > 0 the virtual MOs from the LUMO up to LUMO + V eV (total map only; the molecular gap is the zero of the scale, as in a Tersoff-Hamann LDOS)
--afm-alpha BExponent of V = A rho^B (default 0.78, Moll's CO tip fit)
--afm-prefactor APrefactor A in eV with rho in e/A^3 (default 692)
--afm-tip SIGMA[,s|pz]Research variant: the Pauli energy integrated over a Gaussian tip orbital of width SIGMA (A), s or p_z along the normal (5x5x5 Gauss-Hermite); default 0 = point tip, the CO tip being absorbed in Moll's fitted A and alpha
Plane of the maps: --map-plane / --map-slab / --map-step (runEDDB --help export)

Examples

runEDDB -i @naphthalene --table afmnc-AFM model contrast above every bond
runEDDB -i @naphthalene --export-map afmnc-AFM model image at the tip height 3.5 A
runEDDB -i @pentacene --export-map afm --map-plane fit,3.0the same, tip at 3.0 A
runEDDB -i mol.fchk --export-map stm --stm-bias -1.5STM image (needs SCF MOs: a .fchk / .json / .molden) (your own file)

7. Built-in GFN2-xTB engine --help xtb

Guide: xtb

GFN2-xTB engine (geometry input only)

--xtb-etemp KFermi-smearing temperature in K (default ~300; 0 = off)
--xtb-conv XSCC convergence on max|dq| (default 1e-4)
--xtb-maxiter NMax SCC iterations (default 1500)
--xtb-noaesDisable anisotropic electrostatics (fast; not EDDB-grade)
--xtb-coupled [a_x]NICS from the COUPLED tight-binding magnetic response: the sum over states is iterated with an sTDA-type ZDO exchange kernel (Ohno-Klopman gamma from the GFN2 hardnesses) scaled by ONE parameter a_x (bare flag = 0.20, the B3LYP exchange fraction, fitted on 16 neutral 6-membered rings: EDDB loop current within 7 %, NICS(1)zz within 3 ppm of B3LYP/def2-TZVPP). Not for rings with a pi-donor N-H or O (GFN2 underestimates them ~1.5x with or without coupling) nor for 4n rings (the coupling map is unstable at a_x = 0.2: WARNING + uncoupled fallback; use a_x ~0.1). -v prints iterations, spectral radius and the amplification. --xtb-uncoupled = the default lane.
--xtb-frac-occEXPERIMENTAL (diagnostic). Keep the Fermi-smeared fractional occupations in the ANALYSIS density instead of refilling integers, so D is deliberately NON- IDEMPOTENT and the run takes the post-HF (layer-by-layer) BOP path. Built to exercise that engine with cheap non-idempotent densities -- NOT to produce EDDB values, and NOT comparable with published data. The occupations come from an artificial electronic temperature, not physical static correlation. Pair with a high --xtb-etemp (e.g. 5000); a no-op when smearing is off. Prints a warning when it fires.
--xtb-spinOpen-shell: spin-polarised UHF (the default for M > 1)
--xtb-nospinOpen-shell: ROHF instead of the default spin-polarised UHF
Charge and multiplicity: --xyz-charge / --xyz-mult (runEDDB --help input)

Examples

runEDDB -i @benzene --xtb-etemp 0no Fermi smearing
runEDDB -i @benzene --nics-rings 6 --xtb-coupledNICS from the coupled TB response
runEDDB -i @benzene --export-fchk xtbsave the converged GFN2-xTB wavefunction
runEDDB -i mol.xyz --xyz-charge -2your geometry: any .xyz .mol .mol2 .pdb .sdf (your own file)

8. Cores, verbosity, citations, diagnostics --help runtime

Guide: issues

Runtime / display

--ncores, -n NOpenMP threads (default 1); N=0 uses every core
--quiet, -qBanner + EDDB summary only (no timings/tables/detail)
--verbose, -vAdd stage detail blocks + parser / NAO diagnostics; NMR/NICS/currents: + <stem>.NMR_DIAG.txt (dia/para split at full precision, loop fit, sum rule, edge terms)
--asciiForce 7-bit ASCII output (default: UTF-8 box/Greek glyphs)
--help [TOPIC]Short help (no TOPIC; also shown with no arguments) or the full detail of one topic: input, eddb, tables, export, nmr, afm, xtb, runtime, full (all topics).
NOTE: -h is the EDDB_H scope, not help.
--examples [TOPIC]Ready-to-run commands on built-in molecules for one topic (no TOPIC: a few general ones)

Citations

--cite LISTbib | txt | both -> <stem>.bib / <stem>.refs.txt Method-dependent, de-duplicated; also per stage under -v.

Diagnostics / developer

--test-overlapParse + overlap; verify Tr(D*S) = N_e
--test-roundtrip [FILE]Parse, write FCHK, re-parse; verify D_ao matches
--test-naoParse + run the NAO driver; print a summary
--nao-debugDump every NAO-driver step (atom 1)
--nao-debug-atom NAs --nao-debug, but for atom N
--nao-atdiag-form FORMStage-1 form: sds ((S D S)v=nSv; default) or gep (Dv=nSv)
--dump-element-tablePrint Cor/Val shell counts per element Z and exit
--probe-conventionsScore the AO sign conventions of d/f/g shells (derives the convention table of a new host program)
--ano-diagano-layers selector diagnostics (calibration runs only)
--ano-veto LISTano-layers selector veto list (calibration runs only)

Examples

runEDDB -i @coronene -r 6 -n 0use every available core
runEDDB -i @benzene -vper-stage detail
runEDDB -i @benzene -qbanner and EDDB summary only
runEDDB -i @benzene --cite bibreferences of the methods used -> benzene.bib
runEDDB -i @benzene --ascii7-bit ASCII output (old terminals)
← GFN2-xTB  |  Next: Limits & tips →

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual