Szczepanik Research Group

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

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual


Manual (2026-Nov-03)

runEDDB analyses an electron density that some other program has already computed (a wavefunction file), or it computes one itself from a bare geometry with its built-in GFN2-xTB engine. This page tells you which file to give it for each quantum-chemistry program, which keywords that program needs, and what to watch out for.

1. Which file from which program

ProgramGive runEDDBHow to get it
Gaussian.fchkformcheck in the route, or formchk mol.chk mol.fchk
ORCA.json (recommended) or .moldenorca_2json mol or orca_2mkl mol -molden
Q-Chem.fchkgui = 2 in $rem; run with -save NAME
Turbomole.tmolcat control coord basis mos > mol.tmol (C1 symmetry)
GAMESS-US.gmsthe output log, renamed to .gms
PySCF, MOLCAS, others.moldenthe program's Molden writer
Multiwfn.fchk or .moldenconverts almost any format
NBO 7.49legacy lane, populations and BOP only
No calculation.xyz .mol .sdf .mol2 .pdbrunEDDB runs GFN2-xTB itself
Crystal structure.cif → .xyzexport a complete molecule from Mercury, Olex2, VESTA ...

Supported wavefunctions: RHF, UHF, ROHF and DFT (restricted and unrestricted), and correlated or excited-state densities given as natural orbitals (section 3). Basis functions up to k (L = 7), spherical or Cartesian.

2. Wavefunction files, program by program

Gaussian (.fchk)

Add formcheck to the route section and the .fchk is written next to the checkpoint; or convert afterwards with formchk mol.chk mol.fchk. For a correlated density add density=mp2 (MP2) or density=current (CCSD, CI, CASSCF, TD-DFT) to the route.

terminal
$ runEDDB -i mol.fchk -a
ORCA (.json or .molden)

Prefer .json: it carries the full description of the wavefunction, ECP definitions included, which the Molden format cannot hold. Both are written by ORCA's own tools:

terminal
$ orca_2json mol                 # mol.gbw -> mol.json
$ orca_2mkl mol -molden          # mol.gbw -> mol.molden.input
$ runEDDB -i mol.json -a
Q-Chem (.fchk)

Add gui = 2 to the $rem block and start Q-Chem with -save SAVENAME; the file is $QCSCRATCH/SAVENAME/Test.FChk. For the coupled-cluster density add cc_ref_prop = true. Q-Chem does not write the MP2 density to the FCHK; use Gaussian or ORCA for MP2. With an ECP, Q-Chem writes the full nuclear charges; runEDDB detects this and stops with instructions (section 5).

Turbomole (.tmol)

Concatenate the four key files of the working directory into one bundle:

terminal
$ cat control coord basis mos > mol.tmol
$ runEDDB -i mol.tmol -a

RHF, UHF, ROHF and DFT in the spherical basis (up to k functions: def2 and cc-pVnZ families) are read, the $ecp block included. Two requirements:

  • C1 symmetry. Under a point group Turbomole writes the MOs per irreducible representation, which the reader does not unpack. Rerun the SCF with $symmetry c1; a non-C1 file stops with an ERROR, never with a wrong density.
  • Spherical basis. Cartesian storage ($pople CAO or $cao) is not supported.
GAMESS-US (.gms)

Give the normal output log of rungms, renamed or linked to .gms (the PUNCH file is not used). Run types ENERGY, OPTIMIZE (the final geometry is found automatically) and SADPOINT; RHF, UHF, ROHF and MCSCF natural orbitals. A spherical basis (ISPHER=1) is recommended, Cartesian works too. $ECP blocks and symmetry-reduced basis listings (COORD=UNIQUE) are expanded automatically. The default print precision is enough; for basis-set studies set DGRID=.T. in $CONTRL.

Molden (.molden) from other programs

Most programs (PySCF, MOLCAS/OpenMolcas, Turbomole, GAMESS, ...) can write a Molden file; see the manual of your program for the keyword. Multiwfn converts to and from Molden and FCHK and is a convenient bridge; runEDDB is validated against Multiwfn-written files.

NBO 7 archive (.49), legacy

Accepted for backward compatibility: population analyses and BOP only (no cube files or orbital exports, because NBO uses a different AO convention). This lane will be removed in a future release; use a wavefunction file instead.

