THIS DOC document needs to be upgraded since we have move from a single script to
a package.. this will be done soon

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


Let start with bandstructures, everyboby love them, and at least in my
case is the 99% of the usage of this program.

-First you should choose a suitable PROCAR, by suitable, I mean a
 bandstructure calculation.

  fmunoz@theo109:~.../surf/LDA/bands$ ls -lh PROCAR
  -rw-r--r-- 1 fmunoz fmunoz 165M Feb 20 17:56 PROCAR

In this case, as the output says the PROCAR file is about 165MB, it is
not too much, but, if your favorite PROCAR is about ~250MB you should
consider going first to the section about "filter" (will be written
some day in the future) in first place, or you could run out of memory
(or, you can change the PROCAR file, by instance bulk systems are
always a good starting point).

Now lets invoke the script (as you see is a good idea put it on the
path and give permission to be executed)

  fmunoz@theo109:~/svn/TI/VASP/FM/Bi2Te3/new/sAu2x2$ procar.py usage:
  procar.py [-h] {cat,filter,bandsplot,fermi2D} ...  procar.py: error:
  too few arguments

As you can see, the program printed a error on the screen. If you are
not used to the command line, "[]" means optional thing, "{}" means
choices, and "..." means something like 'once you had choosen
somenthing I will tell you more'. Therefore you can choose "-h" to get
some help. If you are a verbose person "--help" will suit you.

  fmunoz@theo109:~.../surf/LDA/bands$ procar.py  -h
  usage: procar.py [-h] {cat,filter,bandsplot,fermi2D} ...

  procar.py: a python library/script to manipulate and plot VASP's PROCAR files.

  positional arguments:
    {cat,filter,bandsplot,fermi2D}
                          sub-command
      cat                 concatenation of PROCARs files, they should be
                          compatible (ie: joining parts of a large bandstructure
                          calculation).
      filter              Filters (manipulates) the data of the input file
                          (PROCAR-like) and yields a new file (PROCAR-like too)
                          with the changes. This method can do only one
                          manipulation at time (ie: spin/atoms /bands/orbitals).
                          This method is memory friendly and can handle HUGE
                          input files. The output File is PROCAR-like (ie. can
                          be used by this script)
      bandsplot           Bandstructure plot. This kind of plot can be fairly
                          complex therefore its worth to explore all options. If
                          the file is large (>100MB) you should consider use the
                          `filter` command before. Mind not all option are
                          meaningful (even considered) for all `modes`
      fermi2D             Plot the Fermi surface for a 2D Brillouin zone (layer-
                          wise) along z

  optional arguments:
    -h, --help            show this help message and exit

If you are not too lazy, and readed the output you will realize that
you need the subcommand "bandsplot" (fairly intuitive name). By the
way, you already have an idea of what the other subcommands are.Now
let invoke the program with the right subcommand.

  fmunoz@theo109:~.../surf/LDA/bands$ procar.py bandsplot
  usage: procar.py bandsplot [-h] [-v | -q] [-m {scatter,plain,parametric}]
                             [-s {0,1,2,3}] [-a ATOMS [ATOMS ...]]
                             [-o ORBITALS [ORBITALS ...]] [-f FERMI]
                             [--elimit ELIMIT ELIMIT] [--mask MASK]
                             [--markersize MARKERSIZE] [--cmap CMAP]
                             [--vmax VMAX] [--vmin VMIN] [--grid GRID]
                             [--marker MARKER] [--permissive] [--human_atoms]
                             [--savefig SAVEFIG] [--kticks KTICKS [KTICKS ...]]
                             [--kticksnames KTICKSNAMES [KTICKSNAMES ...]]
                             [-t TITLE]
                             file
  procar.py bandsplot: error: too few arguments

Again an error, but a pretty informative one. If you focus on the
"usage" section of the output before, the last argument "file" is not
surrounded by "[]", therefore it is mandatory. Altough it meaning is
intuitive (the PROCAR file do you want to plot) as always you can get
its meaning just running appending a "-h" (Do you recognize a
pattern here?):

  fmunoz@theo109:~.../surf/LDA/bands$ procar.py bandsplot -h

  usage: procar.py bandsplot [-h] [-v | -q] [-m {scatter,plain,parametric}]
                             [-s {0,1,2,3}] [-a ATOMS [ATOMS ...]]
                             [-o ORBITALS [ORBITALS ...]] [-f FERMI]
                             [--elimit ELIMIT ELIMIT] [--mask MASK]
                             [--markersize MARKERSIZE] [--cmap CMAP]
                             [--vmax VMAX] [--vmin VMIN] [--grid GRID]
                             [--marker MARKER] [--permissive] [--human_atoms]
                             [--savefig SAVEFIG] [--kticks KTICKS [KTICKS ...]]
                             [--kticksnames KTICKSNAMES [KTICKSNAMES ...]]
                             [-t TITLE]
                             file
  
  positional arguments:
    file                  Input file. Can be compressed
  
  optional arguments:
    -h, --help            show this help message and exit
    -v, --verbose
    -q, --quiet
    -m {scatter,plain,parametric}, --mode {scatter,plain,parametric}
                          mode of plot
    -s {0,1,2,3}, --spin {0,1,2,3}
                          Block of data to be used: density, magnet. or m_x,
                          m_y, m_z. The default is 0 (density)
    -a ATOMS [ATOMS ...], --atoms ATOMS [ATOMS ...]
                          atoms to be used 0-based: ie. '-a 0 2' for select the
                          1st and 3rd. It defaults to the last one (the 'tot'
                          entry)
    -o ORBITALS [ORBITALS ...], --orbitals ORBITALS [ORBITALS ...]
                          orbital index to be used 0-based. Take a look to the
                          PROCAR file. Its default is the last field (ie: 'tot')
    -f FERMI, --fermi FERMI
                          set the Fermi energy (or any reference energy). To get
                          it you should `grep E-fermi` the self-consistent
                          OUTCAR.
    --elimit ELIMIT ELIMIT
                          Min/Max energy to be ploted
    --mask MASK           If set, masks(hides) values lowers than it. Useful to
                          remove unwanted bands.
    --markersize MARKERSIZE
                          size of markers, if used. Mind each mode has it own
                          scale
    --cmap CMAP           colormap name (google 'matplotlib colormap'). For
                          spin-texture I recommend 'seismic'
    --vmax VMAX           max. value of the parameter (ie: projection on
                          something given by -a, -o or -s) to plot (ie: 1)
    --vmin VMIN           min. value of the parameter to plot (ie: 0 for not
                          magnetic stuff)
    --grid GRID           switch on/off the grid
    --marker MARKER       set the marker shape, ie: 'o'=circle, 's'=square,\
                          '-'=line(only mode `plain`)
    --permissive          Some fault tolerance for ill-formatted files (stupid
                          fortran)But be careful, something could be messed up.
    --human_atoms         enable human-like 1-based order (ie 1st is 1, 2nd is
                          2, and so on)
    --savefig SAVEFIG     Saves the figure, instead of display it on screen.
                          Anyway, you can save from the screen too. Any file
                          extension supported by matplotlib.savefig is valid (if
                          you are too lazy to google it, trial and error also
                          works)
    --kticks KTICKS [KTICKS ...]
                          list of ticks along the kpoints axis (x axis)
    --kticksnames KTICKSNAMES [KTICKSNAMES ...]
                          names of the points given in `--kticks`
    -t TITLE, --title TITLE
                          Title, o out several words "use quotation marks"
  


