TABLE OF CONTENTS
INTRODUCTION
Lineofinput: title_line
&INPUTPH
amass  outdir  prefix  niter_ph  tr2_ph  alpha_mix(niter)  nmix_ph  verbosity  reduce_io  max_seconds  fildyn  fildrho  fildvscf  epsil  lrpa  lnoloc  trans  lraman  eth_rps  eth_ns  dek  recover  low_directory_check  only_init  qplot  q2d  q_in_band_form  electron_phonon  lshift_q  zeu  zue  elop  fpol  ldisp  nogg  asr  ldiag  lqdir  search_sym  nq1  nq2  nq3  nk1  nk2  nk3  k1  k2  k3  start_irr  last_irr  nat_todo  modenum  start_q  last_q  dvscf_star  drho_star
Lineofinput: xq(1) xq(2) xq(3)
qPointsSpecs
nqs  xq1  xq2  xq3  nq
Lineofinput: atom(1) atom(2) ... atom(nat_todo)
ADDITIONAL INFORMATION
INTRODUCTION
Input data format: { } = optional, [ ] = it depends, # = comment
Structure of the input data:
===============================================================================
title_line
&INPUTPH
...
/
[ xq(1) xq(2) xq(3) ] # if ldisp != .true. and qplot != .true.
[ nqs # if qplot == .true.
xq(1,i) xq(2,i) xq(3,1) nq(1)
...
xq(1,nqs) xq(2,nqs) xq(3,nqs) nq(nqs) ]
[ atom(1) atom(2) ... atom(nat_todo) ] # if nat_todo was specified
Line of input

Syntax:
title_line

Description of items:
title_line 
CHARACTER 
Title of the job, i.e., a line that is reprinted on output.



Namelist: &INPUTPH

amass(i), i=1,ntyp 
REAL 
Default: 
0.0

Atomic mass [amu] of each atomic type.
If not specified, masses are read from data file.

outdir 
CHARACTER 
Default: 
value of the ESPRESSO_TMPDIR environment variable if set;
current directory ('./') otherwise

Directory containing input, output, and scratch files;
must be the same as specified in the calculation of
the unperturbed system.

prefix 
CHARACTER 
Default: 
'pwscf'

Prepended to input/output filenames; must be the same
used in the calculation of unperturbed system.

niter_ph 
INTEGER 
Default: 
maxter=100

Maximum number of iterations in a scf step. If you want
more than 100, edit variable "maxter" in PH/phcom.f90

tr2_ph 
REAL 
Default: 
1e12

Threshold for selfconsistency.

alpha_mix(niter) 
REAL 
Default: 
alpha_mix(1)=0.7

Mixing factor (for each iteration) for updating
the scf potential:
vnew(in) = alpha_mix*vold(out) + (1alpha_mix)*vold(in)

nmix_ph 
INTEGER 
Default: 
4

Number of iterations used in potential mixing.

verbosity 
CHARACTER 
Default: 
'default'

Options are:
 'debug', 'high', 'medium' :
verbose output
 'low', 'default', 'minimal' :
short output

reduce_io 
LOGICAL 
Default: 
.false.

Reduce I/O to the strict minimum.

max_seconds 
REAL 
Default: 
1.d7

Maximum allowed run time before the job stops smoothly.

fildyn 
CHARACTER 
Default: 
'matdyn'

File where the dynamical matrix is written.

fildrho 
CHARACTER 
Default: 
' '

File where the charge density responses are written. Note that the file
will actually be saved as ${outdir}/_ph0/${prefix}.${fildrho}1
where ${outdir}, ${prefix} and ${fildrho} are the values of the
corresponding input variables

fildvscf 
CHARACTER 
Default: 
' '

File where the the potential variation is written
(for later use in electronphonon calculation, see also fildrho).

epsil 
LOGICAL 
Default: 
.false.

If .true. in a q=0 calculation for a non metal the
macroscopic dielectric constant of the system is
computed. Do not set epsil to .true. if you have a
metallic system or q/=0: the code will complain and stop.

lrpa 
LOGICAL 
Default: 
.false.

If .true. the dielectric constant is calculated at the
RPA level with DV_xc=0.

lnoloc 
LOGICAL 
Default: 
.false.

If .true. the dielectric constant is calculated without
local fields, i.e. by setting DV_H=0 and DV_xc=0.

