Quantum ESPRESSO is available for download at http://www.quantum-espresso.org/

The interface between Quantum ESPRESSO and BerkeleyGW consists of three programs, 
kgrid.x, pw2bgw.x and bgw2pw.x. kgrid.x is compiled with BerkeleyGW package and 
pw2bgw.x and bgw2pw.x are compiled with Quantum ESPRESSO. 
Files for versions 4.3.2, 5.0.x, and 5.1.x are supplied here. 
Starting with version 5.0, compatible files of pw2bgw.f90 and bgw2pw.f90 are 
distributed with Quantum ESPRESSO.

If you are using espresso-5.1, apply a patch following the
instructions in BerkeleyGW/MeanField/ESPRESSO/version-5.1/README_patch.
Alternatively, you can use BerkeleyGW/MeanField/ESPRESSO/version-5.1/pw2bgw.f90
(rather than espresso-5.1/PP/src/pw2bgw.f90), which includes a bugfix to
the problem of an immediate segmentation fault or error
saying 'MPI_Comm_rank: Invalid communicator'. To use:
cp BerkeleyGW/MeanField/ESPRESSO/version-5.1/pw2bgw.f90 espresso-5.1/PP/src/
Then 'make pp' in espresso. This seems to happen for MPICH and MVAPICH (and
probably the related IntelMPI) but not OpenMPI, but the updated version should work
in all cases. This is fixed in espresso-5.1.1 and later versions.

The development versions of pw2bgw.f90 and bgw2pw.f90 are available from 
Quantum ESPRESSO trunk. Quantum ESPRESSO allows anonymous checkouts of its 
source code. Use the command below and use 'anonymous' as the username and 
a blank password to checkout the code: 
svn checkout http://qeforge.qe-forge.org/svn/q-e/trunk/espresso

You can find more details about Quantum ESPRESSO svn on this website: 
http://www.qe-forge.org/gf/project/q-e/scmsvn/

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

kgrid.x

pw.x can automatically generate a uniform grid of k-points, either unshifted 
or shifted by half a grid step (Monkhorst-Pack grid), and reduce it to the 
irreducible wedge of the Brillouin Zone with the symmetries of the point group 
of the Bravais lattice and optionally with time-reversal symmetry. The same 
functionality (and more) is provided by kgrid.x in this directory. Additionally, 
kgrid.x can use the symmetries of the space group of the crystal instead of the 
symmetries of the point group of Bravais lattice, which is needed for BerkeleyGW. 
kgrid.x is not limited to the unshifted/half-step shifted Monkhorst-Pack grids. 
It can generate an asymmetrically shifted fine grid used to improve the 
convergence in absorption calculations. Also, kgrid.x can generate a grid 
of k-points with a small q-shift used in Epsilon calculation to avoid the 
divergence of the Coulomb interaction. The list of k-points generated by 
kgrid.x must be manually added to the input file of pw.x. Note that time-reversal
symmetry should NOT be used for BerkeleyGW (noinv = .false. if generating the
k-grid in pw.x), unless the utility wfn_time_reversal.x is run afterward.

The format of the input file for kgrid.x (along with an example for Si) is found 
in kgrid.inp. See also more information in the header of kgrid.f90. You can find 
the input files for kgrid.x in examples/DFT in the ESPRESSO subdirectories of 
each example.

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

data-file2kgrid.py

Parses the atomic positions and FFT grid from a Quantum Espresso data-file.xml
file and creates the input file kgrid.inp for the kgrid.x utility.
All options to kgrid.x -- such as number of k-points, k-shift, and k-grid --
are read as optional command-line arguments to data-file2kgrid.py. Type
data-file2kgrid.py --help for a list of possible options.

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

pw2bgw.x

Converts the output files produced by pw.x to the input files for BerkeleyGW.

You cannot use USPP, PAW, or spinors in a pw.x run for BerkeleyGW.

You cannot use "K_POINTS gamma" in a pw.x run for BerkeleyGW. 
Use "K_POINTS { tpiba | automatic | crystal }" even for the 
Gamma-point calculation.

The format of the input file for pw2bgw.x is described 
in files MeanField/ESPRESSO/version-4.3.2/pw2bgw.inp,
MeanField/ESPRESSO/version-5.1/INPUT_pw2bgw.html (copy of espresso-5.1/PP/Doc/INPUT_pw2bgw.html),
which is generated from MeanField/ESPRESSO/version-5.1/INPUT_pw2bgw.def, and
MeanField/ESPRESSO/version-5.0/INPUT_pw2bgw.html (copy of espresso-5.0.3/PP/Doc/INPUT_pw2bgw.html),
which is generated from MeanField/ESPRESSO/version-5.0/INPUT_pw2bgw.def. 
You can find the input files for pw2bgw.x in examples/DFT 
in the ESPRESSO subdirectories of each example.

Version 4.3.2 and earlier:

It is recommended to run a pw.x "nscf" calculation with "K_POINTS crystal" 
and a list of k-points produced by kgrid.x.

Sometimes pw.x generates additional k-points in a "nscf" run with an explicit 
list of k-points. If this is the case for your calculation, there are several 
ways to go around this problem:

* Apply the patch provided with BerkeleyGW. It will prevent pw.x from 
  generating additional k-points if they are provided explicitly, and 
  take care of the normalization of the weights of k-points in a "bands" 
  calculation. 
* Do not specify the atomic positions in the input file of kgrid.x (set 
  number of atoms = 0). Then pw.x will generate additional k-points which 
  are the correct ones. Also set noinv = .true. in the input file of pw.x 
  if time-reversal symmetry was not used in kgrid.x. 
