Help file for the AIM utility of the ABINIT package.

This file explains the use and i/o parameters needed for the Atom-In-Molecule (AIM - Bader analysis) utility of the ABINIT package.

The AIM utility allows to analyse charge densities produced by the ABINIT code. The AIM analysis (Atom-In-Molecule) has been proposed by Bader. Thanks to topological properties of the charge density, the space is partitioned in non-overlapping regions, each containing a nucleus. The charge density of each region is attributed to the corresponding nucleus, hence the concept of Atom-In-Molecule.

It will be easier to discover the present file with the help of the tutorial. (Sorry, not yet available).
It is worthwhile to print this help file, for ease of reading.

Copyright (C) 2002-2004 ABINIT group (PCasek,FF,XG)
This file is distributed under the terms of the GNU General Public License, see ~ABINIT/Infos/copyright or http://www.gnu.org/copyleft/gpl.txt .
For the initials of contributors, see ~ABINIT/Infos/contributors .

Goto : ABINIT home Page | Welcome | Suggested acknowledgments | List of input variables | Tutorial home page | Bibliography
Help files : New user's guide | Abinis (main) | Abinis (respfn) | Mrgddb | Anaddb | AIM (Bader) | Cut3D

Content of the help file.


 

1. Introduction

The Bader technique allows to partition the space in attraction regions. Each of these regions is centered on one atom. The only input for this technique is the total charge density : the density gradient line starting from one point in space leads to one unique attracting atom. (References to the relevant litterature are to be provided).

Around each atom, the basin of attraction forms a irregular, curved polyhedron. Different polyhedra might have faces, vertices of apices in common. Altogether, these polyhedra span the whole space.

The points where the density gradient vanishes are called "critical points" (CP). They all belong to the surface of some Bader polyhedra. According to the number of positive eigenvalues of the Hessian of the density, one will distinguish :

The Euler relation must be fulfilled : the number of BCPs minus the number of RCPs plus the number of CCPs must equal 2. The Bader polyhedra might be convex (this is the usual case), but might as well not be convex.

In the present implementation, the user is required to specify one atom for which he/she wants to compute the Bader volume, surfaces or critical points. Different runs are needed for different atoms.

In case of the search for critical points, one start from the middle of the segment with a neighbouring atom (all neighbouring atoms are examined in turn), and evolves towards a nearby point with zero gradient. Then, in case crit equals 2, one checks that the CP that has been found belongs to the attraction region of the desired atom. This last step is by no means trivial. In the present implementation, the check is done by means of the straight line (radius) connecting the point with the atom. In case the Bader volume is not convex, it might be that a correctly identified CP of the Bader volume defines a radius that goes through a region that does not belong to the Bader volume : the CP is "hidden" from the atom defining the attraction region. In this case, the CP is considered as NOT being part of the Bader volume, unfortunately. The reader is adviced to look at the automatic test of the MgO molecule to see such a pathology : no cage critical point is found for the Mg atom. By chance, this problem is not a severe one, when the user is interested by other aspects of the Bader analysis, as described below.

In case of the search for the Bader surface, or the integral of the charge within the Bader surface, the user should define a series of radii of integration, equally spread over the theta and phi angular variables. Symmetries can be used to decrease the angular region to be sampled. Along each of these radii, the algorithm will determine at which distance the radius crosses the Bader surface. The integral of the charge will be done up to this distance. For this search of the Bader surface, the information needed from the critical points analysis is rather restricted : only an estimation of the minimal and maximal radii of the Bader surface. This is why the fact that not all CP have been determined is rather unimportant. On the other hand, the fact that some part of the Bader surface might not be "seen" by the defining atom must be known by the user. There might be a small amount of "hidden" charge as well. Numerical tests show that the amount of hidden charge is quite small, likely less than 0.01 electron.

The determination of density, gradient of density and hessian of the density is made thanks to an interpolation scheme, within each (small) parallelipiped of the FFT grid (there are n1*n2*n3 such parallelipiped). Numerical subtleties associated with such a finite element scheme are more delicate than for the usual treatment of the density within the main ABINIT code ! There are many more parameters to be adjusted, defining the criteria for stopping the search for a CP, or the distance beyond which CPs are considered different. The user is strongly advised to experiment with the different parameters, in order to have some feeling about the robutness of his/her calculations against variation of these. Examples from the automatic tests should help him/her, as well as the associated comments in the corresponding README files.

Note that the AIM program can also determine the Bader distance for one given angular direction, or determine the density and laplacian at several, given, points in space, according to the user will.


 

2. Input and output files.

To run the program one needs to prepare two files:

