Quantum ESPRESSO (QE) & phonopy calculation#

Quantum ESPRESSO package itself has a set of the phonon calculation system. But the document here explains how to calculate phonons using phonopy, i.e., using the finite displacement and supercell approach.

Supported QE-PW tags#

Currently QE-PW tags that phonopy can read are shown below. Only ibrav = 0 type representation of crystal structure is supported. More tags may be supported on request.

nat, ntyp, celldm(1), ATOMIC_SPECIES, ATOMIC_POSITIONS, CELL_PARAMETERS

Chemical symbols with natural number for ATOMIC_SPECIES like Xn (n>0), e.g.. Fe1, can be used. The formats of X_* and X-* are not supported. When this extended symbol is used, masses of all atoms including usual chemical symbols are read from QE structure file. Otherwise, masses of respective chemical symbols implemented in phonopy are used. Note that when using the extended symbol, if the unit cell of QE structure file is not a primitive cell, and the primitive cell is defined by the transformation matrix (PRIMITIVE_AXES tag or --pa option), atoms with the extended symbols in the unit cell have to be mapped properly to those in the primitive cell.

How to run#

The procedure of QE-phonopy calculation is shown below using the NaCl example found in example/NaCl-QE directory.

Read a QE-PW input file and create supercells with --qe option:
```
% phonopy --qe -d --dim="2 2 2" -c NaCl.in
```
In this example, 2x2x2 supercells are created. supercell.in and supercell-xxx.in (xxx are numbers) give the perfect supercell and supercells with displacements, respectively. In the case of the NaCl example, two files supercell-001.in and supercell-002.in are created. In these supercell files, lines only relevant to crystal structures are given. phonopy_disp.yaml is also generated, which contains information about supercell and displacements.
To make QE-PW input files, necessary setting information is added to supercell-xxx.in files, e.g., by:
```
% for i in {001,002};do cat header.in supercell-$i.in >| NaCl-$i.in; done
```
where header.in is specially made for this NaCl example and this file is found in example/NaCl-QE directory. This setting is of course dependent on systems and has to be written for each interested system. Note that supercells with displacements must not be relaxed in the force calculations, because atomic forces induced by a small atomic displacement are what we need for phonon calculation.

Then QE-PW supercell calculations are executed to obtain force on atoms, e.g., as follows:
```
% pw.x -i NaCl-001.in |& tee NaCl-001.out
% pw.x -i NaCl-002.in |& tee NaCl-002.out
```
To create FORCE_SETS, that is used by phonopy, the following phonopy command is executed:
```
% phonopy -f NaCl-001.out NaCl-002.out
```
Here .out files are the saved text files of standard outputs of the QE-PW calculations. If more supercells with displacements were created in the step 1, all .out files are given in the above command. To run this command, phonopy_disp.yaml has to be located in the current directory because the information on atomic displacements stored in phonopy_disp.yaml are used to generate FORCE_SETS. See some more detail at Quantum ESPRESSO interface.

Now post-process of phonopy is ready to run. The unit cell file used in the step 1 has to be specified but FORCE_SETS is automatically read. Examples of post-process are shown below.

% phonopy-load -p --config band.conf
        _
  _ __ | |__   ___  _ __   ___   _ __  _   _
 | '_ \| '_ \ / _ \| '_ \ / _ \ | '_ \| | | |
 | |_) | | | | (_) | | | | (_) || |_) | |_| |
 | .__/|_| |_|\___/|_| |_|\___(_) .__/ \__, |
 |_|                            |_|    |___/
                                      2.47.1

-------------------------[time 2026-01-16 08:09:24]-------------------------
Compiled with OpenMP support (max 10 threads).
Running in phonopy.load mode.
Python version 3.13.3
Spglib version 2.7.0

"band.conf" was read as phonopy configuration file.
Calculator interface: qe
Crystal structure was read from "phonopy_disp.yaml".
Unit of length: au
Band structure mode
Settings:
  Supercell: [2 2 2]
  Primitive matrix:
    [0.  0.5 0.5]
    [0.5 0.  0.5]
    [0.5 0.5 0. ]
Spacegroup: Fm-3m (225)
Number of symmetry operations in supercell: 1536
Use -v option to watch primitive cell, unit cell, and supercell structures.

