input_description -distribution {Quantum Espresso} -package PWscf -program ph.x {

    toc {}

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

	@b {Structure of the input data:}
	===============================================================================

	title_line 

	@b &INPUTPH
	   ...
	@b /

	[ xq(1) xq(2) xq(3) ]                        @i {# if @ref ldisp != .true.  and  @ref qplot != .true.}

        [ nqs                                        @i {# if @ref 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) ]     @i {# if @ref nat_todo was specified}
    }

    linecard {
	var title_line -type CHARACTER {
	    info {
		Title of the job, i.e., a line that is reprinted on output.
	    }
	}    
    }

    namelist INPUTPH {

	dimension amass -start 1 -end ntyp -type REAL {
	    default { 0.0 }
	    info {
		Atomic mass [amu] of each atomic type.
		If not specified, masses are read from data file.
	    }
	}    

        var outdir -type CHARACTER {
            default {
                value of the @tt ESPRESSO_TMPDIR environment variable if set;
                @br current directory ('./') otherwise
            }
            info {
                Directory containing input, output, and scratch files; 
                must be the same as specified in the calculation of 
                the unperturbed system.
            }
        }
    
        var prefix -type CHARACTER { 
            default { 'pwscf' }
            info {
                Prepended to input/output filenames; must be the same 
                used in the calculation of unperturbed system.
            }
        }

        var niter_ph -type INTEGER { 
            default { maxter=100 }
            info {
                Maximum number of iterations in a scf step. If you want
                more than 100, edit variable "maxter" in PH/phcom.f90
            }
        }

        var tr2_ph   -type REAL { 
            default { 1e-12 }
            info     { Threshold for self-consistency. }
        }

        var alpha_mix(niter)  -type REAL { 
            default { alpha_mix(1)=0.7 }
            info { 
                Mixing factor (for each iteration) for updating 
                the scf potential:

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

        var nmix_ph   -type INTEGER { 
            default { 4 }
            info { Number of iterations used in potential mixing. }
        }

        var verbosity -type CHARACTER { 
            default { 'default' }
            options {
                info { Options are: }
                opt -val {'debug', 'high', 'medium'} { verbose output }
                opt -val {'low', 'default', 'minimal'} { short output }
            }
        }

        var reduce_io -type LOGICAL { 
            default { .false. }
            info { Reduce I/O to the strict minimum. }
        }

        var max_seconds  -type REAL { 
            default { 1.d7 }
            info { Maximum allowed run time before the job stops smoothly. }
        }

        var fildyn -type CHARACTER { 
            default { 'matdyn' }
            info { File where the dynamical matrix is written. }
        }

        var fildrho -type CHARACTER { 
            default { ' ' }
            info { File where the charge density responses are written. }
        }

        var fildvscf  -type CHARACTER { 
            default { ' ' }
            info {
                File where the the potential variation is written 
                (for later use in electron-phonon calculation).
            }
        }


        var epsil  -type LOGICAL { 
            default { .false. }
            info {
                If .true. in a q=0 calculation for a non metal the      
                macroscopic dielectric constant of the system is 
                computed. Do not set @ref epsil to .true. if you have a
                metallic system or q/=0: the code will complain and stop.
            }
        }

        var lrpa  -type LOGICAL { 
            default { .false. }
            info {
                If .true. the dielectric constant is calculated at the
                RPA level with DV_xc=0.
            }
        }

        var lnoloc  -type LOGICAL { 
            default { .false. }
            info {
                If .true. the dielectric constant is calculated without
                local fields, i.e. by setting DV_H=0 and DV_xc=0. 
            }
        }

        var trans  -type LOGICAL { 
            default { .true. }
            info {
                If .true. the phonons are computed.
                If @ref trans .and. @ref epsil are .true. effective charges are 
                calculated.
            }      
        }
        
        var lraman -type  LOGICAL { 
            default { .false. }
            info { 
                If .true. calculate non-resonant Raman coefficients      
                using second-order response as in:
                M. Lazzeri and F. Mauri, PRL 90, 036401 (2003).
            }
        }

        group {
            label { Optional variables for Raman: }
            
            var eth_rps -type REAL {
                default { 1.0d-9 }
                info { Threshold for calculation of  Pc R |psi>. }
            }
            var eth_ns  -type REAL { 
                default { 1.0e-12 }
                info { Threshold for non-scf wavefunction calculation. } 
            }
            var dek     -type REAL { 
                default { 1.0e-3 }
                info { Delta_xk used for wavefunction derivation wrt k.}
            }
        }

        var recover  -type LOGICAL { 
            default { .false. }
            info { If .true. restart from an interrupted run.}
        }

        var low_directory_check  -type LOGICAL { 
            default { .false. }
            info { If .true. search in the phsave directory only the
                  quantities requested in input.}
        }

        var only_init  -type LOGICAL { 
            default { .false. }
            info {
                If .true. only the bands and other initialization quantities are calculated.
                (used for GRID parallelization)}
        }

        var qplot  -type LOGICAL { 
            default { .false. }
            info { If .true. a list of q points is read from input.}
        }

        var q2d  -type LOGICAL { 
            default { .false. }
            info {
                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.
            }
	}

	var q_in_band_form  -type LOGICAL { 
	    default { .false. }
	    info {
		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.
	    }
	}

	var electron_phonon  -type CHARACTER { 
	    default { ' ' }
	    options {
		info {
		    Options are:
		}
		opt -val '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.
		}
		opt -val 'interpolated' {
		    Electron-phonon is calculated by interpolation
		    over the Brillouin Zone as in M. Wierzbowska, et
		    al. arXiv:cond-mat/0504077
		}
                opt -val 'lambda_tetra' {
                    The electron-phonon coefficient \lambda_{q \nu}
		    is calculated with the optimized tetrahedron method.
   	        }
                opt -val 'gamma_tetra' {
                    The phonon linewidth \gamma_{q \nu} is calculated
		    from the electron-phonon interactions
		    using the optimized tetrahedron method.
   	        }
		info {
		    For metals only, requires gaussian smearing.
		
		    If @ref trans=.true., the lambdas are calculated in the same
		    run, using the same k-point grid for phonons and lambdas.
		    If @ref trans=.false., the lambdas are calculated using
		    previously saved DeltaVscf in @ref fildvscf, previously saved
		    dynamical matrix, and the present punch file. This allows
		    the use of a different (larger) k-point grid.
		}
	    }
	}

	var lshift_q  -type LOGICAL { 
	    default { .false. }
	    info { 
	    Use a wave-vector 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.
	    }
	}

	var zeu  -type LOGICAL { 
	    default { zeu=@ref epsil }
	    info {
		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 @ref epsil=.true.
                and @ref zeu=.false. only the dielectric tensor is calculated.
	    }
	}

	var zue  -type LOGICAL { 
	    default { .false. }
	    info {
		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 @ref trans .and. @ref epsil )
		The results should be the same within numerical noise.
	    }
	}

	var elop -type LOGICAL {
	    default { .false. }
	    info {
		If .true. calculate electro-optic tensor.
	    }
	}

	var fpol  -type LOGICAL { 
	    default { .false. }
	    info {        
                 If .true. calculate dynamic polarizabilities            
                 Requires @ref epsil=.true. ( experimental stage:
                 see example09 for calculation of methane ).
	    }
	}

	var ldisp  -type LOGICAL { 
	    default { .false. }
	    info {
		If .true. the run calculates phonons for a grid of      
		q-points specified by @ref nq1, @ref nq2, @ref nq3 - for direct
		calculation of the entire phonon dispersion.
	    }
	}

	var nogg  -type LOGICAL { 
	    default { .false. }
	    info {
		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.
	    }
	}

	var ldiag  -type LOGICAL { 
	    default { .false. }
	    info {
		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 @ref start_irr
                and @ref 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.
	    }
	}

	var lqdir  -type LOGICAL { 
	    default { .false. }
	    info {
		If .true. ph.x creates inside outdir a separate subdirectory 
                for each q vector. The flag is set to .true. when @ref ldisp=.true.
		and @ref fildvscf /= ' ' or when an electron-phonon 
                calculation is performed. The induced potential is saved 
                separately for each q inside the subdirectories.
	    }
	}

	var search_sym  -type LOGICAL { 
	    default { .true. }
	    info {
                Set it to .false. if you want to disable the mode 
                symmetry analysis. 
	    }
	}

	vargroup -type INTEGER {
	    var nq1
	    var nq2
	    var nq3 
	    default { 0,0,0 }
	    info {
		Parameters of the Monkhorst-Pack grid (no offset) used
		when @ref ldisp=.true. Same meaning as for nk1, nk2, nk3
		in the input of pw.x.
	    }
	}


        vargroup -type INTEGER {
            var nk1
            var nk2
            var nk3
            var k1
            var k2
            var k3
            default { 0,0,0,0,0,0 }
            info {
                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.
            }
        }

	group {
	    label { Specification of irreducible representation }

	    var start_irr  -type INTEGER { 
		default { 1 }
		see { last_irr }
		info {      
		    Perform calculations only from @ref start_irr to @ref last_irr 
		    irreducible representations.
		    
		    IMPORTANT:
		       * @ref start_irr must be <= 3*nat
		       * do not specify @ref nat_todo together with 
		         @ref start_irr, @ref last_irr
		}
	    }

	    var last_irr  -type INTEGER { 
		default { 3*nat }
		see { start_irr }
		info {      
		    Perform calculations only from @ref start_irr to @ref last_irr 
		    irreducible representations.
		
		    IMPORTANT:
		       * @ref start_irr must be <= 3*nat
		       * do not specify @ref nat_todo together with 
		         @ref start_irr, @ref last_irr
		}
	    }

	    var nat_todo  -type INTEGER { 
		default { 0, i.e. displace all atoms }
		info {    
		    Choose the subset of atoms to be used in the linear response 
		    calculation: @ref 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:
		       * @ref 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
		}
	    }

	    var modenum -type INTEGER { 
		default { 0 }            
		info {
		    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.
		}
	    }
	}

	group {
	    label { q-point specification } 

	    var start_q  -type INTEGER { 
		default { 1 }
		see { last_q }
		info {      
		    Used only when ldisp=.true..
		    Computes only the q points from @ref start_q to @ref last_q.
		    
		    IMPORTANT:
		       * @ref start_q must be <= @ref nqs (number of q points found)
		       * do not specify @ref nat_todo together with 
		         @ref start_q, @ref last_q
		}
	    }

	    var last_q  -type INTEGER { 
		default { number of q points }
		see { start_q }
		info {      
		    Used only when @ref ldisp=.true..
		    Computes only the q points from @ref start_q to @ref last_q.
		
		    IMPORTANT
		       * @ref last_q must be <= @ref nqs (number of q points)
		       * do not specify @ref nat_todo together with 
		         @ref start_q, @ref last_q
		}
	    }	

	    var dvscf_star  -type STRUCTURE { 
		default { disabled }
		info {      
        It contains the following components:

        @b dvscf_star%open  (logical, default: .false.)
        @b dvscf_star%dir   (character, default: outdir//"Rotated_DVSCF" or the 
                          ESPRESSO_FILDVSCF_DIR environment variable)
        @b dvscf_star%ext   (character, default: "dvscf") the extension to use 
                          for the name of the output files, see below
        @b dvscf_star%basis (character, default: "cartesian") the basis on which 
                          the rotated dvscf will be saved
        @b 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 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.
    }
	    }

	    var drho_star  -type STRUCTURE { 
		see {dvscf_star }
		default { disabled }
		info {      
        It contains the following components:

        @b drho_star%open  (logical, default: .false.)
        @b drho_star%dir   (character, default: outdir//"Rotated_DRHO" or the 
                         ESPRESSO_FILDRHO_DIR environment variable)
        @b drho_star%ext   (character, default: "drho") the extension to use
                         for the name of the output files, see below
        @b drho_star%basis (character, default: "modes") the basis on which
                         the rotated drho will be saved
        @b drho_star%pat   (logical, default: true) save an optional file with the
                         displacement patterns and q vector for each drho file

        Like @ref dvscf_star, but for the perturbation of the charge density.
        Notice that the defaults are different.
    }
	    } 	    
	}   
    }


    choose {
	when -test "ldisp != .true.   and   qplot != .true." {

	    linecard {
		list xq_list -type REAL {
		    format { xq(1)  xq(2)  xq(3) }
		    info {
			The phonon wavevector, in units of 2pi/a0
			(a0 = lattice parameter).
			Not used if @ref ldisp=.true. or @ref qplot=.true.
		    }
		}
	    }
	} 
	elsewhen -test "qplot == .true." {

	    label { Specification of q points when @ref qplot == .true. }

	    card qPointsSpecs -nameless 1 {
		syntax {
		    line {
			var nqs -type INTEGER {
			    info { Number of q points in the list. Used only if @ref qplot=.true.
			    }
			}
		    }
		    
		    table qPoints {
			rows -start 1 -end nqs {
			    colgroup -type REAL {
				info {
                                    q-point coordinates; used only with @ref 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)
				}
				col xq1
				col xq2
				col xq3
			    }
			    col nq -type INTEGER {
				info { 
				    The weight of the q-point; the meaning of nq depends 
				    on the flags q2d and q_in_band_form. }
			    }
			}
		    }
		}
	    }
	}
    }

    choose {
        when -test "nat_todo was specified" {
	    linecard {
		list nat_todo_list -type INTEGER {
		    format { atom(1)  atom(2) ... atom(nat_todo) }
		    info {
			Contains the list of indices of atoms used in the
			calculation if @ref nat_todo is specified.
		    }
		}
	    }
	}
    }

    section -title { ADDITIONAL INFORMATION } {

	text {

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 @ref start_irr, @ref 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 @ref start_irr=0, @ref 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, @ref start_irr and
@ref 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, @ref start_irr, or @ref 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.

}  
}  
}