Except these files you need the valence density in real space (*_DEN file, output of ABINIT) and the core density files (*.fc file, output of the FHI pseudopotential generator code, actually available from the ABINIT Web page)

The files file (called for example aim.files) could look like:

  aim.in    # input-file
  abo_DEN   # valence density (output of ABINIT)
  aim       # the root of the different output files
  at1.fc    # core density files (in the same order as
  at2.fc    # in the ABINIT files-file )
  ...

About the _DEN file:
Usually, the grid in the real space for the valence density should be finer than the one proposed by ABINIT. (For example for the lattice parameter 7-8~a.u. , ngfft at least 64 gives the precision of the Bader charge estimated to be better than 0.003~electrons).

About the core density files:
LDA core density files have been generated for the whole periodic table, and are available on the ABINIT web site. Since the densities are weakly dependent on the choice of the XC functional, and moreover, the charge density analysis is mostly a qualitative tool, these files can be used for other functionals. Still, if really accurate values for the Bader charge analysis are needed, one should generate core density files with the same XC functional as for the valence density.

The main executable file is called aim. Supposing that the "files" file is called aim.files, and that the executable is placed in your working directory, aim is run interactively (in Unix) with the command


or, in the background, with the command

where standard out and standard error are piped to the log file called "log" (piping the standard error, thanks to the '&' sign placed after '>' is really important for the analysis of eventual failures, when not due to AIM, but to other sources, like disk full problem ...). The user can specify any names he/she wishes for any of these files. Variations of the above commands could be needed, depending on the flavor of UNIX that is used on the platform that is considered for running the code.

The syntax of the input file is quite similar to the syntax of the main abinit input files : the file is parsed, keywords are identified, comments are also identified. However, the multidataset mode is not available.

Note that you have to specify what you want to calculate (default = nothing). An example of the simple input file for Oxygen in bulk MgO is given in ~ABINIT/Test_v3/t57.in . There are also corresponding output files in this directory.

Before giving the description of the input variables for the aim input file, we give some explanation concerning the output file.

The atomic units and cartesian coordinates are used for all output parameters. The names of the output files are of the form root+suffix. There are different output files:

The gnuplot scripts are made in the manner that one needs type only
load  'file'
(quotes are necessary). Note, that this isn't considered as the visualization (it is only for working purpose)!

 


 

3. Typical use of input variables.

There are two groups of input variables : those that define the behaviour of the driver and those related to the numerics (all the others). Here is the list of the driver variables :

A standard determination of the electronic charge around one atom will use : Then, the user will have to specify the atom, thanks to atom, and the angular integration, typically with phimax, thetamax, nphi, ntheta.
Finally, the following input variables might often need some tuning : lgrad2, lstep2, dpclim, maxatd, maxcpd.
In most cases, the other input variables will not have to be modified.
Atomic units and cartesian coordinates are used for all input parameters.

 


 

4. List of AIM input variables.

Alphabetical list of AIM input variables.

A. atom   atrad  
B.
C. coff1   coff2   crit  
D. denout   dltyp   dpclim  
E.
F. foldep   follow   folstp  
G. gpsurf  
H.
I. inpt   irho   ivol  
J.
K.
L. lapout   lgrad   lgrad2   lstep   lstep2  
M. maxatd   maxcpd  
N. ngrid   nphi   nsa   nsb   nsc   ntheta  
O.
P. phimax   phimin  
Q.
R. radstp   ratmin   rsurf   rsurdir  
S. scal   surf  
T. thetamax   thetamin  
U.
V. vpts  
W.
X.
Y.
Z.




atom
Characteristic: numerics
Variable type: integer
Default: 1

Index of the investigated atom.



Go to the top | Go to the AIM input variable list
atrad
Characteristic: numerics
Variable type: real
Default: 1.0

A first estimation of the Bader radius (not too important - it is used only two times)



Go to the top | Go to the AIM input variable list
coff1
Characteristic: numerics
Variable type: real
Default: 0.98

See the input variable ratmin.



Go to the top | Go to the AIM input variable list
coff2
Characteristic: numerics
Variable type: real
Default: 0.95

See the input variable ratmin.



Go to the top | Go to the AIM input variable list
crit
Characteristic: driver
Variable type: integer
Default: 0 (no computation of critical points)

Drives the computation of critical points.

The original version searches all critical points (CPs) starting from the center betwen two and three atoms (atom - neighbor(s)) by Newton-Raphson algorithm - without tests (not recommended) - don't use together with surface analysis !

