# Quantum ESPRESSO

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.

## Core wrappers and utilities

### pw2bgw.x

Converts the output files produced by pw.x to the input files for BerkeleyGW. The format of the input file for pw2bgw.x is described here.

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.

#### 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.

#### 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.

### kgrid.x

Utility to generate k-points in Quantum ESPRESSO for BerkeleyGW calculations. The format of the input file for kgrid.x is described here. You can also use the data-file2kgrid.py utility to automatically create the input file for 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.

## Auxiliary wrappers and utilities

### 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.

### bgw2pw.x

Warning

bgw2pw.x is no longer supported by Quantum ESPRESSO version 6.2+.

Converts BerkeleyGW WFN and RHO files to the format ofpw.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.


7) Perform iterative diagonalization in SAPO instead of using pw.x, see examples/DFT/Si2_sapo for details.

8) Use ParaBands instead of pw.x to diagonalize the whole DFT Hamiltonian.

9) 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.

## Older versions

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 gitlab website: https://gitlab.com/QEF/q-e.