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

    toc {}

    intro {
        @b {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). Alternatively:
            computes the local DOS(E) integrated in volumes given in input 
            (see @ref tdosinboxes) or k-resolved DOS (see @ref kresolveddos).
            Atomic projections are written to file "atomic_proj.xml".

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

           @b &PROJWFC
             ...
           @b /
    }

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

        var outdir -type CHARACTER {
            info {
                directory containing the input data, i.e. the same as in @b pw.x
            }
            default {
		value of the ESPRESSO_TMPDIR environment variable if set;
		current directory ('./') otherwise
	    }
        }

        var ngauss -type INTEGER {
            default { 0 }
            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 {
            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 @b .true.  the projections are symmetrized,
                           the partial density of states are computed
                if @b .false. the projections are not symmetrized, the partial 
                           DOS can be computed only in the k-resolved case
            }
        }

        var diag_basis -type LOGICAL {
            default { .false. }
            info {
                if @b .false. the projections of Kohn-Sham states are
                             done on the orthogonalized atomic orbitals
                             in the global XYZ coordinate frame.
                if @b .true. the projections of Kohn-Sham states are
                             done on the orthogonalized atomic orbitals
                             that are rotated to the basis in which the
                             atomic occupation matrix is diagonal 
                             (i.e. local XYZ coordinate frame).
            }
        }

        var pawproj -type LOGICAL {
            default { .false. }
            info {
                if @b .true. use PAW projectors and all-electron PAW basis
                functions to calculate weight factors for the partial 
                densities of states. Following Bloechl, PRB 50, 17953 (1994), 
                Eq. (4 & 6), the weight factors thus approximate the real
                charge within the augmentation sphere of each atom.
                Only for PAW, not implemented in the noncolinear case.
            }
        }

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

        var lwrite_overlaps -type LOGICAL {
            default { .false. }
            info {
                if @b .true., the overlap matrix of the atomic orbitals
                prior to orthogonalization is written to "atomic_proj.xml".
		Does not work together with parallel diagonalization:
                for parallel runs, use "mpirun -np N projwfc.x -nd 1 ... "
            }
        }

        var lbinary_data -type LOGICAL {
            default { .false. }
            info {
		CURRENTLY DISABLED.
                if @b .true., write atomic projections to a binary file.
            }
        }

        var kresolveddos -type LOGICAL {
            default { .false. }
            info {
                if @b .true. the k-resolved DOS is computed: not summed over
                all k-points but written as a function of the k-point index.
                In this case all k-point weights are set to unity
            }
        }

        var tdosinboxes -type LOGICAL {
            default { .false. }
            info {
                if @b .true. compute the local DOS integrated in volumes
		
                Volumes are defined as boxes with edges parallel to the unit cell,
		containing the points of the (charge density) FFT grid included within
		@ref irmin and @ref irmax, in the three dimensions:

		from @ref irmin(j,n) to @ref irmax(j,n) for j=1,2,3 (n=1,@ref n_proj_boxes).
	    }
	}

        var n_proj_boxes -type INTEGER {
            default { 1 }
            info {
                number of boxes where the local DOS is computed
            }
        }
        
        multidimension irmin -start 1,1 -end 3,n_proj_boxes -indexes i,n_proj_boxes -type INTEGER {
            default { 1 for each box }
            info {
                
                first point of the given box

                BEWARE: @ref irmin is a 2D array of the form: @ref irmin(3,@ref n_proj_boxes)
            }
        }       

        multidimension irmax -start 1,1 -end 3,n_proj_boxes -indexes i,n_proj_boxes -type INTEGER {
            default { 0 for each box }
            info {
                
                last point of the given box;
                ( 0 stands for the last point in the FFT grid )

                BEWARE: @ref irmax is a 2D array of the form: @ref irmax(3,@ref n_proj_boxes)
            }
        }       

        var plotboxes -type LOGICAL {
            default { .false. }
            info {
                if @b .true., the boxes are written in output as @b xsf files with 
                3D datagrids, valued 1.0 inside the box volume and 0 outside
                (visualize them as isosurfaces with isovalue 0.5)
            }
        }       
    }

    section -title Notes {
        subsection -title {Format of output files} {
            text {
                Projections are written to standard output, and also to file
                @ref 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)
		    ...

                If @ref kresolveddos=.true., the k-point index is prepended
                to the formats above, e.g. (collinear, spin-unpolarized case)
                    ik E DOS(E) PDOS(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 azimuthal angle: x=r cos(theta)cos(phi), y=r cos(theta)sin(phi)
		This is determined in file upflib/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=+/-2 with sine)
	    }
	}

	subsection -title {Defining boxes for the Local DOS(E)} {
	    text {
		Boxes are specified using the variables @ref irmin and @ref irmax:
		
		FFT grid points are included from irmin(j,n) to irmax(j,n)
		for j=1,2,3 and n=1,...,@ref n_proj_boxes
		
		@ref irmin and @ref irmax range from 1 to nr1 or nr2 or nr3
		
		Values larger than nr1/2/3 or smaller than 1 are folded
		to the unit cell.
		
		If @ref irmax<@ref irmin FFT grid points are included from 1 to irmax
		and from irmin to nr1/2/3.
	    }
	}

	subsection -title {Important notices} {
	    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 &projwfc
		
		* Gaussian broadening is used in all other cases:

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

		    - if @ref degauss is NOT set to any value in namelist &PROJWFC, 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 &PROJWFC, 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
		

		Obsolete variables, ignored:
		    io_choice
		    smoothing
	    }
	}
    }
}