3. Correlated and excited-state densities

A correlated density (MP2, CCSD, CASSCF, CI) or the density of an excited state has fractional natural-orbital occupations. runEDDB then takes its layer-by-layer BOP lane automatically: the density is split into idempotent layers and each is analysed; for a single-determinant density the result is the same as the standard lane.

Excited states (TD-DFT, TDA, CIS)

ORCA writes the natural orbitals of one state (the unrelaxed density):

ORCA input + terminal
! B3LYP def2-TZVP
%tddft
  nroots 5                 # number of excited states
  iroot  1                 # the state to analyse (1 = lowest)
  tda    true              # true = TDA, false = full TD-DFT (both work)
  unrelaxednatorb true     # write the natural orbitals of state iroot
end

$ cp mol.cis.singlet.iroot0.nat mol_S1.gbw      # iroot 1 -> iroot0, iroot 2 -> iroot1
$ orca_2json mol_S1.gbw
$ runEDDB -i mol_S1.json

Triplet states (triplets true) go to .cis.triplet.iroot0.nat. A UKS reference gives separate α and β natural orbitals.

Gaussian writes the relaxed density of state Root with TD(NStates=5,Root=1) density=current (or TDA(...)); runEDDB reads it from the FCHK automatically.

TDA and full TD-DFT differ little; the choice between a relaxed and an unrelaxed density matters more (formaldehyde S1, B3LYP/def2-SVP, EDDBG: unrelaxed 0.608, relaxed 0.577, ground state 0.324). Compare states within one density type and state it in the methods. Excited states need the compilation of 2026-Oct-15 or newer.

Occupations outside 0–2 (relaxed MP2 and TD densities)

A relaxed (response) density is not strictly N-representable: a few occupations fall slightly below 0 or above 2. By default runEDDB replaces the occupation spectrum by the nearest admissible one (one uniform shift, then clipping to 0–2, keeping the electron count; the natural orbitals are not changed). -v reports the correction. --no-nrep analyses the density exactly as read, with a WARNING. Mention the correction in your methods, or use an unrelaxed MP2 density (ORCA) or a wavefunction-based one (CASSCF, CI, CC), which do not need it.

4. Files for NMR and ring currents

The magnetic analyses need the response of the wavefunction to the magnetic field, written by an NMR job. Without it runEDDB still computes an approximate response from the MOs and says so.

ProgramNMR jobGive runEDDB
Gaussian, GIAONMRmol.fchk
Gaussian, CSGTNMR=CSGT IOp(10/33=2)mol.fchk and mol.log in the same folder
ORCA, GIAO! NMR KeepDensmol.json from orca_2json with mol.json.conf = { "Densities": ["all"] }
Turbomole, GIAOmpshift with $gimicmol.tmol and XDENS

Which job to choose for which question is explained on the NMR & currents page.

5. Effective core potentials

With an ECP the core electrons are replaced by a pseudopotential, and each reader takes the effective nuclear charge Zeff from the file so that populations and charges balance: Gaussian FCHK Nuclear charges; ORCA JSON NuclearCharge; Turbomole $ecp; GAMESS ECP POTENTIALS; for NBO .49 it is inferred from the basis. The valence shells are then labelled correctly (W with def2-ECP60: 6s and 5d).

Two files need help. Q-Chem FCHK lists the full nuclear charges even with an ECP; runEDDB detects it and stops; edit the Nuclear charges record to Zeff or rerun in Gaussian or ORCA. Molden files carry Zeff only in an ORCA-style [Pseudo] block; when it is missing but an ECP is evident, runEDDB stops and shows the block to add between [Atoms] and [GTO]:
[Pseudo]
W    1  14         ! atom 1 (W),  Z_eff = 14 (def2-ECP60)
Pt   5  18         ! atom 5 (Pt), Z_eff = 18 (def2-ECP60)
A genuinely highly charged system without an ECP: add --no-ecp.

6. Geometry files (GFN2-xTB)

From a bare structure (a crystal structure, a molecular-dynamics frame, a model from a drawing program) runEDDB builds the electronic structure itself with the semi-empirical GFN2-xTB method and runs the full analysis on it, in seconds and without other software. Use it for a first look; GFN2-xTB inflates EDDB by about 10–20 % relative to range-separated hybrid DFT, so confirm important findings with a DFT wavefunction. The engine itself is described on the GFN2-xTB page.

