input_description -distribution {Quantum ESPRESSO} -package PWscf -program dos.x {

    toc {}

    intro {
	@b {Purpose of dos.x:}
	    calculates the Density of States (DOS) 
	    (separated into up and down components for DSDA)


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

	   @b &DOS
	     ...
	   @b /
	
        IMPORTANT: since v.5 namelist name is &DOS and no longer &INPUTPP
    }

    namelist DOS {

	var prefix -type CHARACTER {
	    default { 'pwscf' } 
	    info {
		prefix of input file produced by pw.x   
		(wavefunctions are not needed)
	    }
	}

        var outdir -type CHARACTER {
            info {
		directory containing the input data, i.e. the same as in pw.x
	    }
            default {
                      value of the @tt ESPRESSO_TMPDIR environment variable if set;
                      current directory ('./') otherwise }
        }
 
        var bz_sum -type CHARACTER {
            options {
	    info {Keyword selecting  the method for BZ summation. Available options are:} 
                 opt -val 'smearing' {
                    integration using gaussian smearing. In fact currently 
                    any string not related to tetrahedra defaults to smearing; 
                  }
                   opt -val 'tetrahedra' {
                    Tetrahedron method, Bloechl's version:
                    P.E. Bloechl, PRB 49, 16223 (1994)
                    Requires uniform grid of k-points, to be
                    automatically generated in pw.x.
		}
		opt -val 'tetrahedra_lin' {
                    Original linear tetrahedron method.
                    To be used only as a reference;
                    the optimized tetrahedron method is more efficient.
                }
		opt -val 'tetrahedra_opt' {
                    Optimized tetrahedron method:
                    see M. Kawamura, PRB 89, 094515 (2014).
                }
              }
              default { 'smearing' if degauss is given in input; 
                         options read from the xml data file otherwise. }  
               }

	var ngauss -type INTEGER {       
	    default { 0 }
	    status { optional }
	    info {
		Type of gaussian broadening: 

		    =  0  Simple Gaussian (default)
		
		    =  1  Methfessel-Paxton of order 1
		    
		    = -1  "cold smearing" (Marzari-Vanderbilt-DeVita-Payne)
		    
		    =-99  Fermi-Dirac function
	    }
	}

	var degauss -type REAL {       
	    info {
		gaussian broadening, Ry (not eV!)
		(see below)
	    }
	}
	
	vargroup -type REAL {
	    var Emin
	    var Emax    
	    default { band extrema }
	    info {
		min, max energy (eV) for DOS plot. If unspecified, the
                lower and/or upper band value, plus/minus 3 times the
                value of the gaussian smearing if present, will be used.
                
	    }
	}
	
	var DeltaE -type REAL {       
	    info {
		energy grid step (eV)
	    }
	}

	var fildos -type CHARACTER {
	    default { '@ref prefix.dos' }
	    info {
		output file containing DOS(E)
	    }
	}
    }

    section -title Notes {
	subsection -title Output {
	    text {
		The total DOS (states/eV plotted vs @i E in eV) is written to file @ref fildos
	    }
	}

	subsection -title {Important !} {
	    text {	    
		The tetrahedron method is used if

		    - the input data file has been produced by pw.x using the option
		      occupations='tetrahedra', AND
		    
		    - a value for degauss is not given as input to namelist &dos


		Gaussian broadening is used in all other cases:

		    - if @ref degauss is set to some value in namelist &DOS, that value
		      (and the optional value for @ref ngauss) is used
		    
		    - if @ref degauss is NOT set to any value in namelist &DOS, the 
		      value of @ref degauss and of @ref ngauss are read from the input data
		      file (they will be the same used in the pw.x calculations)
		    
		    - if @ref degauss is NOT set to any value in namelist &DOS, AND
		      there is no value of @ref degauss and of @ref ngauss in the input data
		      file, @ref degauss=@ref DeltaE (in Ry) and @ref ngauss=0 will be used
	    }
	}
    }
}