* Run a pw.x "bands" calculation instead of "nscf". In this case you have 
  to explicitly specify the occupations in the input file of pw2bgw.x (note 
  that this only works for insulators) and to normalize the weights of 
  k-points to one in the input file of pw.x.

Version 5.0 and later:

It is recommended to run a pw.x "bands" calculation with "K_POINTS crystal" 
and a list of k-points produced by kgrid.x.

You can also run a pw.x "nscf" calculation instead of "bands", but in this 
case pw.x may generate more k-points than provided in the input file of pw.x. 
If this is the case for your calculation you will get errors in BerkeleyGW.

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

bgw2pw.x

Converts BerkeleyGW WFN and RHO files to the format of pw.x. 
This can be useful, for example, if you generate the plane waves 
on top of the valence bands and want to diagonalize them in pw.x. 
Look at the documentation for SAPO code in BerkeleyGW for more information.
Another possible use is to convert between different versions of pw.x.

bgw2pw.x reads common parameters from file prefix.save/data-file.xml and 
writes files prefix.save/charge-density.dat (charge density in R-space), 
prefix.save/gvectors.dat (G-vectors for charge density and potential), 
prefix.save/K$n/eigenval.xml (eigenvalues and occupations for nth k-point), 
prefix.save/K$n/evc.dat (wavefunctions in G-space for nth k-point), and 
prefix.save/K$n/gkvectors.dat (G-vectors for nth k-point).

You must have prefix.save/K$n/eigenval.xml files present, or an error will occur,
even though their contents will not be used and will be overwritten.
The best is to run a pw.x calculation and use its prefix.save, e.g. from scf
and then get unoccupied bands from bgw2pw.x.

bgw2pw.x doesn't create restart files, so you cannot use restart_mode = 'restart'
for a subsequent pw.x run. Instead, use startingwfc = 'file'. Make sure
wf_collect = .true. and there are no prefix.wfc* files present. Also, the pw.x run
that generated the prefix.save directory originally must have wf_collect = .true.
also, for the appropriate links to the K$n files to be present.

bgw2pw.x doesn't modify file prefix.save/data-file.xml so make changes to this 
file manually. For example, you will need to change the NUMBER_OF_BANDS and
NUMBER_OF_PROCESSORS tags (as well as per pool and per image) to make sure these
match the number of bands from the WFN file, as well as the number of processors
you will use in a subsequent run.

The format of the input file for bgw2pw.x is described 
in files MeanField/ESPRESSO/version-4.3.2/bgw2pw.inp,
MeanField/ESPRESSO/version-5.1/INPUT_bgw2pw.html (copy of espresso-5.1/PP/Doc/INPUT_bgw2pw.html),
which is generated from MeanField/ESPRESSO/version-5.1/INPUT_bgw2pw.def, and
MeanField/ESPRESSO/version-5.0/INPUT_bgw2pw.html (copy of espresso-5.0.3/PP/Doc/INPUT_bgw2pw.html),
which is generated from MeanField/ESPRESSO/version-5.0/INPUT_bgw2pw.def.

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

Notes on running pw.x

Sometimes pw.x crashes when trying to generate a LARGE number of unoccupied 
states needed for GW calculations. The error messages may refer to "Cholesky 
decomposition" or "diagonalization". If you run into this problem try one of 
the following workarounds, or a combination of them:

1) Increase ecutwfc. Iterative diagonalization becomes inefficient and 
unstable with increasing the ratio of the number of states to the size 
of the Hamiltonian. Increasing ecutwfc will decrease this ratio 
at the cost of computation time.

2) Split the calculation over k-points. If one k-point fails, it won't 
affect the other k-points. You can merge the final wavefunction file 
using MeanField/Utilities/wfnmerge.x after running pw2bgw.x for each 
k-point.

3) Start with random instead of randomized atomic wavefunctions. For 
this use the following parameter in the input file of pw.x:

    startingwfc = 'random'

4) Split the diagonalization into several steps alternating between 
different diagonalization schemes. For example, use the following 
parameters in the input files for consequent runs of pw.x:

    1st run:
        conv_thr = 1.0d-2
        diagonalization = 'david'

    2nd run:
        conv_thr = 1.0d-4
        diagonalization = 'cg'
        startingwfc = 'file'

    3rd run:
        conv_thr = 1.0d-6
        diagonalization = 'david'
        startingwfc = 'file'

    etc.

5) Run pw.x with "-ndiag 1". Often serial diagonalization is more 
stable than the parallel one, and the time and memory overhead 
is bearable in most cases.

6) Compile pw.x without "-D__SCALAPACK" in DFLAGS in make.sys 
for using a custom distributed-memory diagonalization instead 
of ScaLAPACK. This is useful to check if the problem 
is caused by improper installation of ScaLAPACK. 
Note that you will have to explicitly specify ndiag, 
e.g. "mpirun -np 24 pw.x -ndiag 16 -in prefix.in > prefix.out", 
because pw.x only sets ndiag automatically in case of ScaLAPACK.

7) Last but not least, perform iterative diagonalization 
in SAPO instead of using pw.x, see examples/DFT/Si2_sapo 
for details.

Finally, it is recommended to always use the following parameters 
in the input files for pw.x:

    wf_collect = .true.
    diago_full_acc = .true.

See documentation on Quantum ESPRESSO for information on these 
parameters.

BEWARE: Sometimes wavefunctions may lose orthogonality during 
iterative diagonalization. Neither Quantum ESPRESSO nor BerkeleyGW 
checks for orthogonality of wavefunctions. This may cause erroneous 
behavior like diverging head of eps0mat and possibly many other things. 
This problem could be avoided by using SAPO [see 7) above] which keeps 
wavefunctions orthogonal during iterative diagonalization.
