================================================================================
GW code: Sigma
================================================================================

  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.

  Version 1.1	(June, 2014)
  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:

Sigma is the second half of the GW code.  It should be run after
calculating epsmat/esp0mat in Epsilon.  It gives the quasiparticle
self-energies and dispersion relation for quasielectron and
quasihole states.  The main result is written to sigma.log file.

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

Required Input:

	sigma.inp	Input parameters.  See example in this directory.
	epsmat(.h5)	Inverse dielectric matrix (q<>0).  Created using Epsilon.
			The file has a ".h5" extension if the code is compiled
			with HDF5 support (for specification, see epsmat.h5.spec).
	eps0mat(.h5)	Inverse dielectric matrix (q->0).  Created using Epsilon.
			The file has a ".h5" extension if the code is compiled
			with HDF5 support (for specification, see epsmat.h5.spec).
	WFN_inner	Real or complex wavefunctions. k-grid should be the same as
                        the q-grid of epsmat, though there can be a shift.
			This is usually the reduced points from an
			unshifted grid.
	RHO		Charge density (only needed for generalized plasmon-pole model),
                        from SCF calculation on which WFN_inner is based.
	vxc.dat		Matrix elements of the exchange-correlation potential,
                        from a mean-field calculation or a previous Sigma run.
                        VXC file may be used instead via keyword dont_use_vxcdat.

Additional Input:

	WFN_outer		Outer wavefunctions between which the
				self-energy operator and exchange-correlation
				potential are sandwiched. If absent inner
				wavefunctions will be used instead. Note that
				VXC should be consistent with outer wfn while
				RHO with inner wfn. If outer wfn is generated
                                using a hybrid functional, VXC contains the
                                local part of exchange-correlation potential.
				In this case set bare_exchange_fraction in
				sigma.inp to compensate for the non-local part,
				or use vxc.dat instead of VXC.

	The file below will be read only if eqp_corrections is set in sigma.inp.
	eqp.dat			A list of quasiparticle energy corrections
				for the bands in WFN_inner.
				The corrected eigenvalues are used for
				constructing the self-energy operator.

	The file below will be read only if eqp_outer_corrections is set in sigma.inp.
	eqp_outer.dat		A list of quasiparticle energy corrections for
				the bands in WFN_outer.
				The corrected eigenvalues determine
				the energies at which the self-energy
				operator is calculated.

	vxc2.dat		Matrix elements of the exchange-correlation potential,
                                from a mean-field calculation or a previous Sigma run. This
				is for a one-shot hybrid functional like calculation instead
				of a Sigma calculation. VXC2 file may be used instead via 
				keyword dont_use_vxc2dat.
				

Auxiliary Files:

	x.dat		Matrix elements of the bare exchange, generated by a previous
			Sigma run to speed up subsequent calculations.
                        Read if use_xdat keyword is present, written otherwise.
	VXC		Exchange-correlation potential (whose matrix elements
			are subtracted from DFT eigenvalues). Produced by
			mean-field code, from SCF calculation on which WFN_inner is based
                        (or WFN_outer, if present).
                        Used only if vxc.dat is not present or keyword dont_use_vxcdat is set.
	VXC2		Exchange-correlation potential (whose matrix elements
			are added to the hybrid functional like exchange). Produced by
			mean-field code, from SCF calculation on which WFN_inner is based
                        (or WFN_outer, if present).
                        Used only if vxc2.dat is not present or keyword dont_use_vxc2dat is set.
                        

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

	sigma.inp	Please see example sigma.inp in this directory for complete options.

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

Output Files:  

	The file below will be read only if eqp_corrections is set in sigma.inp.
	eqp0.dat	Contains the on-shell QP energies = Emf - Vxc - Sig(Eo)
			This is *not* the recommended quantity to use for QP properties.
			This is Eqn. 36 from Hybertsen & Louie PRB 34 5390.
	
	eqp1.dat	Contains the off-shell solution to the linearized Dyson`s equation
			= Eqp0 + (dSig/dE) / (1 - dSig/dE) * (Eqp0 - Eo),
			or a full linear interpolation if more freq. points where computed.
			This is the recommended quantity to use for QP properties.
			If you only evaluate Sigma at two frequencies, this is
			Eqn. 37 from Hybertsen & Louie PRB 34 5390. If there are
			more frequencies available, the code uses them to find
			a better linearized solution. For GW calculations without
			plasmon-pole models, the code reports how many solutions
			to Dyson`s equation were found.

	sigma_hp.log	The log file containing quasiparticle energy values
			for desired states. For a full-frequency calculation
                        only the value for Sigma calculated at energy closest
                        to the outer wavefunction eigenvalue is shown. The file 
                        spectrum.dat contains the full Sigma(E) spectra.

        ch_converge.dat Convergence of Coulomb-hole term with respect to empty orbitals.

        spectrum.dat	The real and imaginary parts of Sigma as a function of
                        energy. The energy grid is specified in sigma.inp. This
                        file is only output in full-frequency calculations.
                        Some general notes:

                        * IM(SIGMA) was calculated using the same broadening
                        as RE(SIGMA), while IM(SIGMA2) was calculated without
                        any broadening.

                        There are 2 Sigmas currently reported if doing a real axis 
                        calculation (frequency_dependence_method 0)

                        1. Sigma = SX + CH with no Broadening. We do the energy 
                           denominator integral analytically.
                        2. Sigma = X + COR with no broadening. We do the energy 
                           denominator integral analytically.

                        For contour deformation (frequency_dependence_method 2)
                        only X + COR is given. But spectrum.dat contains columns
                        for contributions from the poles and imaginary axis
                        integral

                        * Ew is not the same as the frequencies specified in
                        sigma.inp. Ew is the absolute off-shell quasiparticle
                        energy, and it is *not* measured wrt the Fermi energy.
                        The (physically meaningful) on-shell quasiparticle
                        energy EQP is the solution of Dyson's equation:
                        Ew = E_LDA - Vxc + Re[Sig(Ew)].
                        

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

