-----------------------------------------------------------------
----------  PlotXct code  ---------------------------------------
-----------------------------------------------------------------

  Version 1.0	(July, 2011)

  Version 0.5	F. Ribeiro (2008)
  Version 0.2	M. L. Tiago (2002-2007)

-----------------------------------------------------------------

Description:

PlotXct plots the exciton wavefunction in real space based on
output of BSE/absorption (with full diagonalization).

-----------------------------------------------------------------

Tricks and hints:

1. Copy/edit plotxct.inp. 

   You'll need:
     . index of the exciton state you want to plot
     . q-shift
     . hole position in lattice coordinates
     . unit-cell lattice vectors 
     . supercell dimensions (or k-grid)
 
   
2. Run plotxct.x

   The ASCII file 'xct.[state].a3Dr' will be created. 

   'a3Dr' means that the file is in ASCII (as opposed to binary: 'b3Dr') and 
   contains 3D data in 'r' real space.

   The header of this file contains information on
     . state index
     . state energy in eV
     . hole position in atomic units (a.u.)
     . supercell lattice vectors in a.u.
     . number of discretization points
   followed by three columns of data corresponding to the complex values of the  
   electronic part of the excitonic wavefunction, and its magnitude squared. 

   The values are written with very low precision due to file-size concerns.

   
3. Convert to a format readable by the plotting utility of your choice.

   Use the 'volume.py' utility:

   Usage: volume.py imfn imff ivfn ivff ovfn ovff phas cplx [hole]

   imfn = input matter file name
   imff = input matter file format
          (mat|paratec|vasp|espresso|siesta|tbpw|xyz|xsf)
   ivfn = input volumetric file name
   ivff = input volumetric file format (a3dr)
   ovfn = output volumetric file name
   ovff = output volumetric file format (cube|xsf)
   phas = remove wavefunction phase (true|false)
   cplx = complex wavefunction (re|im|abs|abs2)
   hole = plot hole (true|false)

   You can specify whether you want a .xsf (XCrysDen) or .cube (Gaussian Cube)
   file format. You can remove or keep the arbitrary phase of the wavefunction
   by setting parameter "phas" to true or false. You can plot the re, im, abs,
   or abs2 part of the wavefunction.

   You must specify a path to the DFT input file (example: "../01-scf/input")
   in a paratec or espresso directory so that the script can obtain the atomic
   positions from the file.

   You can choose whether to display or not the position of the hole by setting
   parameter "hole" to true or false.

   ****************
   Example: 

     % ~/BerkeleyGW/Visual/volume.py ../01-scf/input paratec xct.001.a3Dr a3dr \
                    xct.001.abs2.xsf xsf false abs2 false
     % xcrysden --xsf xct.001.abs2.xsf

   ****************
