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

    toc {}

    intro {
	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
    }

    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 { './' }
	    info { Scratch directory. }
	}
    
	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 { 100 }
	    info {
		Maximum number of iterations in a scf step.
	    }
	}

	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 iverbosity -type INTEGER { 
	    default { 0 }
	    info {
		0 = short output
		1 = verbose 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 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 trans .and. 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, Phys. Rev. Lett. 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 elph  -type LOGICAL { 
	    default { .false. }
	    info {
		If .true. electron-phonon lambda coefficients are computed.
		
		For metals only, requires gaussian smearing.
		
		If elph .and. trans, the lambdas are calculated in the same
		run, using the same k-point grid for phonons and lambdas
		If elph.and..not.trans, 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.
	    }
	}

	var zeu  -type LOGICAL { 
	    default { zeu=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 epsil=.true.
                and 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 trans .and. 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            
                 ( experimental stage, see example33 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 nq1, nq2, 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 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.
	    }
	}

	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 ldisp=
                .true. and fildvscf /= ' ' or when elph is true. 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 ldisp=.true. Same meaning as for nk1, nk2, nk3
		in the input of pw.x.
	    }
	}

	group {
	    label { Specification of irreducible representation }

	    var start_irr  -type INTEGER { 
		default { 1 }
		see { last_irr }
		info {      
		    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"
		}
	    }

	    var last_irr  -type INTEGER { 
		default { 3*nat }
		see { start_irr }
		info {      
		    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"
		}
	    }

	    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: "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
		}
	    }

	    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 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"
		}
	    }

	    var last_q  -type INTEGER { 
		default { number of q points }
		see { start_q }
		info {      
		    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"
		}
	    }	
	}   
    }


    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 ldisp=.true.
	    }
	}
    }
	
    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 "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
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. The procedure is the following:

1) run pw.x with nproc processors and npools pools.
2) run ph.x with nproc*nimage processors, npools pools and nimage images.
3) run ph.x with the same input and recover=.true. on nproc processors 
   and npools pools and only one image. 

During the first ph.x run the phonon code split the total amount of
work into nimage copies. Each image runs with different q and/or
representations.  The second run of ph.x is the final run that
collects all the data calculated by the images and writes the files
with the dynamical matrices.  

}  
}  
}