1.. _qe_interface: 2 3Quantum ESPRESSO (QE) & phonopy calculation 4============================================ 5 6Quantum ESPRESSO package itself has a set of the phonon calculation 7system. But the document here explains how to calculate phonons using 8phonopy, i.e., using the finite displacement and supercell approach. 9 10.. contents:: 11 :depth: 2 12 :local: 13 14Supported QE-PW tags 15--------------------------- 16 17Currently QE-PW tags that phonopy can read are shown below. Only 18``ibrav = 0`` type representation of crystal structure is supported. 19More tags may be supported on request. 20 21:: 22 23 nat, ntyp, celldm(1), ATOMIC_SPECIES, ATOMIC_POSITIONS, CELL_PARAMETERS 24 25How to run 26---------- 27 28The procedure of QE-phonopy calculation is shown below using the 29NaCl example found in ``example/NaCl-QE`` directory. 30 311) Read a QE-PW input file and create supercells with 32 :ref:`qe_mode` option:: 33 34 % phonopy --qe -d --dim="2 2 2" -c NaCl.in 35 36 In this example, 2x2x2 supercells are created. ``supercell.in`` and 37 ``supercell-xxx.in`` (``xxx`` are numbers) give the perfect 38 supercell and supercells with displacements, respectively. In the 39 case of the NaCl example, two files ``supercell-001.in`` and 40 ``supercell-002.in`` are created. In these supercell files, lines 41 only relevant to crystal structures are 42 given. ``phonopy_disp.yaml`` is also generated, which contains 43 information about supercell and displacements. 44 452) To make QE-PW input files, necessary setting information is added to 46 ``supercell-xxx.in`` files, e.g., by:: 47 48 % for i in {001,002};do cat header.in supercell-$i.in >| NaCl-$i.in; done 49 50 where ``header.in`` is specially made for this NaCl example and 51 this file is found in ``example/NaCl-QE`` directory. This 52 setting is of course dependent on systems and has to be written for 53 each interested system. Note that supercells with displacements 54 must not be relaxed in the force calculations, because atomic 55 forces induced by a small atomic displacement are what we need for 56 phonon calculation. 57 58 Then QE-PW supercell calculations are executed to obtain force on 59 atoms, e.g., as follows:: 60 61 % mpirun pw.x -i NaCl-001.in |& tee NaCl-001.out 62 % mpirun pw.x -i NaCl-002.in |& tee NaCl-002.out 63 643) To create ``FORCE_SETS``, that is used by phonopy, 65 the following phonopy command is executed:: 66 67 % phonopy -f NaCl-001.out NaCl-002.out 68 69 Here ``.out`` files are the saved text files of standard outputs of the 70 QE-PW calculations. If more supercells with displacements were 71 created in the step 1, all ``.out`` files are given in the above 72 command. To run this command, ``phonopy_disp.yaml`` has to be located in 73 the current directory because the information on atomic 74 displacements stored in ``phonopy_disp.yaml`` are used to generate 75 ``FORCE_SETS``. See some more detail at 76 :ref:`qe_force_sets_option`. 77 784) Now post-process of phonopy is ready to run. The unit cell file 79 used in the step 1 has to be specified but ``FORCE_SETS`` is 80 automatically read. Examples of post-process are shown below. 81 82 :: 83 84 % phonopy --qe -c NaCl.in -p band.conf 85 _ 86 _ __ | |__ ___ _ __ ___ _ __ _ _ 87 | '_ \| '_ \ / _ \| '_ \ / _ \ | '_ \| | | | 88 | |_) | | | | (_) | | | | (_) || |_) | |_| | 89 | .__/|_| |_|\___/|_| |_|\___(_) .__/ \__, | 90 |_| |_| |___/ 91 1.13.0 92 93 Python version 2.7.14 94 Spglib version 1.10.3 95 Calculator interface: qe 96 Band structure mode 97 Settings: 98 Supercell: [2 2 2] 99 Primitive axis: 100 [ 0. 0.5 0.5] 101 [ 0.5 0. 0.5] 102 [ 0.5 0.5 0. ] 103 Spacegroup: Fm-3m (225) 104 Computing force constants... 105 max drift of force constants: -0.001194 (zz) -0.000000 (zz) 106 Reciprocal space paths in reduced coordinates: 107 [ 0.00 0.00 0.00] --> [ 0.50 0.00 0.00] 108 [ 0.50 0.00 0.00] --> [ 0.50 0.50 0.00] 109 [ 0.50 0.50 0.00] --> [-0.00 -0.00 0.00] 110 [ 0.00 0.00 0.00] --> [ 0.50 0.50 0.50] 111 ... 112 113 |pwscf-band| 114 115 .. |pwscf-band| image:: NaCl-pwscf-band.png 116 :width: 50% 117 118 ``--qe -c NaCl.in`` is specific for the QE-phonopy 119 calculation but the other settings are totally common among calculator 120 interfaces such as 121 122 :: 123 124 % phonopy --qe -c NaCl.in --dim="2 2 2" [other-OPTIONS] [setting-file] 125 126 For settings and command options, see 127 :ref:`setting_tags` and :ref:`command_options`, respectively, and 128 for examples, see :ref:`examples_link`. 129 130Non-analytical term correction (Optional) 131~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 132 133To activate non-analytical term correction, :ref:`born_file` is 134required. This file contains the information of Born effective charge 135and dielectric constant. These physical values are also obtained from 136the PW (``pw.x``) & PH (``ph.x``) codes in Quantum ESPRESSO 137package. There are two steps. The first step is usual self-consistent 138field (SCF) calculation 139by and the second step is running its response function calculations 140under DFPT. 141 142For the SCF calculation, the input file ``NaCl.in`` looks like:: 143 144 &control 145 calculation = 'scf' 146 tprnfor = .true. 147 tstress = .true. 148 pseudo_dir = '/home/togo/espresso/pseudo/' 149 / 150 &system 151 ibrav = 0 152 nat = 8 153 ntyp = 2 154 ecutwfc = 70.0 155 / 156 &electrons 157 diagonalization = 'david' 158 conv_thr = 1.0d-9 159 / 160 ATOMIC_SPECIES 161 Na 22.98976928 Na.pbe-spn-kjpaw_psl.0.2.UPF 162 Cl 35.453 Cl.pbe-n-kjpaw_psl.0.1.UPF 163 ATOMIC_POSITIONS crystal 164 Na 0.0000000000000000 0.0000000000000000 0.0000000000000000 165 Na 0.0000000000000000 0.5000000000000000 0.5000000000000000 166 Na 0.5000000000000000 0.0000000000000000 0.5000000000000000 167 Na 0.5000000000000000 0.5000000000000000 0.0000000000000000 168 Cl 0.5000000000000000 0.5000000000000000 0.5000000000000000 169 Cl 0.5000000000000000 0.0000000000000000 0.0000000000000000 170 Cl 0.0000000000000000 0.5000000000000000 0.0000000000000000 171 Cl 0.0000000000000000 0.0000000000000000 0.5000000000000000 172 CELL_PARAMETERS angstrom 173 5.6903014761756712 0 0 174 0 5.6903014761756712 0 175 0 0 5.6903014761756712 176 K_POINTS automatic 177 8 8 8 1 1 1 178 179where more the k-point mesh numbers are specified. This may be exectued as:: 180 181 mpirun ~/espresso/bin/pw.x -i NaCl.in |& tee NaCl.out 182 183Many files whose names stating with ``pwscf`` should be created. These 184are used for the next calculation. The input file for the response 185function calculations, ``NaCl.ph.in``, is 186created as follows:: 187 188 &inputph 189 tr2_ph = 1.0d-14, 190 epsil = .true. 191 / 192 0 0 0 193 194Similary ``ph.x`` is executed:: 195 196 % mpirun ~/espresso/bin/ph.x -i NaCl.ph.in |& tee NaCl.ph.out 197 198Finally the Born effective charges and dielectric constant are 199obtained in the output file ``NaCl.ph.out``. The ``BORN`` file has to 200be created manually following the ``BORN`` format 201(:ref:`born_file`). The ``BORN`` file for this NaCl calculation would 202be something like below:: 203 204 default value 205 2.472958201 0 0 0 2.472958201 0 0 0 2.472958201 206 1.105385 0 0 0 1.105385 0 0 0 1.105385 207 -1.105385 0 0 0 -1.105385 0 0 0 -1.105385 208 209Once this is made, the non-analytical term correction is included 210just adding the ``--nac`` option as follows:: 211 212 % phonopy --qe --nac -c NaCl.in -p band.conf 213 214 215|pwscf-band-nac| 216 217.. |pwscf-band-nac| image:: NaCl-pwscf-band-NAC.png 218 :width: 50% 219 220.. _qe_q2r: 221 222Using ``q2r.x`` to create phonopy force constants file 223------------------------------------------------------- 224 225**Experimental** 226 227A parser of ``q2r.x`` output is implemented experimentally. Currently 228command-line user interface is not prepared. Using the following 229script, the force constants file readable by phonopy is 230created. Probably thus obtained force constants are required to be 231symmetrized by the translational invariance condition using 232``FC_SYMMETRY = .TRUE.``. 233 234:: 235 236 #!/usr/bin/env python 237 238 import sys 239 from phonopy.interface.qe import read_pwscf, PH_Q2R 240 241 primcell_filename = sys.argv[1] 242 q2r_filename = sys.argv[2] 243 cell, _ = read_pwscf(primcell_filename) 244 q2r = PH_Q2R(q2r_filename) 245 q2r.run(cell) 246 q2r.write_force_constants() 247 248Saving this script as ``make_fc_q2r.py``, this is used as, e.g., 249 250:: 251 252 % python make_fc_q2r.py NaCl.in NaCl.fc 253 254This gives ``force_constants.hdf5`` file in the compact format (see 255:ref:`file_force_constants`). From version 1.13.2, full supercell 256force constants can be written by ``q2r.run(cell, is_full_fc=True)`` 257instead of ``q2r.run(cell)`` in the above 258script. ``FORCE_CONSTANTS`` file instead of ``force_constants.hdf5`` 259can be obtained by ``q2r.write_force_constants(fc_format='text')``. 260 261Non-analytical term correction 262~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 263 264Treatment of non-analytical term correction (NAC) is different between 265phonopy and QE. For insulator, QE automatically calculate dielectric 266constant and Born effective charges at PH calculation when q-point 267mesh sampling mode (``ldisp = .true.``), and these data are written in 268the Gamma point dynamical matrix file (probably in ``.dyn1`` 269file). When running ``q2r.x``, these files are read including the 270dielectric constant and Born effective charges, and the real space 271force constants where QE-NAC treatment is done are written to the q2r 272output file. This is not that phonopy expects. Therefore the 273dielectric constant and Born effective charges data have to be removed 274manually from the Gamma point dynamical matrix file before running 275``q2r.x``. Alternatively Gamma point only PH calculation with 'epsil = 276.false.' can generate the dynamical matrix file without the dielectric 277constant and Born effective charges data. So it is possible to replace 278the Gamma point file by this Gamma point only file to run ``q2r.x`` 279for phonopy. 280 281Creating BORN file 282^^^^^^^^^^^^^^^^^^^ 283 284If the ``q2r.x`` output contains dielectric constant and Born 285effective charges, the following script can generate ``BORN`` format 286text. 287 288:: 289 290 #!/usr/bin/env python 291 292 import sys 293 import numpy as np 294 from phonopy.structure.symmetry import elaborate_borns_and_epsilon 295 from phonopy.interface.qe import read_pwscf, PH_Q2R 296 297 primcell_filename = sys.argv[1] 298 q2r_filename = sys.argv[2] 299 cell, _ = read_pwscf(primcell_filename) 300 q2r = PH_Q2R(q2r_filename) 301 q2r.run(cell, parse_fc=False) 302 if q2r.epsilon is not None: 303 borns, epsilon, _ = elaborate_borns_and_epsilon( 304 cell, 305 q2r.borns, 306 q2r.epsilon, 307 supercell_matrix=np.diag(q2r.dimension), 308 symmetrize_tensors=True) 309 print("default") 310 print(("%13.8f" * 9) % tuple(epsilon.ravel())) 311 for z in borns: 312 print(("%13.8f" * 9) % tuple(z.ravel())) 313 314Saving this script as ``make_born_q2r.py``, 315 316:: 317 318 % python make_born_q2r.py NaCl.in NaCl.fc > BORN 319 320NaCl example 321^^^^^^^^^^^^^ 322 323NaCl example is found at 324https://github.com/phonopy/phonopy/tree/master/example/NaCl-QE-q2r. 325 326:: 327 328 % phonopy --qe -c NaCl.in --dim="8 8 8" --band="0 0 0 1/2 0 0 1/2 1/2 0 0 0 0 1/2 1/2 1/2" --readfc --readfc-format=hdf5 --fc-symmetry --nac -p 329 330|q2r-band-nac| 331 332.. |q2r-band-nac| image:: NaCl-q2r-band-NAC.png 333 :width: 50% 334