common_keywords.rst 16.6 KB
 anoop chandran committed Dec 16, 2018 1 .. _common_keywords: anoop chandran committed Dec 16, 2018 2 anoop chandran committed Dec 16, 2018 3 4 5 **************** Common Keywords **************** anoop chandran committed Dec 16, 2018 6 Christoph Friedrich committed Jan 11, 2019 7 This section discusses several settings that are common for all calculations. Some of them are explained in more detail in later chapters. anoop chandran committed Dec 16, 2018 8 anoop chandran committed Dec 16, 2018 9 10 General Settings ================= anoop chandran committed Dec 16, 2018 11 anoop chandran committed Dec 16, 2018 12 13 .. _job: anoop chandran committed Dec 16, 2018 14 15 JOB -------- Christoph Friedrich committed Jan 11, 2019 16 Each Spex run needs a job definition, which defines what Spex should do, e.g., JOB GW 1:(1-5) for a *GW* calculation of the specified set of bands. The available jobs are anoop chandran committed Dec 16, 2018 17 Christoph Friedrich committed Jan 11, 2019 18 * GW - *GW* method anoop chandran committed Dec 16, 2018 19 20 21 22 * HF - Hartree-Fock method * PBE0 - PBE0 hybrid functional * SX - Screened exchange * COSX - Coulomb-hole screened-exchange (COHSEX) Christoph Friedrich committed Jan 11, 2019 23 24 * GT - *GT* method * GWT - *GW* and *GT* combined anoop chandran committed Dec 16, 2018 25 26 27 28 29 30 31 * HFENE - Total Hartree-Fock exchange energy * RPAENE - RPA correlation energy * SUSCEP - Susceptibility (Polarization function) * SUSCEPR - Renormalized susceptibility (RPA or Bethe-Salpeter) * DIELEC - Dielectric function * SCREEN - Screened interaction * SCREENW - Screened interaction projected onto Wannier basis Christoph Friedrich committed Jan 30, 2019 32 * KS - Single-particle energies (e.g., KS energies) anoop chandran committed Dec 16, 2018 33 Christoph Friedrich committed Jan 30, 2019 34 35 36 Details of these jobs are explained in subsequent sections. The job definition must not be omitted but may be empty: JOB, in which case Spex will just read the wavefunctions and energies, perform some checks and some elemental calculations (e.g., Wannier interpolation), and stop. anoop chandran committed Dec 16, 2018 37 Christoph Friedrich committed Jan 30, 2019 38 39 40 41 42 The job KS is included only for convenience. When given, Spex simply writes the single-particle energies (e.g., KS energies), read from the input data, to the output in the *standard* format, similar to the output of *GW* or HF values. In principle, Spex supports multiple jobs such as JOB GW 1:(1-5) DIELEC 1:{0:1,0.01}. This feature is, however, seldom used and is not guaranteed to work correctly in all versions. anoop chandran committed Dec 16, 2018 43 Christoph Friedrich committed Jan 11, 2019 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 .. list-table:: Examples :widths: 95 100 * - JOB COSX 1:(1-5) - Perform COHSEX calculation. * - JOB COSX 1:(1-5) SCREEN 2:{0:1,0.01} - Subsequently, calculate the screened interaction on a frequency mesh. * - JOB - Just perform some checks and stop. .. _WRTKPT: BZ and WRTKPT -------------- There are only two keywords that must not be omitted from the input file. The first is JOB, the second BZ, which defines the k-point set for the sampling of the Brillouin zone. The keyword requires four integer arguments, BZ l m n, defining an :math:l\times m\times n k-point set. If the keyword WRTKPT is set (or, alternatively, with the command line option spex -w), Spex uses the BZ definition to construct the irreducible wedge of the k-point set and writes the respective list of k points to a file, which is then read by the DFT code. .. list-table:: Example :widths: 16 100 * - BZ 8 4 2. - Define a :math:8\times 4\times 2 k-point sampling. 66 67 68 MEM ----------- Calculations based on many-body perturbation theory are costly, not only in terms of computation time but also in terms of memory. Since the problem sizes (e.g., number of atoms) are thus effectively restricted by the memory hardware of the computer, the latter constitutes in some ways a more serious limit than the computation time the user can afford to invest. Therefore, an upper limit for the memory that Spex is allowed to use can be defined with the keyword MEM x with x in MB. The default is MEM 1000. Christoph Friedrich committed Mar 24, 2019 69 In parallel Spex, the value would correspond to the upper limit per (physical) node. If possible, Spex will divide the work load into packets in such a way that the memory usage stays below the limit. (Actually, Spex might use a bit more memory than specified.) 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 .. list-table:: Example :widths: 16 100 * - MEM 2000 - Restrict memory usage to 2GB (Default: 1GB). STOREIBZ --------- Spex reads wavefunctions and energies as a first step. In general, these have to be stored for all k vectors in the set (e.g., for all 64 points of a :math:4\times 4\times 4 set), filling up a lot of memory. This can be restricted to the irreducible zone (only eight points in the example) with the keyword STOREIBZ. Spex then regenerates the wavefunctions on equivalent k points on the fly. This might slow down the calculation but is more economical with computer memory. --enable-load ----------------- (*) Another possibility to reduce the memory consumption is to reconfigure (and recompile) the code with the option --enable-load (or recompile with the flag -DLOAD in the Makefile). With this option, Spex stores the wavefunctions in memory only temporarily and rereads them from harddisc whenever they are needed. Obviously, this requires a fast harddisc and network connection. The HDF5 library is used for the data transfer. There is no possibility to set the option in the input file because it strongly affects the way the wavefunction data is handled in the code. anoop chandran committed Dec 16, 2018 85 86 RESTART -------- Christoph Friedrich committed Jan 11, 2019 87 88 89 90 91 92 93 94 95 This is an important keyword. It enables (a) continuing a calculation that has, for some reason, stopped or crashed and (b) reusing data of a previous calculation. If specified, Spex will store intermediate results in a file or read them if the particular data is already present in the file. Even if RESTART was not specified in the first run, Spex might still be able to reuse data from a previous run with RESTART 2. (This option usually gives less freedom for a change of parameters. RESTART 1 and RESTART are equivalent.) It depends on the particular job definition whether RESTART and/or RESTART 2 are available and how they work. See below for details. .. list-table:: Examples :widths: 18 100 * - RESTART - Read/write restart file. * - RESTART 2 - Try to reuse data from standard output files. anoop chandran committed Dec 16, 2018 96 Christoph Friedrich committed Mar 07, 2019 97 98 99 100 101 102 103 104 105 NOSTORE (COULOMB) ------------------ Most job types require the calculation of the Coulomb matrix (with respect to the mixed product basis). The Coulomb matrix is k dependent. By default, Spex pre-calculates the Coulomb matrices for all k and stores them in memory. However, this can be quite memory-demanding (especially for large k-point sets). Therefore, the keyword NOSTORE (section COULOMB) avoids the storage of all Coulomb matrices. Instead, at any given time, only one Coulomb matrix is stored in memory. This keyword is recommendable in particular for parallel runs (due to a rather inefficient parallelization of calculations without NOSTORE.) anoop chandran committed Dec 16, 2018 106 107 108 109 Input data =========== Spex needs data from a previous self-consistent solution of a mean-field system (e.g., KS-DFT). Several keywords can be used to analyze, check, and modify the input data. anoop chandran committed Dec 16, 2018 110 111 .. _nband: anoop chandran committed Dec 16, 2018 112 113 NBAND ----- Christoph Friedrich committed Jan 11, 2019 114 The Green function involves a summation over electronic bands, as do the polarization function [Eq. :eq:eqP] and the self-energy. The convergence with respect to the number of bands is a very important aspect in calculations based on many-body perturbation theory. The keyword NBAND n sets the number of bands to n. Obviously, n must not be larger than the number of bands provided by the input data. It should be noted that the actual number of bands can differ from n and also from k point to k point because Spex makes sure that degenerate subspaces are not cut in order to avoid symmetry breaking. If n is a real number (i.e., if it contains a decimal point: 3.0), it is interpreted as the maximal band energy. Then, all bands up to this energy are included. This is helpful if one wants to use a single parameter for calculations with differently sized unit cells. For example, when the unit cell doubles, one would have to include twice as many bands to reach the same accuracy, while the maximal band energy (practically) remains unchanged. If NBAND is unset, all available bands are used. anoop chandran committed Dec 16, 2018 115 Christoph Friedrich committed Jan 11, 2019 116 117 118 119 120 121 122 123 124 .. list-table:: Examples :widths: 24 100 * - NBAND 100 - Use 100 bands per k point. * - NBAND 3.0 - Use all bands up to 3 Hartree. * - NBAND 50.0eV - Use all bands up to 50 eV. anoop chandran committed Dec 16, 2018 125 Christoph Friedrich committed Jan 11, 2019 126 .. _CORESOC: anoop chandran committed Dec 16, 2018 127 Christoph Friedrich committed Jan 11, 2019 128 CORESOC anoop chandran committed Dec 16, 2018 129 ------- Christoph Friedrich committed Jan 11, 2019 130 131 132 133 134 135 136 137 138 139 140 141 142 143 By default, Spex averages over the SOC-splitted states. For example, the two states 2p\ :sup:1/2 and the four states 2p\ :sup:3/2 are averaged to give the six quasi-non-relativistic states of the 2p shell (or the three spin-up 2p states and the three spin-down 2p states in the case of spin polarization). Then, all core states of a given shell have the same energy and the same radial form of the wavefunction. The averaging procedure can be avoided by specifying CORESOC. The SOC-splitted states and the different energies and wavefunctions are then retained and taken into account in the calculations of the self-energy, polarization function, et cetera. In the case of spin polarization, the Weiss field gives rise to further lifting of degeneracies. Spex calculates the respective new splittings, energies, and wavefunctions. For reference, the core-state energies are written to the output file. Usually, the effect of CORESOC is numerically small, but it still might play an important role for *GW* calculations in the case of very small band gaps. CHKMISM and CHKOLAP -------------------- (*) The set of wavefunctions read from harddisc can be checked in terms of their orthonormality and continuity (mismatch) at the muffin-tin (MT) boundary with the keywords CHKOLAP and CHKMISM, respectively. The former test gives a value for the deviation from exact orthonormality. The smaller the value, the better the condition of orthonormality is fulfilled. If the deviation is too large, the program stops. The second keyword yields, for each k point, the average and maximal MT mismatch of the wavefunctions. If any of these tests yield too large errors, there could be a problem with the read-in process or with the data written by the DFT code. The developers should be informed in this case. anoop chandran committed Dec 16, 2018 144 145 146 MTACCUR ------- Christoph Friedrich committed Jan 11, 2019 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 (*) The LAPW method relies on a partitioning of space into MT spheres and the interstitial region. The basis functions are defined differently in the two regions, interstitial plane waves in the latter and numerical functions in the spheres with radial parts :math:{u(r)}, {\dot{u}(r)=\partial u(r)/\partial\epsilon}, :math:{u^\mathrm{LO}(r)} and spherical harmonics :math:{Y_{lm}(\hat{\mathbf{r}})}. The plane waves and the angular part of the MT functions can be converged straightforwardly with the reciprocal cutoff radius :math:{g_\mathrm{max}} and the maximal l quantum number :math:{l_\mathrm{max}}, respectively, whereas the radial part of the MT functions is not converged as easily. The standard LAPW basis is restricted to the functions :math:{u} and :math:{\dot{u}}. Local orbitals :math:{u^\mathrm{LO}} can be used to extend the basis set, to enable the description of semicore and high-lying conduction states. The accuracy of the radial MT basis can be analyzed with the keyword MTACCUR e1 e2 which gives the MT representation error [Phys. Rev. B 83, 081101] in the energy range between e1 and e2. (If unspecified, e1 and e2 are chosen automatically.) The results are written to the output files "spex.mt.t" where t is the atom type index, or "spex.mt.s.t" with the spin index s(=1 or 2) for spin-polarized calculations. The files contain sets of data for all l quantum numbers, which can be plotted separately with gnuplot (e.g., plot "spex.mt.1" i 3 for :math:{l=3}) .. list-table:: Examples :widths: 24 100 * - MTACCUR -1 2 - Calculate MT representation error between -1 and 2 Hartree. * - MTACCUR - Automatic energy range. anoop chandran committed Dec 16, 2018 167 168 BANDINFO Christoph Friedrich committed Jan 11, 2019 169 170 171 172 173 174 175 176 177 178 179 180 181 182 --------- (*) This keyword lets Spex analyze the orbital character of the wavefunctions. The results are given, first, in the form of a table in the output file containing the orbital decomposition for each eigenstate and, second, as projected density-of-states (DOS) plots in the files "spex.dos.NNN" (where NNN is a three-digit running index). As the table can be very large, there is a possibility to choose the atom type index at whose spheres the analysis is to be performed. .. list-table:: Examples :widths: 20 100 * - BANDINFO - Calculate orbital decomposition and DOS plots. * - BANDINFO 2 - Restrict the orbital-decomposition table to atom type 2. Christoph Friedrich committed Jan 11, 2019 183 184 .. _ENERGY: Christoph Friedrich committed Jan 11, 2019 185 ENERGY anoop chandran committed Dec 16, 2018 186 -------- Christoph Friedrich committed Jan 12, 2019 187 188 (*) In some cases, it may be necessary to replace the energy eigenvalues, provided by the mean-field (DFT) calculation, by energies (e.g., *GW* quasiparticle energies) obtained in a previous Spex run, for example, Christoph Friedrich committed Jan 11, 2019 189 190 191 192 to determine the *GW* Fermi energy or to perform energy-only self-consistent calculations. This can be achieved with the keyword ENERGY file, where "file" contains the new energies in eV. The format of "file" corresponds to the output of the spex.extr utility: spex.extr g spex.out > file. It must be made sure that "file" contains energy values for the whole irreducible Brillouin zone. Christoph Friedrich committed Jan 12, 2019 193 Band energies not contained in "file" will be adjusted so that the energies are in ascending order Christoph Friedrich committed Jan 11, 2019 194 (provided that there is at least one energy value for the particular k point). Christoph Friedrich committed Jan 11, 2019 195 196 197 198 199 200 201 .. list-table:: Example :widths: 34 100 * - ENERGY energy.inp - Replace the mean-field energy eigenvalues by the energies provided in the file "energy.inp". anoop chandran committed Dec 16, 2018 202 203 204 205 DELTAEX ------- (*) This keyword modifies the exchange splitting of a collinear magnetic system, i.e., it shifts spin-up and spin-down energies relative to to each other so as to increase or decrease the exchange splitting. With DELTAEX x, the spin-up (spin-down) energies are lowered (elevated) by x/2. The parameter x can be used to enforce the Goldstone condition in spin-wave calculations [Phys. Rev. B 94, 064433 (2016)] Christoph Friedrich committed Jan 11, 2019 206 207 208 209 210 211 .. list-table:: Example :widths: 26 100 * - DELTAEX 0.2eV - Increase the exchange splitting by 0.2 eV (spin-up/down energies are decreased/increased by 0.1 eV) anoop chandran committed Dec 16, 2018 212 213 PLUSSOC ------- Christoph Friedrich committed Jan 11, 2019 214 215 216 (*) With this keyword, Spex adds spin-orbit coupling (SOC) to the mean-field solution using a one-shot second-variation approach and stops, so it is non-iterative but updates the wavefunctions and energies. The new energies are written to standard output and, together with the new wavefunctions, to new input files on the harddisc, Christoph Friedrich committed Jan 11, 2019 217 218 thus overwriting the old input data. In the case of Fleur, the modified files are "gwa", "KS.hdf", and "spex.sym". The latter is written only if the system is spin polarized (non-collinear magnetism). It has the same form as "sym.out". Christoph Friedrich committed Jan 11, 2019 219 220 221 Spex reads the file "spex.sym" if it exists and "sym.out" otherwise. After the PLUSSOC calculation, a subsequent Spex run will read the new input data, now including SOC. (The keyword PLUSSOC must be removed for this new run, otherwise Spex stops with an error, since it cannot add SOC to a solution that contains it already.) anoop chandran committed Dec 16, 2018 222 Christoph Friedrich committed Jan 11, 2019 223 224 225 226 227 228 229 230 231 232 233 A possible application of this feature is to add SOC corrections to *GW* quasiparticle energies, already calculated. To this end, store the *GW* energies to a file using the "spex.extr" utility (example: spex.extr g spex.out > energy.inp). Then, tell Spex to replace the single-particle energies (that it reads from the input data) by the ones from the file ("energy.inp") with the keyword ENERGY (ENERGY energy.inp, see :numref:ENERGY) and add PLUSSOC. In a subsequent run, Spex will apply the SOC operator to the *GW* quasiparticle energies using a second-variation technique, write the corrected energies to the output, and write the new input data files. The latter can be used in a subsequent Spex run, for example, to calculate a Wannier-interpolated band structure, containing *GW* quasiparticle and SOC corrections. From a theoretical point of view this approach is a bit inconsistent [Phys. Rev. B 88, 165136 (2013)], but it is considerably faster than running *GW* with SOC from the start. Besides, the latter approach is currently not applicable to systems with noncollinear magnetism. So, using the present procedure with PLUSSOC is the only viable approach for this case. anoop chandran committed Dec 16, 2018 234 235 ITERATE ------- Christoph Friedrich committed Jan 11, 2019 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 (*) If ITERATE is specified, Spex only reads the LAPW basis set from the input data, provided by the mean-field (DFT) code, but performs the diagonalization of the Hamiltonian at the k points itself. This calculation effectively replaces the second run of the DFT code. In this sense, the name of the keyword is a bit misleading, as the calculation is non-iterative. The keyword ITERATE is mostly intended for testing and debugging. It is not available for executables compiled with -DLOAD (configured with --enable-load). .. list-table:: Examples :widths: 30 100 * - ITERATE NR - Diagonalize a non-relativistic Hamiltonian. * - ITERATE SR - Use scalar-relativity. * - ITERATE FR - Also include SOC. * - ITERATE SR -1 - Diagonalize scalar-relativistic Hamiltonian and neglect eigenvalues below -1 htr. * - ITERATE FR STOP - Diagonalize relativistic Hamiltonian (including SOC), then stop. anoop chandran committed Dec 16, 2018 257 258