%!TEX root=./user_guide.tex
\chapter{Generic Band interpolation}\label{ch:geninterp}

By setting $\verb#geninterp#=\verb#TRUE#$, \postw\ will calculate the
band energies (and possibly the band derivatives, if also
\verb#geninterp_alsofirstder# is set to \verb#TRUE#) on a generic list
of $k$ points provided by the user.

The list of parameters of the Generic Band Interpolation module are
summarized in Table~\ref{parameter_keywords_geninterp}. 
The list of input $k$ points for which the band have to be calculated
is read from the file named {\tt seedname\_geninterp.kpt}. The format
of this file is
described below. 

\section{Files}
\subsection{{\tt seedname\_geninterp.kpt}}
INPUT. Read by \postw\ if {\tt geninterp} is \verb#true#. 

The first line is a comment (its maximum allowed length is 500
characters).

The second line must contain \verb#crystal# (or \verb#frac#) if the
$k$-point coordinates are given in crystallographic units,
i.e., in fractional units with respect to the primitive reciprocal
lattice vectors.
Otherwise, it must contain \verb#cart# (or \verb#abs#) if instead the
$k-$point coordinates are given in absolute 
coordinates (in units of 1/\AA) along the $k_x$, $k_y$ and $k_z$
axes.

\emph{Note on units}: In the case of absolute coordinates, 
if $a_{lat}$ is the lattice constant expressed in angstrom,
and you want to represent for instance the point
$X=\frac {2\pi}{a_{lat}} [0.5, 0, 0]$, then you have to input for its $x$ coordinate
$k_x = 0.5 * 2 * \pi / a_{lat}$. As a practical example, if
$a_{lat}=4$\AA, then $k_x = 0.78539816339745$ in 
absolute coordinates in units of 1/\AA.

The third line must contain the number $n$ of following $k$ points.

The following $n$ lines must contain the list of $k$ points in the
format
\begin{verbatim}
kpointidx k1 k2 k3
\end{verbatim}
where \verb#kpointidx# is an integer identifying the given $k$ point,
and \verb#k1#, \verb#k2# and \verb#k3# are the three coordinates of the
$k$ points in the chosen units.


\subsection{{\tt seedname\_geninterp.dat} or {\tt
    seedname\_geninterp\_NNNNN.dat}}
\label{sec:seedname.geninterp.dat}
OUTPUT. This file/these files contain the interpolated band energies (and also the band
velocities if the input flag \verb#geninterp_alsofirstder# is \verb#true#).

If the flag \verb|geninterp_single_file| is \verb|true|, then a single
file {\tt seedname\_geninterp.dat} is written by the code at the end
of the calculation. If instead one sets \verb|geninterp_single_file|
to \verb|false|, each process writes its own output file, named 
{\tt seedname\_geninterp\_00000.dat}, {\tt
  seedname\_geninterp\_00001.dat}, \ldots

This flag is useful when one wants to parallelize the calculation on
many nodes, and it should be used especially for systems with a small
number of Wannier functions, when one wants to compute the bands on a
large number of $k$ points (if the flag \verb|geninterp_single_file|
is \verb|true|, instead, all the I/O is made by the root node, which
is a significant bottleneck).

{\bf Important!} The files are not deleted before the start of a
calculation, but only the relevant files are overwritten. Therefore,
if one first performs a calculation and then a second one with a smaller
number of processors, care is needed to avoid to mix the results of
the older calculations with those of the new one. In case of doubt,
either check the date stamp in the first line of the {\tt
    seedname\_geninterp\_*.dat} files, or simply
delete the  {\tt
    seedname\_geninterp\_*.dat} files before starting the new
  calculation.

To join the files, on can simply use the following command:
\begin{verbatim}
cat seedname_geninterp_*.dat > seedname_geninterp.dat
\end{verbatim}
or, if one wants to remove the comment lines:
\begin{verbatim}
rm seedname_geninterp.dat
for i in seedname_geninterp_*.dat ; do grep -v \# "$i" >> \
seedname_geninterp.dat ; done
\end{verbatim}


The first few lines of each files are comments (starting with \#),
containing a datestamp, the
comment line as it is read from the input file, and a header.
The following lines contain the band energies (and
derivatives) for each band and $k$ point (the energy
index runs faster than the $k$-point index).
For each of these lines, the first four columns contain the $k$-point index as provided in the
input, and the $k$ coordinates (always in absolute coordinates, in
units of 1/\AA).
The fifth column contains the band energy.

If \verb#geninterp_alsofirstder# is \verb#true#, three further columns
are printed, containing the three first derivatives of the bands along the $k_x$, $k_y$
and $k_z$ directions.

The $k$ point coordinates are in units of 1/\AA, the band energy is in eV.




