quantum-espresso/doc-def/INPUT_PROJWFC.def

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

    toc {}

    intro {
	Purpose of projwfc.x: 
	    projects wavefunctions onto orthogonalized atomic wavefunctions, 
	    calculates Lowdin charges, spilling parameter, projected DOS 
	    (separated into up and down components for lSDA)

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

	   &INPUTPP
	     ...
	   /
    }

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

	var outdir -type CHARACTER {
	    info { directory containing the input file }
	    default { './' }
	}

	var ngauss -type INTEGER {
	    default { 0 }
	    info {
		Type of gaussian broadening:
		    0 ... Simple Gaussian (default)
		    1 ... Methfessel-Paxton of order 1
		   -1 ... Marzari-Vanderbilt "cold smearing"
		  -99 ... Fermi-Dirac function
	    }
	}
	
	var degauss -type REAL {
	    default { 0.0 } 
	    info { gaussian broadening, Ry (not eV!) }
	}

	vargroup -type REAL {
	    var Emin
	    var Emax
	    info { min & max energy (eV) for DOS plot }
	    default { (band extrema) }
	}
	var DeltaE -type REAL {
	    info { energy grid step (eV) }
	}
	
	var lsym -type LOGICAL {
	    default { .true. }
	    info {
		if true the projections are symmetrized
	    }
	}

	var filpdos -type CHARACTER {
	    info { prefix for output files containing PDOS(E) } 
	    default { (value of prefix variable) }
	}
	
	var filproj -type CHARACTER {
	    default { (standard output) }
	    info {
		file containing the projections
	    }
	}
    }

    section -title Notes {
	subsection -title {Format of output files} {
	    text {
	        Projections are written to standard output,
	        and also to file filproj if given as input.
	        
	        The total DOS and the sum of projected DOS are written to file 
	        "filpdos".pdos_tot.
	        
	        * The format for the collinear, spin-unpolarized case and the
	          non-collinear, spin-orbit case is:
	              E DOS(E) PDOS(E)
	              ...
	        
	        * The format for the collinear, spin-polarized case is:
	              E DOSup(E) DOSdw(E)  PDOSup(E) PDOSdw(E) 
	              ...
	        
	        * The format for the non-collinear, non spin-orbit case is:
	              E DOS(E) PDOSup(E) PDOSdw(E) 
	              ...
     	        
	        In the collinear case and the non-collinear, non spin-orbit case
	        projected DOS are written to file "filpdos".pdos_atm#N(X)_wfc#M(l),
	        where N = atom number , X = atom symbol, M = wfc number, l=s,p,d,f
	        (one file per atomic wavefunction found in the pseudopotential file) 
	        
	        * The format for the collinear, spin-unpolarized case is:
	              E LDOS(E) PDOS_1(E) ... PDOS_2l+1(E)
	              ...
	        
	        where LDOS = \sum m=1,2l+1 PDOS_m(E)
	        and PDOS_m(E) = projected DOS on atomic wfc with component m
	        
	        * The format for the collinear, spin-polarized case and the 
	          non-collinear, non spin-orbit case is as above with
	          two components for both  LDOS(E) and PDOS_m(E)
      	        
	        In the non-collinear, spin-orbit case (i.e. if there is at least one
	        fully relativistic pseudopotential) wavefunctions are projected
	        onto eigenstates of the total angular-momentum. 
	        Projected DOS are written to file "filpdos".pdos_atm#N(X)_wfc#M(l_j),
		where N = atom number , X = atom symbol, M = wfc number, l=s,p,d,f
		and j is the value of the total angular momentum.
		In this case the format is:
		    E LDOS(E) PDOS_1(E) ... PDOS_2j+1(E)
		    ...

		All DOS(E) are in states/eV plotted vs E in eV
	    }
	}

	subsection -title {Orbital Order} {
	    text {
		Order of m-components for each l in the output:
		
		    1, cos(phi), sin(phi), cos(2*phi), sin(2*phi), .., cos(l*phi), sin(l*phi)
		
		where phi is the polar angle:x=r cos(theta)cos(phi), y=r cos(theta)sin(phi)
		This is determined in file flib/ylmr2.f90 that calculates spherical harmonics.

	        for l=1:
	          1 pz     (m=0)
	          2 px     (real combination of m=+/-1 with cosine)
	          3 py     (real combination of m=+/-1 with sine)
	        
	        for l=2:
	          1 dz2    (m=0)
	          2 dzx    (real combination of m=+/-1 with cosine)
	          3 dzy    (real combination of m=+/-1 with sine)
	          4 dx2-y2 (real combination of m=+/-2 with cosine)
	          5 dxy    (real combination of m=+/-1 with sine)
	    }
	}

	subsection -title {Important notices} {
	    text {
		* The tetrahedron method is presently not implemented.
		
		* Gaussian broadening is used in all cases:

		    - if degauss is set to some value in namelist &inputpp, that value
		      (and the optional value for ngauss) is used

		    - if degauss is NOT set to any value in namelist &inputpp, the 
		      value of degauss and of ngauss are read from the input data
		      file (they will be the same used in the pw.x calculations)

		    - if degauss is NOT set to any value in namelist &inputpp, AND
		      there is no value of degauss and of ngauss in the input data
		      file, degauss=DeltaE (in Ry) and ngauss=0 will be used
		

		Obsolete variables, ignored:
		    io_choice
		    smoothing
	    }
	}
    }
}