%!TEX root=./user_guide.tex
\chapter{Utilities}\label{ch:utilities}

The \wannier\ code is shipped with a few utility programs that may be
useful in some occasions. In this chapter, we describe their use.

\section{$\tt{kmesh.pl}$}
\label{sec:kmesh}
The \wannier\ code requires the definition of a full Monkhorst--Pack
grid of $k$ points.
In the input file 
the size of this mesh is given by means of the \texttt{mp\_grid} variable. E.g.,
setting
\begin{verbatim}
mp_grid = 4 4 4
\end{verbatim}
tells \wannier\ that we want to use a $4\times 4\times 4$ $k$ grid.

One has then to specify (inside the \texttt{kpoints} block in the 
the \texttt{seedname.win} file) the list of $k$ points of the grid.
Here, the \texttt{kmesh.pl} Perl script becomes 
useful, being able to generate the required list.

The script can be be found in the
\texttt{utility} directory of the \wannier\ distribution.
To use it, simply type:
\begin{verbatim}
./kmesh.pl nx ny nz
\end{verbatim}
where \verb|nx|, \verb|ny| and \verb|nz| define the size of the
Monkhorst--Pack grid that we want to use (for instance, in the above example of the
$4\times 4\times 4$ $k$ grid, 
 \verb|nx|$=$\verb|ny|$=$\verb|nz|$=$4).

This produces on output the list of $k$ points in Quantum
Espresso format, where (apart from a header) the first three columns
of each line are the $k$ coordinates, and the fourth column is the weight
of each $k$ point. This list can be used to create the input file
for the ab-initio \verb|nscf| calculation.

If one wants instead to generate the list of the $k$ coordinates
without the weight (in order to copy and paste the output inside the
\texttt{seedname.win} file), one simply has to provide a fourth
argument on the command line. For instance, for a $4\times 4\times 4$
$k$ grid,
use
\begin{verbatim}
./kmesh.pl 4 4 4 wannier
\end{verbatim}
and then copy the output inside the in the \texttt{kpoints} block in the \texttt{seedname.win} file.

We suggest to always use this utility to generate the $k$ grids. This
allows to
provide the $k$ point coordinates with the accuracy required by
\wannier, and moreover it
makes sure that the $k$ grid used in the ab-initio code and in
\wannier\ are the same.

\section{$\tt{w90chk2chk.x}$\label{sec:w90chk2chk}}
During the calculation of the Wannier functions, \wannier\ produces a
\verb|.chk| file that contains some information to restart the
calculation.

This file is also required by the \postw\ code. 
In particular, the \postw\ code requires at least the \verb|.chk| file, the
\verb|.win| input file, and (almost always) the \verb|.eig|
file. Specific modules may require further files: see the
documentation of each module.

However, the \verb|.chk| file is
written in a machine-dependent format. If one wants to run \wannier\
on a machine, and then continue the calculation with \postw\ on a
different machine (or with \postw\ compiled with a different compiler), the file has to be
converted first in a machine-independent ``formatted'' format on the
first machine, and
then converted back on the second machine.

To this aim, use the \verb|w90chk2chk.x| executable. Note that this
executable is not compiled by default: you can obtain it by executing 
\begin{verbatim}
make w90chk2chk
\end{verbatim}
in the main \wannier\ directory.

A typical use is the following:
\begin{enumerate}
\item Calculate the Wannier functions with \wannier
\item At the end of the calculation you will find a \verb|seedname.chk|
  file. Run (in the folder with this file) the command
\begin{verbatim}
w90chk2chk.x -export seedname
\end{verbatim}
or equivalently
\begin{verbatim}
w90chk2chk.x -u2f seedname
\end{verbatim}
(replacing \verb|seedname| with the seedname of your calculation).

This command reads the \verb|seedname.chk| file and creates a
formatted file  \verb|seedname.chk.fmt| that is safe to be transferred
between different machines.
\item Copy the \verb|seedname.chk.fmt| file (together with the
  \verb|seedname.win| and \verb|seedname.eig| files) on the machine on
  which you want to run \postw.
\item On this second machine (after having compiled
  \verb|w90chk2chk.x|) run