This time there is a lot of output, since there are a lot of options
to get your desired bandstruture. If you want to learn how to use the
program, please expend some of your time reading the embedded
help. Regarding the bandstructure plot, we know taht the PROCAR file
also can be compressed (gzipped).

  fmunoz@theo109:~.../surf/LDA/bands$ procar.py bandsplot PROCAR
  Fermi Energy not set!!!

  (and a figure pops on the screen)

At last, the program is ploting something. Also a Warning regarding
the fermi level is displayed. To put the fermi level, as you already
now from the embedded help, use the "-f" of "--fermi". Remember that
you need the Fermi level from a regular-meshed calculation (not
bandstructure). In my case:

  fmunoz@theo109:~.../surf/LDA/bands$ grep E-fermi ../OUTCAR 
   E-fermi :   3.6663     XC(G=0):  -8.1111     alpha+bet : -8.8571

Also is useful plot just some energy window around E-fermi, lets call
the program again:

  procar.py bandsplot PROCAR -f 3.6663 --elimit -1 1

  (a nicer figure pops on the screen)

You can see a bandstructure, with color ranging from yellow to
black. The color is (by default) the projection of each band into all
atoms (ie: spheres of RWIG diameters). If you do not want to see any
color (up to they are now useless), just select a featureless "plain"
"mode". Also if you do not like points just set the "marker" to
nothing.

  fmunoz@theo109:~.../surf/LDA/bands$ procar.py bandsplot PROCAR -f 3.6663 --elimit -1 1 --mode plain --marker ""
  old spd.shape=  (108800, 231)
  new spd.shape=  (200, 136, 4, 21, 11)
  self.kpoints:  (200, 3)
  xaxis.shape :  (200,)
  bands.shape :  (136, 200)

  (figure)

It would be far more fun use the real power of the PROCAR file, say to
look the projection of orbitals px+py on the surface, say atoms 1 to
3. Remember (yes I said "remember", since you already readed the
embedded help). Try the following (and change accordingly to your
E-fermi):

  fmunoz@theo109:~/svn/TI/VASP/FM/Bi2Te3/hex/surf/LDA/bands$ procar.py bandsplot PROCAR -f 3.6663 --elimit -1 1 -o 1 2 -a 0 1 2 --mode parametric
   old spd.shape=  (108800, 231)
   new spd.shape=  (200, 136, 4, 21, 11)

  (figure)

How do I know that the desired orbital are "-o 1 2", well take a look
to the help and run:

  fmunoz@theo109:~.../surf/LDA/bands$ head PROCAR
  
  PROCAR lm decomposed
  # of k-points:  200         # of bands: 136         # of ions:  20
  
   k-point    1 :    1.08176271 1.08176271 0.00000000     weight = 0.00500000
  
  band   1 # energy   -9.41911267 # occ.  1.00000000
   
  ion      s     py     pz     px    dxy    dyz    dz2    dxz    dx2    tot
    1  0.002  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.000  0.003
    2  0.032  0.000  0.001  0.000  0.000  0.000  0.000  0.000  0.000  0.033

And you will realize that the orbital indexes are s=0, px=1, py=2, ...
Also you should had noted that the atoms (as the orbitals) are
0-based. If you are a fortran-lover or too human for a 0-based list of
atoms just append "--human_atoms" and you could use a 1-based list of
atoms.

What else? I think you should know how to use the script: relying
(very often) on the embedded help. To end I will put a suitable set of
options for spin textured bands along Sx (of course your PROCAR should
be non-collinear, and is up to you to know what are the quantization
axis pointing to).

fmunoz@theo109:~.../surf/LDA/bands$ procar.py bandsplot PROCAR -f 3.6663 --elimit -1 1 -s 1 --vmin -1 --vmax 1 --cmap seismic --mask 0.05