================================================================================
BerkeleyGW: MeanField wrappers and utilities
================================================================================

  Version 2.0   (May, 2018)
  To be announced.

  Version 1.2   (Aug, 2016)
  F. H. da Jornada, J. Deslippe, D. Vigil-Fowler, J. I. Mustafa, T. Rangel,
  F. Bruneval, F. Liu, D. Y. Qiu, D. A. Strubbe, G. Samsonidze, J. Lischner.

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

Description:

BerkeleyGW uses a mean-field starting point, typically from DFT.
Currently, BerkeleyGW supports two plane-wave DFT codes, 
PARATEC and Quantum ESPRESSO; one localized-orbital DFT code, SIESTA;
and two real-space codes, Octopus and PARSEC. 
You can find details on how to use BerkeleyGW with these codes in
their respective directories.

For testing purposes and for crude calculations of large systems,
BerkeleyGW can be executed on top of the empirical pseudopotential
plane-wave code. See MeanField/EPM for details.

There is a tool for generating large numbers of unoccupied orbitals
(approximate from plane waves or exact by iterative diagonalization).
It is located in MeanField/SAPO.

You can find a simple code for computing the Coulomb integral within
an image-charge model in MeanField/ICM.

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

Tricks and hints:

1. Vxc0

Vxc0 is the G=0 component of the exchange-correlation potential Vxc. 
Vxc0 is added to the eigenvalues in the wavefunction files produced 
by PARATEC and ESPRESSO. Vxc0 is also included in the VXC and vxc.dat 
files produced by PARATEC and ESPRESSO (the VXC file contains Vxc(G) 
and the vxc.dat file contains matrix elements of Vxc). The two Vxc0 
terms cancel out when calculating the quasiparticle corrections 
in the Sigma code.

2. Vacuum level

To correct the DFT eigenvalues for the vacuum level take the average 
of the electrostatic potential on the faces of the unit cell in the 
non-periodic directions and subtract it from the DFT eigenvalues. 
The electrostatic potential is defined as Velec = Vbare + Vhartree, 
while the total potential is Vtot = Vbare + Vhartree + Vxc, hence 
Vtot contains Vxc0 and Velec does not. The average of Velec is 
fed into the Sigma code using keywords avgpot and avgpot_outer. 
The potentials can be generated with PARATEC and ESPRESSO. 
In PARATEC, use elecplot for Velec or potplot for Vtot, then 
convert from a3dr to cube using the Visual/volume.py script. 
In ESPRESSO, use iflag=3, output_format=6, and plot_num=11 
for Velec or plot_num=1 for Vtot. The averaging is done with 
the Visual/average.py script.

3. Unit cell size

If you truncate the Coulomb interaction, make sure that the size 
of the unit cell in non-periodic directions is at least two times 
larger than the size of the charge distribution. This is needed 
to avoid spurious interactions between periodic replicas but at 
the same time not to alter interactions within the same unit cell. 
Run Visual/surface.x to plot an isosurface that contains 99% of the 
charge density (see Visual/README for instructions on how to do this). 
The code will print the size of the box that contains the isosurface 
to stdout. Multiply the box dimensions in non-periodic directions 
by two to get the minimum size of the unit cell.

4. Inversion symmetry

When using the real flavor of the code, make sure the inversion 
symmetry has no associated fractional translation (if it does, 
shift the coordinate origin). Otherwise WFN, VXC, RHO (and VSC 
in SAPO) have non-vanishing imaginary parts which are simply 
dropped in the real flavor of the code. This won't do any 
good to your calculation...