A Note About the Wings of Epsilon (for Semiconductors Only):

The wings of Chi have terms of the following form:

< vk | e^(i(G+q)r) | ck+q >< ck+q | e^(-iqr) | vk > (1)

The matrix element on the right is < u_ck+q | u_vk > where u is the periodic part 
of the Bloch function. From k.p perturbation theory, this matrix element is proportional
to q. The matrix element on the left with a non-zero G is typically roughly
a constant as a function of q for small q (q being a small addition to G).

Thus for a general G-vector, Chi_wing(G,q) \propto q. This directly leads 
to the wings of the screened untruncated Coulomb interaction being proportional 
to 1/q. Note that this function changes sign as q -> -q. Thus, when treating the 
q=0 point, we set the value of the wing to zero (the average of its value in the 
mini-Brillouin zone (mBZ).

For G-vectors on high-symmetry lines, some of the matrix elements on the left of (1)
will be zero for q=0, and therefore proportional to q. For such cases,
Chi_wing(G,q) \propto q^2, and the wings of the screened Coulomb interaction
are constant as a function of q. However, setting the q->0 wings to zero still 
gives us, at worst, linear convergence to the final answer with increased k-point 
sampling, because the q->0 point represents an increasingly smaller area in the 
BZ. Thus, we still zero out the q->0 wings, as discussed in
A Baldereschi and E Tosatti, Phys. Rev. B 17, 4710 (1978).

In the future, it may be worthwhile to have the user calculate chi / epsilon at 
two q-points (a third q-point at q=0 is known) in order to compute the linear 
and quadratic coefficients of each chi_wing(G,q) so that all the correct analytic
limits can be taken. This requires a lot of messy code and more work for the user
for only marginally better convergence with respect to k-points (the wings tend
to make a small difference, and this procedure would matter for only a small set
of the G-vectors). 

It is important, as always, for the user to converge their calculation 
with respect to both the coarse k-point grid used in sigma and kernel as well
as with the fine k-point grid in absorption.


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

Tricks and hints:

1. Comments on convergence of scc (screened_coulomb_cutoff)
   and bcc (bare_coulomb_cutoff)

The parameters scc and bcc are independent to each other and are
related to the number or terms taken into account in the
plane-wave expansion of Sigma_(SEX + COH) and V_xc, respectively.

Since Sigma_(SEX) is related to epsilon, scc should be equal to 
or less than the epsilon_cutoff used to compute chi0 and epsilon.

If you are to use large values for scc and bcc (say 50 Ry or so),  
a good suggestion is run the sigma code twice: first with large
bcc and small scc, just to get x.dat and vxc.dat; then with large
scc and any bcc, using the x.dat and vxc.dat files generated before.
The second run is usually much faster than a run with large scc
and bcc.

2. Metals

If you are doing a metal you should report the shift used in sigma.inp 
whether using truncation or not.

3. Off-diagonal

If you are doing off-diagonal matrix elements of Sigma use the utility 
offdiag in this directory to diagonalize the Sigma matrix.

4. Linear extrapolation for eqp1

If |eqp0 - ecor| > finite_difference_spacing linear extrapolation 
for eqp1 may be inaccurate. You should test the validity of eqp1 
by rerunning calculation with self-energy evaluated at the eqp0 
energies. For that, use the eqp_outer.dat file created 
with eqp.py script and point WFN_outer to WFN_inner (if you were
not already using WFN_outer), i.e. run
i) ln -s WFN_inner WFN_outer
ii) ln -s eqp1.dat eqp_outer.dat
and add eqp_outer_corrections to sigma.inp. If you get the same eqp1,
the linearization looks good; if not, you can continue iterations like
this to converge to the solution of the Dyson equation.

5. Utilities:

-------------------------------------------------------------------------------
Sigma: QP shift and scissors paramters
-------------------------------------------------------------------------------

TOOL: qp_shifts.py

USAGE: qp_shift.py sigma_hp.log

From sigma_hp.log file, writes two files which contain the LDA 
energies and the GW shifts (E_qp-E_lda) for that energy. Useful
for determining scissor shifting parameters ecdel, evdel, etc.

-------------------------------------------------------------------------------
Sigma: QP extraction
-------------------------------------------------------------------------------

TOOL: eqp.py

USAGE: eqp.py sigma_hp.log

Extracts QP energies from sigma_hp.log file and generates file
eqp.dat. This utility is currently deprecated, since the code
writes the eqp0.dat and eqp1.dat automatically.
