              Marios Zacharias [1] & Feliciano Giustino [2,3], May 2022

[1] Department of Mechanical and Materials Science Engineering, Cyprus University of Technology, 
    P.O. Box 50329, 3603 Limassol, Cyprus 
[2] Oden Institute for Computational Engineering and Sciences, The University of Texas at Austin,
Austin, Texas 78712, USA 
[3] Department of Physics, The University of Texas at Austin, Austin, Texas 78712, USA
---------------------------------------------------------------------------------------------------

If you use ZG.x or bands_unfold.x please do cite the following work:

[1] Marios Zacharias and Feliciano Giustino, Phys. Rev. Research 2, 013357, (2020).
[2] Marios Zacharias and Feliciano Giustino, Phys. Rev. B 94, 075125, (2016).

If you use disca.x please do cite the following work:

[1] Marios Zacharias, Feliciano Giustino et al., Phys. Rev. B 104, 205109, (2021)
[2] Marios Zacharias, Feliciano Giustino et al., Phys. Rev. Lett. 127, 207401, (2021)

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

Acknowledgement: We thank Hyungjun Lee, Oden Institute for Computational Engineering and Sciences, 
                 for help packaging this release.

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

Executables in ZG folder
------------------------
ZG.x             ---> for generating ZG configurations, ZG diffuse scattering, phonon unflolding
bands_unfold.x   ---> for performing band structure unfolding in supercell calculations
pp_spctrlfn.x    ---> for obtaining the electron spectral function after bands_unfold.x
epsilon_Gaus.x   ---> for calculating optical properties as in epsilon.x but Gaussian broadening
disca.x          ---> for calculating one-phonon and all-phonon inelastic scattering intensities
pp_disca.x       ---> for applying broadening and setting a resolution of scattering patterns
src/local folder ---> for post-processing. Compile them by "./compile_gfortran.sh"

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

For full instructions on how to run the exercises in the tarball "tutorial.tar.gz"
please refer to the EPW documentation site, or send an email to Marios Zacharias:  
zachariasmarios@gmail.com 

Links for input flags and tutorials:

https://epwdoc.gitlab.io/source/doc/InputsZG.html
https://epwdoc.gitlab.io/source/doc/TutorialZG.html

---------------------------------------------------------------------------------------------------
Instructions for the construction of the Zacharias-Giustino "ZG" displacement following 
Eq. (2) of Phys. Rev. Research 2, 013357, 2020. The approach for generating the ZG-displacement 
is based on the generalized theory of the special displacement method as in 
Phys. Rev. Research 2, 013357, (2020). 

STEPS for generating the "ZG-displacement" for the calculation of temperature-dependent properties of solids: 

0.  Compile the version of Quantum Espresso 6.6.0 or later; PW, PH, and PP subroutines
    are required to run all executables, e.g. "make pw ph pp".
    Go to "/path_to_your_espresso/EPW/ZG/src" and "make".
    The code is also compiled with "make epw". 
    This code exploits some main routines of matdyn.x. In particular, the code
    takes advantage of the phonon interpolation scheme implemented for matdyn.x. This is 
    important, for example, in taking into account the LO-TO splitting in polar materials. 
    The necessary input files are the interatomic force constants "file.fc" and "ZG.in". 
    See for example files in the "example/silicon/ZG_structure/inputs" folder.

1.  Run a scf calculation: for example "/path_to_your_espresso/bin/pw.x < si.scf.in > si.scf.out" 
    for the silicon unit cell. 

2.  Run a phonon calculation: for example "/path_to_your_espresso/bin/ph.x < si.ph.in > si.ph.out" 
    for a relatively "dense" q-grid to obtain a converged phonon dispersion. 

3.  Run "/path_to_your_espresso/bin/q2r.x <q2r.in> q2r.out".
    The input "q2r.in" has the standard format of Quantum Espresso for calculating the 
    interatomic force constant matrix elements to be used to construct the 
    "ZG-configuration.dat" file. 

4.  Calculate the phonon dispersion with "matdyn.x" and make sure that your phonon dispersion is
    correct (compare to other literature results). This is not a necessary step for the construction of the 
    "ZG-configuration". However, you need to ensure that the phonons, to be used for the construction 
    of the "ZG-configuration", are those you expect. For a polar material, LO-TO splitting should be 
    included.   
    
