    ------------------------------------------------------------------------
    INPUT FILE DESCRIPTION

    Program: ph.x / PWscf / Quantum Espresso
    ------------------------------------------------------------------------

    Input data format: { } = optional, [ ] = it depends, # = comment

    Structure of the input data:
    ===============================================================================

    title_line

    &INPUTPH
       ...
    /

    xq(1) xq(2) xq(3)
    [ atom(1)  atom(2)  ... atom(nat_todo) ]     # if "nat_todo" was specified

    ========================================================================
    Line of input:

          title_line

       DESCRIPTION OF ITEMS:

          +--------------------------------------------------------------------
          Variable:       title_line

          Type:           CHARACTER
          Description:    Title of the job, i.e., a line that is reprinted on output.
          +--------------------------------------------------------------------

    ===End of line-of-input=================================================

    ========================================================================
    NAMELIST: &INPUTPH

       +--------------------------------------------------------------------
       Variable:       amass(i), i=1,ntyp

       Type:           REAL
       Default:        0.0
       Description:    Atomic mass [amu] of each atomic type.
                       If not specified, masses are read from data file.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       outdir

       Type:           CHARACTER
       Default:        value of the ESPRESSO_TMPDIR environment variable if set;
                       current directory ('./') otherwise
       Description:    Directory containing input, output, and scratch files;
                       must be the same as specified in the calculation of
                       the unperturbed system.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       prefix

       Type:           CHARACTER
       Default:        'pwscf'
       Description:    Prepended to input/output filenames; must be the same
                       used in the calculation of unperturbed system.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       niter_ph

       Type:           INTEGER
       Default:        maxter=100
       Description:    Maximum number of iterations in a scf step. If you want
                       more than 100, edit variable "maxter" in PH/phcom.f90
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       tr2_ph

       Type:           REAL
       Default:        1e-12
       Description:    Threshold for self-consistency.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       alpha_mix(niter)

       Type:           REAL
       Default:        alpha_mix(1)=0.7
       Description:    Mixing factor (for each iteration) for updating
                       the scf potential:

                       vnew(in) = alpha_mix*vold(out) + (1-alpha_mix)*vold(in)
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       nmix_ph

       Type:           INTEGER
       Default:        4
       Description:    Number of iterations used in potential mixing.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       iverbosity

       Type:           INTEGER
       Default:        0
       Description:    0 = short output
                       1 = verbose output
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       reduce_io

       Type:           LOGICAL
       Default:        .false.
       Description:    Reduce I/O to the strict minimum.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       max_seconds

       Type:           REAL
       Default:        1.d7
       Description:    Maximum allowed run time before the job stops smoothly.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       fildyn

       Type:           CHARACTER
       Default:        'matdyn'
       Description:    File where the dynamical matrix is written.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       fildrho

       Type:           CHARACTER
       Default:        ' '
       Description:    File where the charge density responses are written.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       fildvscf

       Type:           CHARACTER
       Default:        ' '
       Description:    File where the the potential variation is written
                       (for later use in electron-phonon calculation).
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       epsil

       Type:           LOGICAL
       Default:        .false.
       Description:    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.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       lrpa

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. the dielectric constant is calculated at the
                       RPA level with DV_xc=0.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       lnoloc

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. the dielectric constant is calculated without
                       local fields, i.e. by setting DV_H=0 and DV_xc=0.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       trans

       Type:           LOGICAL
       Default:        .true.
       Description:    If .true. the phonons are computed.
                       If trans .and. epsil are .true. effective charges are
                       calculated.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       lraman

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. calculate non-resonant Raman coefficients
                       using second-order response as in:
                       M. Lazzeri and F. Mauri, Phys. Rev. Lett. 90, 036401 (2003).
       +--------------------------------------------------------------------

       ///---
          OPTIONAL VARIABLES FOR RAMAN:

          +--------------------------------------------------------------------
          Variable:       eth_rps

          Type:           REAL
          Default:        1.0d-9
          Description:    Threshold for calculation of  Pc R |psi>.
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       eth_ns

          Type:           REAL
          Default:        1.0e-12
          Description:    Threshold for non-scf wavefunction calculation.
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       dek

          Type:           REAL
          Default:        1.0e-3
          Description:    Delta_xk used for wavefunction derivation wrt k.
          +--------------------------------------------------------------------

       \\\---

       +--------------------------------------------------------------------
       Variable:       recover

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. restart from an interrupted run.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       electron_phonon

       Type:           CHARACTER
       Default:        ' '
       Description:    If equal to 'simple' electron-phonon lambda coefficients
                       are computed for a given q and a grid of k-points specified
                       by the variables nk1, nk2, nk3, k1, k2, k3.

                       If equal to 'interpolated' electron-phonon is calculated
                       by interpolation over the Brillouin Zone as in
                       M. Wierzbowska, et al. arXiv:cond-mat/0504077

                       For metals only, requires gaussian smearing.

                       If trans=.true., the lambdas are calculated in the same
                       run, using the same k-point 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) k-point grid.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       zeu

       Type:           LOGICAL
       Default:        zeu=epsil
       Description:    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.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       zue

       Type:           LOGICAL
       Default:        .false.
       Description:    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.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       elop

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. calculate electro-optic tensor.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       fpol

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. calculate dynamic polarizabilities
                       Requires epsil=.true. ( experimental stage:
                       see example09 for calculation of methane ).
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       ldisp

       Type:           LOGICAL
       Default:        .false.
       Description:    If .true. the run calculates phonons for a grid of
                       q-points specified by nq1, nq2, nq3 - for direct
                       calculation of the entire phonon dispersion.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       nogg

       Type:           LOGICAL
       Default:        .false.
       Description:    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. This option MUST
                       BE USED if a run with ph.x is to be followed by a run
                       with d3.x for third-order terms calculation.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       ldiag

       Type:           LOGICAL
       Default:        .false.
       Description:    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.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       lqdir

       Type:           LOGICAL
       Default:        .false.
       Description:    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 electron-phonon
                       calculation is performed. The induced potential is saved
                       separately for each q inside the subdirectories.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variable:       search_sym

       Type:           LOGICAL
       Default:        .true.
       Description:    Set it to .false. if you want to disable the mode
                       symmetry analysis.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variables:      nq1, nq2, nq3

       Type:           INTEGER
       Default:        0,0,0
       Description:    Parameters of the Monkhorst-Pack grid (no offset) used
                       when ldisp=.true. Same meaning as for nk1, nk2, nk3
                       in the input of pw.x.
       +--------------------------------------------------------------------

       +--------------------------------------------------------------------
       Variables:      nk1, nk2, nk3, k1, k2, k3

       Type:           INTEGER
       Default:        0,0,0,0,0,0
       Description:    When these parameters are specified the phonon program
                       runs a pw non-self consistent calculation with a different
                       k-point grid thant that used for the charge density.
                       This occurs even in the Gamma case.
                       nk1,nk2,nk3 are the parameters of the Monkhorst-Pack grid
                       with offset determined by k1,k2,k3.
       +--------------------------------------------------------------------

       ///---
          SPECIFICATION OF IRREDUCIBLE REPRESENTATION

          +--------------------------------------------------------------------
          Variable:       start_irr

          Type:           INTEGER
          Default:        1
          See:            last_irr
          Description:    Perform calculations only from start_irr to last_irr
                          irreducible representations.

                          IMPORTANT:
                             * start_irr must be <= 3*nat
                             * do not specify "nat_todo" together with
                               "start_irr", "last_irr"
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       last_irr

          Type:           INTEGER
          Default:        3*nat
          See:            start_irr
          Description:    Perform calculations only from start_irr to last_irr
                          irreducible representations.

                          IMPORTANT:
                             * start_irr must be <= 3*nat
                             * do not specify "nat_todo" together with
                               "start_irr", "last_irr"
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       nat_todo

          Type:           INTEGER
          Default:        0, i.e. displace all atoms
          Description:    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,m and be aware
                          that this is an approximation and may not work.
                          IMPORTANT:
                             * nat_todo <= nat
                             * if linear-response is calculated for a given atom, it
                               should also be done for all symmetry-equivalent atoms,
                               or else you will get incorrect results
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       modenum

          Type:           INTEGER
          Default:        0
          Description:    For single-mode 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 single-mode 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.
          +--------------------------------------------------------------------

       \\\---

       ///---
          Q-POINT SPECIFICATION

          +--------------------------------------------------------------------
          Variable:       start_q

          Type:           INTEGER
          Default:        1
          See:            last_q
          Description:    Used only when ldisp=.true..
                          Computes only the q points from start_q to last_q.

                          IMPORTANT:
                             * start_q must be <= nqs (number of q points found)
                             * do not specify "nat_todo" together with
                               "start_q", "last_q"
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       last_q

          Type:           INTEGER
          Default:        number of q points
          See:            start_q
          Description:    Used only when ldisp=.true..
                          Computes only the q points from start_q to last_q.

                          IMPORTANT
                             * last_q must be <= nqs (number of q points)
                             * do not specify "nat_todo" together with
                               "start_q", "last_q"
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       dvscf_star

          Type:           STRUCTURE
          Default:        disabled
          Description:    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: true) 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 self-consistent 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 q-point, expressed as fractions in crystalline coordinates
                          (notice that ph.x reads q-points 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 1-atom displacements
                          (dvscf_star%basis='cartesian') or on the basis of the modes at the rotated q-point
                          (dvscf_star%basis='modes'). Notice that the el-ph 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 q-point 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.
          +--------------------------------------------------------------------

          +--------------------------------------------------------------------
          Variable:       drho_star

          Type:           STRUCTURE
          See:            dvscf_star
          Default:        disabled
          Description:    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: false) 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.
          +--------------------------------------------------------------------

       \\\---

    ===END OF NAMELIST======================================================

    ========================================================================
    Line of input:

          xq(1)  xq(2)  xq(3)

       DESCRIPTION OF ITEMS:

          +--------------------------------------------------------------------
          Variables:      xq(1)  xq(2)  xq(3)

          Type:           REAL
          Description:    The phonon wavevector, in units of 2pi/a0
                          (a0 = lattice parameter).
                          Not used if ldisp=.true.
          +--------------------------------------------------------------------

    ===End of line-of-input=================================================

    ________________________________________________________________________
    * IF nat_todo was specified :

       ========================================================================
       Line of input:

             atom(1)  atom(2) ... atom(nat_todo)

          DESCRIPTION OF ITEMS:

             +--------------------------------------------------------------------
             Variables:      atom(1)  atom(2) ... atom(nat_todo)

             Type:           INTEGER
             Description:    Contains the list of indices of atoms used in the
                             calculation if "nat_todo" is specified.
             +--------------------------------------------------------------------

       ===End of line-of-input=================================================

    ENDIF
    ________________________________________________________________________

    ::::  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
       data-file.#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 data-file.#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 data-file.#iq.#irr.xml files on
            its tmp_dir/_ph0/{prefix}.phsave directory. Then you collect all the
            data-file.#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 dispacement 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 data-file.#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 data-file.#iq.#irr.xml are
       collected on a single tmp_dir/_ph0/{prefix}.phsave directory (remember to
       collect also data-file.#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.