mirror of https://gitlab.com/QEF/q-e.git
596a99433f
|
||
|---|---|---|
| .. | ||
| src | ||
| README | ||
| tutorial.tar.gz | ||
README
Marios Zacharias [1] & Feliciano Giustino [2,3], April 2024
[1] Univ Rennes, INSA Rennes, CNRS, Institut FOTON - UMR 6082, F-35000 Rennes, France
[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 for the special displacement method (SDM) please do cite the following work:
[a] M. Zacharias and F. Giustino, Phys. Rev. Research 2, 013357, (2020).
[b] M. Zacharias and F. Giustino, Phys. Rev. B 94, 075125, (2016).
If you use ZG.x for the anhamonic special displacement method (A-SDM) please do cite the
following work:
[a] M. Zacharias, G. Volonakis, F. Giustino, and J. Even, Phys. Rev. B 108, 035155 (2023)
If you use disca.x for inelastic scattering please do cite the following work:
[a] M. Zacharias, F. Giustino et al., Phys. Rev. B 104, 205109, (2021)
[b] M. Zacharias, F. Giustino et al., Phys. Rev. Lett. 127, 207401, (2021)
---------------------------------------------------------------------------------------------------
Acknowledgement: We thank Sabyasachi Tiwari, Oden Institute for Computational Engineering
and Sciences, for help packaging this release. M.Z. acknowledges
funding from European Union (project ULTRA-2DPK / HORIZON-MSCA-2022-PF-01 /
Grant Agreement No. 101106654)
---------------------------------------------------------------------------------------------------
Executables in the ZG folder
-----------------------------
ZG.x ---> for generating ZG configurations, A-SDM, 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 multiphonon 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://docs.epw-code.org/doc/InputsZG.html
https://docs.epw-code.org/doc/School2023.html
---------------------------------------------------------------------------------------------------
Instructions for the construction of the Zacharias-Giustino "ZG" displacements following Eq. (2) of
Phys. Rev. Research 2, 013357 (2020). The approach for generating the ZG displacements is based on
the generalized theory of the special displacement method as in Phys. Rev. Research 2, 013357 (2020).
STEPS for generating the ZG displacements to calculate 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 "ZG-configuration.dat".
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 generating 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 displacements.
(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)
"T_array(1), etc.." : Real number indicating the temperature at which the calculations will be performed.
Fill T_array for generating ZG configurations for different temperatures.
If nconfs = 1, the same set of signs is maintained for all temperatures. This is
important for consistency reasons. If nconfs > 1 then "nconfs" ZG configurations
are generated each temperature specified in T_array. A maximum of 100 temperatures
are allowed.
(default -1)
"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 a smooth Berry connection between 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.
If integer "nconfs" > 1 then "niters" necomes equal to "nconfs".
(default 15000)
"nconfs" : Integer. If greater than 1 allows "nconfs" ZG configurations for each temperature
to be generated. "compute_error" is set to .false.
"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) "single_ph_displ" is .true. (see below), and (iii) "nconfs" is larger than 1.
(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 displacements are constructed. The threshold is usually chosen
to be less than 30% of the diagonal terms, i.e. those terms that contribute
to the calculation of temperature-dependent properties. Meaningless if
compute_error = .fasle. and/or "nconfs" > 1.
(default 0.30)
"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 displacements. 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.
"ASDM" : Logical flag that enables the iterative procedure for evaluating anharmonic IFCs.
(default .false.)
"na_ifc" : Logical flag that adds the non analitic contributions to the interatomic force constants
if the finite displacement method is used, as in Wang et al. Phys. Rev. B 85, 224303 (2012).
Important if "ASDM" flad is true.
(default .false.)
"ph_unfold" : Logical flag to activate phonon unfolding procedure. To perform phonon
unfolding ZG_conf must be set to .false.. If ph_unfold = .true. then q_external = .true.
(default: .false.)
"flfrq" : Output file for phonon frequencies to printed with the spectral weights.
(default: 'frequencies.dat')
"flweights" : Output file for the spectral weights to printed with phonon 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 displacements 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 displacements for a particular temperature and supercell size.
The third one has the ZG velocities of the nuclei generated in the same spirit with ZG displacements.
iii) The calculation of the ZG displacements should usually take 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 printed in "ZG.out".
Reducing the value of "threshold" should bring the anisotropic displacement tensor closer to the exact values.
7. The ZG displacements 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 displacements (supercell) that incorporates automatically
the electron-phonon interaction and quantum zero-point motion.
8. The ZG displacements can also be employed for the calculation of full temperature-dependent
band structures using the unfolding technique for supercell calculations.
----------------------------------------------------------------------------------------------------------
Example using the ZG displacements 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/local" 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 be used to generate self-consistent anharmonic special displacements (i.e. the A-SDM method).
These displacement essentially minimize the Gibbs free energy of a strongly anharmonic system, and can
be used to incorporare the effect of anharmonic electron-phonon coupling in one-shot DFT-ZG calculations.
On how to apply A-SDM please refer to exercise 3 of the tutorial.
2. 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.