trans 
LOGICAL 
Default: 
.true.

If .true. the phonons are computed.
If trans .and. epsil are .true. effective charges are
calculated.

lraman 
LOGICAL 
Default: 
.false.

If .true. calculate nonresonant Raman coefficients
using secondorder response as in:
M. Lazzeri and F. Mauri, PRL 90, 036401 (2003).

Optional variables for Raman:
eth_rps 
REAL 
Default: 
1.0d9

Threshold for calculation of Pc R psi>.

eth_ns 
REAL 
Default: 
1.0e12

Threshold for nonscf wavefunction calculation.

dek 
REAL 
Default: 
1.0e3

Delta_xk used for wavefunction derivation wrt k.


recover 
LOGICAL 
Default: 
.false.

If .true. restart from an interrupted run.

low_directory_check 
LOGICAL 
Default: 
.false.

If .true. search in the phsave directory only the
quantities requested in input.

only_init 
LOGICAL 
Default: 
.false.

If .true. only the bands and other initialization quantities are calculated.
(used for GRID parallelization)

qplot 
LOGICAL 
Default: 
.false.

If .true. a list of q points is read from input.

q2d 
LOGICAL 
Default: 
.false.

If .true. three q points and relative weights are
read from input. The three q points define the rectangle
q(:,1) + l (q(:,2)q(:,1)) + m (q(:,3)q(:,1)) where
0< l,m < 1. The weights are integer and those of points two
and three are the number of points in the two directions.

q_in_band_form 
LOGICAL 
Default: 
.false.

This flag is used only when qplot is .true. and q2d is
.false.. When .true. each couple of q points q(:,i+1) and
q(:,i) define the line from q(:,i) to q(:,i+1) and nq
points are generated along that line. nq is the weigth of
q(:,i). When .false. only the list of q points given as
input is calculated. The weights are not used.

electron_phonon 
CHARACTER 
Default: 
' '

Options are:
 'simple' :
Electronphonon lambda coefficients are computed
for a given q and a grid of kpoints specified by
the variables nk1, nk2, nk3, k1, k2, k3.
 'interpolated' :
Electronphonon is calculated by interpolation
over the Brillouin Zone as in M. Wierzbowska, et
al. arXiv:condmat/0504077
 'lambda_tetra' :
The electronphonon coefficient \lambda_{q \nu}
is calculated with the optimized tetrahedron method.
 'gamma_tetra' :
The phonon linewidth \gamma_{q \nu} is calculated
from the electronphonon interactions
using the optimized tetrahedron method.
For metals only, requires gaussian smearing.
If trans=.true., the lambdas are calculated in the same
run, using the same kpoint grid for phonons and lambdas.
If trans=.false., the lambdas are calculated using
previously saved DeltaVscf in fildvscf, previously saved
dynamical matrix, and the present punch file. This allows
the use of a different (larger) kpoint grid.

lshift_q 
LOGICAL 
Default: 
.false.

Use a wavevector grid displaced by half a grid step
in each direction  meaningful only when ldisp is .true.
When this option is set, the q2r.x code cannot be used.

zeu 
LOGICAL 
Default: 
zeu=epsil

If .true. in a q=0 calculation for a non metal the
effective charges are computed from the dielectric
response. This is the default algorithm. If epsil=.true.
and zeu=.false. only the dielectric tensor is calculated.

zue 
LOGICAL 
Default: 
.false.

If .true. in a q=0 calculation for a non metal the
effective charges are computed from the phonon
density responses. This is an alternative algorithm,
different from the default one (if trans .and. epsil )
The results should be the same within numerical noise.

elop 
LOGICAL 
Default: 
.false.

If .true. calculate electrooptic tensor.

fpol 
LOGICAL 
Default: 
.false.

If .true. calculate dynamic polarizabilities
Requires epsil=.true. ( experimental stage:
see example09 for calculation of methane ).

ldisp 
LOGICAL 
Default: 
.false.

If .true. the run calculates phonons for a grid of
qpoints specified by nq1, nq2, nq3  for direct
calculation of the entire phonon dispersion.

nogg 
LOGICAL 
Default: 
.false.

If .true. disable the "gamma_gamma" trick used to speed
up calculations at q=0 (phonon wavevector) if the sum over
the Brillouin Zone includes k=0 only. The gamma_gamma
trick exploits symmetry and acoustic sum rule to reduce
the number of linear response calculations to the strict
minimum, as it is done in code phcg.x.