NAC params were read from "BORN".
Displacement-force dataset was read from "FORCE_SETS".
-------------------------------- Symfc start -------------------------------
Symfc version 1.6.0 (https://github.com/symfc/symfc)
Citation: A. Seko and A. Togo, Phys. Rev. B, 110, 214302 (2024)
Computing [2] order force constants.
Increase log-level to watch detailed symfc log.
--------------------------------- Symfc end --------------------------------
Max drift of force constants: -0.00000000 (yy) -0.00000000 (yy)
Max drift after symmetrization by symfc projector: -0.00000000 (yy) -0.00000000 (yy)

Reciprocal space paths in reduced coordinates:
[ 0.000  0.000  0.000] --> [ 0.500  0.000  0.000]
[ 0.500  0.000  0.000] --> [ 0.500  0.500  0.000]
[ 0.500  0.500  0.000] --> [ 0.000  0.000  0.000]
[ 0.000  0.000  0.000] --> [ 0.500  0.500  0.500]

Summary of calculation was written in "phonopy.yaml".
-------------------------[time 2026-01-16 08:09:27]-------------------------
                 _
   ___ _ __   __| |
  / _ \ '_ \ / _` |
 |  __/ | | | (_| |
  \___|_| |_|\__,_|

--qe -c NaCl.in is specific for the QE-phonopy calculation but the other settings are totally common among calculator interfaces such as

% phonopy --qe -c NaCl.in --dim="2 2 2" [other-OPTIONS] [setting-file]

For settings and command options, see Setting tags and Command options, respectively, and for examples, see Examples.

Non-analytical term correction (Optional)#

To activate non-analytical term correction, BORN (optional) is required. This file contains the information of Born effective charge and dielectric constant. These physical values are also obtained from the PW (pw.x) & PH (ph.x) codes in Quantum ESPRESSO package. There are two steps. The first step is usual self-consistent field (SCF) calculation by and the second step is running its response function calculations under DFPT.

For the SCF calculation, the input file NaCl.in looks like:

 &control
    calculation = 'scf'
    tprnfor = .true.
    tstress = .true.
    pseudo_dir = '/home/togo/espresso/pseudo/'
 /
 &system
    ibrav = 0
    nat = 8
    ntyp = 2
    ecutwfc = 70.0
 /
 &electrons
    diagonalization = 'david'
    conv_thr = 1.0d-9
 /
ATOMIC_SPECIES
 Na  22.98976928 Na.pbe-spn-kjpaw_psl.0.2.UPF
 Cl  35.453      Cl.pbe-n-kjpaw_psl.0.1.UPF
ATOMIC_POSITIONS crystal
 Na   0.0000000000000000  0.0000000000000000  0.0000000000000000
 Na   0.0000000000000000  0.5000000000000000  0.5000000000000000
 Na   0.5000000000000000  0.0000000000000000  0.5000000000000000
 Na   0.5000000000000000  0.5000000000000000  0.0000000000000000
 Cl   0.5000000000000000  0.5000000000000000  0.5000000000000000
 Cl   0.5000000000000000  0.0000000000000000  0.0000000000000000
 Cl   0.0000000000000000  0.5000000000000000  0.0000000000000000
 Cl   0.0000000000000000  0.0000000000000000  0.5000000000000000
CELL_PARAMETERS angstrom
 5.6903014761756712 0 0
 0 5.6903014761756712 0
 0 0 5.6903014761756712
K_POINTS automatic
 8 8 8 1 1 1

where more the k-point mesh numbers are specified. This may be exectued as:

% pw.x -i NaCl.in |& tee NaCl.out

Many files whose names stating with pwscf should be created. These are used for the next calculation. The input file for the response function calculations, NaCl.ph.in, is created as follows:

 &inputph
  tr2_ph = 1.0d-14,
  epsil = .true.
 /
0 0 0

Similary ph.x is executed:

% ph.x -i NaCl.ph.in |& tee NaCl.ph.out

Finally the Born effective charges and dielectric constant are obtained in the output file NaCl.ph.out. The BORN file has to be created following the BORN format (BORN (optional)). The BORN file for this NaCl calculation would be something like below:

default value
2.472958201 0 0 0 2.472958201 0 0 0 2.472958201
1.105385 0 0 0 1.105385 0 0 0 1.105385
-1.105385 0 0 0 -1.105385 0 0 0 -1.105385

This BORN file can be made using phonopy-qe-born command.

% phonopy-qe-born NaCl.in NaCl.ph.out | tee BORN

Once this is made, the non-analytical term correction is included just adding the --nac option as follows:

% phonopy-load -p --config band.conf

Using `q2r.x` to create phonopy force constants file#

Experimental

Using PW, PH, and Q2R, we can obtain supercell force constants that can be used for phonopy. But we may need some treatment before running Q2R. See Non-analytical term correction.

NaCl.in

 &control
    calculation = 'scf'
    restart_mode='from_scratch',
    tprnfor = .true.
    tstress = .true.
    prefix='NaCl',
    pseudo_dir = '/home/togo/code/q-e-qe-7.5/pseudo'
    outdir='.'
 /
 &system
    ibrav = 0
    nat = 2
    ntyp = 2
    ecutwfc = 70.0
 /
 &electrons
    diagonalization = 'david'
    !mixing_beta = 0.7
    conv_thr = 1.0d-12
 /
ATOMIC_SPECIES
 Na  22.98976928 Na.pbe-spn-kjpaw_psl.0.2.UPF
 Cl  35.453      Cl.pbe-n-kjpaw_psl.0.1.UPF
ATOMIC_POSITIONS crystal
 Na   0.0000000000000000  0.0000000000000000  0.0000000000000000
 Cl   0.5000000000000000  0.5000000000000000  0.5000000000000000
CELL_PARAMETERS angstrom
0 2.8451507380878356 2.8451507380878356
2.8451507380878356 0 2.8451507380878356
2.8451507380878356 2.8451507380878356 0
K_POINTS automatic
8 8 8 0 0 0

and NaCl.ph.in

phonons of NaCl
 &inputph
  tr2_ph=1.0d-16,
  prefix='NaCl',
  ldisp=.true.,
  nq1=4, nq2=4, nq3=4
  amass(1)=22.98976928,
  amass(2)=35.453,
  outdir='.',
  fildyn='NaCl.dyn',
 /

The PH calculation can be peformed for each q-point independently, e.g.,

phonons of NaCl
 &inputph
  tr2_ph=1.0d-16,
  prefix='NaCl',
  ldisp=.true.,
  nq1=4, nq2=4, nq3=4
  amass(1)=22.98976928,
  amass(2)=35.453,
  outdir='.',
  fildyn='NaCl.dyn',
  start_q=1
  last_q=1
 /

The output file at the Gamma point calculated this way contains the Born effective charges and dielectric constant if the crystal is an insulator. These are unnecessary for phonopy. Therefore, the NaCl.dyn1 file should be replaced with NaCl.dyn, which is calculated using the following input:

phonons of NaCl
 &inputph
  tr2_ph=1.0d-16,
  prefix='NaCl',
  epsil=.false.,
  outdir='.',
  fildyn='NaCl.dyn',
 /
0.0 0.0 0.0

Then having all NaCl.dyn1, …, files, NaCl.fc for phonopy can be generated using Q2R.

A parser of q2r.x output is implemented experimentally. Currently command-line user interface is not prepared. Using the following script, the force constants file readable by phonopy is created.

#!/usr/bin/env python

import sys
from phonopy.interface.qe import read_pwscf, PH_Q2R

primcell_filename = sys.argv[1]
q2r_filename = sys.argv[2]
cell, _ = read_pwscf(primcell_filename)
q2r = PH_Q2R(q2r_filename)
q2r.run(cell)
q2r.save()

Saving this script as make_fc_q2r.py, this is used as, e.g.,

% python make_fc_q2r.py NaCl.in NaCl.fc

This gives phonopy_params_q2r.yaml file that contains supercell force constants.

Non-analytical term correction#

The treatment of non-analytical term correction (NAC) differs between phonopy and QE. For insulators, QE automatically calculates the dielectric constant and Born effective charges during PH calculations when the q-point mesh sampling mode is enabled (ldisp = .true.). These data are written to the Gamma point dynamical matrix file (typically the .dyn1 file). When running q2r.x, this program reads these files including the dielectric constant and Born effective charges, and writes the real-space force constants (with QE’s NAC treatment applied) to the Q2R output file. However, this differs from what phonopy expects. Therefore, the dielectric constant and Born effective charges data must be manually removed from the Gamma point dynamical matrix file before running q2r.x. Alternatively, performing a Gamma point-only phonon calculation with epsil = .false. generates a dynamical matrix file without the dielectric constant and Born effective charges data. This Gamma point-only file can then replace the original Gamma point file, allowing q2r.x to be run for phonopy without modification.

NaCl example#

NaCl example is found at phonopy/phonopy.

% phonopy-load phonopy_params_q2r.yaml --band="0 0 0  1/2 0 0  1/2 1/2 0  0 0 0  1/2 1/2 1/2" -p

Quantum ESPRESSO (QE) & phonopy calculation

Contents