The simplified and standard versions search CP(3,-1) starting from the center of the pairs~atom-neighbor; then CP(3,1) from the center between two CP(3,-1) and finally CP(3,3) from the center between two CP(3,1). The robust Popeliers's algorithm is used. The difference between the two is based in the fact that the standard version makes the test if the CP is really on the Bader surface of the calculated atom for each CP, while the simplified version does this only for CP(3,-1). When CP analysis is rather fast (with respect to surface determination), 2 is recommended. In all cases the number of neighbors considered is limited by distance cutoff (variable maxatd)



Go to the top | Go to the AIM input variable list


denout
Characteristic: driver
Variable type: integer
Default: 0

Output of the electronic density. The specification of the line (plane) in the real space must be given in the input variable vpts and grid in ngrid. It is also possible to get only the valence density or the core density (see dltyp).



Go to the top | Go to the AIM input variable list
dltyp
Characteristic: driver
Variable type: integer
Default: 0

Specification of the contribution of the electronic density corresponding to the density and/or laplacian output (see denout and lapout)



Go to the top | Go to the AIM input variable list
dpclim
Characteristic: numerics
Variable type: real
Default: 1.d-2

If two "numerically different" critical points are separated by less than dpclim, they are considered to be the same critical point. This often happens because of numerical inaccuracies : one CP might be "seen" by two different finite elements. The default should be OK when the ecut is quite large, on the order of 60 Hartree. For less accurate calculations of the density, increase the default value to 5.d-2, let's say.



Go to the top | Go to the AIM input variable list
foldep
Characteristic: numerics
Variable type: real foldep(3)
Default: 0.0, 0.0, 0.0

Needed in the case follow=1 only. Defines the starting point.



Go to the top | Go to the AIM input variable list
follow
Characteristic: driver
Variable type: integer
Default: 0

Follow the gradient path to the corresponding atom starting from the position specified in the input variable foldep.



Go to the top | Go to the AIM input variable list
folstp
Characteristic: numerics
Variable type: real
Default: 0.5

The first step for following the gradient path.



Go to the top | Go to the AIM input variable list
gpsurf
Characteristic: driver
Variable type: integer
Default: 0

Drives the graphic output (gnuplot script) of the irreducible part of the calculated Bader surface.



Go to the top | Go to the AIM input variable list
inpt
Characteristic: numerics
Variable type: integer
Default: 100

Number of radial points used for integration of the Bader charge (not too sensitive).



Go to the top | Go to the AIM input variable list
irho
Characteristic: driver
Variable type: integer
Default: 0

Drives the integration of the charge of the Bader atom.



Go to the top | Go to the AIM input variable list
ivol
Characteristic: driver
Variable type: integer
Default: 0

Drives the integration of the volume of the Bader atom.



Go to the top | Go to the AIM input variable list
lapout
Characteristic: driver
Variable type: integer
Default: 0

Output of the laplacian of electronic density. The specification of the line (plane) in the real space must be given in the input variable vpts and grid in ngrid. It is also possible to get only the valence density or the core density (see dltyp).



Go to the top | Go to the AIM input variable list
lgrad
Characteristic: numerics
Variable type: real
Default: 1.d-12

The search for one particular CP is decided to be succesfull when either the norm of the gradient of the electron density is smaller than lgrad or when the length of the planned search step is smaller than lstep. If the number of search step becomes larger than an internal limit (presently set to 100), one will allow a weaker criteria for satisfaction, based on lgrad2 and lstep2. If the internal limit is reached, and the criteria on lgrad2 and lstep2 are not satisfied, then the searching procedure continues with the next seed.



Go to the top | Go to the AIM input variable list
lgrad2
Characteristic: numerics
Variable type: real
Default: 1.d-5

Determines the criterion for deciding that a CP has been found. See lgrad for more details.



Go to the top | Go to the AIM input variable list
lstep
Characteristic: numerics
Variable type: real
Default: 1.d-10

Determines the criterion for deciding a CP has been found. See lgrad for more details.



Go to the top | Go to the AIM input variable list
lstep2
Characteristic: numerics
Variable type: real
Default: 1.d-5

Determines the criterion for deciding that a CP has been found. See lgrad for more details.



Go to the top | Go to the AIM input variable list
maxatd
Characteristic: numerics
Variable type: real
Default: 10.0

Atoms within this maximal distance are considered in order to start the search of a CP.

Note that the supercell, determined by nsa, nsb, and nsc might be too small to actually lead to the consideration of all the desired atoms.



Go to the top | Go to the AIM input variable list


maxcpd
Characteristic: numerics
Variable type: real
Default: 5.0

The CPs are searched for within this maximal distance.

