Starting with TopChem2 Cube

1

==========================================================================

Starting with TopChem2 Cube

==========================================================================

Contact author: Julien Pilmé

email: pilme@lct.jussieu.fr. WebPage: http://www.lct.jussieu.fr/pagesperso/pilme/

I. Generalities and Quick Introduction

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_cube. Several fortran binaries are provided in the package: topchem2_cube : the main program topchem2_cube_view: utility to compute & view 2D- and 3D-plots. vasp_to_cube : utility for generating cubes from CHGCAR and ELFCAR VASP files. topchem_gui.py : Graphical User interface written in Python3 for easy computing and viewing. Python3, tkinter and matplotlib python packages need to firstly be installed.

TopChem2 Cube is a standalone program which allows for advanced and robust topological analyses

of the electron localization function/molecular electrostatic potential/electron density function

from 3D-cube files. The program is easily usable in command-line offering a user-friendly

experience. An optional graphical user interface allows to display 2D and 3D plots.

2

III. Output Files

A calculation produces 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 or file_cpmep.xyz : xyz file format containing the

xyz coordinates (Å) of found critical points.

� file_rbas.sbf or file_ebas.sbf or file_mbas.sbf : binary Fortran files: Contains

assignment basin codes of 3D-grid points. These files are needed to compute

populations and integrated quantities. The file format is compatible with the

TopMod output files.

� file_elf_esyn.cube or file_elf_msyn.cube: cube file containing color basin code of

grid points. Needed to visualize ELF/MEP basin colors (see below content VI.)

II. Rapid Start in command-line

Just open a terminal window, and type topchem2_cube 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.

For a rapid start of topchem2_cube, 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),

For a QTAIM analysis, enter the following at a command prompt:

> topchem2_cube input:h2o_rho.cube function:rho output:output.txt

For the ELF topological analysis, enter the following at a command prompt:

> topchem2_cube 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

3

IV. TopChem2 Cube USAGE

Type >topchem2_cube help :

The argument parameters have the following meanings:

� input: [string] Current electron density/ELF/MEP cube file.

� output: [string] output text file. Main numerical results are gathered in this file.

� function:[ rho/elf/mep]

OPTIONS:

� cp: [y/n/o] y(enabled)/n(disabled) the search of critical points. “o” enables 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/MEP.

� 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. All the negative values for MEP and the

default threshold is 10-8 a.u for positive values.

� th_cp: [real] Below the threshold, all found critical points are dismissed.

� 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/MEP.

4

� periodic: [y/n] y(enabled)/n(disabled) the periodic cell properties for the basin

analysis. Default: n

� grad:[y/n] y(enabled)/n(disabled) the use of numerical gradients for the basin analysis.

Default: y

� proc: [integer] Number of used processors for the basin analysis. Default: 1

� rho_file: [string] Electron density cube file needed to compute ELF/MEP populations

and moments.

� bas_file: [string] Binary file provided by TopChem or TopMod which will be used to

compute QTAIM atomic contributions to ELF/MEP basins.

� refine: [y/n] refinement step at the final stage of the basin analysis. Default: y

V. Critical Points section

Critical points are searched and printed following the conventional ranking:

� (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 (maxima) are retained.

5

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.

ELF analysis and pseudopotentials.

When pseudopotentials are used, the electron density is recovered for the atomic core regions

using a simplistic tight core gaussian function. Enabled by default if pseudopotentials are

detected. See details by reference herein, Todd A. Keith and Michael J. Frisch, J. Phys. Chem.

A, 115, pp. 12879-12894, 2011.

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)

Several values of QTAIM descriptors are calculated at critical points locations:

Electron density, Shape Function, Radial distribution, ellipticity, bond metallicity, Shannon

entropy and gradients, Laplacian of the Electron density and Hessian eigenvalues:

As shown on the following snapshot, local energy densities are also computed at bond critical

points. The Kirzhnits approximation used in Density Functional Theory is applied here to

compute the kinetic energy density from the electron density only [D. A. Kirzhnits, Sov. Phys.

JETP ,5 , 64, 1957].

6

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) or file_elf_mbas.sbf (MEP). For

ELF/MEP, color codes are assigned to basins and stored in the cube file file_elf_esyn.cube/

file_elf_msyn.cube.

7

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

8

VII. Population Analysis section

The basin populations and distributed electrostatic moments are automatically computed.

In addition to the ELF/MEP cube file, it is noted that the electron density cube file is also

needed in order to obtain ELF/MEP populations & moments.

9

VIII. vasp_to_cube utility

TopChem2 Cube 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 Ranges

The parameters have the following meanings:

VASP_File (string) : CHGCAR/ELFCAR

Function (string) : rho/elf/mep

ntype (only one integer) : Number of each atom type