5.  Now one needs to decide on the size of the supercell configuration to be used for calculating 
    temperature dependent properties. For help, please see exercise1 in tutorial tarball. 
    One could potentially generate any supercell size by simply changing "dim1","dim2", 
    "dim3", and the list of q-points (optional, see below). "ZG.in" has the standard 
    format as a "matdyn.in" file for Quantum Espresso. Here we use the following input parameters:
    ---------------------------------------------------------------------------------------
    i) "ZG_conf"            : Logical flag that enables the creation of the ZG-displacement. 
                              (default .true.) 
       "flscf"              : String for the name of the scf input file used to calculate the phonons. The 
                              code will read information for preparing the input file of the supercell calculation. 
                              If left empty the code will not generate the input file of the supercell calculation.
                              (default ' ')
       "T"                  : Real number indicating the temperature at which the calculations will be performed. 
                              "T" essentially defines the amplitude of the normal coordinates. 
                              (default 0.00)
       "dim1","dim2","dim3" : Integers corresponding to the dimensionality of the supercell i.e.:
                              size of supercell will be [dim1 * a(1), dim2 * a(2), dim3 * a(3)],
                              where a(1), a(2), a(3) are the lattice vectors of the unit cell used
                              to compute the phonons.
                              (default 0, 0, 0)
       "atm_zg(1), etc.."   : String describing the element of each atomic species
                              (default "Element")
       "qhat_in"            : Vector with three real entries for specifying the direction qhat 
                              for the non-analytic part when dim1=dim2=dim3=1.
                              Use for example "qhat_in(1) = 0.1, qhat_in(2) =0.0, qhat_in(3) = 0.0"
                              to account for LO-TO splitting from the direction [1 0 0]. 
                              (default 0.1,0.1,0.1)
       "synch"              : Logical flag that enables the synchronization of the modes. 
                              (default .false.)
       "niters"             : Integer for the number of iterations the algorithm needs to 
                              go through for finding the optimum configuration. The algorithm 
                              generates a set of "+,-,+,-" signs and its possible permutations, 
                              trying to minimize the error coming from the coupling of modes with 
                              the same q-wavevector but at different branch. For a finite supercell
                              size the order of using the "+,-,+,-" set and its permutations is  
                              important giving different results. Therefore the algorithm checks 
                              the combination that brings the error lower than a threshold.
                              (default 15000)
       "compute_error"      : Logical flag: if set to .true. allows the code to find the optimal ZG configuration 
                              by minimizing the error based on the "threshold" flag (see below). Set it
                              to .false. if speed up is required. This is useful when (i) large supercell 
                              sizes are considered for which the error is minimized by the first set of signs, 
                              (ii) only single phonon displacements are of interest (see below) 
                              (default .true.)
       "error_thresh"       : Real number indicating the error at which the algorithm stops while it's 
                              looking for possible combinations of signs. Once this limit is reached, 
                              the ZG-displacement is constructed. The threshold is usually chosen 
                              to be less than 5% of the diagonal terms, i.e. those terms that contribute 
                              to the calculation of temperature-dependent properties. 
                              (default 0.05)
       "incl_qA"            : Logical flag, to decide whether to include phonon modes in set A or not. 
                              (default .true.)
       "single_ph_displ"    : Logical flag that allows to displace the nuclei along single phonon modes. 
                              Use output configurations to compute electron-phonon matrix elements with a direct 
                              supercell calculation. Set the displacement to the zero point by "T = 0". 
                              This finite displacement should carry precisely the effect of diagonal elements of [g(q)+g(-q)].
                              Output files: "single_phonon-displacements.dat" and "single_phonon-velocities.dat".
                              (default .false.)
       "q_external"         : Logical flag that allows the use of a q-point list specified by the user in the input file. 
                              If .false. the q-point list is specified by the supercell dimensions dim1, dim2, and dim3. 
                              If .false. any q-point list after the input flags is ignored.
                              If .true. the q-point list must be provided by the user (or see "qlist_AB.txt").
                              IF ph_unfold = .true. then q_external = .true. automatically and the q-path is provided as 
                              in a standard phonon dispersion calculation. 
                              (default .false.)
       "qlist_AB.txt"       : This file contains the external q-list in crystal coordinates as in the "ZG_444.in" example,
                              after the input flags. It corresponds to the q-points commensurate to the supercell size. 
                              Only one of the q-point time-reversal partners is kept for the construction of the 
                              ZG-displacement. The calculations, for the moment, assume systems with time-reversal symmetry. 
                              For the generation of the "qlist_AB.txt" set the q-gird in file 
                              "example/silicon/input/qlist.in" and run "../../../src/create_qlist.x < qlist.in > qlist.out".
                              One can modify the "create_qlist.f90" to generate a different path for consecutive q-points.
                              Paste the output of "qlist_AB.txt" to "ZG.in" after namelist &input. Set the flag 
                              q_external = .true. for the code to read the list.  
   
       "ph_unfold"          : Logical flag to activate phonon unfolding procedure. (default: .false.). To perform phonon 
                              unfolding ZG_conf must be set to .false.. If ph_unfold = .true. then q_external = .true. 
  
       "flfrq"              : Output file for frequencies to printed with unfolding weights (default: 'frequencies.dat')
  
       "flweights"          : Output file for unfolding weights to printed with frequncies (default: 'unfold_weights.dat')
  
      "ng1","ng2","ng3"     : Integers corresponding to the (h k l) indices of the reciprocal lattice vector g.  
                              Increase their values to check convergence. Default is a good starting point. 
                              (default 10,10,10)
  
    ii)  To generate the ZG-displacement run "/path_to_your_espresso/bin/ZG.x <ZG.in> ZG.out".
         This generates three output files: the "equil_pos.dat", "ZG-configuration.dat" and "ZG-velocities.dat". 
         The first file has the equilibrium coordinates of the nuclei and the second has the optimum set of nuclear coordinates 
         that define the ZG-displacement for a particular temperature and supercell size. 
         The third one has the ZG-velocities or momenta of the nuclei generated in the same spirit with the ZG displacement. 
    iii) The calculation of the ZG-displacement should usually takes a few seconds to few minutes with one processor. 

