ABINIT, tutorial :
indications for the visualisation of different graphical data.

Copyright (C) 2000-2006 ABINIT group (XG,MM)
This file is distributed under the terms of the
GNU General Public License, see ~abinit/COPYING
or http://www.gnu.org/copyleft/gpl.txt .
For the initials of contributors, see ~abinit/doc/developers/contributors .

- total energy curves (as a function of the interatomic distances, or
 lattice parameters)
- the three-dimensional charge density
- the band structure
It relies on the XMGR and Matlab softwares. 
The first is free 
 (http://plasma-gate.weizmann.ac.il/Xmgr). 
The second is not free, but Scilab is a equivalent software, 
that is free (http://www-rocq.inria.fr/scilab).

Many indications are valid for the MAPR2451 lecture, in Louvain-la-Neuve.

====================================================================
 
0. For the MAPR2451 lecture : 
 how to access xmgr ?

In bash, execute
. /usr/local/mapr/profile.mapr

In csh, the corresponding command is
source /usr/local/mapr/csh.mapr

xmgr should become accessible ...
(In bash, you might need :
 export DISPLAY=display_name
 or, in csh :
 setenv DISPLAY=display_name
 where display_name is to be replaced by the name of your display)

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

1. Visualisation of the H2 energy curve

From the t12.out file, get the data

    etotal1  -1.0368223887E+00
    etotal2  -1.0538645429E+00
    etotal3  -1.0674504849E+00
    etotal4  -1.0781904895E+00
    etotal5  -1.0865814784E+00
    etotal6  -1.0930286804E+00
    etotal7  -1.0978628208E+00
    etotal8  -1.1013539125E+00
    etotal9  -1.1037224214E+00
    etotal10 -1.1051483730E+00
    etotal11 -1.1057788247E+00
    etotal12 -1.1057340255E+00
    etotal13 -1.1051125108E+00
    etotal14 -1.1039953253E+00
    etotal15 -1.1024495225E+00
    etotal16 -1.1005310615E+00
    etotal17 -1.0982871941E+00
    etotal18 -1.0957584182E+00
    etotal19 -1.0929800578E+00
    etotal20 -1.0899835224E+00
    etotal21 -1.0867972868E+00

and put them in a file, for example "energies".
Get rid off the string "etotal", and put it in
a file "data", for example
using the stream editor sed :

sed 's/etotal//' energies > data

Now, you can use xmgr to visualize the data file :

xmgr

In the file menu, read sets ;
select the "data" file, in XY format, autoscale on read ...
You should get the graph ...  

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

2. Visualisation of the three-dimensional charge densities.
 (Section 1.4.c , visualisation of the H2 charge density)

The UNFORMATTED density files can be visualized
in two steps :
- first create a file with FORMATTED data ;
- visualize these data using MATLAB.  

2.1. The generation of the FORMATTED datafile.

One can rely on the cut3d utility, present in ABINIT. 
Follow the instructions given in ~abinit/doc/users/cut3d_help.html .
Use the option 
5) conversion to formatted file

On the screen, you will get, among others, some
information about the FFT grid as well as minimum
and maximum density. You should take note of these. 
In addition to the above-mentioned information on the screen,
you will get a formatted file, that you can name "file.out", 
with one column of numbers, like the following :

 0.000002
 0.000003
 0.000003
 0.000003
 0.000003
 0.000003
 0.000002
 0.000001
 0.000000
 0.000002
 0.000009
 0.000030
 0.000074
 0.000143
 0.000211
 0.000235
 0.000201
 0.000135     
  ....

This is a typical formatted density file. Since such file does NOT contain
any information about how they were generated, it is preferable
not to keep them, but only use them as temporaries, for the
generation of charge density plots, as explained later.
                                                                                  
2.2. The visualisation of a 3D charge density using Matlab.

The reference directory contains a compressed formatted density file :
~abinit/tests/tutorial/Refs/Pb_in_SiO2.out.gz
You should decompress it :

gunzip Pb_in_SiO2.out.gz

Then, you will use the dim.m script to visualize that density. 
Edit this dim.m script . Note that it requires the formatted density 
file to be placed in file.out . Note also that it needs the
x, y and z linear size of the FFT grid (ngx, ngy, ngz). Finally,
it also needs the value of the charge density isosurface that
will be computed (isodens).

So, copy Pb_in_SiO2.out in the proper place :

cp Pb_in_SiO2.out file.out

Then, run matlab : 

matlab

and, when you are in matlab, input the dim.m script :

dim

A new window will open, with the desired 3D visualisation
of the charge density. The 3D charge density isosurface that
you are looking at corresponds to the unoccupied gap state of 
a Pb impurity placed in a 2x2x2 SiO2-quartz supercell. 
It is an anti-bonding combination of Pb6s and O2p states.

You can change the file by first clearing
    clf
then input the script again (with eventual modified values):
    dim
You can exit using
    exit             

For other formatted data, you will likely have to change the ngx, ngy and ngz
values, as well as the isodens value.


2.3. The H2 charge density

If you follow the above-mentioned steps, starting from the t1xo_DEN
(or maybe another name has been given to the file from the t14.in run ?),
you will obtain a graphics that show a sphere splitted in the eight corners
of the cubic supercell. Indeed, the H2 molecule was centered on (0 0 0),
while the visualisation cell has reduced coordinates ([0,1],[0,1],[0,1]).
Thus the center of the molecule corresponds to the corners of the cube.

In order to obtain a molecule correctly centered in the supercell, one
should start from the following coordinates :

xcart      4.249  5.0  5.0
           5.761  5.0  5.0

that is, the original coordinates have been shifted by 5.0 5.0 5.0 , 
to be in the center of the supercell.


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

3. Visualisation of the Si band structure.
 
At the end of the section 3.4 , you should extract the eigenvalues (in eV),
starting with

 kpt#   1, nband=  8, wtk=1.00000, kpt=  0.5000  0.0000  0.0000 (reduced coord.)
   5.85700   8.48654  14.34081  14.34081  17.03075  18.88266  18.88266  23.10049
 kpt#   2, nband=  8, wtk=1.00000, kpt=  0.4500  0.0000  0.0000 (reduced coord.)
   5.71762   8.68744  14.35705  14.35705  17.04972  18.89958  18.89958  23.13268
 kpt#   3, nband=  8, wtk=1.00000, kpt=  0.4000  0.0000  0.0000 (reduced coord.)
   5.39103   9.20107  14.41138  14.41138  17.11127  18.95585  18.95585  23.22068
 kpt#   4, nband=  8, wtk=1.00000, kpt=  0.3500  0.0000  0.0000 (reduced coord.)
   5.00529   9.89423  14.50143  14.50143  17.21136  19.02706  19.02706  23.28882
 kpt#   5, nband=  8, wtk=1.00000, kpt=  0.3000  0.0000  0.0000 (reduced coord.)
    ....

and store them in a file, let us call it "eigenenergies".
In order to generate a file that can be treated by XMGR, one has to
suppress the lines that begin with "kpt#", and one has to number
the remaining lines.
You can process this file as follows :

grep -v wtk eigenenergies | grep -n '.' > data

(some other instruction might generate it as well, but this one works fine ...)
The result is stored in "data".

You can now proceed with the band structure visualisation, using XMGR.
The only difference with the visualisation of the total energy is that
you have more than one curve. So, select the 

X Y1 Y2 ...

mode instead of the  X Y  mode.

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