Starting with TopChem2

==========================================================================
Starting with TopChem2
==========================================================================
Contact author: Julien Pilmé
email: [email protected]
WebPage: http://www.lct.jussieu.fr/pagesperso/pilme/

I. Generalities and Quick Introduction

TopChem2 is a standalone program which allows for advanced and robust topological analyses of
the electron localization function, the electron density and the molecular electrostatic potential
from 3D- cube or from wfn/wfx gaussian files. The Non Covalent Interaction (NCI) index is also
computed. The program is easily usable in command-line offering a user-friendly experience.

Dependencies:

- Linux Intel/AMD x86, 64 bit operating systems

Installation:

A] Open a linux terminal and extract the files from the tar archive:
> tar -xvf TopChem2_cube64.tar.gz
B] Change the directory to where the files are located:
> cd INSTALL_TOPCHEM64
C] Run the bash script installer, it does not require administrative privileges to run:
> bash installer.sh

The setup installer is an easy-to-follow dialog. Please follow the corresponding instructions
for installing TopChem2.

Several fortran binaries are provided in the package:

topchem2 : the main program

vasp_to_cube : utility for generating cubes from CHGCAR/ELFCAR VASP files.
.

1
 II. Quick-Start in command-line
Just open a terminal window, and type topchem2 with optional parameters. Default parameters for
critical points search and integration procedure are in general of sufficient quality to afford reliable
results. The program runs through three different sections: critical points search, basin analysis and
population analysis.

Analysis from wfn/wfx files

For a rapid start of topchem2, using the default parameters setup options and the wfn file example
h2o.wfn (assumed to be in the current directory),
For a QTAIM analysis, enter the following at a command prompt:
> topchem2 wfn:h2o.wfn function:rho output:output.txt proc:6
ELF topological analysis from wfn, enter the following at a command prompt:
> topchem2 wfn:h2o.wfn function:elf output:output.txt th_assign:0.0001 dist_cp:0.2 proc:6

Analysis from cube files

For a rapid start of topchem2, using the default parameters setup options and the cube files examples
h2o_rho.cube and h2o_elf.cube (assumed to be in the current directory),
QTAIM analysis from cube file, enter the following at a command prompt:
> topchem2 input:h2o_rho.cube function:rho output:output.txt proc:6
For the ELF topological analysis from cube file, enter the following at a command prompt:
> topchem2 input:h2o_elf.cube function:elf output:output.txt cp:y th_assign:0.0001
th_cp:0.001 dist_cp:0.2 rho_file:h2o_rho.cube

III. Output Files

A calculation can produce several output files:
 One output text file where the main numerical values are gathered. All values are
given in atomic units.
 file_elf_cpelf.xyz or file_cprho.xyz : xyz file format containing the xyz coordinates
(Å) of found critical points.
 file_rbas.sbf or file_ebas.sbf : binary Fortran files: Contains assignment basin

codes of 3D-grid points. These files are needed to compute populations and
integrated quantities.

2
  topmod_rbas.sbf or topmod_ebas.sbf : These files format are compatible with
the TopMod program.
 file_elf_esyn.cube: cube file containing color basin code of grid points. Needed to

visualize ELF basin colors (see below content VI.)

IV. TopChem2 USAGE

Type >topchem2 help :

.....................................
The main argument parameters have the following meaning:
1. input: [string] Input Current electron density/ELF/MESP cube file.
2. wfn/wfx: [string] Input Current Gaussian wfn/wfx file.
3. output: [string] output text file. Main numerical results are gathered in this file.
4. function: [string]. Compute the three-dimensional grid and enable the basin analysis.
a) string ≡ rho: Electron density ρ(r) (QTAIM analysis): 3d-Grid and Analysis. Of all
the possible ways to analysis the electron density in a molecule or in a solid, the Quantum
Theory of Atoms in Molecules (QTAIM) is probably the most used for discussing the nature
of chemical bonding . The pioneering works are due to Richard F. W. Bader and coworkers in
the 70s. this methodology can be applied to both experimental and computed electron
densities, the topological atoms being defined as the union of a nucleus and of its atomic
3
basin. The topology of the density gradient field is characterized by critical points and their
connectivity. Among the saddle points, a bond critical point (BCP) plays an essential role
because the values of some local descriptors based on the electron density are usually
related to the nature of the chemical bond.
See R. Bader, Chem. Rev. 91, pp. 893-928 (1991)

