-----------------------------------------------------------------
----------  GW code, Epsilon  -----------------------------------
-----------------------------------------------------------------

  Version 1.0	(September, 2011)

  Version 0.5	J. Deslippe, D. Prendergast, L. Yang, F. Ribeiro, G. Samsonidze (2008)
  Version 0.2	S. Ismail-Beigi (2002)
  Version 0.1	G. M. Rignanese, E. Chang, X. Blase  (1998)
  Version 0.0	M. Hybertsen (1985)

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

Description:

Epsilon is the name of the code that generates the polarizability matrix and 
the inverse dielectric matrix for a bulk or nanoscale system. The main 
result of the Epsilon code is the generation of epsmat which can be used
in a Sigma or BSE calculation.

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

Required Input:

	epsilon.inp	Input parameters. See example in this directory. 
	WFN		This is linked to the unshifted grid. 
	WFNq		For non-box type truncated Coulomb interactions 
                        (including no-truncation) or metallic/graphene
			systems this is linked to the shifted grid.  If you are using
			Coulomb truncation on a semiconductor, this is typically
			simply linked to WFN, and q0 is set to exactly zero.

Auxiliary Files: (output files from previous runs, used as input to speed up calculation)

	chimat		Polarizability matrix. No need to recalculate matrix elements.
	chi0mat		Polarizability matrix at q=0. No need to recalculate matrix elements.

        The files below are used if eqp_corrections is set in epsilon.inp.
        The corrected eigenvalues are used for constructing the polarizability matrix.
        eqp.dat         A list of quasiparticle energy corrections for the bands in WFN.
        eqp_q.dat       A list of quasiparticle energy corrections for the bands in WFNq.

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

	epsilon.inp	Please see example epsilon.inp in this directory
			for more complete options.

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

Output Files: 
	
	espmat			Inverse dielectric matrix (q<>0).
	eps0mat			Inverse dielectric matrix (q->0).
	epsilon.log		The log file containing values of chimat and epsmat.
        chi_converge.dat	Convergence chi with respect to empty orbitals.
                                Columns: number of conduction bands,
                                Re chi(G=0,G'=0,q),     extrapolated Re chi(G=0,G'=0,q),
				Re chi(G=Max,G'=Max,q), extrapolated Re chi(G=Max,G'=Max,q)

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

Tricks and hints:

1. Comments on convergence of epsilon_cutoff

There are many ways to check convergence of this parameter:

-Ideally, the inverse epsilon matrix is almost diagonal for large 
G vectors. So, for small ( G , G' ) it is usually large but, for 
 G or G' close to G_max, it is smaller by a factor of 100, more or 
less. Check if the ratio between the greatest and lowest matrix 
elements is large.

-Alternatively, one can check if epsinv( G_max , G'_max ) is close 
to 1 for G = G'. It should be about 0.999 or so. Note that 0.9 isn't 
"close to 1" in this case! Also check if epsinv( G_max , G'_max ) is 
indeed small for G != G'.

2. Comments on the null point

The null point (Gamma point) is treated in a special manner. In input, 
declare it as slightly shifted from the true Gamma point:

  0.0000    0.0050    0.0050   1.0   1

This is the only k-point with itestq=1 instead of 0!

The magnitude of this vector must be small: of order 0.01 or smaller 
for less than 100 points in full Brillouin zone. If the density 
of points in BZ increases, that magnitude should decrease accordingly.

3. Macroscopic dielectric constant

In GW, the screened interaction gives the formula:

  eps(G,G';q) = delta_GG' - [4pi e^2/(q+G)^2 ] chi(G,G';q) 

where chi(G,G';q) is the polarizability (P in the literature).

  if G=0  and q=0

  then we let

   eps(0,G';q) = delta_0G' - lim(q->0) [4pi/(q)^2] chi(0,G';q)

always check chi(0,0;q->0) and eps^(-1)(0,0;q->0)
in epsilon.log

1/eps^(-1)(0,0;q->) should be the macroscopic epsilon, 
                    local-field effects
1/(1-4*pi*chi(0,0;q->0)*V_c(0) should also be (roughly) the macroscopic epsilon,
                              without local-field effects

4. Merging epsmat files

The Epsilon code is complex and involves lots of computation. Frequently, 
it is useful to calculate the epsilon matrix for a small number 
of points, and later put all those pieces of matrix in a small big
epsmat file. Use epsmat_merge to do this. See below.

Notes:
-epsilon cutoff *must* be the same for all files to be merged
-The ordering of q-points must correspond to the ordering of epsmat 
files: the first file has the first set of points, the second file 
has the second and so on.

5. Utilities:

----------------------------------------------------------------------
---------  epsmat, eps0mat conversion  -------------------------------
----------------------------------------------------------------------

TOOLS: epsbinasc, epsascbin

USAGE: simply type name of executable. 

The input file is named epsconv.inp.

----------------------------------------------------------------------
--------  WFN/RHO/VXC conversion -------------------------------------
----------------------------------------------------------------------

TOOL: mf_convert_wrapper.sh

USAGE: 
  sh mf_convert_wrapper.sh infile outfile

Real/complex, bin/asc, file type, is automatically detected.

----------------------------------------------------------------------
---------  epsmat merging  -------------------------------------------
----------------------------------------------------------------------

TOOL: epsmat_merge

USAGE:  epsmat_merge.[real/cplx].x epsmat1 epsmat2 [more epsmat files] epsmat_out

Merges the content of binary files epsmat1 and epsmat2 into
epsmat_out, basically concatenating data.


Converters from old versions of file formats to current version are available in version 2.4.
