%!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 indexes of a full grid needed for interpolation into the reduced grid needed for the GW calculation with Yambo. \newline \newline
Usage:\newline 

\verb|path/k_mapper.py nx ny nz QE_nscf_output|\newline

where \verb|path| is the path of \verb|utility| folder, 
\verb|QE_nscf_output| is the 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
Usage:

\verb|path/gw2wannier90.py seedname options|
\newline \newline
where \verb|path| is the path of \verb|utility| folder.\newline\newline

Available options are:
\begin{verbatim}
mmn, amn, spn, unk, uhu, uiu,
spn_formatted, unk_formatted, uhu_formatted, uiu_formatted,
write_formatted
\end{verbatim}

If no options are specified, all the files (\verb|mmn, amn, spn, UNK, uHu, uIu|) are considered.

Binary (unformatted Fortran) files are supported, though not reccommended, 
since they are compiler-dependent.
A safer choice is to use (bigger) formatted files, with options:

\verb|spn_formatted, uiu_formatted, uhu_formatted, unk_formatted|

In default, the output format is the same as the input format.
To generate formatted files with unformatted input, use option:
\verb|write_formatted|
\label{sec:w90aaa}

\section{$\tt{w90spn2spn.x}$\label{sec:w90spn2spn}}
The interface between ab-initio code and \wannier\ 
(e.g. \texttt{pw2wannier90.x}) can produce a
\verb|.spn| file that is used by \postw\ to 
calculate some spin related quantities.

The \verb|.spn| file can be 
written in a machine-dependent or a machine-independent format 
depending on the input parameter \texttt{spn\_formatted} 
(the default is \texttt{false} which means the \verb|.spn| file 
is machine-dependent) of the 
\texttt{pw2wannier90.x}. If a \verb|.spn| file has been generated 
on a machine with machine-dependent format, 
and then one wants to 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. 

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

A typical use is the following:
\begin{enumerate}
	\item Calculate the \verb|.spn| file, e.g. by \texttt{pw2wannier90.x}
	\item At the end of the calculation you will find a \verb|seedname.spn|
	file. If the file is ``unformatted'', run (in the folder with this file) the command
	\begin{verbatim}
	w90spn2spn.x -export seedname
	\end{verbatim}
	or equivalently
	\begin{verbatim}
	w90spn2spn.x -u2f seedname
	\end{verbatim}
	(replacing \verb|seedname| with the seedname of your calculation).
	
	This command reads the \verb|seedname.spn| file and creates a
	formatted file  \verb|seedname.spn.fmt| that is safe to be transferred
	between different machines.
	\item Copy the \verb|seedname.spn.fmt| file on the machine on
	which you want to run \postw.
	\item On this second machine (after having compiled
	\verb|w90spn2spn.x|) run
	\begin{verbatim}
	w90spn2spn.x -import seedname
	\end{verbatim}
	or equivalently
	\begin{verbatim}
	w90spn2spn.x -f2u seedname
	\end{verbatim}
	
	This command reads the \verb|seedname.spn.fmt| file and creates an
	unformatted file \verb|seedname.spn| ready to be used by \postw.
	
	\item Run the \postw\ code.
	
\end{enumerate}

Note if \texttt{spn\_formatted} is set to \texttt{true} in both 
\texttt{pw2wannier90.x} and \postw\ input files, then the \verb|.spn| file will 
be written and read as ``formatted'', so \texttt{w90spn2spn.x} is not needed. 
However, if an ``unformatted'' \verb|seedname.spn| has been created and 
you do not want to rerun \texttt{pw2wannier90.x}, then 
\texttt{w90spn2spn.x} can be useful. 
Also, once a ``formatted'' \verb|seedname.spn| has been generated, the step 4 can be skipped if 
\texttt{spn\_formatted} is set to \texttt{true} in \postw\ input file \verb|seedname.win|.