Note that the supercell, determined by nsa, nsb, and nsc might be too small to actually lead to the consideration of all the critical points.



Go to the top | Go to the AIM input variable list


ngrid
Characteristic: numerics
Variable type: integer ngrid(2)
Default: 30,30

Defines the grid in real space, for the density and laplacian outputs, governed by denout and lapout.



Go to the top | Go to the AIM input variable list
nphi
Characteristic: numerics
Variable type: integer
Default: 48

With ntheta, this variable defines the angular grid for the integration within the Bader volume, in particular, the number of phi angles, to be used between phimin and phimax. When the difference between these two variables is 2 pi, the recommended value of nphi is 48. When it is pi (for symmetry reasons), the recommended value is 32. When it is pi/2 (for symmetry reasons), the recommended value is 20.



Go to the top | Go to the AIM input variable list
nsa, nsb, nsc
Characteristic: numerics
Variable type: integer
Default: 3

These variables define a "supercell", from the primitive cell repeated along each primitive direction. This supercell is build as follows :
do isa=-nsa,nsa
 do isb=-nsb,nsb
  do isc=-nsc,nsc
    -> here, the cell is translated by the vector
    -> (isa,isb,isc) in crystallographic coordinates
    -> and accumulated, to give the supercell
  enddo
 enddo
enddo




Go to the top | Go to the AIM input variable list
ntheta
Characteristic: numerics
Variable type: integer
Default: 32

With nphi, this variable defines the angular grid for the integration within the Bader volume, in particular, the number of theta angles, to be used between thetamin and thetamax. When the difference between these two variables is pi, the recommended value of ntheta is 32. When it is pi/2 (for symmetry reasons), the recommended value is 20.



Go to the top | Go to the AIM input variable list
phimin, phimax
Characteristic: numerics
Variable type: real
Default: 0.0 for phimin, 2 pi for phimax

Angular limits of integration of the Bader volume for the phi variables. The number of integration points is given by nphi. The range of integration can be decreased if there are symmetry reasons for doing this.



Go to the top | Go to the AIM input variable list
radstp
Characteristic: numerics
Variable type: real
Default: 0.05

The length of the first step in the search of the exact Bader radius.



Go to the top | Go to the AIM input variable list
ratmin
Characteristic: numerics
Variable type: real
Default: 1.0

The first estimation of the smallest radius of the bassin of the atom (the distance at which the procedure that follows the gradient path annonces that the gradient path finishes in the corresponding atom) This parameter is very important for the speed of the calculation, but this first estimation is not usually used because the program makes a new one based on the knowledge of CPs. In fact after the CP analysis, the new estimation is done by the product of the adhoc parameter coff1 (default 0.98) by the distance of the nearest bonding CP. If there is a problem later, coff2 (default 0.95) is used instead.



Go to the top | Go to the AIM input variable list
rsurdir
Characteristic: numerics
Variable type: real rsurdir(2)
Default: 0.0, 0.0

In the case rsurf=1, gives the direction (angular coordinates theta,phi) along which the radius of the Bader surface is to be determined.



Go to the top | Go to the AIM input variable list
rsurf
Characteristic: driver
Variable type: integer
Default: 0

Drive the computation of the radius of the Bader surface for the angles specified in the input variable rsurdir



Go to the top | Go to the AIM input variable list
scal
Characteristic: numerics
Variable type: real scal(3)
Default: 1.0, 1.0, 1.0

The scaling of the cartesian coordinates for the computation of the distances (x'[i]=x[i]/scal[i]). Not really useful.



Go to the top | Go to the AIM input variable list
surf
Characteristic: driver
Variable type: integer
Default: 0

Drive the computation of the full Bader surface.



Go to the top | Go to the AIM input variable list
thetamin, thetamax
Characteristic: numerics
Variable type: real
Default: 0.0 for thetamin, pi for thetamax

Angular limits of integration of the Bader volume for the theta variables. The number of integration points is given by ntheta. The range of integration can be decreased if there are symmetry reasons for doing this.



Go to the top | Go to the AIM input variable list
vpts
Characteristic: numerics
Variable type: real vpts(6) or vpts(9)
Default: all zero

Basic vectors of the line or rectangle in real space, defining the points for which the density or laplacian will be computed, thanks to denout or lapout



Go to the top | Go to the AIM input variable list
Goto : ABINIT home Page | Welcome | Suggested acknowledgments | List of input variables | Tutorial home page | Bibliography
Help files : New user's guide | Abinis (main) | Abinis (respfn) | Mrgddb | Anaddb | AIM (Bader) | Cut3D