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

    toc {}

    intro {
	@b {Purpose of bands.x:}
	   Re-order bands, computes band-related properties. Currently,
	   re-ordering can be done with two different algorithms:
	   (a) by maximising the overlap with bands at previous k-point
           (b) by computing symmetry properties of each wavefunction
           Bands-related properties that can be computed are currently
	   (a) The expectation value of the spin operator on each spinor
               wave-function (noncolinear case only)
	   (b) The expectation value of p

        The input data can be read from standard input or from file using
	command-line options "bands.x -i file-name" (same syntax as for pw.x)	

	Output files:
	- file @ref filband containing the band structure, in a format
	  suitable for plotting code "plotband.x"
	- file "filband".rap (if @ref lsym is .t.)  with symmetry information,
	  to be read by plotting code "plotband.x"
	- if (@ref lsigma(i)): file "filband".i, i=1,2,3, with expectation values
	  of the spin operator in the noncolinear case
	- file "filband".gnu with bands in eV, directly plottable using gnuplot	
	- file @ref filp with matrix elements of p

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

	   @b &BANDS
	     ...
	   @b /
    }

    namelist BANDS {

	var prefix -type CHARACTER {   
            default {'pwscf'}
	    info {
		prefix of files saved by program pw.x
	    }
	}

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

	var filband -type CHARACTER {     
            default {'bands.out'}
	    info {
		file name for band output (to be read by "plotband.x")
	    }
	}

	var spin_component -type INTEGER { 
	    info {
		In the lsda case select:
		
		   1 = spin-up
		   2 = spin-down
	    }
	}

	dimension lsigma  -start 1 -end 3 -type LOGICAL { 
	    info {
		If true computes expectation values of the spin operator
		on the spinor wave-functions (only in the noncollinear case),
		writes them to a file "filband".i, i=1,2,3
	    }
	}

        var lp -type LOGICAL {
            default { .false. }
            info {
                If .true. matrix elements of the momentum operator p between
                conduction and valence bands are computed and written to file
		specified in @ref filp
            }

        }      
        var filp -type CHARACTER {
            default { 'p_avg.dat' }
            info {
                If @ref lp is set to .true., file name for matrix elements of p
	    }

        }      
	var lsym -type LOGICAL {
	    default { .true. }
	    info {
		If .true. the bands are classified according to the
		irreducible representations of the small group of k.
		A file "filband".rap with the same format of "filband"
		is written, for usage by "plotband.x"
	    }
	}
	 
	var no_overlap -type LOGICAL { 
	    default { .true. }
	    info {		
		If .false., and if @ref lsym is .false., writes the eigenvalues
		in the order that maximises overlap with the neighbor k-points

	    }
	}

        var plot_2d -type LOGICAL {
            default { .false. }
            info {
                If .true. writes the eigenvalues in the output file
                in a 2D format readable by gnuplot. Band ordering is not 
                changed. Each band is written in a different file called 
                filband.# with the format:
		@i {
                   xk, yk, energy
                   xk, yk, energy
                   ..  ..  ..
		}
		energies are written in eV and xk in units 2\pi/a.
        }

      }           
	vargroup -type INTEGER {
	    var firstk
	    var lastk 
	    info {		
		if @ref lsym=.true. makes the symmetry analysis only for k
		points between firstk to lastk		
	    }
	}
    }
}