6. VERY IMPORTANT NOTE: It is perfectly reasonable to find different ZG-displacements / ZG-configurations,
   since the modes obtained  by diagonalizing the dynamical matrix can differ by a phase factor 
   (or a unitary matrix in case of degeneracy) if the processor, or compiler, or libraries have changed. 
   The eigenvalues of course should remain the same in all cases. The synchronization routine should align the sign
   of the modes with respect to a reference mode, but the sign of this reference depends on the machine,
   and degeneracy is not taken into account. The best way to check the validity of your configuration is 
   by comparing the anisotropic displacement tensor with the exact values, both obtained at the end of the 
   "ZG-configuration.dat". Reducing the value of "threshold" should bring the anisotropic displacement tensor
   closer to the exact values. 

7. The ZG-displacement can be employed for the calculation of any temperature-dependent 
   observable that is described by the Fermi Golden rule. The procedure is exactly the same as for 
   the calculation of the observable obtained with the nuclei clamped at their equilibrium positions, 
   but now, instead, using the ZG-displacement (supercell) that incorporates automatically 
   the electron-phonon interaction and quantum zero-point motion. 

8. The ZG-displacement can also be employed for the calculation of full temperature-dependent
   band structures using the unfolding technique for supercell calculations. 

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

   Example using the ZG-displacement and JDOS

Here we show a simple example on how to use the ZG-displacement for calculating the temperature dependence 
of the JDOS and eventually extract the zero-point renormalization and temperature dependence of the band gap.

Steps: 

1. Once you generate the ZG-configuation from previous step, then you can run your first SCF calculation
   with the special displacement method.  Use the atomic positions in the file "ZG-configuration.dat" and 
   prepare your "scf.in" file. Make sure your lattice constants are comensurate with the supercell size. 
   For example, check the input files in the directory 'example/silicon/JDOS/inputs/333/ZG_0K'. 

2. Run an scf calculation and then prepare an "nscf.in" to run a non-self-consistent (nscf) calculation on a denser grid. 
   For example, check the input files in the directory 'example/silicon/JDOS/inputs/333/ZG_0K'.

3. Once you obtain the ".xml" file from the nscf calculation, run "commands.sh" as in the directory
   'example/silicon/JDOS/inputs/333/ZG_0K'. This will generate the file "data_one_column.dat" 
   with all eigenvalues calculated for each k-point using the ZG-configuration. Note that in 
   the file "commands.sh", only "NR+44" should be changed for a different run. 44 indicates how many 
   lines containing the eigenvalues exist, after the string match "eigenvalues size" in the ".xml" file.

4. Use the output file "data_one_column.dat" to calculate the joint-density of states (JDOS) via the executable 
   "JDOS_Gaus.x" located in the "src/JDOS" folder. Command:  "/path_to/JDOS_Gaus.x <JDOS_Gaus.in > JDOS_Gaus.out". 
   For extracting the band gap from the joint-density of states follow the procedure in Ref.[Phys. Rev. B 94, 075125, (2016)].

5. Compare your results with the data in the directory 'example/silicon/JDOS/outputs/333'. 
   Gnuplot commands are aslo given to facilitate comparison.

6. In the examples you will also find ZG-configurations generated by setting the flag "incl_qA = .true." 
   and the flag "synch = .false.". The names of the ZG files end with "...qA.dat" and "...nosym.dat", respectively. 
   Outputs of the "scf", "nscf" and "JDOS" are also provided. Comparion of the results obtained with different settings 
   shows the importance of exluding the qA modes, which break the degeneracy at high-symmetry points, 
   in small supercell structures. For example, the valence band top of silicon is threefold degenerated. A general rule is 
   to keep "synch = .true." and "incl_qA = .false.", unless there is a particular reason to change them.  

7. Examples for the 3x3x3 and 5x5x5 Si ZG-configurations are provided. In the "outputs" directory the calculated 
   zero-point renormalization (ZPR) for each case is given in the gnuplot files. For a 5x5x5 Si ZG-configuration the 
   calculated ZPR is 55 meV, very close to the converged value of 57 meV obtained using an 8x8x8 Si ZG-configuration
   in Ref. [Phys. Rev. B 94, 075125, (2016)].
   
--------------------------------------------------------------------------------------------------------------

Other capabilities of ZG.x: 

1.  ZG.x can also be used to generate displaced configurations along single phonon modes.
    Please see "single_phonon_displ" flag. 
    Find an example in:
    "example/silicon/single_ph_displ/444/inputs/".
    To run the example use: 
    "/path_to_your_espresso/bin/ZG.x <ZG_444.in> ZG_444.out". 
    The output files of interest are: 
    "single_phonon-displacements.dat" and "single_phonon-velocities.dat".
     
--------------------------------------------------------------------------------------------------------------

        NOW YOU CAN ENJOY GENERATING SPECIAL DISPLACENTS AND CALCULATE FINITE TEMPERATURE EFFECTS.