Ranges (6 integers need to be given): Range of fractional coordinates for generating several

cells using periodic conditions. xmin,ymin,zmin,xmax,ymax,zmax

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

> vasp_to_cube CHGCAR_benzene rho 2 0 0 0 1 0 1

Produces cube file from CHGCAR_benzene.cube, CHGCAR contains only two different

types of atoms (C and H). 4 cells are considered in the produced cube file.

10

IX. Graphical User Interface (GUI)

A basic graphical user interface written in python3 is included in the package for setting up

and running calculations with topchem2_cube. Tkinter and matplotlib python packages need

to be firstly installed. Example for the linux Ubuntu distribution:

> sudo apt-get install python3-pip

> sudo apt-get install python3-tk

> sudo python3 -mpip install -U matplotlib

The installer script (see section 1) creates a new script. To run the GUI, type: > topchem_gui elf & if ELF cube files > topchem_gui mep & if MEP cube files

> topchem_gui rho & if Electron Density cube files The gnuplot program needs to be installed and a visual molecular program needs to be

specified during the installation process. For example, VMD or Molekel programs can be used

for these tasks. If gnuplot is not found, 3D visualization will be disabled in the GUI. If none

external visualization program is specified, xyz structures and basin surfaces functionalities

will be disabled.

11

Main GUI Window:

i. TopChem Parameters:

The meaning of parameters are given in section IV. The results are gathered in a standard txt output file.

ii. Function Value:

Compute the value of the scalar function and local descriptors (given in section V) at given cartesian coordinates. The results are gathered in a standard txt output file

iii. 1D-Plot and 3D-Plot specifications:

Specifications for the 1D-plotting. The value of the scalar function are computed from min values to max values (Bohr).

The number of points used needs to be given by the user.

For 1D-plot, 500 points are used by default. The step between each point is computed as:

(max-min)/500

For 3D-plot, 50 points for each cartesian axis are used by default.

12

File Menu

i. Open New Cube File: Replace the currently loaded cube file by a new cube file.

ii. Open Plot-2D: Visualize a 2D DATA file produced by topchem2_cube_view.

iii. Open txt File: Open a text file in a new window.

iv. Open xyz File: Visualize a xyz file using an external visual molecular program specified during the installation process.

v. Export 2D-Plot: Export 2D DATA file produced by topchem2_cube_view in a mathematica notebook format (DATA.nb)

vi. Export 3D-Plot: Export 3D DATA file produced by topchem2_cube_view in a mathematica notebook format (DATA.nb)

vii. Exit: Close the graphical interface.

13

Process Menu

All the output files are gathered in the new directory “topchem_xxxx” creates by the

graphical interface.

i. Full Topological Analysis:

The search of 3D critical points (optional), the basin analysis and the population analysis are

performed. The parameters specified in the main window are used for this task. The

calculation is similar to that preformed in command-line, as described in section 2. All the

results are gathered in the specified text output file. Output files (xyz and fortran binaries)

described in section 3 are produced by the calculation.

ii. Find 3D attractors:

The topchem2_cube_cp program explores the 3D space contained by the limit box in order to

find the critical points (all for the electron density, only the attractors for ELF, both minima

and attractors for MEP). All the results of calculations are gathered in the specified text output

file. A xyz output file containing the critical points coordinates is produced.

iii. Function Value:

Compute the values of local descriptors at cartesian coordinates (Bohr) specified in the main

window of the GUI.

14

View Menu

i. Show Molecular Structure:

Run the external visual molecular program specified by the user during the installation process

for viewing the atoms coordinates (bohr).

ii. Show Basin Surface:

Run the external visual molecular program specified by the user during the installation process

for viewing the basin isosurface.

iii. Show 2D Plot:

2D plotting ranges from (xmin, ymin, zmin) to (xmax, ymax, zmax).

iv. Show 2D-X Plot:

2D plotting ranges from [xmin-xmax].

v. Show 2D-Y Plot:

2D plotting ranges from [ymin-ymax].

vi. Show 2D-Z Plot:

2D plotting ranges from [zmin-zmax].

15

vii. Show 3D-XY Plot:

3D plotting in the XY plane contained by the limit box. Gnuplot is needed for this task.

viii. Show 3D-XZ Plot:

3D plotting in the XZ plane contained by the limit box.

ix. Show 3D-YZ Plot:

3D plotting in the YZ plane contained by the limit box.

x. Show 3D-XY contour:

Contour plotting (isovalues) in the XY plane contained by the limit box.

xi. Show 3D-XZ contour:

Contour plotting (isovalues) in the XZ plane contained by the limit box.

xii. Show 3D-YZ contour:

Contour plotting (isovalues) in the YZ plane contained by the limit box.