asr 
LOGICAL 
Default: 
.false.

Apply Acoustic Sum Rule to dynamical matrix, effective charges
Works only in conjunction with "gamma_gamma" tricks (see above)

ldiag 
LOGICAL 
Default: 
.false.

If .true. forces the diagonalization of the dynamical
matrix also when only a part of the dynamical matrix
has been calculated. It is used together with start_irr
and last_irr. If all modes corresponding to a
given irreducible representation have been calculated,
the phonon frequencies of that representation are
correct. The others are zero or wrong. Use with care.

lqdir 
LOGICAL 
Default: 
.false.

If .true. ph.x creates inside outdir a separate subdirectory
for each q vector. The flag is set to .true. when ldisp=.true.
and fildvscf /= ' ' or when an electronphonon
calculation is performed. The induced potential is saved
separately for each q inside the subdirectories.

search_sym 
LOGICAL 
Default: 
.true.

Set it to .false. if you want to disable the mode
symmetry analysis.

nq1, nq2, nq3 
INTEGER 
Default: 
0,0,0

Parameters of the MonkhorstPack grid (no offset) used
when ldisp=.true. Same meaning as for nk1, nk2, nk3
in the input of pw.x.

nk1, nk2, nk3, k1, k2, k3 
INTEGER 
Default: 
0,0,0,0,0,0

When these parameters are specified the phonon program
runs a pw nonself consistent calculation with a different
kpoint grid thant that used for the charge density.
This occurs even in the Gamma case.
nk1,nk2,nk3 are the parameters of the MonkhorstPack grid
with offset determined by k1,k2,k3.

Specification of irreducible representation
nat_todo 
INTEGER 
Default: 
0, i.e. displace all atoms

Choose the subset of atoms to be used in the linear response
calculation: nat_todo atoms, specified in input (see below)
are displaced. Can be used to estimate modes for a molecule
adsorbed over a surface without performing a full fledged
calculation. Use with care, at your own risk, and be aware
that this is an approximation and may not work.
IMPORTANT:
* nat_todo <= nat
* if linearresponse is calculated for a given atom, it
should also be done for all symmetryequivalent atoms,
or else you will get incorrect results

modenum 
INTEGER 
Default: 
0

For singlemode phonon calculation : modenum is the index of the
irreducible representation (irrep) into which the reducible
representation formed by the 3*nat atomic displacements are
decomposed in order to perform the phonon calculation.
Note that a singlemode calculation will not give you the
frequency of a single phonon mode: in general, the selected
"modenum" is not an eigenvector. What you get on output is
a column of the dynamical matrix.


qpoint specification
dvscf_star 
STRUCTURE 
Default: 
disabled

It contains the following components:
dvscf_star%open (logical, default: .false.)
dvscf_star%dir (character, default: outdir//"Rotated_DVSCF" or the
ESPRESSO_FILDVSCF_DIR environment variable)
dvscf_star%ext (character, default: "dvscf") the extension to use
for the name of the output files, see below
dvscf_star%basis (character, default: "cartesian") the basis on which
the rotated dvscf will be saved
dvscf_star%pat (logical, default: false) save an optional file with the
displacement patterns and q vector for each dvscf file
IF dvscf_star%open is .true. use symmetry to compute and store the variation
of the selfconsistent potential on every q* in the star of the present q.
The rotated dvscf will then be stored in directory dvscf_star%dir with name
prefix.dvscf_star%ext.q_name//"1". Where q_name is derived from the coordinates
of the qpoint, expressed as fractions in crystalline coordinates
(notice that ph.x reads qpoints in cartesian coordinates).
E.g. q_cryst= (0, 0.5, 0.25) > q_name = "0_1o2_1o4"
The dvscf can be represented on a basis of cartesian 1atom displacements
(dvscf_star%basis='cartesian') or on the basis of the modes at the rotated qpoint
(dvscf_star%basis='modes'). Notice that the elph wannier code requires 'cartesian'.
Each dvscf file comes with a corresponding pattern file with an additional ".pat"
suffix; this file contains information about the basis and the qpoint of the dvscf.
Note: rotating dvscf can require a large amount of RAM memory and can be i/o
intensive; in its current implementation all the operations are done
on a single processor.
Note2: this feature is currently untested with image parallelisation.