FormatCharge and spinNotes
.xyzoptional on line 1: N_atoms charge multiplicityseveral structures in one file = a trajectory
.mol / .sdfM CHG and M RAD recordsV2000 only; 3D coordinates required; .sdf may hold many records
.mol2none: neutral singletelement from the SYBYL atom type
.pdb / .entnone: neutral singletfirst alternate location; add missing hydrogens first (e.g. obabel in.pdb -O out.pdb -h)
mol.xyz
12  0 1                 # atom count, charge, multiplicity (the last two optional)
benzene
C    0.000000    1.396792    0.000000
...
terminal
$ runEDDB -i mol.xyz -a
$ runEDDB -i mol.pdb --xyz-charge -1 --xyz-mult 2      # radical anion
$ runEDDB -i traj.xyz --xyz-frame 25                   # frame 25 of a trajectory
Tip: comparable cubes along a trajectory

Centring every frame with --xyz-center would put each on its own centroid and the cubes would not overlap. Centre one reference frame with --xyz-center geom -v, read the printed translation vector, and run every frame with that vector in --xyz-translate, optionally with --cube-ref reference.cube to share the grid. The cubes can then be compared and subtracted (differential maps).

Diradicals and open-shell singlets

GFN2-xTB cannot converge a broken-symmetry singlet reliably. A practical screen: run the molecule as a triplet; if the spin settles on two separated atoms or fragments, an open-shell singlet ground state is likely. --table no adds natural-orbital diagnostics, including ⟨S2⟩. Confirm with a broken-symmetry DFT calculation analysed through a wavefunction file.

Crystal structures (.cif)

A CIF holds a unit cell and symmetry operations, not a molecule. Complete the molecule in Mercury, Olex2, VESTA or Diamond and export it as .xyz (or .mol, .pdb). For simple molecular crystals obabel structure.cif -O structure.xyz --fillUC strict works too (it fills the cell, so it does not suit polymers or ionic lattices). Add hydrogens if they are missing.

7. Built-in molecules (-i @NAME)

For tests, teaching and a first look at an option, runEDDB carries 39 molecules: arenes (benzene to kekulene), heterocycles, small charged rings, macrocycles (porphine, phthalocyanine, [18]annulene, cycloparaphenylenes) and the C60 isomers of GMTKN55. They run through GFN2-xTB like a geometry file; charge and multiplicity are part of the model.

terminal
$ runEDDB -i @list                           # the catalogue
$ runEDDB -i @benzene                        # a bare name, if unique
$ runEDDB -i @arenes/benzene --nics-rings 6  # the full group/name path
$ runEDDB -i @gmtkn55/c60iso/5 -r 5,6 -q     # a dataset entry, all 5- and 6-rings

Atom numbering. Ring atoms are numbered around the ring, starting at the heteroatom if there is one (pyrrole: N1, C2–C5); fused systems along the perimeter (naphthalene: 1-2-...-10-1, fusion atoms 4 and 9); hydrogens last. So -p 1-2-3-4-5-1 on pyrrole is the ring.

The library geometries are MMFF94 force-field conformers for trying things out, not quantum-chemically optimized structures. Report results on your own optimized geometry.

8. Methods and references

MethodReference
GFN2-xTB (geometry input)C. Bannwarth, S. Ehlert, S. Grimme, J. Chem. Theory Comput. 15 (2019) 1652, doi:10.1021/acs.jctc.8b01176
DFT-D4 dispersion in GFN2-xTBE. Caldeweyher et al., J. Chem. Phys. 150 (2019) 154122, doi:10.1063/1.5090222
Spin-polarized GFN2-xTB (multiplicity > 1)H. Neugebauer, B. Bädorf, S. Ehlert, A. Hansen, S. Grimme, J. Comput. Chem. 44 (2023) 2120, doi:10.1002/jcc.27185
Multiwfn (format conversion)T. Lu, F. Chen, J. Comput. Chem. 33 (2012) 580, doi:10.1002/jcc.22885
← Start  |  Next: EDDB analysis →

HOME      PROJECTS      PUBLICATIONS      runEDDB      X

About EDDB       Download       Tutorials       Manual