b) string ≡ elf: Electron localization function (ELF): 3d-Grid and Analysis. The
electron localization function (ELF) topological analysis was intensively used for studying of
the bonding schemes in molecules and in solids, or for rationalizing the chemical reactivity. It
relies on the Laplacian of the conditional same spin pair probability scaled by the
homogeneous electron gas kinetic energy density. ELF is usually interpreted as a signature of
the electron-pair distribution. Its topological analysis represents a bridge between the
traditional pictures of the chemical bond derived from the Lewis theory, and first principles
quantum-mechanical methodologies. Overall, the spatial distribution of the valence basins
closely matches the non-bonding and bonding domains of the VSEPR model. ELF was
expressed in the framework of the density functional theory by Savin et al. and rationalized
in terms of the local excess kinetic energy due to the Pauli repulsion. ELF can be computed at
each grid point as follows:

where τ is the kinetic energy density .

See for definitions: J. Chem Phys, 92, 5397-5403 (1990). Savin, Angewandte 31 187–188
(1992) and its topological analysis with Nature 371, 683 (1994)

c) string ≡ mep: Molecular Electrostatic Potential: 3d-Grid and location of (3,+3)

critical points. The MESP is an interesting travel guide assessing the chemical reactivity of
molecules towards positive (electrophilic) or negative (nucleophilic) sites of reactants. The
MESP is typically visualized using mapping its values onto the electron density isosurface
reflecting the molecular sites boundaries.
See H. Suresh, Geetha S. Remya, Puthannur K. Anjalikrishna, WIREs Comput Mol. Sci
12:e1601 (2022)

d) string ≡ fm, fp, dld : Frontier Molecular orbital and orbital-weigthed

approximations for Fukui f+ and f- functions and Dual descriptor: 3d-Grid and Analysis.
The Fukui functions and the Dual Descriptor are suitable tools of the conceptual DFT
designed to describe and predict the chemical reactivity. They describe how the electron
density is modified after adding or removing some amount of electrons. They can predict
where are the electrophilic/nucleophilic molecular sites. f-(r) indicates which are the
preferred sites for an electrophilic attack while f+(r) indicates which are the preferred sites
for a nucleophilic attack. Dual Descriptor combines the both properties of the Fukui
functions.
See P. Geerlings, F. De Proft, and W. Langenaeker Chem. Rev. 103, 5, pp. 1793-1874 (2003).
J. Phys. Chem. A (2005), 109, 1, 205–212, J. Comput. Chem., 38, 481 (2017) and J. Phys.
4
Chem. A, 123, 10556 (2019). The orbital weighted definition is useful in order to study the
local reactivity of molecular systems whose frontier molecular orbitals are degenerated.

e) string ≡ nci: 3d-Grid and of sign(λ2)*ρ(r) mapped onto RDG isosurfaces.

The non-covalent interaction index (NCI) method relies of the properties of the reduced
density gradient (RDG),

RDG is very used for studying the weak interactions : The « strength » of weak interaction
can be visualized using a mapping of sign(λ2)*ρ(r) onto RDG isosurfaces sign(λ2) being the
sign of the second density Hessian eigenvalue (λ2). Typically, the attractive and repulsive
interactions are identified as regions where λ2 < 0 and λ2 > 0, respectively. Weak van der
Waals interactions when λ2 becomes nul.
See J. Am. Chem. Soc., 132, 6498 (2010).

f) string ≡fmw: No grid is computed. Fast analysis of the

wavefunction.

g) string ≡cvb: Automatically search of ELF Core-Valence

bifurcation (cvb) indexes.
see DOI 10.1007/s002149900100

GENERAL OPTIONAL KEYWORDS:

5. cp: [y/n/o] y(enabled)/n(disabled) the search of critical points. “o” enables only the
search of critical points but both basin analysis and populations will be disabled. The
default is “n” for the electron density and “y” for ELF.
6. th_assign: [real] All grid points where the value of the function remains below the
given threshold will be ignored in the basin analysis. The default threshold is 0.001
a.u. for the electron density and 0.75 for ELF.
7. th_cp: [r(eal] Below the threshold, all found critical points are dismissed.
8. dist_cp: [real] Enforced minimal distance between 2 critical points. Default threshold
of 0.25 bohr for the electron density and 0.6 bohr for ELF.
9. atom_dist:[real] Enforced minimal distance (bohr) between critical points and atoms.
Default value: 0.3 bohr
10. periodic: [y/n] y(enabled)/n(disabled) the periodic cell properties for the basin
analysis. Default: n
11. voronoi Voronoi charge discrete distribution instead of topological basin analysis.
see J. Chem. Phys. 139, 071103 (2013).

5
12. grad:[y/n] y(enabled)/n(disabled) the use of numerical gradients for the basin
analysis. Default: y
13. proc: [integer] Number of used processors for the basin analysis. Default: 1
14. rho_file: [string] Electron density cube file needed to compute ELF populations and
moments.
15. bas_file: [string] Binary file provided by TopChem or TopMod which will be used to
compute QTAIM atomic contributions to ELF basins.
16. refine: [y/n/f]: y(enabled)/n(disabled)/f(full). Additional refinement step at the final
stage of the basin analysis. full: all points are assigned. Default: y
17. val: [real,real,real] x,y,z (bohr): value of some descriptors computed at the (x,y,z)
point.
18. print: enable the verbose mode.
19. algo:[offgrid/neargrid/ongrid] : used algorithm for the basin analysis
offgrid: see DOI : 10.1002/jcc.27105. Computers & Chemistry 1999, 23, (6), 597-604
(default)
neargrid: see Journal of Physics: Condensed Matter 2009, 21(8), 084204, J. Comput.
Chem. 2011, 32(15), 3207.
ongrid: see Comput. Mater. Sci. 2006, 36(3), 354
 descriptor Enable the calculation of the values of some local descriptors at the
critical points locations (by default if cp=”o” or cp=”y”): Electron density, Shape
Function, Radial distribution, ellipticity, bond metallicity, Shannon entropy and
gradients, Laplacian of the electron density and Hessian eigenvalues. Local energy
densities are also computed at bond critical points. The Kirzhnits approximation used
in DFT is applied here to compute the kinetic energy density from the electron
density only [D. A. Kirzhnits, Sov. Phys. JETP ,5 , 64, 1957].

WFN OPTIONAL KEYWORDS:

20. level: [rhf/uhf/rohf/nat] level of theory. Default: rhf.
nat is the natural orbitals approximation for correlated post-HF wavefunction
(MPn, CI or CCSD level of theory)
21. pop: [pop/cov/pol/orb/ken] Compute integrated quantities over the basin volume.
pop: basin volumes and populations (Default).

6
 cov: variance and covariance analysis. For QTAIM: localization and
delocalization indices and LDM matrices.
pol: condensed dipole and quadrupole basins.
orb: orbital contribution to basin populations.
ken: integration positive defined kinetic energy.
22. sizebox: [large/medium]: Size of the parallelepipedic box. The function is calculated
on a 3-D grid parallel to the standard axis defined in the ab initio calculation.
23. sizegrid: [low/medium/high/vhigh] step between the grid points. low: 0.2 bohr,
medium: 0.1 bohr, high: 0.075 bohr, vhigh:0.05 bohr. Default: medium.
24. num_int: use numerical integrations to compute basin integrated quantities
(populations). Very fast process.
25. fukui: [fp,fm,dd] Frontier Molecular Orbital Fukui basin Condensation, fp:Fukui f+,
fm:Fukui f-, dd:Dual Descriptor LUMO-HOMO (DOI: 10.1021/jp046577a).
26. mathematica : produce a mathematica notebook (*.nb) for the electron density
calculation.
Electron localization Function and Electrostatic Potential OPTIONS:
 contrib : [y/n] y(enabled)/n(disabled) QTAIM contributions to basin populations.
Default: n
 rho_file: [string] Electron density cube file needed to compute ELF/MEP basin
populations.
 bas_file: [string] Binary file used to compute QTAIM atomic contributions
(*_rbas.sbf).
 merge : [y/n] y(enabled)/n(disabled) Merge degenerated attractors. Default: y
 noh : Provide additional output cube files without protonated basins.
 vmd : Provide a vmd visualization state file. Only available for ELF.

7
 V. Critical Points section
Critical points are searched and printed following the conventional ranking:

Displaying of the xyz critical points of the electron density gradient field for the ortho-nitrophenol molecule.
Color code: location of critical points are displayed with brown spheres.

 (3,-3): The three Hessian eigenvalues are all negative. This is a maxima (attractor) of
the density function field.
 (3,-1): Two negative and one positive Hessian eigenvalues. This is a saddle point of
the field, maxima in two directions and minimum in the other. If the density function
is the electron density, it is termed as Bond Critical Point (BCP).
 (3,+1): One negative and two positive Hessian eigenvalues. This is a saddle point,
maximum in one direction and minima elsewhere. If the density function is the
electron density, the critical point is called Ring Critical Point (RCP).
 (3,+3): All the three Hessian eigenvalues are positives. This critical point is a minimum
of the field. If the density function is the electron density, the critical point is called
Cage Critical Points (CCP).

 For ELF, only the attractors (3, -3) are kept. For MEP, only the minima (3,+3) are
kept.

Electron density and ELF analysis using pseudopotentials

When pseudopotentials are used, the gaussian wfx files
use additional core density function data to represent the
electron density of the ECP-modeled core electrons (EDF
primitive functions). See
http://aim.tkgristmill.com/wfxformat.html#edfsforecps

8
For wfn or cube files generated without recovering of the core regions, the electron density
can be recovered in the core regions using a simplistic tight core gaussian function. Enabled
by default when pseudo keyword is added to the command-line of TopChem2. See details by
reference herein, Todd A. Keith and Michael J. Frisch, J. Phys. Chem. A, 115, pp. 12879-
12894, 2011.
The syntax is,
pseudo:[Atom1=Z1,Atom2=Z2,..] Enable pseudopotentials for specified atoms
When pseudopotentials are used, the ELF core basin radii (given in Bohr) are looking for for
both the critical points section and the basin analysis. No critical points are sought inside the
atomic sphere defined by this radius. However, this shell radius can be specified in a user file
located in the work directory. This file needs to be termed as pseudo_radius_ELF.txt. Each
line of this file corresponds to a specification of a radius given in the following format:
Atomic_ number (integer) radius (real in Bohr)

VI. Basin Analysis section

TopChem2 looks for all basins of the gradient scalar field along the descent trajectories from
attractor points. The algorithm is similar to the one used by the TopMod program
[Computers & chemistry, 23 (6), pp. 597-604, 1999].Each grid point is assigned to basin
volumes and assignment codes are stored in binaries files file_elf_ebas.sbf (Electron density)
or file_elf_ebas.sbf (ELF). For ELF, color codes are assigned as basin types and stored in the
cube file file_elf_esyn.cube. The basin type can be:
1: lone pair, usually shown in red

2: protonated bonds C-H, N-H, shown in turquoise

3: bonding, green

4: H-, white or yellow

5: core, purple

9
Displaying ELF color isosurfaces by means of VMD

1. Loading the file

a. File > New Molecule>Browse : You choose the name-elf.cube
file
b. Button LOAD
c. Select name-elf.cube file in the VMD main Window
d. File/Load Data into Molecule>Browse : You choose the name-
syn.cube file
e. Button LOAD

2. Drawing/coloring ELF isosurfaces

Menu : Graphics > Representation

A. Drawing Surface
a. Drawing Method: Isosurface
b. Vol: Select name_elf.cube file
c. Isovalue: Using cursor to select isosurface value upper
than 0.80
d. Draw: Solid Surface

B. Coloring Surface
a. Coloring Method: Volume
b. Material: Select name_esyn.cube

3. Saving your picture

a. File > Render > Filename: file.bmp
b. Start Rendering

10
Nice ELF, MEP and NCI Visualizations Using VMD
Alternatively use “vmd” option in the command-line for the ELF analysis. The color types (see
above) will be automatically assigned and stored in five separated cube files. A vmd file called,
file_elf_ebas.vmd will be also created. This can be directly read in VMD as a “Load
visualization file” using :
 vmd –e file_elf_ebas.vmd
Loading all cube files might take a while, but you end up with a nice display . As all cube
files are read sequentially for all basins, you can delete the basins that you do not want to
plot.

For NCI, a vmd (3D) and a gnnuplot are automatically produced by TopChem2
 vmd –e file_nci.vmd
 gnuplot file_nci.gnu

11
 VII. The population Analysis section
If only cube files are used, the basin populations and distributed electrostatic moments
are automatically computed. In addition to the ELF cube file, it is noted that the electron
density cube file is also needed in order to obtain ELF populations & moments.

If a wfn file is used, analytical integrations are performed. Computed quantities depends of
the pop optional keyword:
pop: basin volumes and populations (Default).
cov: Variance and covariance analysis. For QTAIM, it provides the localization
and the delocalization indices (DI).
pol: integrated dipole and quadrupole topological moments.
orb: orbital contribution to basin populations.
ken: integrated positive defined kinetic energy over the basin volume.

12
 VIII. vasp_to_cube utility

TopChem2 package includes a standalone command-line utility for generating cubes from
CHGCAR and ELFCAR VASP files. The utility is termed vasp_to_cube. It has the following
syntax:

> vasp_to_cube VASP_File Function ntype

The parameters have the following meanings:

VASP_File (string) : CHGCAR/ELFCAR

Function (string) : rho/elf
ntype (only one integer) : Number of each atom type

Example for the case of a benzene molecule in the cubic cell:

> vasp_to_cube CHGCAR_benzene rho 2

Produces cube file from CHGCAR_benzene.cube, CHGCAR contains only two different types
of atoms (C and H). The considered cell in the produced cube file.

13