drho_star 
STRUCTURE 
Default: 
disabled

See: 
dvscf_star 
It contains the following components:
drho_star%open (logical, default: .false.)
drho_star%dir (character, default: outdir//"Rotated_DRHO" or the
ESPRESSO_FILDRHO_DIR environment variable)
drho_star%ext (character, default: "drho") the extension to use
for the name of the output files, see below
drho_star%basis (character, default: "modes") the basis on which
the rotated drho will be saved
drho_star%pat (logical, default: true) save an optional file with the
displacement patterns and q vector for each drho file
Like dvscf_star, but for the perturbation of the charge density.
Notice that the defaults are different.




IF ldisp != .true. and qplot != .true. :
Line of input

Syntax:
xq(1) xq(2) xq(3)

Description of items:
xq(1) xq(2) xq(3)

REAL 
The phonon wavevector, in units of 2pi/a0
(a0 = lattice parameter).
Not used if ldisp=.true. or qplot=.true.




ELSEIF qplot == .true. :
Specification of q points when qplot == .true.
Card: qPointsSpecs 
Syntax:

Description of items:
nqs 
INTEGER 
Number of q points in the list. Used only if qplot=.true.

xq1, xq2, xq3

REAL 
qpoint coordinates; used only with ldisp=.true. and qplot=.true.
The phonon wavevector, in units of 2pi/a0 (a0 = lattice parameter).
The meaning of these q points and their weights nq depend on the
flags q2d and q_in_band_form. (NB: nq is integer)

nq 
INTEGER 
The weight of the qpoint; the meaning of nq depends
on the flags q2d and q_in_band_form.





IF nat_todo was specified :

ADDITIONAL INFORMATION
NB: The program ph.x writes on the tmp_dir/_ph0/{prefix}.phsave directory
a file for each representation of each q point. This file is called
dynmat.#iq.#irr.xml where #iq is the number of the q point and #irr
is the number of the representation. These files contain the
contribution to the dynamical matrix of the irr representation for the
iq point.
If recover=.true. ph.x does not recalculate the
representations already saved in the tmp_dir/_ph0/{prefix}.phsave
directory. Moreover ph.x writes on the files patterns.#iq.xml in the
tmp_dir/_ph0/{prefix}.phsave directory the displacement patterns that it
is using. If recover=.true. ph.x does not recalculate the
displacement patterns found in the tmp_dir/_ph0/{prefix}.phsave directory.
This mechanism allows:
1) To recover part of the ph.x calculation even if the recover file
or files are corrupted. You just remove the _ph0/{prefix}.recover
files from the tmp_dir directory. You can also remove all the _ph0
files and keep only the _ph0/{prefix}.phsave directory.
2) To split a phonon calculation into several jobs for different
machines (or set of nodes). Each machine calculates a subset of
the representations and saves its dynmat.#iq.#irr.xml files on
its tmp_dir/_ph0/{prefix}.phsave directory. Then you collect all the
dynmat.#iq.#irr.xml files in one directory and run ph.x to
collect all the dynamical matrices and diagonalize them.
NB: To split the q points in different machines, use the input
variables start_q and last_q. To split the irreducible
representations, use the input variables start_irr, last_irr. Please
note that different machines will use, in general, different
displacement patterns and it is not possible to recollect partial
dynamical matrices generated with different displacement patterns. A
calculation split into different machines will run as follows: A
preparatory run of ph.x with start_irr=0, last_irr=0 produces the sets
of displacement patterns and save them on the patterns.#iq.xml files.
These files are copied in all the tmp_dir/_ph0/{prefix}.phsave directories
of the machines where you plan to run ph.x. ph.x is run in different
machines with complementary sets of start_q, last_q, start_irr and
last_irr variables. All the files dynmat.#iq.#irr.xml are
collected on a single tmp_dir/_ph0/{prefix}.phsave directory (remember to
collect also dynmat.#iq.0.xml). A final run of ph.x in this
machine collects all the data contained in the files and diagonalizes
the dynamical matrices. This is done requesting a complete dispersion
calculation without using start_q, last_q, start_irr, or last_irr.
See an example in examples/GRID_example.
On parallel machines the q point and the irreps calculations can be split
automatically using the nimage flag. See the phonon user guide for further
information.