\begin{verbatim}
w90chk2chk.x -import seedname
\end{verbatim}
or equivalently
\begin{verbatim}
w90chk2chk.x -f2u seedname
\end{verbatim}

This command reads the \verb|seedname.chk.fmt| file and creates an
unformatted file  \verb|seedname.chk| ready to be used by \postw.

\item Run the \postw\ code.

\end{enumerate}


\section{$\tt{PL\_assessment}$}
\label{sec:pl_assessment}

The function of this utility is to assess the length of a principal
layer (in the context of a Landauer-Buttiker quantum conductance
calculation) of a periodic system using a calculation on a single unit
cell with a dense k-point mesh.

The utility requires the real-space Hamiltonian in the MLWF basis,
\verb|seedname_hr.dat|. 

The \verb|seedname_hr.dat| file should be copied to a directory containing
executable for the utility. Within that directory, run:

\begin{verbatim}
\$> ./PL_assess.x  nk1 nk2 nk3 num_wann 
\end{verbatim}

where:

 \verb|nk1| is the number of k-points in x-direction
 \verb|nk2| is the number of k-points in y-direction
 \verb|nk3| is the number of k-points in z-direction
 \verb|num_wann| is the number of wannier functions of your system

e.g.,

\begin{verbatim} 
\$> ./PL_assess.x  1 1 20 16
\end{verbatim}

Note that the current implementation only allows for a single k-point
in the direction transverse to the transport direction.

When prompted, enter the seedname.

The programme will return an output file \verb|seedname_pl.dat|, containing four columns
\begin{enumerate}
        \item Unit cell number, $R$
        \item Average 'on-site' matrix element between MLWFs in 
             the home unit cell, and the unit cell $R$ lattice
             vectors away
        \item Standard devaition of the quantity in (2)
        \item Maximum absolute value in (2)
\end{enumerate}

\section{$\tt{w90vdw}$}
\label{sec:w90vdw}

This utility provides an implementation of a method for calculating
van der Waals energies based on the idea of density decomposition via
MLWFs. 

For theoretical details, please see the following publication
and references therein:

Lampros Andrinopoulos, Nicholas D. M. Hine and Arash A. Mostofi, 
``Calculating dispersion interactions using maximally localized
Wannier functions'', \emph{J. Chem. Phys.} \textbf{135}, 154105 (2011).

For further details of this program, please see the documentation
in \verb|utility/w90vdw/doc/| and the related examples in
\verb|utility/w90vdw/examples/|.

\section{$\tt{w90pov}$}
\label{sec:w90pov}

An utility to create Pov files (to render the Wannier functions using
the PovRay utility) is provided inside \verb|utility/w90pov|.

Please refer to the documentation inside \verb|utility/w90pov/doc|
for more information.


\section{$\tt{k\_mapper.py}$}
\label{sec:k_mapper}
The \wannier\ code requires the definition of a full Monkhorst--Pack
grid of $\mathbf{k}$-vectors, which can be obtained by means of the \verb|kmesh.pl| utility.
In order to perform a GW calculation with the Yambo code, you need to perform a nscf calculation on a grid in the irreducible BZ. Moreover, you may need a finer grid to converge the GW calculation than what you need to interpolate the band structure. The \verb|k_mapper.py| tools helps in finding the $\mathbf{k}$-vectors indeces of a full grid needed for interpolation into the reduced grid needed for the GW calculation with Yambo. \newline \newline
Within the \verb|/utility| folder type:\newline 
\verb|./k_mapper.py nx ny nz "path_of_the_QE_nscf_output_file_given_to_Yambo"|
\section{$\tt{gw2wannier90.py}$}
This utility allows to sort in energy the input data of \verb|wannier90| (e.g. overlap matrices and energy eigenvalues). \verb|gw2wannier90.py| allows to use \verb|wannier90| at the $G_0W_0$ level, where quasi-particle corrections can change the energy ordering of eigenvalues (Some \verb|wannier90| modules require states to be ordered in energy).\newline \newline
Within the work directory type:
\verb|./gw2wannier90.py seedname options|
\newline \newline
NB: Binary files are supported, though not reccommended.
\label{sec:w90aaa}

